Capitalise nouveaux patterns backend/frontend/BMAD et externalise les templates du post-install BMAD

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 : 09-03-2026
+Dernière mise à jour : 10-03-2026
 
 ---
 
@@ -39,6 +39,11 @@ Dernière mise à jour : 09-03-2026
 - [Entitlements — TTL cache supérieur au SLA de propagation](#risque-entitlements-ttl-sla)
 - [Guard NestJS route-level — null-check manquant sur `request.user`](#risque-guard-request-user-null)
 - [Compteurs in-memory ≠ métriques persistées](#risque-compteurs-inmemory)
+- [Interface provider incomplète ou divergente de ses implémentations](#risque-interface-provider-incomplete)
+- [Boucle `upsert` N+1 sur synchronisation provider](#risque-upsert-n-plus-un-provider)
+- [Stripe `list()` sans gestion de `has_more`](#risque-stripe-list-has-more)
+- [Concurrence entre activation locale et webhook sur transition trial → payant](#risque-trial-payant-concurrence)
+- [`jest.clearAllMocks()` dans des `beforeEach` imbriqués avec mocks Prisma](#risque-jest-clearallmocks-imbrique)
 
 ---
 
@@ -378,3 +383,123 @@ if (!user?.userId) {
 - V1 low-cost : `Redis INCRBY` best-effort par `eventType` → persisté et agrégé multi-instances
 - Évolutif vers Prometheus/OTel sans changer l'interface (abstraction dès le départ)
 - Contexte technique : Redis / NestJS — 09-03-2026
+
+---
+
+<a id="risque-interface-provider-incomplete"></a>
+## Interface provider incomplète ou divergente de ses implémentations
+
+### Risques
+
+- Une implémentation expose des méthodes non déclarées dans le contrat commun
+- Les appelants contournent l’interface et se couplent à un provider concret
+- Une stratégie provider devient non interchangeable en pratique
+
+### Symptômes
+
+- Appels avec cast ou accès direct à une implémentation spécifique
+- Méthodes présentes dans une classe mais absentes de l’interface
+- Régression lors d’un changement de provider
+
+### Bonnes pratiques / mitigations
+
+- Toute capacité commune attendue par les appelants doit être déclarée dans l’interface
+- Interdire les méthodes “cachées” consommées hors contrat
+- Tester au moins une implémentation par le contrat abstrait
+- Contexte technique : TypeScript / provider strategy — 10-03-2026
+
+---
+
+<a id="risque-upsert-n-plus-un-provider"></a>
+## Boucle `upsert` N+1 sur synchronisation provider
+
+### Risques
+
+- Latence multipliée par le nombre d’items
+- Charge DB inutile
+- Timeouts ou contention sur gros volumes
+
+### Symptômes
+
+- Une boucle applicative exécute un `upsert` par item
+- Temps de traitement qui explose avec le volume
+- Logs SQL répétitifs et séquentiels
+
+### Bonnes pratiques / mitigations
+
+- Batcher quand c’est possible
+- Précharger les données nécessaires avant boucle
+- Mesurer explicitement le coût d’un `upsert` unitaire dans les flux de sync
+- Contexte technique : Prisma / synchronisation provider — 10-03-2026
+
+---
+
+<a id="risque-stripe-list-has-more"></a>
+## Stripe `list()` sans gestion de `has_more`
+
+### Risques
+
+- Pagination tronquée silencieusement
+- Réconciliation incomplète d’abonnements, achats ou moyens de paiement
+- Décisions métier prises sur un jeu de données partiel
+
+### Symptômes
+
+- Comportement correct sur petits comptes mais faux sur comptes plus chargés
+- Premiers éléments traités, les suivants ignorés
+- Absence de boucle de pagination ou d’auto-pagination
+
+### Bonnes pratiques / mitigations
+
+- Traiter explicitement `has_more`
+- Utiliser l’auto-pagination Stripe si adaptée
+- Tester au moins un cas avec plusieurs pages de résultats
+- Contexte technique : Stripe API — 10-03-2026
+
+---
+
+<a id="risque-trial-payant-concurrence"></a>
+## Concurrence entre activation locale et webhook sur transition trial → payant
+
+### Risques
+
+- Double création ou double attachement d’une ressource unique
+- Conflit `P2002`
+- État local différent de l’état Stripe pendant la transition
+
+### Symptômes
+
+- La transition fonctionne parfois, puis échoue aléatoirement
+- Un webhook Stripe et une action applicative écrivent la même mutation métier
+- Erreurs d’unicité lors de l’activation payante
+
+### Bonnes pratiques / mitigations
+
+- Définir une seule source autorisée pour chaque transition d’état
+- Rendre les écritures idempotentes
+- Sérialiser ou réconcilier explicitement les transitions pilotées à la fois par action utilisateur et webhook
+- Contexte technique : Stripe / Prisma / trial subscription — 10-03-2026
+
+---
+
+<a id="risque-jest-clearallmocks-imbrique"></a>
+## `jest.clearAllMocks()` dans des `beforeEach` imbriqués avec mocks Prisma
+
+### Risques
+
+- Remise à zéro d’un setup attendu par un scope de test plus profond
+- Tests verts ou rouges pour de mauvaises raisons
+- Forte difficulté à comprendre l’état réel des mocks
+
+### Symptômes
+
+- Comportement différent selon l’ordre ou le niveau d’imbrication des `describe`
+- Mocks Prisma “perdus” entre deux tests
+- Corrections locales qui cassent d’autres blocs de tests
+
+### Bonnes pratiques / mitigations
+
+- Centraliser la stratégie de reset des mocks
+- Éviter les `clearAllMocks()` concurrents à plusieurs niveaux de nesting
+- Préférer un setup explicite et local par scénario quand les mocks Prisma sont structurants
+- Contexte technique : Jest / Prisma / tests NestJS — 10-03-2026