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

10_backend_patterns_valides.md

@@ -8,7 +8,7 @@ Ce fichier contient **uniquement** des patterns back-end :
 
 Objectif : éviter de réinventer la roue et réduire le temps de debug.
 
-Dernière mise à jour : 09-03-2026
+Dernière mise à jour : 10-03-2026
 
 ---
 
@@ -27,6 +27,10 @@ Dernière mise à jour : 09-03-2026
 - [Stripe — metadata sur `subscription_data`, pas sur la Session](#pattern-stripe-subscription-metadata)
 - [Webhooks entrants — parsing unique (single constructWebhookEvent)](#pattern-webhook-parsing-unique)
 - [Contracts-First — error codes comme contrat obligatoire](#pattern-contracts-error-codes)
+- [RedisHealthService avec cache interne court](#pattern-redis-health-cache-court)
+- [Sémantique explicite `Trial` vs `Paid` dans Subscription](#pattern-subscription-trial-vs-paid)
+- [Restauration d’achats Stripe en 3 étapes](#pattern-restauration-achats-stripe)
+- [Mapping explicite de `P2002` Prisma sur update de champ unique](#pattern-prisma-p2002-update-unique)
 
 ---
 
@@ -558,6 +562,132 @@ handlePackWebhookEvent(event): PackWebhookResult | null
 
 ---
 
+<a id="pattern-redis-health-cache-court"></a>
+## Pattern : RedisHealthService avec cache interne court
+
+- Objectif : exposer un état Redis exploitable par les guards globaux sans ping Redis à chaque requête.
+- Contexte : backend Node/NestJS avec Redis consulté dans le chemin de décision d’écriture.
+- Quand l’utiliser : quand plusieurs requêtes concurrentes doivent consulter l’état Redis.
+- Quand l’éviter : si Redis n’est pas consulté dans le chemin request/response.
+- Avantage :
+  - réduit fortement le flood de `PING`
+  - garde un signal d’état suffisamment frais
+- Limites / vigilance :
+  - la fenêtre de cache doit rester courte
+  - l’état initial doit être explicite et assumé
+- Validé le : 10-03-2026
+- Contexte technique : NestJS / Redis
+
+### Implémentation (exemple minimal)
+
+```txt
+- Mémoriser lastStatus et lastCheck
+- Si le dernier check a moins de 5s, retourner l’état en cache
+- Sinon exécuter un vrai PING et mettre le cache à jour
+- Utiliser un état initial optimiste (`up`) si le produit ne doit pas bloquer les écritures au boot
+```
+
+### Checklist
+
+- Cache court documenté
+- Pas de ping Redis à chaque requête
+- Comportement initial explicite
+
+---
+
+<a id="pattern-subscription-trial-vs-paid"></a>
+## Pattern : Sémantique explicite `Trial` vs `Paid` dans Subscription
+
+- Objectif : aligner le modèle métier, les guards et les jeux de tests sur une définition unique de l’abonnement payant actif.
+- Contexte : modèle `Subscription` où `trialEndsAt` matérialise un essai.
+- Quand l’utiliser : dès qu’un même enregistrement supporte trial et abonnement payant.
+- Quand l’éviter : si trial et abonnement payant sont modélisés par des entités distinctes.
+- Avantage :
+  - évite les incohérences silencieuses dans les guards
+  - rend les fixtures et mocks e2e cohérents avec la règle métier
+- Limites / vigilance :
+  - toute logique `isActive` doit préciser si elle signifie “trial ou paid” ou “paid only”
+- Validé le : 10-03-2026
+- Contexte technique : Backend agnostique / modèle d’abonnement
+
+### Implémentation (exemple minimal)
+
+```txt
+- Un abonnement payant actif n’est pas seulement status = ACTIVE
+- Il doit aussi avoir trialEndsAt = null
+- Les fixtures et mocks e2e d’un abonnement payant fixent toujours trialEndsAt: null
+```
+
+### Checklist
+
+- Règle métier explicitée
+- Guards alignés sur la sémantique choisie
+- Fixtures et seeds cohérents
+
+---
+
+<a id="pattern-restauration-achats-stripe"></a>
+## Pattern : restauration d’achats Stripe en 3 étapes
+
+- Objectif : reconstruire un état local cohérent à partir de Stripe sans dépendre d’une hypothèse fragile.
+- Contexte : flux de restore purchases mobile/web avec état local potentiellement désynchronisé.
+- Quand l’utiliser : dès qu’un utilisateur peut restaurer des achats depuis un nouveau device ou après désynchronisation.
+- Quand l’éviter : si l’état Stripe n’est pas la source de vérité.
+- Avantage :
+  - rend la réconciliation explicite
+  - supporte retries et restaurations tardives
+- Limites / vigilance :
+  - la pagination Stripe et l’idempotence d’écriture restent obligatoires
+- Validé le : 10-03-2026
+- Contexte technique : Stripe API / backend Node/NestJS
+
+### Implémentation (exemple minimal)
+
+```txt
+1. Résolution du customer Stripe (ID persisté en DB, fallback robuste si absent)
+2. Reconstruction de l’état Stripe utile au domaine
+3. Réconciliation et écritures locales idempotentes
+```
+
+### Checklist
+
+- `stripeCustomerId` persistant côté app
+- Réconciliation explicite documentée
+- Upsert ou écriture idempotente
+
+---
+
+<a id="pattern-prisma-p2002-update-unique"></a>
+## Pattern : mapping explicite de `P2002` Prisma sur update de champ unique
+
+- Objectif : transformer un conflit d’unicité prévisible en erreur métier exploitable plutôt qu’en 500 opaque.
+- Contexte : `update` Prisma sur un champ `@unique` alimenté par une source externe ou concurrente.
+- Quand l’utiliser : dès qu’un champ unique peut être mis à jour après création.
+- Quand l’éviter : jamais si le champ peut réellement entrer en collision.
+- Avantage :
+  - réponse client stable
+  - diagnostic métier plus rapide
+- Limites / vigilance :
+  - le mapping doit rester cohérent avec le format d’erreur API standardisé
+- Validé le : 10-03-2026
+- Contexte technique : Prisma / PostgreSQL / NestJS
+
+### Implémentation (exemple minimal)
+
+```txt
+- Catch explicite de PrismaClientKnownRequestError code P2002
+- Mapping vers une erreur métier stable
+- Conserver requestId et format d’erreur standardisé
+```
+
+### Checklist
+
+- `P2002` intercepté sur les updates sensibles
+- Code d’erreur métier stable
+- Pas de 500 générique sur conflit prévisible
+
+---
+
 ### Notes importantes
 
 - On préfère 5 patterns solides à 50 “bons conseils”.