Checklist documentation après développement

:::danger Règle non négociable Toute tâche de développement est incomplète tant que la documentation n'a pas été mise à jour. Cette règle s'applique aux développeurs humains et aux agents IA (Claude Code, Cursor, Codex…). :::

L'objectif est qu'une personne ne connaissant pas le projet puisse comprendre ce qui a été mis en place en lisant uniquement cette documentation.

---

Tableau de correspondance développement → documentation

Ce qui a changé dans le code	Document(s) à mettre à jour
Nouveau module	docs/modules/<module>.md (créer) · docs/intro.md · docs/architecture/overview.md
Nouveau service	Doc du module concerné — section "Services"
Nouveau modèle Eloquent	Doc du module — section "Modèles" + table DB
Nouvelle migration / table	docs/database/schema-conventions.md
Nouveau endpoint API v1	docs/modules/api.md
Nouveau endpoint ThaliaBridge v2	docs/modules/thalia-bridge.md
Nouvelle commande Artisan	Doc du module + docs/deployment/procedures.md si opérationnelle
Nouveau scheduler	Doc du module — section "Tâches planifiées"
Nouvelle permission / rôle	docs/security/authorization.md
Changement d'authentification	docs/security/authentication.md
Nouveau pattern de code	docs/conventions/ ou docs/architecture/ selon portée
Nouvelle procédure de déploiement	docs/deployment/
Nouveau workflow Thalia	docs/thalia/
Nouveau widget Dashboard	docs/modules/dashboard.md
Changement de design/layout	docs/design/

---

Checklist à cocher après chaque développement

Code

• Contrôleurs minces (pas de logique métier)
• Form Request pour toute entrée externe
• Policy ou Gate pour toute action sensible
• Service pour la logique métier
• try/catch + log pour les workflows critiques
• Transactions pour les écritures multi-étapes
• Soft delete si entité historique
• Clés étrangères au format id_*
• Valeurs sensibles avec cast encrypted

Documentation

• Doc du ou des modules impactés mise à jour
• Nouveau module ? → docs/intro.md + docs/architecture/overview.md mis à jour
• Nouvelles tables ? → docs/database/schema-conventions.md mis à jour
• Nouveaux endpoints ? → docs/modules/api.md ou docs/modules/thalia-bridge.md mis à jour
• Nouvelles commandes / schedulers ? → documentés dans le doc du module
• Nouvelles conventions introduites ? → docs/conventions/ mis à jour
• Build Docusaurus vérifié sans erreur : npm run build dans /opt/git/intranet-docs/

---

Niveau de détail attendu

Chaque doc de module doit couvrir :

1. Rôle — À quoi sert ce module ? Quel problème résout-il ?
2. Architecture — Arborescence des fichiers clés
3. Modèles — Tables, colonnes importantes, relations
4. Services — Nom du service + ce qu'il fait
5. Routes — Sous-domaine, préfixe, routes principales
6. Commandes Artisan — Si applicable
7. Configuration — Variables .env requises, clés Application->settings
8. Sécurité — Middleware, policies, permissions requises
9. Cas particuliers — Règles métier non évidentes, contraintes cachées

---

Commit de documentation

Un commit de documentation accompagne chaque commit fonctionnel, ou peut être groupé en fin de feature :

git add docs/modules/mon-module.md docs/intro.md
git commit -m "docs(mon-module): documenter service X et endpoints Y"

Convention de préfixe : docs(<périmètre>): <description>

---

Vérifier que la doc est à jour

# Build complet — détecte les liens cassés et les erreurs
cd /opt/git/intranet-docs && npm run build

# Démarrer en local pour vérifier visuellement
npm run start

Le site est accessible sur http://docs-intranet.tarbouriech.tech en production.