ajout contextes agents

10_backend_patterns_valides.md

@@ -300,6 +300,129 @@ Si ce n’est pas confirmé comme fonctionnel et utile, **ça n’a rien à fair
 - Idempotence documentée
 - Logs corrélés (requestId/traceId)
 
+---
+
+## Pattern : Contracts-First / Zod-Infer / No-DTO (monorepo TypeScript fullstack)
+
+- Objectif : avoir une seule source de vérité pour les contrats d’interface entre API et client, sans redéfinition manuelle de types.
+- Contexte : monorepo TypeScript avec un package partagé (`packages/contracts` ou équivalent), consommé par le backend et le front/mobile.
+- Quand l’utiliser : dès qu’une API est consommée par un client TypeScript dans le même repo.
+- Quand l’éviter : si le client est externe (autre organisation, autre langage) — dans ce cas, OpenAPI reste la référence.
+- Avantage :
+  - Zéro drift entre contrat et implémentation
+  - Types TypeScript gratuits via `z.infer<>` — aucune réécriture
+  - Changement de contrat = erreur de compilation immédiate côté client
+  - Mocks de tests alignés automatiquement
+- Limites / vigilance :
+  - Ne pas mettre de logique métier dans `packages/contracts` (IO only)
+  - Attention aux dépendances circulaires si le package grossit
+- Validé le : 07-03-2026
+- Contexte technique : TypeScript / Zod / NestJS + Expo (React Native) — pattern agnostique framework
+
+### Implémentation (exemple minimal)
+
+```typescript
+// packages/contracts/src/auth/auth.schemas.ts
+export const RegisterRequestSchema = z.object({
+  email: z.string().email(),
+  password: z.string().min(8),
+});
+export type RegisterRequest = z.infer<typeof RegisterRequestSchema>; // type GRATUIT
+
+// packages/contracts/src/index.ts
+export * from ‘./auth/auth.schemas’;
+export * from ‘./errors/error-code’;
+
+// apps/api/src/modules/auth/auth.controller.ts
+import type { RegisterRequest } from ‘@monrepo/contracts’;
+// + ZodValidationPipe → validation automatique, zéro DTO manuel
+
+// apps/mobile/src/domains/auth/auth.store.ts
+import type { RegisterRequest } from ‘@monrepo/contracts’;
+// même type, même schéma, zéro duplication
+```
+
+### Structure cible du package contracts
+
+```
+packages/contracts/src/
+  auth/auth.schemas.ts       ← request/response auth
+  users/users.schemas.ts     ← request/response users
+  billing/billing.schemas.ts ← request/response billing (Epic suivant)
+  errors/error-code.ts       ← enum codes d’erreur stables
+  http/envelopes.ts          ← { data, meta } / { error, meta }
+  index.ts                   ← re-export tout
+```
+
+### Ce qui appartient à contracts
+
+- Schémas Zod request/response
+- Types inférés (`z.infer<>`)
+- Codes d’erreur applicatifs stables
+- Enums et constantes partagées (ex : liste officielle de sujets/topics)
+
+### Ce qui n’appartient PAS à contracts
+
+- Logique métier
+- Modules/services/guards framework (NestJS, etc.)
+- State management client (Zustand, Redux, etc.)
+
+### Checklist
+
+- [ ] Zéro DTO manuel dans l’API — uniquement `z.infer<typeof Schema>`
+- [ ] `ZodValidationPipe` global ou par endpoint pour la validation d’entrée
+- [ ] Constantes partagées (enums, listes) dans contracts, jamais dupliquées
+- [ ] Mocks de tests importent les types depuis contracts
+
+---
+
+## Pattern : Guard global NestJS — ordre d’enregistrement et décorateurs de bypass
+
+- Objectif : protéger tous les endpoints par défaut, avec un mécanisme explicite pour les exceptions.
+- Contexte : API NestJS avec plusieurs guards globaux (authn, authz, feature flags...).
+- Quand l’utiliser : dès qu’on a 2+ guards globaux dont l’un dépend du résultat de l’autre.
+- Quand l’éviter : si un seul guard suffit.
+- Avantage :
+  - Sécurité par défaut (opt-out, pas opt-in)
+  - Ordre d’exécution garanti et explicite
+  - Bypass documenté et traçable via décorateurs
+- Limites / vigilance :
+  - L’ordre des `APP_GUARD` dans `providers[]` est l’ordre d’exécution — ne pas inverser
+  - Exporter le service depuis son module si injecté dans un guard global d’un autre module
+- Validé le : 07-03-2026
+- Contexte technique : NestJS v10+
+
+### Implémentation (exemple minimal)
+
+```typescript
+// app.module.ts
+providers: [
+  { provide: APP_GUARD, useClass: AuthGuard },          // 1er : peuple request.user
+  { provide: APP_GUARD, useClass: EmailVerifiedGuard }, // 2ème : lit request.user
+  { provide: APP_GUARD, useClass: EntitlementsGuard },  // 3ème : lit request.user + entitlements
+]
+
+// skip-auth.decorator.ts
+export const SKIP_AUTH = ‘skipAuth’;
+export const SkipAuth = () => SetMetadata(SKIP_AUTH, true);
+
+// auth.guard.ts
+const skip = this.reflector.getAllAndOverride<boolean>(SKIP_AUTH, [
+  context.getHandler(),
+  context.getClass(), // permet @SkipAuth() au niveau classe
+]);
+if (skip) return true;
+```
+
+### Checklist
+
+- [ ] AuthGuard enregistré en premier dans `providers[]`
+- [ ] AuthModule exporte AuthService si AuthGuard est dans AppModule
+- [ ] Décorateur `@SkipAuth()` sur tous les endpoints publics (auth, health, docs)
+- [ ] Tests unitaires sur le guard avec reflector mocké
+
+---
+
 ### Index (à remplir au fil des validations)
 
 - Format d’erreur API standardisé
@@ -309,6 +432,8 @@ Si ce n’est pas confirmé comme fonctionnel et utile, **ça n’a rien à fair
 - Exécution asynchrone des tâches longues (queue + outbox light)
 - Soft delete et archivage explicite
 - Webhooks sortants robustes et idempotents
+- Contracts-First / Zod-Infer / No-DTO (monorepo TypeScript fullstack)
+- Guard global NestJS — ordre d’enregistrement et décorateurs de bypass
 
 ⸻