Mettre à jour la documentation technique et utilisateur

La documentation technique d'une application regroupe tout ce qui permet à un développeur ou à un administrateur de l'installer, de la comprendre et de la modifier : README, architecture, schéma de la base, documentation de l'API, commentaires du code. La documentation d'utilisation explique aux utilisateurs comment s'en servir. En maintenance, la règle est simple : la documentation suit le code. Une correction ou une évolution n'est pas terminée tant que les documents qu'elle rend faux n'ont pas été mis à jour. Ce chapitre passe en revue les documents d'une application, dit lesquels mettre à jour après chaque type de changement, et donne des modèles : README, JSDoc et PHPDoc, OpenAPI, décision d'architecture.

Les documents d'une application

Le référentiel du BTS SIO demande de « mettre à jour des documentations technique et d'utilisation », et, pour la conception, qu'un document soit rédigé pour chaque contexte d'utilisation. Autrement dit : on n'écrit pas la même chose pour un développeur, un administrateur et un comptable.

Quoi mettre à jour après un changement

La question à te poser à la fin de chaque ticket : quels documents ce changement a-t-il rendus faux ? Cette matrice donne les réponses habituelles.

Pour l'évolution #250 du chapitre 6 (refus d'une ligne avec motif), cela donne : le changelog, le dictionnaire de données (deux colonnes), la documentation de l'API (une route, deux champs), les docblocks des nouvelles fonctions, et le guide du comptable et du salarié.

Le README

Le README est la porte d'entrée du projet. Il doit permettre à quelqu'un qui ne connaît rien au projet de le faire tourner en un quart d'heure. Un plan qui fonctionne :

# Sorbier Frais — API

API REST de gestion des notes de frais de Sorbier : saisie par les salariés,
contrôle et validation par les comptables. Version actuelle : voir CHANGELOG.md.

## Prérequis
- Node.js 24 ou 26
- MySQL 8.4 (ou Docker, qui fournit la base)

## Installation
```bash
git clone git@github.com:sorbier/frais-api.git
cd frais-api
cp .env.example .env      # puis renseigner les variables ci-dessous
docker compose up -d      # base MySQL sur le port 3306
npm ci
npm run migrate           # applique les scripts de migrations/
```

## Configuration
| Variable | Rôle | Exemple |
|---|---|---|
| DB_HOST, DB_PORT | Serveur MySQL | localhost, 3306 |
| DB_USER, DB_PASSWORD | Compte applicatif (droits limités) | frais_app, … |
| JWT_SECRET | Clé de signature des jetons (64 caractères aléatoires) | … |

## Lancer et tester
- `npm run dev` : serveur sur http://localhost:3000, rechargement automatique
- `npm test` : tests unitaires et d'intégration
- `npm run lint` : vérification du style et des erreurs probables

## Structure
routes/ → controllers/ → services/ → repositories/ → MySQL.
Voir docs/architecture.md et docs/adr/ pour les choix techniques.

## Comptes de démonstration
Après `npm run seed` : salarie@sorbier.test et comptable@sorbier.test
(mot de passe dans .env.example, base de développement uniquement).

Chaque section répond à une question précise. Les commandes sont copiables telles quelles. Les variables d'environnement sont toutes listées, avec leur rôle, mais jamais avec leurs vraies valeurs : les secrets restent dans le .env, qui n'est pas versionné.

Commenter le code : JSDoc et PHPDoc

Un bon code se passe de commentaires sur ce qu'il fait : ses noms le disent. Les commentaires servent à deux choses.

Expliquer le pourquoi, ce que le code ne peut pas dire :

// mysql2 renvoie les colonnes DECIMAL sous forme de chaînes (pour ne pas perdre
// de précision) : on convertit, et on calcule en centimes pour éviter les erreurs
// d'arrondi des nombres à virgule (ticket #231).

Documenter le contrat des fonctions publiques avec un docblock : ce qu'elle attend, ce qu'elle renvoie, les erreurs qu'elle peut lever. En JavaScript, le format standard est JSDoc :

/**
 * Calcule le total d'une note de frais.
 *
 * @param {Array<{montant: string|number}>} [lignes=[]] Les lignes de la note ; les montants
 *   peuvent arriver en texte depuis la base.
 * @returns {number} Le total en euros, arrondi au centime.
 * @throws {TypeError} Si un montant n'est pas un nombre lisible (par exemple "12,50").
 */
function totalNote(lignes = []) {
  // …
}

En PHP, le format PHPDoc suit la même logique. Il complète les types natifs de PHP quand ils ne suffisent pas, par exemple pour décrire le contenu d'un tableau :

<?php
/**
 * Kilométrage moyen parcouru par réservation.
 *
 * @param list<array{km_depart: int, km_retour: int}> $reservations
 * @return float|null La moyenne en kilomètres, ou null s'il n'y a aucune réservation.
 */
public function kmMoyen(array $reservations): ?float
{
    // …
}

Ces docblocks ne sont pas que de la décoration. VS Code les affiche au survol de chaque appel de la fonction ; les outils d'analyse statique comme PHPStan, ou TypeScript en mode checkJs, s'en servent pour vérifier les appels ; et des générateurs (JSDoc, phpDocumentor) en tirent une documentation en HTML.

Documenter une API

Les applications qui appellent ton API (le front React, une application mobile, le logiciel comptable) ont besoin d'un contrat précis. Le standard est OpenAPI : un fichier YAML ou JSON qui décrit chaque route, et dont des outils comme Swagger UI ou Redoc tirent une documentation interactive.

# docs/openapi.yaml (extrait)
openapi: 3.1.0
info:
  title: Sorbier Frais API
  version: 1.5.0
paths:
  /api/lignes/{id}/refus:
    patch:
      summary: Refuser une ligne de frais (comptable uniquement)
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: integer }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [motif]
              properties:
                motif: { type: string, minLength: 10, maxLength: 255 }
      responses:
        '204': { description: Ligne refusée }
        '401': { description: Jeton absent ou invalide }
        '403': { description: L'utilisateur n'est pas comptable }
        '404': { description: Ligne introuvable }
        '422': { description: Motif absent, trop court ou trop long }

Le fichier est versionné avec le code et porte le numéro de version de l'API. À chaque évolution de l'API, il est mis à jour dans la même pull request. Pour un petit projet, un tableau Markdown par route (méthode, URL, paramètres, réponses, droits) fait aussi l'affaire, à condition d'être tenu à jour.

Garder la trace des décisions : l'ADR

Dans deux ans, quelqu'un se demandera pourquoi les montants sont calculés en centimes, ou pourquoi l'équipe n'a pas activé l'option decimalNumbers de mysql2. L'historique Git dit ce qui a changé, rarement pourquoi on a choisi cette solution plutôt qu'une autre. L'ADR (Architecture Decision Record, enregistrement de décision d'architecture) répond à cette question : un court fichier Markdown par décision importante, rangé dans docs/adr/ et numéroté.

# ADR 004 — Calculer les montants en centimes

- Date : 2026-11-03
- Statut : acceptée

## Contexte
Le pilote mysql2 renvoie les colonnes DECIMAL en texte. Le calcul des totaux
en JavaScript a produit des concaténations (ticket #231) et des écarts d'un
centime dus aux nombres à virgule.

## Options étudiées
1. Activer `decimalNumbers` dans mysql2 : simple, mais change le type de toutes
   les colonnes DECIMAL de l'application d'un coup.
2. Convertir chaque montant et calculer en centimes entiers dans les services.

## Décision
Option 2. Les services convertissent avec `enCentimes()` et ne divisent par 100
qu'au moment de renvoyer le résultat.

## Conséquences
- Tout nouveau calcul de montant passe par `enCentimes()`.
- L'option 1 pourra être réévaluée lors de la prochaine version majeure.

Un ADR ne se modifie pas une fois accepté : si la décision change, on écrit un nouvel ADR qui remplace l'ancien, et l'on passe le statut de l'ancien à « remplacée par l'ADR 009 ». L'historique des raisonnements reste lisible.

Le dictionnaire de données et les schémas

Chaque migration de base doit se retrouver dans le schéma et dans le dictionnaire de données. Après l'évolution #250 :

Les diagrammes (MCD, diagramme de classes, diagramme de séquence) se mettent à jour de la même façon. Pour qu'ils suivent le code sans effort, beaucoup d'équipes les écrivent en texte, avec un outil comme Mermaid : le diagramme est un bloc de texte dans un fichier Markdown, que GitHub ou GitLab affichent sous forme de dessin, et qui se relit et se versionne comme du code.

La documentation d'utilisation

Le guide d'utilisation s'adresse à quelqu'un qui veut accomplir une tâche, pas comprendre le logiciel. Quelques principes :

• Organiser par tâches : « Refuser une ligne de frais », « Corriger une note refusée », plutôt que par écrans ou par menus.
• Parler la langue de l'utilisateur : « note de frais », « justificatif », pas « entité », « endpoint » ou « statut refusee ».
• Numéroter les étapes, une action par étape, avec une capture d'écran quand elle aide.
• Dire ce qui se passe ensuite : « Le salarié voit le motif dans sa note. La ligne n'est pas remboursée. »
• Tenir compte de l'accessibilité : du texte pour chaque information portée par une image, des contrastes suffisants.

Après une correction, pense aussi à la base de connaissances du support : le contournement « ouvrez la note en PDF pour voir le bon total », publié pendant le bug #231, doit disparaître une fois la version corrective livrée. Le cours ITIL et support montre comment rédiger un article utile.

Exercices

function estHorsDelai(mois, dateCloture) {
  if (dateCloture === null) return false;
  return dateCloture.slice(0, 10) > dateLimiteCloture(mois);
}

/**
 * Indique si une note a été clôturée après la date limite (le 10 du mois suivant).
 *
 * @param {string} mois Le mois de la note, au format 'AAAA-MM'.
 * @param {string|null} dateCloture La date de clôture, au format 'AAAA-MM-JJ'
 *   (une heure éventuelle est ignorée), ou null si la note n'est pas clôturée.
 * @returns {boolean} true si la note a été clôturée après la date limite ;
 *   false si elle l'a été à temps ou si elle n'est pas encore clôturée.
 */

# ADR 007 — Destination des réservations en texte libre

- Date : 2026-11-20
- Statut : acceptée

## Contexte
Le responsable du parc veut connaître la destination de chaque réservation
(évolution #270). Les destinations sont souvent des clients précis.

## Options étudiées
1. Une table `ville` et une liste déroulante : données homogènes, statistiques
   par ville faciles, mais une liste à créer et à maintenir.
2. Une colonne `destination VARCHAR(100)` en texte libre : simple, souple.

## Décision
Option 2, à la demande du responsable du parc, qui ne souhaite pas gérer de liste.

## Conséquences
- Les statistiques par ville ne seront pas fiables (orthographes variées).
- Si ce besoin apparaît, une évolution pourra ajouter une ville normalisée
  à côté du texte libre, sans perte de données.

## Installation
Installer les dépendances et lancer le projet. La base est sur le serveur de prod
(mdp : Sorbier2024!). Il faut aussi configurer quelques variables.