docs: ajoute index+ancres et capitalise app-alexandrie

10_backend_risques_et_vigilance.md

@@ -8,7 +8,7 @@ Ce fichier recense des risques back-end susceptibles de provoquer :
 - régressions coûteuses,
 - incohérences de données.
 
-Dernière mise à jour : 25-01-2026
+Dernière mise à jour : 09-03-2026
 
 ---
 
@@ -22,6 +22,22 @@ Dernière mise à jour : 25-01-2026
 
 ---
 
+## Index
+
+- [AuthN/AuthZ dispersée](#risque-authn-authz-dispersee)
+- [Guard global manquant (request.user)](#risque-guard-global-manquant)
+- [Duplication silencieuse de constantes (contracts)](#risque-duplication-constantes-contracts)
+- [Contrats API implicites](#risque-contrats-api-implicites)
+- [Erreurs non standardisées](#risque-erreurs-non-standardisees)
+- [Migrations risquées / non reproductibles](#risque-migrations-risquees)
+- [Non-idempotence sur opérations sensibles](#risque-non-idempotence)
+- [Stripe : `billing_cycle_anchor` vs `current_period_end`](#risque-stripe-current-period-end)
+- [PostgreSQL/Prisma : `@unique` nullable](#risque-prisma-unique-nullable)
+- [Observabilité insuffisante](#risque-observabilite-insuffisante)
+
+---
+
+<a id="risque-authn-authz-dispersee"></a>
 ## AuthN/AuthZ dispersée (contrôles d’accès au fil de l’eau)
 
 ### Risques
@@ -44,6 +60,52 @@ Dernière mise à jour : 25-01-2026
 
 ---
 
+<a id="risque-guard-global-manquant"></a>
+## Guard global manquant (request.user jamais peuplé)
+
+### Risques
+
+- Chaîne auth bâtie sur une fondation inopérante (tout “a l’air OK” en dev/tests, mais casse en prod)
+- Guards aval qui dépendent de `request.user` en erreur (ou contournements involontaires)
+- Découvert tard (souvent uniquement en code review ou en prod)
+
+### Symptômes
+
+- `request.user` vaut `undefined` dans un guard supposé “après auth”
+- Endpoints qui passent alors qu’ils devraient être refusés (si les guards aval se désactivent/retournent true par défaut)
+- Tests “verts” car trop mockés (pas de test e2e qui valide le pipeline complet)
+
+### Bonnes pratiques / mitigations
+
+- Poser explicitement le guard global dès les foundations (au moins `AuthGuard`)
+- Vérifier l’ordre des `APP_GUARD` (AuthGuard avant tout guard qui lit `request.user`)
+- Ajouter au minimum 1 test d’intégration/e2e qui prouve que `request.user` est bien peuplé sur un endpoint protégé
+
+---
+
+<a id="risque-duplication-constantes-contracts"></a>
+## Duplication silencieuse de constantes partagées (contracts) via fichier orphelin
+
+### Risques
+
+- Deux sources de vérité qui divergent silencieusement (ex : topics officiels, enums métier, slugs)
+- Bug non détecté par TypeScript si la duplication est dans un fichier non importé (code mort)
+
+### Symptômes
+
+- Incohérences entre API et client sur des listes/enums “censées être partagées”
+- “Ça marche chez moi” selon l’endroit où la constante est importée
+- Un fichier de config existe dans `apps/*` mais n’est jamais importé/greffé au runtime
+
+### Bonnes pratiques / mitigations
+
+- Toute constante partagée vit dans `packages/contracts/src/` et est importée depuis là (jamais recopiée dans `apps/*`)
+- En review : repérer les fichiers “config/constants” ajoutés dans `apps/*` sur des domaines déjà couverts par `contracts`
+- (Optionnel) Outillage : intégrer une étape de détection de code mort / exports inutilisés au CI si ça devient récurrent
+
+---
+
+<a id="risque-contrats-api-implicites"></a>
 ## Contrats API implicites (validation faible ou absente)
 
 ### Risques
@@ -65,6 +127,7 @@ Dernière mise à jour : 25-01-2026
 
 ---
 
+<a id="risque-erreurs-non-standardisees"></a>
 ## Erreurs non standardisées (4xx/5xx incohérents)
 
 ### Risques
@@ -86,6 +149,7 @@ Dernière mise à jour : 25-01-2026
 
 ---
 
+<a id="risque-migrations-risquees"></a>
 ## Migrations risquées / non reproductibles
 
 ### Risques
@@ -108,6 +172,7 @@ Dernière mise à jour : 25-01-2026
 
 ---
 
+<a id="risque-non-idempotence"></a>
 ## Non-idempotence sur opérations sensibles
 
 ### Risques
@@ -129,6 +194,48 @@ Dernière mise à jour : 25-01-2026
 
 ---
 
+<a id="risque-stripe-current-period-end"></a>
+## Stripe (v17+) : confusion `billing_cycle_anchor` vs `current_period_end`
+
+### Risques
+
+- Stocker une date de fin de période incorrecte en DB (bug silencieux)
+- État d’abonnement incohérent (UI, relances, accès premium)
+
+### Symptômes
+
+- `currentPeriodEnd` correspond à une date “bizarre” (souvent proche de la création), ou à un jour du mois
+- Des accès premium expirent trop tôt / trop tard
+
+### Bonnes pratiques / mitigations
+
+- Ne jamais interpréter `billing_cycle_anchor` comme une date de fin de période
+- Utiliser `subscription.current_period_end` (timestamp) pour la fin de période courante
+- Ajouter un test sur un événement webhook/Subscription qui vérifie la date persistée
+
+---
+
+<a id="risque-prisma-unique-nullable"></a>
+## PostgreSQL / Prisma : `@unique` sur champ nullable (idempotence cassée)
+
+### Risques
+
+- Doublons en base malgré un “unique” attendu (PostgreSQL autorise plusieurs `NULL` dans un index UNIQUE)
+- Upserts non idempotents si la clé peut être `null` (`where: { externalId: null }` crée plusieurs lignes)
+
+### Symptômes
+
+- Plusieurs enregistrements “équivalents” avec `externalId = NULL`
+- Rejouer un webhook / retry réseau crée une nouvelle ligne au lieu d’upsert
+
+### Bonnes pratiques / mitigations
+
+- Toute clé utilisée dans un `where` d’`upsert` doit être **non-nullable**
+- Si un identifiant externe peut légitimement être `null`, ne pas l’utiliser comme clé d’idempotence : choisir une autre clé unique non-nullable
+
+---
+
+<a id="risque-observabilite-insuffisante"></a>
 ## Observabilité insuffisante (logs non structurés, pas de corrélation)
 
 ### Risques