Audit des routes API Laravel

Objectif

Éviter les divergences entre les routes Laravel réellement exposées et la documentation API du Master Book.

Ce document décrit la méthode d’audit. Il ne prétend pas que l’audit a été exécuté tant que les commandes php artisan route:list n’ont pas été lancées et que leurs sorties n’ont pas été comparées.

Structure Laravel à vérifier

Le backend Laravel se trouve dans le dossier api/.

Fichiers et dossiers importants :

• api/artisan : commande Laravel CLI.
• api/routes/api.php : routes API racine.
• api/app/Modules/*/Routes/api.php : routes API modulaires.
• api/bootstrap/providers.php : déclaration des providers modulaires.
• api/app/Http/Middleware/IdentifyApp.php : middleware X-App-Source.

Commandes d’audit

Depuis la racine du projet :

cd api
php artisan route:list
php artisan route:list --path=api/v1
php artisan route:list --path=api/v1 --columns=method,uri,name,action,middleware
php artisan route:list --json > ../docs/07-backend/api/route-list.snapshot.json

Colonnes à vérifier

Colonne	Pourquoi la vérifier
method	Vérifie le verbe HTTP documenté : GET, POST, PATCH, DELETE.
uri	Vérifie le chemin réel exposé.
name	Permet de repérer les routes nommées et conventions internes.
action	Relie la route au contrôleur Laravel.
middleware	Vérifie auth, RBAC, identify.app, device.token, ensure.admin.

Méthode de comparaison doc ↔ code

1. Générer la liste réelle des routes.
2. Ouvrir les fichiers docs/07-backend/api/*.md.
3. Pour chaque domaine API, comparer :
   • verbe HTTP ;
   • URI ;
   • middleware ;
   • portée publique/protégée/admin ;
   • statut : confirmé, cible, obsolète.
4. Marquer toute divergence dans un rapport court.
5. Mettre à jour la documentation ou créer un ticket si le code doit changer.

Statuts des routes

Statut	Définition	Action documentaire
Confirmée	Présente dans route:list ou dans les fichiers routes Laravel.	Documenter dans “Endpoints confirmés”.
Cible	Non présente dans le code, mais souhaitée pour l’architecture.	Documenter explicitement comme “proposée” ou “cible”.
Obsolète	Documentée mais absente du code et non souhaitée.	Retirer ou déplacer dans une section historique.
À confirmer	Présente indirectement, ambiguë ou dépendante d’un provider.	Ajouter un point à confirmer.

Gestion des divergences

Cas	Décision
Route présente dans le code mais absente de la doc	Ajouter ou compléter le fichier API concerné.
Route documentée comme confirmée mais absente du code	Reclasser en cible ou supprimer de la section confirmée.
Middleware différent	Priorité à la sécurité : vérifier le code, puis corriger doc ou implémentation.
URL ambiguë	Confirmer avec route:list, pas uniquement avec les commentaires.
Route sensible non auditée	Ajouter un point de contrôle sécurité et RBAC.

Règles de sécurité à contrôler

• X-App-Source doit être présent là où identify.app est attendu.
• Les routes admin doivent avoir auth:sanctum et ensure.admin.
• Les routes mairie protégées doivent avoir mairie.access.
• Les routes AssoSuite membres doivent avoir asso.access.
• Les routes PlayLoop device doivent utiliser device.token.
• Les webhooks ne doivent pas dépendre de auth:sanctum mais d’une signature provider.
• L’IA ne doit pas accéder directement aux tables ni appeler des routes sensibles sans backend contrôlé.

Livrables attendus après audit

• route-list.snapshot.json généré depuis Laravel.
• Liste des routes confirmées.
• Liste des routes documentées mais absentes du code.
• Liste des routes code non documentées.
• Liste des écarts middleware/RBAC.
• Décisions : documenter, corriger, supprimer, ou ouvrir une question.

Future automatisation CI

Une automatisation CI pourra :

1. lancer php artisan route:list --json ;
2. extraire les routes documentées depuis docs/07-backend/api/*.md ;
3. comparer les routes confirmées avec le snapshot ;
4. échouer si une route confirmée disparaît sans mise à jour documentaire ;
5. publier un rapport en artifact CI.

Cette automatisation doit rester informative au départ, puis devenir bloquante lorsque les contrats API seront stabilisés.