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

Les agents peuvent proposer librement ici.
Les propositions doivent rester courtes et factuelles.
La validation et l'intégration finale dans Lead_tech sont faites manuellement.
Une fois intégrée, la proposition doit être supprimée de ce fichier.
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 :

Toujours vérifier READ_METHODS.has(request.method) EN PREMIER, avant tout check de statut.
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é.

// ❌ 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.

// ❌ 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.

9.4 KiB Raw Blame History