_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 :

- `knowledge/backend/patterns/<thème>.md`
- `knowledge/backend/risques/<thème>.md`
- `knowledge/frontend/patterns/<thème>.md`
- `knowledge/frontend/risques/<thème>.md`
- `knowledge/ux/patterns/<thème>.md`
- `knowledge/ux/risques/<thème>.md`
- `knowledge/n8n/patterns/general.md`
- `knowledge/n8n/risques/general.md`
- `knowledge/product/patterns/general.md`
- `knowledge/product/risques/<thème>.md`
- `knowledge/workflow/risques/story-tracking.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**.

---

_Aucune entrée pour le moment_

---

# Format attendu

Chaque proposition doit suivre ce format :

```
DATE — PROJET

FILE_UPDATE_PROPOSAL
Fichier cible : <knowledge/backend/patterns/<thème>.md | knowledge/backend/risques/<thème>.md | knowledge/frontend/patterns/<thème>.md | knowledge/frontend/risques/<thème>.md | knowledge/ux/patterns/<thème>.md | knowledge/ux/risques/<thème>.md | knowledge/n8n/patterns/general.md | knowledge/n8n/risques/general.md | knowledge/product/patterns/general.md | knowledge/product/risques/<thème>.md | knowledge/workflow/risques/story-tracking.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 : knowledge/backend/patterns/prisma.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`).

---

# Rôle dans l'architecture

```
Projet
  ↓
Proposition
  ↓
95_a_capitaliser.md
  ↓
Validation humaine
  ↓
Lead_tech
```

Ce mécanisme permet :

- d'éviter la pollution de la base de connaissance
- de capitaliser progressivement l'expérience des projets
- de garder `Lead_tech` cohérent et fiable.

---

## 2026-03-30 — app-alexandrie

FILE_UPDATE_PROPOSAL
Fichier cible : knowledge/backend/risques/nestjs.md

Pourquoi :
Guard NestJS avec statuts multiples (PENDING/BLOCKED) : le check READ_METHODS doit précéder les checks de statut. Sans ça, les sessions BLOCKED ne peuvent pas accéder aux endpoints GET (ex: /auth/devices), enfermant l'utilisateur sans possibilité de révocation.

Proposition :
### Guard multi-statut : READ_METHODS avant statut, whitelist pour les endpoints de sortie de blocage

**Risque** : un guard qui vérifie le statut BLOCKED avant de vérifier la méthode en lecture bloque les GET, dont les endpoints permettant à l'utilisateur de sortir du blocage (lister ses appareils, révoquer).

**Règle** :
1. Toujours vérifier `READ_METHODS.has(request.method)` EN PREMIER, avant tout check de statut.
2. Définir une whitelist explicite des writes autorisés même en état bloqué (ex: révocation). Sans elle, le circuit de sortie est fermé.

```typescript
// ❌ DANGEREUX — BLOCKED bloque aussi les GET
if (user.sessionStatus === 'BLOCKED') throw new HttpException(...);
if (READ_METHODS.has(request.method)) return true; // jamais atteint pour BLOCKED

// ✅ CORRECT
if (READ_METHODS.has(request.method)) return true;
if (isDeviceManagementPath(request.path)) return true; // whitelist writes critiques
if (user.sessionStatus === 'BLOCKED') throw new HttpException(...);
```

FILE_UPDATE_PROPOSAL
Fichier cible : knowledge/backend/patterns/nestjs.md

Pourquoi :
Pattern fusion DB : quand un service de réconciliation d'état est appelé à chaque requête authentifiée, faire 2 prisma.update séparés (statut + lastSeenAt) double le coût DB par requête.

Proposition :
### Fusionner lastSeenAt dans l'update de réconciliation — évite N requêtes DB par request

Passer `now` en paramètre et inclure `lastSeenAt` dans le même update conditionnel.

```typescript
// ❌ 2 requêtes par requête authentifiée
private async reconcileSessionStatus(session) {
  if (statusChanged) await prisma.session.update({ data: { status, graceEndsAt } });
}
await prisma.session.update({ data: { lastSeenAt: now } }); // 2ème update systématique

// ✅ 1 requête — lastSeenAt toujours inclus dans le même appel
private async reconcileSessionStatus(session, now = new Date()) {
  await prisma.session.update({
    data: { lastSeenAt: now, ...(statusChanged && { status, graceEndsAt }) }
  });
}
```
2026-03-30 — base / FILE_UPDATE_PROPOSAL / Fichier cible: knowledge/backend/risques/contracts.md / Pourquoi: Une story marquée conforme « pas de process.env direct en service métier » dérivait encore vers une lecture brute de variable d'environnement dans un helper utilisé par le service; la validation Zod existait mais était contournée au runtime. / Proposition: Ajouter une vigilance explicite « Feature flags backend: ne pas lire process.env dans les services ni helpers métier; injecter ConfigService (ou config validée) et centraliser la lecture via une fonction pure recevant la config injectée. » + symptôme review « tests green mais dépendance implicite à l'état process global ». 

2026-03-30 — base / FILE_UPDATE_PROPOSAL / Fichier cible: knowledge/frontend/risques/tests.md / Pourquoi: Un test déclaré comme “test composant” validait en réalité des helpers recopiés dans le fichier de test, créant un faux positif (la logique réellement exécutée en production pouvait diverger sans casser le test). / Proposition: Ajouter un anti-pattern « Helpers copiés localement dans les tests » avec règle: les tests doivent importer le module réellement utilisé par l'écran/composant (ou extraire un utilitaire partagé), jamais dupliquer la logique métier dans le test. Inclure checklist review: « aucune fonction de prod recopiée dans *.spec.ts ». 
2026-03-30 — base / FILE_UPDATE_PROPOSAL / Fichier cible: knowledge/workflow/risques/story-tracking.md / Pourquoi: En code review, une story peut afficher des tâches [x] et une File List propre, mais le working tree contient de nombreux changements source non tracés pour cette story; sans note de périmètre explicite, le reviewer peut valider un faux scope ou rejeter à tort. / Proposition: Ajouter une règle « File List vs branch dirty »: si des changements hors story sont présents, documenter explicitement un bloc “hors périmètre de la story” dans le Dev Agent Record (liste courte + justification), et ne marquer done qu'après clarification de périmètre.

2026-03-30 — base / FILE_UPDATE_PROPOSAL / Fichier cible: knowledge/frontend/risques/tests.md / Pourquoi: Un test “écran” qui importe seulement un helper utilitaire ne valide pas le comportement réel de l'écran; il peut rester vert même si la logique de décision UI dans le screen diverge. / Proposition: Ajouter un anti-pattern « test écran indirect »: imposer que la logique de décision UI soit soit testée via rendu composant, soit extraite dans un module dédié importé par le screen et par le test (single source of truth), jamais testée uniquement via un helper adjacent non relié au flux écran.

2026-03-31 — app-template-resto / FILE_UPDATE_PROPOSAL / Fichier cible: knowledge/backend/risques/nextjs.md / Pourquoi: En code review story 4.1, une Server Action appelait fetch() vers elle-même (loopback HTTP) pour contourner la contrainte “server-only”. Cette approche ajoute une latence réseau, une fragilité sur APP_URL en Docker, une double authentification, et une surface SSRF. La vraie solution est d'appeler directement la fonction server-only depuis la Server Action — les deux sont côté serveur et le “server-only” ne bloque pas les imports inter-modules serveur. / Proposition: Ajouter un anti-pattern « Self-request / loopback HTTP depuis Server Action »: une Server Action peut importer et appeler directement des modules marqués server-only sans fetch interne. Règle: si tu te retrouves à reconstituer des cookies de session pour faire un fetch vers ta propre API depuis une Server Action, c'est un signal que l'appel doit être direct.

2026-03-31 — app-template-resto / FILE_UPDATE_PROPOSAL / Fichier cible: knowledge/backend/risques/nextjs.md / Pourquoi: L'écriture atomique (tmp + rename) pour les fichiers media échoue avec EXDEV si le tmpdir système (/tmp) est sur un device différent du volume de stockage (cas courant Docker bind-mount). / Proposition: Ajouter un pattern « écriture atomique intra-device »: créer le fichier temporaire dans le même répertoire que la destination finale (pas dans os.tmpdir()), ce qui garantit que rename() reste intra-device et ne lève jamais EXDEV. Inclure note: s'assurer que le répertoire cible est créé avant l'écriture du tmp.