APAJH — Documentation

Apparence

Documentation APAJH ​

Documentation du produit, en français. Elle est maintenue avec le code : une modification de comportement met à jour sa page dans la même pull request, selon la table de routage d'AGENTS.md.

Pour faire tourner la stack, la développer ou la déployer, voir plutôt README.md à la racine.

Elle se lit de trois façons, qui montrent le même contenu : dans ce dépôt, sur GitHub, et sur le portail que la plateforme sert elle-même sur son propre nom d'hôte (DOCS_HOST) — avec une recherche en français et les diagrammes rendus. Le portail est déployé par le même mécanisme que le code : il n'y a pas de seconde chaîne de publication où la documentation pourrait prendre du retard.

Les documents ​

  • Modèle de données — ce que l'application enregistre, table par table, avec le libellé métier de chaque colonne, les valeurs autorisées et les règles en base. Pour un analyste fonctionnel ou une reprise de données.
  • Bibliothèques et services — dépendances directes du backend et du frontend, versions réellement installées, licences, et le rôle de chacune dans le projet. Plus les services et images tierces de la stack.
  • Changelog — ce qui est parti sur l'environnement de développement, une section par version déployée. Les versions sont les tags posés automatiquement à chaque mise en ligne : il n'y a pas de numéro à incrémenter à la main.
  • Recette — comment vérifier qu'un ticket a été livré comme demandé : un chapitre par écran, des scénarios numérotés reliés à leur ticket, et deux annexes générées — la traçabilité par ticket et l'inventaire de ce que les tests prouvent déjà.
  • Guide d'administration — piloter le back-office : référentiel organisationnel, salariés et contrats, comptes et rôles, jours fériés, compteurs. Une page par domaine, plus une annexe générée qui liste les colonnes, filtres et droits de chaque écran.
  • DAT — document d'architecture technique — l'architecture de la plateforme pour un lecteur extérieur : contexte et périmètre, domaines métier, découpage applicatif, la stack et ses douze services, sécurité, exploitation. Sept sections numérotées, dont une annexe générée.

Documents générés ​

Sept documents sont produits à partir du code, de l'historique et des suites de tests, et portent un en-tête qui le dit : le modèle de données, les dépendances, le changelog, les deux annexes de la recette (par-ticket.md, couverture-automatisee.md), la référence des écrans du back-office (administration/reference-ecrans.md) et les annexes du DAT (dat/07-annexes.md). Ils ne se modifient pas à la main : la génération suivante écrase la retouche.

bash
make docs         # régénère les documents dérivés
make docs-check   # + échoue sur une dérive ou un invariant cassé (ce que fait la CI)
make docs-serve   # lit le portail en local, avec rechargement (http://localhost:5175)

make docs-check verrouille à l'octet ce qui ne dépend que du dépôt — le modèle de données, la couverture automatisée, la référence des écrans et les annexes du DAT : oublier de régénérer casse la construction. Les autres bougent sans que personne n'ait touché au dépôt : un correctif publié en amont change une version de dépendance, un déploiement ajoute une section au changelog et remplit la colonne « Livré dans ». Les verrouiller ferait échouer la CI sur le calendrier, alors ce sont des invariants qui les tiennent.

Pour changer ce qu'un document généré raconte, il faut changer ce qu'il lit — un verbose_name dans un modèle, un rôle dans scripts/docs/roles-fr.json — ou son moteur de rendu dans scripts/docs/render/. Les règles de rédaction sont dans references/documentation.md.