Integrate Next.js runtime-only backend pattern

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 : 16-03-2026
+Dernière mise à jour : 19-03-2026
 
 ---
 
@@ -34,6 +34,7 @@ Dernière mise à jour : 16-03-2026
 - [Autorisation interne minimale sans RBAC complet](#pattern-autorisation-interne-minimale)
 - [Anti-énumération sur endpoints auth liés à un email](#pattern-anti-enumeration-auth-email)
 - [Token à usage unique — génération, hash et invalidation atomique](#pattern-token-usage-unique)
+- [Next.js runtime-only — orchestration en bord et logique pure testable](#pattern-nextjs-runtime-only-logique-pure-testable)
 - [Guardrails multi-tenant — 403 vs 404 selon la sémantique](#pattern-guardrails-multi-tenant-403-404)
 - [Repository tenant-aware — `tenantId` obligatoire dans la signature](#pattern-repository-tenant-aware)
 - [Défense en profondeur — inclure `tenantId` dans les updates](#pattern-tenantid-dans-updates)
@@ -826,6 +827,45 @@ handlePackWebhookEvent(event): PackWebhookResult | null
 
 ---
 
+<a id="pattern-nextjs-runtime-only-logique-pure-testable"></a>
+## Pattern : Next.js runtime-only — orchestration en bord et logique pure testable
+
+- Objectif : préserver la testabilité unitaire et la lisibilité du code serveur Next.js en limitant les dépendances runtime-only aux couches d’orchestration.
+- Contexte : applications Next.js avec Server Actions, route handlers, modules email/auth et logique métier testée côté Node.
+- Quand l’utiliser : dès qu’un flux serveur mélange APIs Next.js runtime-only (`cookies()`, `headers()`, `redirect()`, `server-only`) et logique métier réutilisable.
+- Quand l’éviter : petits modules purement runtime sans logique métier notable, ou fonctions triviales sans intérêt à être testées séparément.
+- Avantage :
+  - garde la logique métier importable dans un runner Node standard
+  - évite que `server-only` contamine des modules purs
+  - facilite les tests unitaires sans mocks lourds du runtime Next.js
+  - clarifie la responsabilité des Server Actions et handlers serveur
+- Limites / vigilance :
+  - demande une discipline de découpage
+  - peut introduire une indirection inutile si la logique extraite est réellement triviale
+  - les frontières d’injection doivent rester simples pour éviter un excès d’abstraction
+- Validé le : 19-03-2026
+- Contexte technique : Next.js / Server Actions / Node test runner / modules backend injectables
+
+### Implémentation (exemple minimal)
+
+```txt
+- réserver `import "server-only"` aux fichiers qui utilisent réellement des APIs runtime Next.js
+- garder la Server Action, route handler ou module email comme couche d’orchestration fine
+- extraire la logique métier pure dans une fonction ou un service sans dépendance à `cookies()`, `headers()`, `redirect()` ou `server-only`
+- injecter explicitement les dépendances utiles (client DB, token, callback de redirect, logger, etc.)
+- tester unitairement le module pur dans le runner Node ; tester l’orchestrateur plus légèrement
+```
+
+### Checklist
+
+- `server-only` absent des modules de logique pure
+- APIs Next.js runtime-only limitées aux couches d’entrée
+- Logique métier principale testable sans runtime Next.js
+- Dépendances injectées explicitement quand utile
+- Server Action ou handler fin et lisible
+
+---
+
 <a id="pattern-guardrails-multi-tenant-403-404"></a>
 ## Pattern : Guardrails multi-tenant — 403 vs 404 selon la sémantique