docs: ajoute index+ancres et capitalise app-alexandrie

40_decisions_et_archi.md

@@ -8,7 +8,96 @@ Objectifs :
 - éviter de reposer les mêmes questions
 - assumer les compromis
 
-Dernière mise à jour : 2025-12-19
+Dernière mise à jour : 2026-03-09
+
+---
+
+## Index
+
+- [Story sizing — foundations vs qualité non bloquante](#decision-story-sizing-foundations)
+- [Code review adversariale — contexte frais](#decision-code-review-adversariale)
+- [Workflows n8n complexes = mini-systèmes](#decision-n8n-mini-systemes)
+- [Le front-end est un logiciel en production](#decision-frontend-production)
+- [Le back-end est un logiciel en production](#decision-backend-production)
+- [Contrats d’API explicites et versionnés](#decision-contrats-api)
+- [Gestion standard des erreurs et des statuts HTTP](#decision-erreurs-http)
+- [Migrations et évolution de schéma maîtrisées](#decision-migrations)
+- [Observabilité minimale obligatoire](#decision-observabilite)
+- [Authentification et autorisation centrales](#decision-auth-central)
+- [Idempotence et gestion des retries](#decision-idempotence-retries)
+- [Structure Docker et données persistantes](#decision-structure-docker)
+
+---
+
+<a id="decision-story-sizing-foundations"></a>
+## Story sizing — foundations bloquantes vs qualité non bloquante (CI mobile)
+
+- Date : 2026-03-09
+- Statut : Accepted
+- Périmètre : global
+
+### Contexte
+
+Des items “infra” ont été mis dans des stories foundations d’epic alors qu’aucune story métier suivante n’en dépendait (ex : CI Maestro mobile iOS/Android).
+Résultat observé : story foundations “never-done”, friction et coût de contexte, sans bénéfice sur le throughput métier.
+
+### Options envisagées
+
+- Mettre toutes les améliorations de qualité dans foundations “par principe”
+- Séparer les prérequis réellement bloquants du reste (qualité non bloquante)
+
+### Décision
+
+On distingue explicitement :
+
+- **Prérequis bloquants** : à inclure dans foundations (les stories suivantes en dépendent)
+- **Qualité non bloquante** : story indépendante, en parallèle ou après, sans bloquer le métier
+
+### Justification
+
+- Un epic doit pouvoir avancer sur le métier dès que les dépendances techniques minimales sont là
+- Les chantiers “qualité” (CI mobile, perf, audits…) ont souvent une inertie qui ne doit pas geler l’epic
+
+### Conséquences
+
+- Pour chaque AC “infra” en foundations : poser la question “la story X+1 est-elle bloquée si ce n’est pas fait ?”
+- Si la réponse est non : sortir l’AC en story dédiée (tag qualité / infra), et la planifier à part
+
+---
+
+<a id="decision-code-review-adversariale"></a>
+## Code review adversariale — passe dédiée en contexte frais
+
+- Date : 2026-03-09
+- Statut : Accepted
+- Périmètre : global
+
+### Contexte
+
+Certaines issues CRITICAL sont invisibles dans le contexte d’implémentation (biais de confirmation : “je sais comment c’est censé marcher”).
+Elles émergent uniquement en lecture froide : fondations manquantes, usages dépréciés, invariants non respectés (ex : sessions sans TTL).
+
+### Options envisagées
+
+- Review “au fil de l’eau” dans le même contexte que l’implémentation
+- Review dédiée, séparée, en contexte frais (nouvelle session / nouveau modèle / reviewer différent)
+
+### Décision
+
+La code review doit être une passe **séparée** de l’implémentation, en **contexte frais**, avec un objectif explicite : chercher des CRITICAL sans concession.
+
+### Justification
+
+- Les incohérences systémiques (sécurité, idempotence, TTL, drift de contracts) se détectent mieux en lecture froide
+- Réduit fortement le coût de debug tardif (prod/staging) et les refactors “de fondations”
+
+### Conséquences
+
+- Process recommandé :
+  1. Dev termine l’implémentation, marque la story `review`
+  2. Nouvelle session (contexte frais) : charger uniquement story + diff
+  3. Review adversariale : lister CRITICAL + mitigations
+  4. Corriger avant `done`
 
 ---
 
@@ -32,6 +121,7 @@ Dernière mise à jour : 2025-12-19
 
 ---
 
+<a id="decision-n8n-mini-systemes"></a>
 ## Workflows n8n complexes = mini-systèmes
 
 - Date : 2025-12-19
@@ -67,6 +157,7 @@ Les considérer comme du code.
 
 ---
 
+<a id="decision-frontend-production"></a>
 ## Le front-end est un logiciel en production
 
 - Date : 2026-01-25
@@ -119,6 +210,7 @@ Il est soumis aux mêmes principes que le backend :
 
 ---
 
+<a id="decision-backend-production"></a>
 ## Le back-end est un logiciel en production (qualité, observabilité, sécurité)
 
 - Date : 2026-01-25
@@ -168,6 +260,7 @@ Exigences minimales :
 
 ---
 
+<a id="decision-contrats-api"></a>
 ## Contrats d’API explicites et versionnés
 
 - Date : 2026-01-25
@@ -208,6 +301,7 @@ Minimum attendu :
 
 ---
 
+<a id="decision-erreurs-http"></a>
 ## Gestion standard des erreurs et des statuts HTTP
 
 - Date : 2026-01-25
@@ -247,6 +341,7 @@ Les erreurs HTTP sont standardisées :
 
 ---
 
+<a id="decision-migrations"></a>
 ## Migrations et évolution de schéma maîtrisées
 
 - Date : 2026-01-25
@@ -287,6 +382,7 @@ Principes :
 
 ---
 
+<a id="decision-observabilite"></a>
 ## Observabilité minimale obligatoire (logs, corrélation, signaux)
 
 - Date : 2026-01-25
@@ -326,6 +422,7 @@ Observabilité minimale obligatoire :
 
 ---
 
+<a id="decision-auth-central"></a>
 ## Authentification et autorisation comme responsabilités centrales
 
 - Date : 2026-01-25
@@ -368,6 +465,7 @@ Principes :
 
 ---
 
+<a id="decision-idempotence-retries"></a>
 ## Idempotence et gestion des retries pour les opérations sensibles
 
 - Date : 2026-01-25
@@ -409,6 +507,7 @@ Principes :
 
 ---
 
+<a id="decision-structure-docker"></a>
 ## Convention de structure pour les projets Docker et les données persistantes
 
 - Date : 2026-03-06