_Assistant_Lead_Tech/95_a_capitaliser.md

# 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 :
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-19 — app-template-restau

FILE_UPDATE_PROPOSAL
Fichier cible : 10_frontend_patterns_valides.md

Pourquoi :
Sur les fonctionnalités publiques reposant sur un service tiers en mode link-out (ex: réservation), un parcours canonique unique évite les ambiguïtés UX et centralise mieux les garde-fous, le wording et les fallbacks.

Proposition :
### Intégration tierce en mode link-out : préférer une page locale canonique

Quand une fonctionnalité publique dépend d’un service tiers accessible via lien externe, préférer le parcours :

- CTA internes (home, navigation, landing) → page locale du site
- page locale dédiée → service tiers externe

Éviter de mélanger plusieurs parcours concurrents (ex: home qui sort directement vers le tiers alors qu’une page `/reservation` dédiée existe déjà).

Bénéfices :
- UX plus cohérente
- garde-fous centralisés au même endroit
- fallbacks plus simples à gérer
- évolution facilitée vers une variante embed / click-to-load