mirror of
https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech
synced 2026-04-06 13:31:43 +02:00
docs: capitaliser les patterns valides du 16 mars
This commit is contained in:
MaksTinyWorkshop
@@ -75,6 +75,53 @@ Description courte, factuelle, orientée réutilisation.
|
||||
4. Une fois intégrée, la proposition doit être **supprimée de ce fichier**.
|
||||
5. La structure de ce fichier est **restaurée à son état initial** (voir `70_templates/template_a_capitaliser.md`).
|
||||
|
||||
---
|
||||
|
||||
# Revue de tri — 2026-03-16
|
||||
|
||||
Cette section sert à qualifier les propositions en attente avant intégration manuelle.
|
||||
|
||||
## Rappel
|
||||
|
||||
L'exemple plus haut est conservé volontairement pour montrer aux agents le format attendu.
|
||||
Il ne fait pas partie des propositions à intégrer.
|
||||
|
||||
## À intégrer
|
||||
|
||||
Intégré le 16-03-2026 dans les fichiers cibles.
|
||||
|
||||
## À fusionner avant intégration
|
||||
|
||||
- `2026-03-16 — app-template-resto` → `10_backend_patterns_valides.md`
|
||||
`Isolation des guards purs des modules server-only`
|
||||
- `2026-03-16 — app-template-resto` → `10_backend_patterns_valides.md`
|
||||
``server-only` réservé aux modules avec APIs Next.js exclusivement serveur`
|
||||
- `2026-03-16 — app-template-resto` → `10_backend_patterns_valides.md`
|
||||
`Server Action Next.js — isoler la logique pure dans un module injectable`
|
||||
|
||||
Fusion recommandée :
|
||||
`Next.js server-only / Server Actions : garder l'orchestration runtime-only fine et extraire la logique pure testable`
|
||||
|
||||
- `2026-03-16 — app-template-resto` → `10_backend_patterns_valides.md`
|
||||
`Transaction obligatoire pour les opérations auth multi-étapes`
|
||||
- `2026-03-16 — app-template-resto` → `10_backend_patterns_valides.md`
|
||||
`Suppression de session idempotente (P2025)`
|
||||
|
||||
Fusion recommandée :
|
||||
`Opérations auth sensibles : atomiques, idempotentes et cohérentes en cas d'erreur`
|
||||
|
||||
## À laisser en tampon
|
||||
|
||||
- `2026-03-10 — app-alexandrie` → `10_backend_patterns_valides.md`
|
||||
`Progression V1 calculée sans persistance dédiée`
|
||||
Motif : intéressant mais encore trop lié à un choix produit / modélisation métier.
|
||||
- `2026-03-16 — app-template-resto` → `10_backend_risques_et_vigilance.md`
|
||||
`Divergence schéma / spec story`
|
||||
Motif : utile en review, mais trop lié au process de story pour la mémoire durable.
|
||||
- `2026-03-16 — app-template-resto / code-review story 1.11` → `10_backend_risques_et_vigilance.md`
|
||||
`server-only dans les repositories bloque les tests unitaires`
|
||||
Motif : le problème est réel, mais la solution proposée (`stub` local) ne doit pas devenir un standard.
|
||||
|
||||
2026-03-10 — app-alexandrie
|
||||
|
||||
FILE_UPDATE_PROPOSAL
|
||||
@@ -95,13 +142,97 @@ Pour une feature de progression minimum viable :
|
||||
|
||||
Évite le scope creep vers un module `achievements` prématuré et garde un contrat stable.
|
||||
|
||||
2026-03-10 — app-alexandrie
|
||||
2026-03-16 — app-template-resto
|
||||
|
||||
FILE_UPDATE_PROPOSAL
|
||||
Fichier cible : 10_frontend_patterns_valides.md
|
||||
Fichier cible : 10_backend_patterns_valides.md
|
||||
|
||||
Pourquoi :
|
||||
Pour une capacité admin mince sur mobile, une route dédiée légère branchée sur le domaine existant et un refresh explicite du store après mutation permettent de rester testable et robuste sans lancer un back-office séparé.
|
||||
Code review story 1.9 a révélé un pattern récurrent : les services avec opérations multi-étapes (hash + update + delete) doivent systématiquement utiliser $transaction pour éviter les race conditions.
|
||||
|
||||
Proposition :
|
||||
Pattern "UI admin légère sur domaine existant" : pour une action interne simple (publication, activation, modération légère), ajouter une route dédiée minimale qui réutilise le service/store métier existant, afficher le statut courant, bloquer les actions concurrentes avec un flag `isUpdating*`, et déclencher un refresh explicite des vues impactées après succès au lieu d’un `fire-and-forget`.
|
||||
**Pattern : Transaction obligatoire pour les opérations auth multi-étapes**
|
||||
Toute opération qui combine hashing de mot de passe + update user + invalidation de tokens doit être enveloppée dans `prisma.$transaction()`. Sans transaction, une interruption entre les étapes laisse l'état incohérent (ex: token valide après reset du mot de passe).
|
||||
Exemple : consumePasswordReset — marquer consumedAt + update passwordHash + deleteMany autres tokens dans une seule transaction.
|
||||
|
||||
---
|
||||
2026-03-16 — app-template-resto
|
||||
|
||||
FILE_UPDATE_PROPOSAL
|
||||
Fichier cible : 10_backend_risques_et_vigilance.md
|
||||
|
||||
Pourquoi :
|
||||
Code review story 1.9 a révélé un anti-pattern : les tâches de story peuvent déclarer [x] consumedAt sans que le champ existe réellement dans le schéma Prisma.
|
||||
|
||||
Proposition :
|
||||
**Anti-pattern : Divergence schéma / spec story**
|
||||
Lors d'une implémentation, valider que chaque champ mentionné dans les tâches (consumedAt, tokenHash, etc.) existe réellement dans le schéma Prisma avant de marquer la tâche [x]. Une story peut décrire consumedAt comme stratégie de conception sans que le champ soit présent — toujours croiser avec schema.prisma.
|
||||
|
||||
---
|
||||
2026-03-16 — app-template-resto
|
||||
|
||||
FILE_UPDATE_PROPOSAL
|
||||
Fichier cible : 10_backend_patterns_valides.md
|
||||
|
||||
Pourquoi :
|
||||
Le module sendPasswordResetEmail utilise `server-only` ce qui le rend non-importable dans le runner de tests Node. Résolution : tester la logique pure (safeHttpUrl) dans un fichier séparé sans dépendances Next.js.
|
||||
|
||||
Proposition :
|
||||
**Pattern : Isolation des guards purs des modules server-only**
|
||||
Extraire la logique pure (validation URL, sanitisation) dans des fonctions utilitaires sans import `server-only` ou `nodemailer`. Le module email orchestre uniquement. Cela permet de tester les guards en isolation sans les contraintes du runtime Next.js.
|
||||
|
||||
---
|
||||
2026-03-16 — app-template-resto
|
||||
|
||||
FILE_UPDATE_PROPOSAL
|
||||
Fichier cible : 10_backend_patterns_valides.md
|
||||
|
||||
Pourquoi :
|
||||
Pattern validé sur story 1.10 — la règle `server-only` vs testabilité est implicite dans le projet mais mérite d'être explicitée pour les agents futurs.
|
||||
|
||||
Proposition :
|
||||
**Pattern : `server-only` réservé aux modules avec APIs Next.js exclusivement serveur**
|
||||
Ne pas mettre `import "server-only"` sur les modules de logique pure injectés via dépendances (ex: `deleteSession({ prisma, sessionToken })`). Réserver `server-only` aux modules qui appellent des APIs Next.js runtime-only (`cookies()`, `headers()`, `redirect()`). Les modules purs sans ces imports peuvent être importés par le test runner Node et testés unitairement sans friction.
|
||||
|
||||
---
|
||||
2026-03-16 — app-template-resto
|
||||
|
||||
FILE_UPDATE_PROPOSAL
|
||||
Fichier cible : 10_backend_patterns_valides.md
|
||||
|
||||
Pourquoi :
|
||||
Pattern validé sur story 1.10 — suppression de session avec gestion idempotente, réutilisable pour toute opération de révocation.
|
||||
|
||||
Proposition :
|
||||
**Pattern : Suppression de session idempotente (P2025)**
|
||||
Lors d'une déconnexion ou révocation de session, entourer le `prisma.session.delete()` d'un try/catch qui absorbe silencieusement le code Prisma `P2025` (record not found). Une session peut déjà avoir été supprimée (expiration, logout concurrent) — ce n'est pas une erreur, ne pas la propager.
|
||||
|
||||
---
|
||||
2026-03-16 — app-template-resto
|
||||
|
||||
FILE_UPDATE_PROPOSAL
|
||||
Fichier cible : 10_backend_patterns_valides.md
|
||||
|
||||
Pourquoi :
|
||||
Pattern validé sur story 1.10 — Server Action Next.js qui orchestre des dépendances Next.js runtime non-testables : isoler la logique pure dans un module injectable.
|
||||
|
||||
Proposition :
|
||||
**Pattern : Server Action Next.js — isoler la logique pure dans un module injectable**
|
||||
Une Server Action qui appelle `cookies()`, `headers()` ou `redirect()` ne peut pas être testée unitairement (imports runtime-only). Pattern : extraire la logique pure (suppression DB, validation) dans une fonction avec injection de dépendances (`performSignOut({ prismaClient, sessionToken, redirectFn })`). La Server Action reste fine et orchestre uniquement les dépendances Next.js. Le module extrait est testable sans friction avec le runner Node natif.
|
||||
|
||||
---
|
||||
2026-03-16 — app-template-resto / code-review story 1.11
|
||||
|
||||
FILE_UPDATE_PROPOSAL
|
||||
Fichier cible : 10_backend_risques_et_vigilance.md
|
||||
|
||||
Pourquoi :
|
||||
`import "server-only"` dans les repositories casse les tests Node.js hors Next.js — rencontré lors de cette review.
|
||||
|
||||
Proposition :
|
||||
## Risque : `server-only` dans les repositories bloque les tests unitaires
|
||||
|
||||
`import "server-only"` empêche l'exécution des fichiers hors runtime Next.js.
|
||||
Solution : créer un stub `node_modules/server-only/index.js` (no-op) pour les tests.
|
||||
Alternativement, ne mettre `server-only` que dans les fichiers qui utilisent des APIs
|
||||
Next.js (`cookies()`, `headers()`), pas dans les repositories purs.
|
||||
|
||||
Reference in New Issue
Block a user