# Backend — Patterns validés — Index

Patterns backend testés et validés en conditions réelles.

Avant toute proposition backend, identifie le fichier dont le nom et la description matchent le domaine traité, puis lis-le.

---

| Fichier | Domaine | Entrées clés |
|---------|---------|--------------|
| `auth.md` | Auth, sessions, tokens, erreurs API, corrélation | Format erreur standardisé, middleware requestId, anti-énumération, token usage unique, autorisation interne, opérations atomiques, jose whitelist algo, membrane BFF fédérée (jonction unique, session stateless JWE, pont d'identité idpSub, refresh 100% serveur), cutover irréversible, token opaque quick-link, RBAC dérivé JWT enrichi, 403 vs 404 oracle d'existence |
| `contracts.md` | Contrats API, Zod, error codes, HTTP sémantique | Contracts-First/Zod-Infer/No-DTO, error codes comme contrat, HTTP 200 payload métier, idempotence POST = retour ressource existante, typer strict à la source, prop audience templates mail/PDF, verbe HTTP marker idempotent, endpoint distinct vs paramètre force, Zod .optional() honnête |
| `prisma.md` | Prisma, DB, migrations, pagination | Soft delete, pagination cursor, idempotency key, P2002 unique, Decimal sérialisation, migration manuelle P3014 (+ réalignement DB dev), filtrage métier dans service, colonnes plates vs table dédiée, étape dérivée source unique, row réactivable, endpoint replace atomique, bascule idempotente updateMany, pagination relation N-N (some), $queryRawUnsafe en façade, token usage-unique condition WHERE, FK + snapshot label dérivé, migration String/Int → enum (backfill + sans downtime), util crypto transverse |
| `stripe.md` | Stripe, paiements, webhooks entrants, subscriptions | Provider-Strategy, metadata subscription_data, parsing webhook unique, restauration achats, Trial vs Paid, prix en base → price_data inline |
| `nestjs.md` | NestJS, guards, Redis, quotas | Guard global APP_GUARD, RedisHealthService cache court, quota INCR+EXPIREAT atomique, ressource paire non ordonnée (clé canonique), batched eligibility (anti N+1 .map async), providers externes via injection par token, e2e DB-based NestJS + Prisma v7 |
| `multi-tenant.md` | Multi-tenant, isolation, feature flags | 403 vs 404, repository tenant-aware, tenantId dans updates, helper tenant partagé, feature flag tenant, EN enforcement |
| `nextjs.md` | Next.js App Router, Server Actions, isolation | Runtime-only logique pure, server-only isolation, utilitaires purs sans server-only, réutiliser champ V1, validation URL externe |
| `async.md` | Jobs async, webhooks sortants, queues | Exécution asynchrone outbox light, webhooks sortants HMAC + retries idempotents, hooks fire-and-forget après création DB, fanout notification avec filtre grade, auto-purge fenêtre temporelle SQL, test de rollback pipeline multi-fichiers atomique, Promise.all queries DB indépendantes, cron multi-instance lock Redis SET NX EX, verrou une-action-par-entité updateMany, persist-then-send (effet de bord à statut persistant) |
| `general.md` | Architecture générale, helpers, RBAC | Helper auth centralisé enrichissable, ordre canonique des gates HTTP, délégation agrégat → endpoint agrégé, anti-énumération DELETE 204, lazy init memoizé, cap LRU par-user, convention dot-notation audit, whitelist explicite audit, singleton DB config, invalidation cache avant mutation, pipeline CI/CD GitHub Actions → VPS, contrôle d'accès conditionnel pure logic shared, safe path resolution anti-traversal, alias d'import @/* migration en masse, test d'invariant de structure (scan statique), script ops batch fail-closed, helper transverse paramétrable (sendMailWithRetry) |
| `tests.md` | Tests d'intégration DB, isolation, atomicité | `cleanup.track()` LIFO, `globalSetup` purge, template database Postgres, helper `waitForX()` polling-borné (+ vérif absence side-effect), test d'atomicité transaction, convention `describe()` 2 niveaux, refactor itératif d'un fichier monolithe, DI testable via hooks module-level `__setXForTests`, e2e DB-based NestJS + Prisma v7 (Jest/swc) |
| `llm-providers.md` | Fournisseurs LLM, auth, coûts | OAuth consumer ≠ API key, prompt caching system prompt stable, budget cap fournisseur |