mirror of
https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech
synced 2026-04-06 21:41:42 +02:00
239 lines
10 KiB
Markdown
239 lines
10 KiB
Markdown
# Capitalisation en attente — Lead_tech
|
||
|
||
Ce fichier sert de **zone tampon de capitalisation**.
|
||
|
||
Les agents et les projets peuvent y déposer des propositions
|
||
d’amélioration de la base de connaissance globale (`Lead_tech`).
|
||
|
||
Le contenu de ce fichier **n'est pas encore validé**.
|
||
|
||
Une fois relues et confirmées, les propositions doivent être **déplacées**
|
||
vers les fichiers appropriés :
|
||
|
||
- `10_backend_patterns_valides.md`
|
||
- `10_frontend_patterns_valides.md`
|
||
- `10_ux_patterns_valides.md`
|
||
- `10_product_patterns_valides.md`
|
||
- `10_n8n_patterns_valides.md`
|
||
- `10_backend_risques_et_vigilance.md`
|
||
- `10_frontend_risques_et_vigilance.md`
|
||
- `10_ux_risques_et_vigilance.md`
|
||
- `10_n8n_risques_et_vigilance.md`
|
||
- `10_conventions_redaction.md`
|
||
- `40_decisions_et_archi.md`
|
||
- `90_debug_et_postmortem.md`
|
||
|
||
Ce fichier ne doit donc **jamais devenir une documentation permanente**.
|
||
|
||
---
|
||
|
||
# Format attendu
|
||
|
||
Chaque proposition doit suivre ce format :
|
||
|
||
```
|
||
DATE — PROJET
|
||
|
||
FILE_UPDATE_PROPOSAL
|
||
Fichier cible : <10_backend_patterns_valides.md | 10_frontend_patterns_valides.md | 10_ux_patterns_valides.md | 10_product_patterns_valides.md | 10_n8n_patterns_valides.md | 10_backend_risques_et_vigilance.md | 10_frontend_risques_et_vigilance.md | 10_ux_risques_et_vigilance.md | 10_n8n_risques_et_vigilance.md | 10_conventions_redaction.md | 40_decisions_et_archi.md | 90_debug_et_postmortem.md>
|
||
|
||
Pourquoi :
|
||
<raison pour laquelle ce savoir mérite d'être capitalisé>
|
||
|
||
Proposition :
|
||
<contenu suggéré à intégrer dans le fichier cible>
|
||
```
|
||
|
||
---
|
||
|
||
# Exemple
|
||
|
||
```
|
||
2026-03-08 — portfolio
|
||
|
||
FILE_UPDATE_PROPOSAL
|
||
Fichier cible : 10_backend_patterns_valides.md
|
||
|
||
Pourquoi :
|
||
Pattern réutilisable validé sur un projet réel.
|
||
|
||
Proposition :
|
||
|
||
## Nom du pattern
|
||
|
||
Description courte, factuelle, orientée réutilisation.
|
||
```
|
||
|
||
---
|
||
|
||
# Règles
|
||
|
||
1. Les agents peuvent **proposer librement** ici.
|
||
2. Les propositions doivent rester **courtes et factuelles**.
|
||
3. La validation et l'intégration finale dans `Lead_tech`
|
||
sont faites **manuellement**.
|
||
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
|
||
Fichier cible : 10_backend_patterns_valides.md
|
||
|
||
Pourquoi :
|
||
Pattern réutilisable pour exposer une progression V1 sans ouvrir trop tôt un domaine `achievements` ou `analytics`, tout en gardant une couture propre vers des contributions futures.
|
||
|
||
Proposition :
|
||
|
||
## Progression V1 calculée sans persistance dédiée
|
||
|
||
Pour une feature de progression minimum viable :
|
||
- garder l'agrégat dans le domaine métier déjà source de vérité (`content`, `billing`, etc.)
|
||
- calculer les compteurs période (`thisWeek`, `thisMonth`) côté base avec `count`/agrégations filtrées
|
||
- centraliser le catalogue d'objectifs en code explicite et testable
|
||
- prévoir une couture zéro-safe pour les sources futures (`contributions`, `posts`, etc.) au lieu d'inventer les tables en avance
|
||
|
||
Évite le scope creep vers un module `achievements` prématuré et garde un contrat stable.
|
||
|
||
2026-03-16 — app-template-resto
|
||
|
||
FILE_UPDATE_PROPOSAL
|
||
Fichier cible : 10_backend_patterns_valides.md
|
||
|
||
Pourquoi :
|
||
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 : 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.
|