# Backend — Risques & vigilance : Général > Extrait de la base de connaissance Lead_tech. Voir `knowledge/backend/risques/README.md` pour l'index complet. --- ## Observabilité insuffisante (logs non structurés, pas de corrélation) ### Risques - MTTR très élevé : on devine - Incapacité à mesurer l'impact utilisateur ### Symptômes - Logs "ça a crash" sans contexte - Impossible de relier une requête à une erreur - Latence qui dérive sans alerte ### Bonnes pratiques / mitigations - Logs structurés + requestId/traceId - Métriques de base (latence, erreurs, throughput) - Alertes simples sur 5xx/latence --- ## Migrations risquées / non reproductibles ### Risques - Downtime - Perte de données - Incohérence entre environnements ### Symptômes - "Ça marche en local" mais pas en prod - Migration qui échoue à mi-chemin - Rollback impossible ### Bonnes pratiques / mitigations - Migrations versionnées + tests staging - Stratégie expand/contract si besoin - Plan de rollback/mitigation --- ## Boucle `upsert` N+1 sur synchronisation provider ### Risques - Latence multipliée par le nombre d'items - Charge DB inutile - Timeouts ou contention sur gros volumes ### Symptômes - Une boucle applicative exécute un `upsert` par item - Temps de traitement qui explose avec le volume - Logs SQL répétitifs et séquentiels ### Bonnes pratiques / mitigations - Batcher quand c'est possible - Précharger les données nécessaires avant boucle - Mesurer explicitement le coût d'un `upsert` unitaire dans les flux de sync - Contexte technique : Prisma / synchronisation provider — 10-03-2026 --- ## Anti-pattern : Authorize-after-fetch (contrôle d'accès après chargement) ### Risques - Le contrôle d'accès effectué après chargement des relations métier volumineuses augmente le coût DB et la surface de fuite temporelle pour des requêtes finalement refusées ### Symptômes - Handler qui charge un agrégat complet (avec includes/relations) puis vérifie l'accès - Requêtes refusées après un temps de réponse anormalement long ### Bonnes pratiques / mitigations - Pour les endpoints détail sensibles, filtrer l'accès dans la requête DB (`where` + scope grade/tenant) ou faire un pré-check minimal avant de charger les relations - Les accès non autorisés ne doivent pas déclencher un fetch complet des données métier ### RBAC-before-parse — autoriser avant de parser le body - Le guard d'authentification/autorisation doit TOUJOURS être évalué AVANT tout accès au body de la requête. Un attaquant non authentifié peut sinon sonder les erreurs de validation Zod (codes, messages, structure du schéma) avant d'être rejeté, ce qui expose la surface d'attaque. - Ordre obligatoire dans chaque handler HTTP : (1) `requireAuth` / `requireRoleAccess`, (2) validation du path/query params, (3) `request.json()` + validation Zod du body. Ne jamais inverser les étapes 1 et 3. - Ne pas parser un payload pour un appel qui sera de toute façon refusé : c'est à la fois une fuite d'info et un coût inutile. - **Signal review** : `request.json()` ou `schema.parse(body)` qui précède l'appel au guard d'autorisation dans un handler. - Cas vécu : `handleUpdateReportManualSections` dans `seasonReportService.ts` (RBAC après parse), corrigé en revue adversariale v2-3-1. - Contexte technique : backend général — RL799_V2 02-04-2026 (RBAC-before-parse ajouté 19-06-2026) --- ## Valeur sentinelle `""` au lieu de `null` dans un DTO de date nullable ### Risques - Un champ de date optionnel dans le modèle Prisma (`Date | null`) sérialisé en `""` dans le DTO au lieu de `null` - Le type DTO ment (`string` au lieu de `string | null`), et tout consommateur testant `if (profile.field)` a un comportement incorrect sur `""` ### Symptômes - `?? ''` sur une date issue de `?.toISOString()` dans un repository Prisma - Type DTO avec `someDate: string` non optionnel pour un modèle qui autorise `null` en DB ### Bonnes pratiques / mitigations - Si un champ de date peut être `null` en DB, le type DTO doit être `string | null` - Le repository utilise `?? null` (pas `?? ''`) pour les dates nulles - Le frontend utilise `??` (nullish coalescing) pas `||` pour les fallbacks d'affichage sur ces champs - Contexte technique : Prisma / DTO — RL799_V2 02-04-2026 --- ## Endpoint idempotent sans contrôle de doublon ### Risques - Un endpoint crée un event/enregistrement censé être unique par contexte (ex: un vote par tenue, un PDF par planche) sans vérifier l'existence préalable - Un double-clic ou retry réseau crée des doublons silencieux, ou des fichiers orphelins en cas d'artefact physique ### Symptômes - `writeFile` + `prisma.create` sans `findFirst` préalable dans le même handler - Plusieurs enregistrements identiques avec le même contexte en base - Fichiers physiques (PDF, export) dupliqués sur disque ### Bonnes pratiques / mitigations - Avant tout `create` d'un event contextuel, lire les events existants avec le même filtre de contexte - Retourner 409 si l'event existe déjà, ou mettre à jour l'existant selon la sémantique métier - Pour les artefacts physiques : retourner l'existant (200) au lieu de recréer (201), ou supprimer l'ancien avant d'en créer un nouveau - Contexte technique : backend général — RL799_V2 03-04-2026 --- ## Fichier orphelin sur échec de persistance en base ### Risques - Un service écrit un fichier sur disque puis crée l'entrée correspondante en base ; si la création en base échoue, le fichier reste orphelin - Un `catch {}` vide rend le debug impossible ### Symptômes - Fichiers physiques présents sur disque sans enregistrement correspondant en base - Erreurs de persistance invisibles dans les logs ### Bonnes pratiques / mitigations ```ts const file = await writeFileToDisk(...); try { await createDbRecord(...); } catch (err) { await cleanupFile(file.path); console.error('Erreur persistance:', err); throw err; } ``` - Si la création en base échoue, supprimer le fichier physique (cleanup) - Toujours logger l'erreur dans le catch, même si on retourne une réponse d'erreur propre au client - Contexte technique : backend / fichiers — RL799_V2 03-04-2026 --- ## Mélange Date locale / Date UTC dans les données de seed ### Risques - Des dates dynamiques construites via `new Date(year, month, day, hour)` (heure locale) cohabitent avec des dates fixes en UTC (`new Date('...T19:00:00Z')`) dans le même fichier - L'incohérence est silencieuse et produit des décalages horaires non reproductibles entre environnements ### Symptômes - `new Date(year, month, day, hour)` (local) dans un fichier qui utilise aussi `new Date('...Z')` (UTC) - Données de seed dont les heures varient selon la timezone de l'environnement dev ### Bonnes pratiques / mitigations - Les dates dynamiques dans un seed doivent être construites en UTC (`Date.UTC(...)`) si les dates fixes sont en UTC - **Signal review** : `new Date(year, month, day, hour)` dans un fichier qui utilise aussi `new Date('...Z')` - Contexte technique : Node.js / seed — RL799_V2 03-04-2026 --- ## Champ fantôme accepté par validation Zod mais non persisté ### Risques - Un champ optionnel ajouté dans un schéma Zod est accepté par la validation mais jamais exploité par la chaîne handler → repository → modèle Prisma - L'utilisateur envoie une donnée sans erreur, mais elle est silencieusement perdue ### Symptômes - Champ optionnel dans le schéma Zod absent du modèle Prisma - Champ passé au service mais non inclus dans l'appel `create`/`update` du repository ### Bonnes pratiques / mitigations - Avant d'ajouter un champ au schéma de validation, s'assurer que le modèle DB le supporte - Si le modèle ne le supporte pas, ne pas accepter le champ du tout - **Signal review** : champ dans le schéma Zod qui n'apparaît pas dans le `data` de l'appel Prisma - Contexte technique : Zod / Prisma — RL799_V2 06-04-2026 --- ## Catch vide avalant les exceptions sans logging ### Risques - Les `catch {}` ou `catch { // ignore }` dans les services métier masquent les erreurs réelles - En production, un disque plein ou un bug PDFKit retourne un message générique sans trace serveur ### Symptômes - `catch {` sans `console.error` ni logger dans un service métier - Bloc catch qui retourne un message d'erreur générique sans capturer `err` ### Bonnes pratiques / mitigations - Toujours capturer et logger l'exception dans les catch des services métier - Les catch de rollback secondaire (ex: unlink d'un fichier) peuvent être silencieux mais devraient au minimum émettre un `warn` - **Signal review** : `catch {` sans variable dans un service métier (hors rollback secondaire) - Contexte technique : backend général — RL799_V2 06-04-2026 --- ## Paramètres de route non validés avant passage à Prisma ### Risques - Un paramètre de route (`id`, `memberId`) passé directement à `prisma.findUnique({ where: { id } })` sans validation de format (UUID, slug) - Des chaînes arbitraires atteignent la couche DB, polluant les logs et violant le principe de validation aux frontières ### Symptômes - `const { id } = params; prisma.model.findUnique({ where: { id } })` sans `isValidUuid(id)` - Erreurs Prisma non significatives en production sur des identifiants malformés ### Bonnes pratiques / mitigations - Toujours valider les identifiants (UUID, slug, etc.) dès l'entrée du handler ou du service, avant tout appel DB - Retourner 400 immédiatement si invalide - Contexte technique : backend / validation — RL799_V2 07-04-2026 --- ## Cast TypeScript brut sur valeurs DB non contraintes ### Risques - Un cast `value as 'expected_a' | 'expected_b'` sur un champ Prisma de type `String` sans enum DB masque silencieusement toute valeur inattendue - Le type-checking passe, mais une valeur inattendue en DB provoque des comportements incohérents en aval ### Symptômes - `status as 'pending' | 'late'` sur un champ Prisma `String` sans enum DB - Pas de fallback explicite pour les valeurs non attendues ### Bonnes pratiques / mitigations - Utiliser des conditions explicites (`if (s === 'a') ... else if (s === 'b') ... else fallback`) ou un mapping validé - Ne jamais faire confiance au type runtime via un simple cast TS - **Signal review** : `as 'literal_a' | 'literal_b'` sur un champ Prisma de type `String` - Contexte technique : TypeScript / Prisma — RL799_V2 07-04-2026 --- ## Création de ressource temporelle sans détection de chevauchement ### Risques - Un endpoint crée une ressource avec `startDate`/`endDate` sans vérifier les collisions avec les ressources existantes - Un double-clic ou une erreur humaine génère des doublons avec les mêmes dates ### Symptômes - Deux ressources avec des plages temporelles qui se chevauchent pour le même contexte (cotisations, abonnements, sessions) ### Bonnes pratiques / mitigations - Avant insertion, query les ressources existantes dont les plages se chevauchent : `WHERE start < newEnd AND end > newStart` - Retourner 409 Conflict si collision - S'applique aux cotisations, abonnements, périodes de garde, sessions — tout ce qui a des bornes temporelles - Contexte technique : backend général — RL799_V2 07-04-2026 --- ## TOCTOU sur opérations conditionnelles sans transaction ### Risques - `findUnique` → check status → `update` en séquence sans transaction crée une fenêtre TOCTOU (Time-of-Check Time-of-Use) - Un traitement concurrent peut modifier l'état entre la vérification et la mise à jour ### Symptômes - Données incohérentes sous charge concurrente (rare en MVP mais critique en prod) - Double relance de cotisation, double changement de statut ### Bonnes pratiques / mitigations - Wrapper dans `prisma.$transaction()` ou utiliser un `UPDATE ... WHERE status != 'paid'` atomique - **Règle** : toute séquence read → validate → write sur la même entité doit être atomique - Contexte technique : Prisma / backend général — RL799_V2 07-04-2026 --- ## Calcul de moyenne vs ratio global — biais d'agrégation ### Risques - Le ratio global (somme numérateurs / somme dénominateurs) donne un résultat biaisé vers les entités avec les dénominateurs les plus grands quand on veut calculer une "moyenne de taux" sur N entités ### Symptômes - "% de présence moyenne par degré" calculé comme total_présents / total_inscrits au lieu d'une moyenne par tenue - Tests verts car les données de test symétriques donnent le même résultat avec les deux méthodes ### Bonnes pratiques / mitigations - Moyenne de présence par tenue → calculer le taux par tenue, puis la moyenne des taux — pas le ratio global - Rédiger un test qui construit des données asymétriques pour détecter la différence (ex: une tenue avec 10 inscrits/8 présents, une avec 2 inscrits/2 présents → 83% global vs 90% moyenne correcte) - Contexte technique : backend / statistiques — RL799_V2 07-04-2026 --- ## Couplage sémantique sur les types d'erreur partagés ### Risques - Un helper générique (ex: authHelpers) importe un type nommé d'après un domaine métier spécifique (ex: ConvocationErrorCode) - Chaque nouveau domaine qui utilise l'auth helper "dépend" conceptuellement du module d'origine ### Symptômes - Un helper générique utilisé par 12+ fichiers importe un type nommé d'après un seul domaine métier - Couplage sémantique incohérent hérité de la première implémentation ### Bonnes pratiques / mitigations - À la prochaine refacto touchant le helper, extraire un type `ApiErrorCode` générique dans le package partagé et faire pointer les types domaine vers lui - Contexte technique : backend / architecture — RL799_V2 07-04-2026 --- ## Service HTTP-aware — violation de la séparation des couches ### Risques - Un fichier `service.ts` importe `Response`, construit les headers et status HTTP, et retourne un objet `Response` - Le service devient intestable sans mock HTTP, la logique métier est couplée au transport, et la réutilisation (CLI, cron, WebSocket) est impossible ### Symptômes - Le fichier route.ts ne fait que `(req) => handleX(req)` — pass-through d'une ligne - Import de `Response` dans un fichier service ### Bonnes pratiques / mitigations - Le service doit retourner `{ data: T } | { error: { code, message } }` et la route construit la Response - Refactoriser quand un service est touché - Contexte technique : architecture en couches — RL799_V2 07-04-2026 --- ## Count sans filtre sur User — confusion membres / utilisateurs ### Risques - `prisma.user.count()` sans `where` inclut les comptes techniques (admin, secretaire) dans les comptages métier "nombre de membres inscrits" - Les stats métier sont faussées silencieusement ### Symptômes - `prisma.user.count()` sans `where` pour un affichage de type "effectifs inscrits" - Écart entre le comptage affiché et la réalité métier ### Bonnes pratiques / mitigations - Toujours filtrer `{ where: { role: { not: 'admin' } } }` (ou équivalent) pour les comptages métier - À terme, ajouter un champ `status` (active/inactive/suspended) pour distinguer les membres actifs - **Signal review** : `prisma.user.count()` sans `where` dans un contexte de statistiques - Contexte technique : Prisma / stats — RL799_V2 07-04-2026 --- ## Variables d'environnement lues au top-level d'un module ### Risques - `const FOO = process.env.FOO || 'default'` en dehors d'une fonction fige la valeur au premier `import` - Les tests qui modifient `process.env` après l'import ne voient pas l'effet - Config non-reloadable sans redémarrage ### Symptômes - `process.env.X` assigné à une constante au top-level d'un module Node - Tests qui doivent manipuler l'ordre d'import pour surcharger une variable d'environnement ### Bonnes pratiques / mitigations - Encapsuler dans un getter : `const getFoo = () => process.env.FOO || 'default'` - Permet la surcharge en test et le rechargement dynamique - Contexte technique : Node.js / tests — RL799_V2 07-04-2026 --- ## Rate limiting — couverture de test insuffisante ### Risques - Tester uniquement l'objet `RateLimiter` en isolation (`.check()`, `.reset()`) donne une fausse confiance. Les bugs de câblage (limiter non appelé, mauvais limiter sur le mauvais endpoint, format de réponse 429 incorrect) passent au travers. ### Symptômes - Tests unitaires verts mais réponse 429 absente ou mal formatée en intégration - Header `retry-after` manquant dans la réponse HTTP ### Bonnes pratiques / mitigations - Pour chaque rate limiter intégré dans un endpoint, ajouter au minimum : 1. Un test d'intégration qui dépasse le seuil via le handler HTTP et vérifie status 429 + body + header `retry-after` 2. Un test d'expiration de fenêtre (mock `Date.now` et avancer le temps) 3. Vérifier que le logging sécurité est déclenché (au minimum visible dans la sortie test) - Contexte technique : backend / rate limiting — RL799_V2 07-04-2026 --- ## Nommage des métriques agrégées dans les DTO ### Risques - Nommer un champ `xxxCount` ou `xxxThisYear` sans que le nom reflète exactement ce qui est compté - Confusion en maintenance, bugs d'affichage, labels UI incohérents ### Symptômes - `tenuesThisYear` qui compte en réalité les *présences* du membre, pas le nombre total de tenues - Labels frontend incohérents avec le comportement réel du champ ### Bonnes pratiques / mitigations - Le nom du champ DTO doit refléter exactement l'entité comptée ET le scope du comptage - Préférer `presencesThisYear` à `tenuesThisYear` si on compte les attendances d'un user, réserver `tenuesThisYear` pour le COUNT de tenues elles-mêmes - **Signal review** : tout champ `xxxCount` ou `xxxThisYear` dont le nom ne correspond pas à la requête sous-jacente - Contexte technique : backend / DTO — RL799_V2 07-04-2026 --- ## `.gitignore` — `.env*` wildcard capture `.env.example` ### Risques - Utiliser `.env*` dans `.gitignore` sans exception exclut aussi `.env.example`, qui est le fichier standard de documentation des variables d'environnement et qui DOIT être versionné ### Symptômes - Le fichier `.env.example` existe sur le disque mais n'apparaît pas dans `git status` - Les développeurs ne savent pas quelles variables configurer ### Bonnes pratiques / mitigations - Toujours ajouter `!.env.example` après le wildcard `.env*` dans chaque `.gitignore` (racine ET sous-projets du monorepo) - Vérifier avec `git check-ignore ` que l'exception fonctionne - **Signal review** : `.env*` dans `.gitignore` sans `!.env.example` - Contexte technique : git / configuration — RL799_V2 08-04-2026 --- ## Strip HTML regex — single-pass insuffisant ### Risques - `input.replace(/<[^>]*>/g, '')` en un seul passage laisse des fragments exploitables sur des inputs malformés type `ipt>alert(1)` ### Symptômes - Après strip, le résultat contient encore des fragments `>` ou des reconstitutions partielles de tags ### Bonnes pratiques / mitigations - Toujours (1) boucler le strip jusqu'à stabilisation (`while (prev !== result)`) ET (2) supprimer les chevrons orphelins `<>` après la boucle - Pour du plain text (pas de rich text), c'est suffisant. Pour du rich text, utiliser une lib dédiée (DOMPurify, sanitize-html) - **Signal review** : `replace(/<[^>]*>/g, '')` sans boucle dans un code qui traite de l'input utilisateur - Contexte technique : sécurité / sanitisation — RL799_V2 08-04-2026 --- ## Incohérence source de vérité — filtrage vs affichage sur des tables différentes ### Risques - Filtrer des entités sur un champ d'une table relationnelle (`profile.grade`) tout en affichant le résultat depuis une autre table (`directory.grade`). Si les deux tables ne sont pas synchronisées en permanence, les résultats de filtrage et d'affichage divergent silencieusement. ### Symptômes - Un membre apparaît éligible mais avec un grade affiché incohérent, ou inversement un membre éligible est invisible parce que seule la table d'affichage a été mise à jour ### Bonnes pratiques / mitigations - Toujours utiliser la même table comme source de vérité pour le filtrage ET l'affichage d'un même attribut - Si deux tables portent la même information, choisir celle qui fait autorité et aligner le code dessus - **Signal review** : `where` sur `tableA.field` avec `select` sur `tableB.field` pour le même attribut - Contexte technique : Prisma / relations — RL799_V2 08-04-2026 --- ## Check-then-create non atomique — catcher P2002 ### Risques - Vérifier l'existence d'un enregistrement (`findFirst/findUnique`) puis créer dans un second appel est une race condition classique - Deux requêtes concurrentes passent le check, l'une échoue sur la contrainte unique ### Symptômes - Erreur 500 générique au lieu d'un conflit 409, intermittent et difficile à reproduire ### Bonnes pratiques / mitigations - Toujours catcher l'erreur Prisma `P2002` (unique constraint violation) dans le bloc catch de la création et la transformer en réponse métier explicite (`USER_ALREADY_EXISTS`, `CONFLICT`, etc.) - Le check préalable reste utile pour le cas nominal mais ne doit pas être la seule protection - **Règle** : tout `prisma.create` sur une entité à contrainte unique doit avoir un catch `P2002` - Contexte technique : Prisma / concurrence — RL799_V2 08-04-2026 --- ## Double update non transactionnel sur la même entité ### Risques - Enchaîner deux `prisma.update` séparés sur la même entité (ex: update status puis update metadata) sans transaction laisse l'entité dans un état partiel si le second échoue ### Symptômes - L'entité est dans un état qui ne correspond à aucune transition définie - Les flux aval (workflows, UI) se retrouvent bloqués ### Bonnes pratiques / mitigations - Quand plusieurs champs d'une même entité doivent être modifiés ensemble pour représenter une transition d'état cohérente, les regrouper dans un seul appel `prisma.update` ou les envelopper dans une `$transaction` - **Signal review** : deux `prisma.update` séquentiels sur le même `where: { id }` sans `$transaction` - Contexte technique : Prisma / atomicité — RL799_V2 08-04-2026 --- ## Fallback "legacy" qui bypass un nouveau workflow ### Risques - Laisser un fallback de compatibilité dans une transition d'état (ex: accepter `'draft'` en plus de `'pending_vm_approval'` comme état source de la publication) crée un chemin de contournement du nouveau workflow - Un appel direct à la fonction interne bypass le contrôle métier ### Symptômes - Transition d'état possible depuis un état qui ne devrait plus être accepté - `{ in: ['ancien', 'nouveau'] }` dans un filtre Prisma sur une transition d'état ### Bonnes pratiques / mitigations - Quand un nouveau workflow remplace un flux direct, retirer le fallback vers l'ancien état dans la transition atomique - Si la rétro-compatibilité est nécessaire, l'encapsuler dans un flag explicite ou une route dédiée, pas dans un `{ in: ['ancien', 'nouveau'] }` silencieux - Contexte technique : workflow / transitions d'état — RL799_V2 08-04-2026 --- ## Couverture incomplète des chemins d'écriture lors d'ajout de sécurité transverse ### Risques - Quand on ajoute une mesure de sécurité (chiffrement, sanitisation, validation, audit) sur un chemin d'écriture (ex: upload), les chemins alternatifs vers la même ressource (ex: create-from-text, import CSV, seed) sont oubliés, laissant une faille ### Symptômes - Un chemin d'écriture protégé, un autre non protégé, pour la même ressource - Données non chiffrées ou non sanitisées créées par un chemin secondaire ### Bonnes pratiques / mitigations - Avant de marquer une tâche sécurité comme terminée, lister TOUS les chemins d'écriture vers la ressource ciblée (grep `createDocument`, `writeFile`, `prisma.model.create`) et vérifier que chacun est couvert - Documenter la liste dans les Dev Notes de la story - Contexte technique : sécurité / transverse — RL799_V2 08-04-2026 --- ## Anonymisation RGPD — pièges courants ### Risques - **Données personnelles dans les audit logs** : stocker email ou nom dans les métadonnées d'un audit log d'anonymisation annule le droit à l'oubli (art. 17) - **Password en clair après anonymisation** : remplacer le password par une string comme `'ANONYMIZED'` est un signal exploitable en base - **Dernier admin anonymisable** : le système peut se retrouver sans administrateur - **Sessions non révoquées** : le JWT existant reste valide jusqu'à expiration ### Symptômes - Email en clair dans les métadonnées d'audit après anonymisation - Password `'ANONYMIZED'` visible en base au lieu d'un hash bcrypt structurellement invalide - Aucun admin actif restant après anonymisation - Utilisateur anonymisé qui peut encore accéder à l'application ### Bonnes pratiques / mitigations - Utiliser un hash tronqué (ex: `sha256(email).slice(0,12)`) pour la corrélation dans les audit logs, pas l'email brut - Remplacer le password par un hash bcrypt structurellement invalide (ex: `$2b$10$INVALID...`) - Vérifier qu'au moins un admin actif reste après anonymisation - Révoquer tous les refresh tokens du user dans la même transaction - Contexte technique : RGPD / sécurité — RL799_V2 08-04-2026 --- ## Assertions de body d'erreur non mises à jour après migration de codes ### Risques - Lors d'une migration de codes d'erreur (ex: distinguer `UNAUTHORIZED` de `FORBIDDEN`), les assertions de status HTTP sont mises à jour mais pas les assertions sur le body JSON ### Symptômes - `assert.equal(response.status, 401)` passe, mais `assert.equal(body.error.code, 'FORBIDDEN')` échoue — le code réel est `UNAUTHORIZED` - Détecté seulement quand on relance la suite complète ### Bonnes pratiques / mitigations - Lors de toute modification d'un code d'erreur dans un helper centralisé, rechercher TOUTES les assertions qui testent l'ancien code (`grep -rn 'FORBIDDEN' __tests__/`) et les mettre à jour en cohérence - Ne pas se fier au fait que "les tests passent" sans les exécuter réellement - Contexte technique : tests / migration de codes — RL799_V2 08-04-2026 --- ## Audit conditionnel sur un lookup DB secondaire ### Risques - Le handler utilise `requireRoleAccess` qui ne retourne que `{ email, role }` mais pas `userId`. Pour logger l'audit, un second lookup (`getUserByEmail`) est nécessaire et peut échouer silencieusement ### Symptômes - Une action sensible (création, promotion, suppression) réussit mais aucun log d'audit n'est écrit - Le caller est pourtant authentifié ### Bonnes pratiques / mitigations - Sur tout endpoint qui doit journaliser un audit, utiliser un helper qui retourne `{ userId, email, role }` directement depuis le JWT `sub` claim, plutôt qu'un helper + lookup DB - Le userId est déjà dans le token — pas besoin d'aller le chercher en base - Contexte technique : audit / auth — RL799_V2 08-04-2026 --- ## Dérive du format d'erreur API entre services ### Risques - Chaque service recrée sa propre fonction `errorResponse` locale au lieu de réutiliser un helper centralisé - Le format standard `{ error: { code, message, requestId } }` n'est pas imposé par le typage ### Symptômes - Certaines routes API retournent `{ error: { code, message } }` sans `requestId`, d'autres incluent le `requestId` - Les erreurs sans requestId sont impossibles à tracer en production ### Bonnes pratiques / mitigations - Tout nouveau service doit inclure `requestId: crypto.randomUUID()` dans ses réponses d'erreur - Factoriser un helper `createApiErrorResponse` partagé dans `lib/` pour éviter la divergence - **Signal review** : réponse d'erreur sans `requestId` dans un nouveau service - Contexte technique : observabilité / API — RL799_V2 08-04-2026 --- ## Unicité applicative sans contrainte DB ### Risques - Un contrôle d'unicité uniquement applicatif sur des affectations "actives" reste vulnérable aux races concurrentes et peut créer deux titulaires actifs sur un même rôle ### Symptômes - Deux enregistrements actifs pour un slot censé être unique (ex: deux titulaires pour un rôle d'officier) - Bug intermittent sous charge concurrente, invisible en dev ### Bonnes pratiques / mitigations - Pour tout agrégat avec invariant "un seul actif" (ex: mandat d'officier par rôle), imposer une contrainte d'unicité au niveau base (index unique partiel ou stratégie équivalente) en plus des checks service - Les checks applicatifs seuls ne suffisent pas sous concurrence - Contexte technique : Prisma / contraintes — RL799_V2 08-04-2026 --- ## Docker Compose — migrations exécutées après redémarrage applicatif ### Risques - Fenêtre de non-compatibilité entre code déployé et schéma DB. - Crash silencieux sur colonnes/contraintes nouvellement requises. ### Symptômes - Redéploiement "vert" puis erreurs runtime immédiates sur accès DB. ### Bonnes pratiques / mitigations - Appliquer les migrations avant le redémarrage applicatif. - Séquence recommandée : `docker compose build` -> `docker compose run --rm api prisma migrate deploy` -> `docker compose up -d`. - Contexte technique : Docker Compose / déploiement — RL799_V2 08-04-2026 --- ## Scripts shell — sourcing global de `.env` ### Risques - `set -a; source .env` exporte tous les secrets à tous les sous-processus. ### Symptômes - Secrets inutiles visibles dans l'environnement de commandes annexes (docker/curl/webhooks). ### Bonnes pratiques / mitigations - Charger uniquement les variables nécessaires (`grep`/`cut` ou équivalent). - Réserver `source .env` aux scripts qui ont réellement besoin de tout le contexte. - Contexte technique : shell / secrets env — RL799_V2 08-04-2026 --- ## Docker Compose — services auxiliaires sans `healthcheck` ### Risques - Faux positifs de disponibilité d'un service qui démarre mais n'est pas prêt. ### Symptômes - Service "up" mais non exploitable (port bloqué, DB locale corrompue, etc.). ### Bonnes pratiques / mitigations - Ajouter un `healthcheck` homogène sur tous les services critiques et auxiliaires. - Aligner la politique de readiness/liveness sur l'ensemble du compose. - Contexte technique : Docker Compose / observabilité service — RL799_V2 08-04-2026 --- ## Configuration fail-open d'un bind réseau en production ### Risques - Dashboard/service exposé publiquement si variable d'environnement manquante. ### Symptômes - Service censé rester localement accessible exposé sur `0.0.0.0`. ### Bonnes pratiques / mitigations - Forcer le bind sûr dans l'override de production (`127.0.0.1` ou réseau privé explicite). - Ne pas dépendre d'un `.env` optionnel pour une contrainte de sécurité. - Contexte technique : Docker Compose / sécurité réseau — RL799_V2 08-04-2026 --- ## Logging de previews payload/HTML contenant des PII ### Risques - Fuite de données personnelles via logs applicatifs agrégés. ### Symptômes - Logs de debug contenant noms/emails/contenu message en clair. ### Bonnes pratiques / mitigations - Ne jamais logger le body complet d'un message métier en prod. - Journaliser uniquement des métadonnées minimales (id, statut, taille, hash tronqué). - Contexte technique : logs / conformité — RL799_V2 15-04-2026 --- ## Base64 invalide — `Buffer.from(..., 'base64')` ne lève pas d'exception ### Risques - Configuration/signature invalide traitée comme erreur avaleuse (401 répétés sans cause claire). ### Symptômes - Échec systématique de vérification HMAC sans signal de configuration corrompue. ### Bonnes pratiques / mitigations - Valider explicitement le format/base64 attendu avant dérivation HMAC. - Retourner un signal d'erreur opérationnelle explicite (config invalide) côté logs internes. - Contexte technique : crypto / intégration webhook — RL799_V2 15-04-2026 --- ## Dates localisées sans `timeZone` explicite ### Risques - Rendu de date divergent entre dev/CI/prod selon TZ machine. ### Symptômes - Même ISO affiché sur des jours différents selon environnement. ### Bonnes pratiques / mitigations - Toujours passer `timeZone` dans `toLocaleDateString`/`Intl.DateTimeFormat` pour les sorties métier. - Définir une timezone métier unique pour les communications utilisateur. - Contexte technique : dates / formatage serveur — RL799_V2 15-04-2026 --- ## Dérive silencieuse DTO liste vs DTO détail ### Risques - Un DTO "détail" expose un ensemble complet de champs métier, pendant qu'un DTO "liste" ne propage qu'un sous-ensemble jugé "suffisant" au moment où il est créé - Au fil du temps, le front a besoin de plus de champs et découvre que les DTOs de liste sont **amputés** — workarounds ad-hoc, champs morts produits jamais consommés, helpers partagés impossibles à appeler sur les listes sans cast ### Symptômes - Un consommateur front appelle l'endpoint détail juste pour obtenir un champ qui existe côté détail mais pas liste (N+1 réseau déguisé) - Workarounds ad-hoc (`soireeClosedAt: Date | null` dans un mapper TenueSummary, copie partielle de champs) parce que le champ racine manque - Helper partagé (`getSoireeLifecycle(input)`) qui accepte un `SoireeLifecycleInput` qu'**aucun** DTO de liste n'implémente réellement - Type "sous-ensemble" (`SoireeCalendarStatus = 'draft' | 'pending_vm_approval' | 'published'`) aligné sur un filtre SQL transitoire plutôt que sur la sémantique du domaine ### Bonnes pratiques / mitigations - **Règle par défaut** : DTO liste = sous-ensemble de DTO détail, pas un type parallèle. Extraire une base commune si besoin (`SoireeCore`). - Pour chaque champ scalaire ajouté au DTO détail, se poser la question : doit-il aussi être dans les DTOs de liste ? Si oui, le propager sur-le-champ - **Typage fort sur les sous-ensembles** : `SoireeCalendarStatus = SoireeStatus` (alias) plutôt qu'une union locale qui reflète un filtre SQL - Test de coverage statique qui vérifie, pour chaque DTO ciblé, que tous ses mappers exposent les champs requis - Audit périodique après une livraison qui ajoute des champs (ex : `openedAt` persistant) : lister les DTOs de liste et vérifier qu'aucun n'est amputé - Contexte technique : DTO / contrats partagés — RL799_V2 23-04-2026 --- ## Notification `linkUrl` non rôle-aware → page vide / 403 silencieux ### Risques - Une notification envoyée à N destinataires multi-rôles avec un `linkUrl` constant route certains utilisateurs vers une page à laquelle ils n'ont pas accès - Symptôme côté membre : "la notif m'envoie sur une page vide" — UX cassée sans message d'erreur explicite ### Symptômes - Code de création de notif qui fait `recipients.map((r) => ({ linkUrl: 'constant' }))` sans lire `r.role` - Notif qui cible plusieurs rôles (ex : "tous les membres") mais utilise un linkUrl pointant vers un module à accès restreint ### Bonnes pratiques / mitigations ```typescript // Toujours sélectionner role dans le select des recipients const recipients = await prisma.user.findMany({ where: { isActive: true, role: { in: [...ROLES_ALL_ACTIVE] } }, select: { id: true, role: true }, }); // Brancher le linkUrl par rôle const secretariatRoles = new Set(['secretaire', 'venerable', 'admin']); linkUrl: secretariatRoles.has(recipient.role) ? `/secretariat?soireeId=${id}` : `/tenues?tab=calendrier`; ``` **Règle d'or** : le `linkUrl` d'une notif doit ouvrir une page **que l'utilisateur a le droit de voir ET où le contexte de la notif est visible**. Un membre qui reçoit "Soirée annulée" doit atterrir sur le calendrier (carte rouge), pas sur un module secrétariat qu'il ne peut pas consulter. **Test E2E suggéré** : publier une notif multi-rôles, se connecter avec chaque rôle, cliquer, vérifier que chacun arrive sur une page accessible et pertinente. - Contexte technique : notifications / RBAC — RL799_V2 23-04-2026 --- ## Matrice documentée ≠ code — dérive silencieuse ### Risques - Une matrice de permissions / contrats publiée dans une story (markdown) diverge discrètement de l'implémentation - La doc dit "X peut Y", le code refuse Y à X (ou inversement). Aucun test ne couvre la combinaison rare - La divergence se paye au prochain audit RBAC ou au touchement suivant du module — souvent par surprise ### Symptômes - Story d'origine qui annonce une perm que le code ne grant pas (ou inversement) - Un nouvel agent lit la story et la matrice, pense que la perm est active, et écrit du code qui repose dessus → faux positif aval - Bug détecté plusieurs cycles après publication, par hasard ### Bonnes pratiques / mitigations 1. **Audit pré-flight systématique** avant tout PATCH d'un module RBAC : `grep -rn '' apps/` pour confirmer les call sites, comparer avec la matrice de la story d'origine 2. **Réconciliation atomique** : si on touche un helper de permission, mettre à jour les **deux couches** (granulaire `permissions.ts` + fonctionnelle `documentPermissions.ts`) dans la même PR 3. **Test de matrice dédié** : un test unitaire qui itère la matrice de la story et vérifie chaque cellule. Casse à la première dérive 4. Préférer **un seul source of truth** (le code) et générer la doc automatiquement (markdown depuis tests, ou inverse) - Contexte technique : RBAC / documentation — RL799_V2 20-04-2026 --- ## Format `User.id` : UUID OU slug, jamais les deux ### Risques - Un schéma où `User.id` est un `String` libre finit par mélanger deux formats : IDs lisibles du seed (`admin`, `membre-m05`) et vrais UUIDs générés à l'invitation - Conséquence : impossible de mettre `z.string().uuid()` dans les DTOs qui prennent un `userId` sans casser la prod - Surface d'injection grande (payloads de 100 caractères acceptés au lieu de UUID stricts) ### Symptômes - Schéma Zod avec `z.string().min(1).max(128)` là où on voudrait `z.string().uuid()` - Commentaire "l'ID n'est pas forcément un UUID, on accepte toute chaîne" - Deux populations d'ids coexistantes en base (seed slug + invitations UUID) ### Bonnes pratiques / mitigations - Décider tôt : soit `@default(uuid())` côté Prisma partout, soit IDs structurés documentés avec une regex stricte (`^[a-z]+-[a-z0-9]+$`) publiée dans un helper shared (`isValidUserId`) - **Ne jamais mélanger** - Ajouter un test d'invariant : à la fin du seed, assert que tous les `users.id` matchent le format choisi - Si migration vers UUID en cours de route : prévoir un script qui propage sur **toutes** les FKs (`audit_logs.user_id`, `notifications.recipient_id`, `refresh_tokens.user_id`, et tout `@relation` vers `User`) - Pattern de migration : UUID v5 déterministe via `seedUserId(slug)` (cf. `pattern-uuid-v5-deterministe-seed` dans `patterns/prisma.md`) - Contexte technique : Prisma / Zod — RL799_V2 22-04-2026 --- ## Web Push `topic` header > 32 chars rejeté/tronqué (RFC 8030) ### Risques - La [RFC 8030 §5.4](https://datatracker.ietf.org/doc/html/rfc8030#section-5.4) limite le header `Topic` à 32 caractères URL-safe - FCM tronque silencieusement (topics distincts pour deux notifs censées dédupliquer), Apple Push rejette la requête, Mozilla autopush comportement variable - Symptôme : déduplication absente → avalanche de notifs au reconnect d'un device offline ### Symptômes - Push provider qui retourne 4xx sur des `topic` longs - Plusieurs notifs reçues là où une seule devrait l'être ### Bonnes pratiques / mitigations ```typescript import crypto from 'node:crypto'; const hashTopic = (seed: string): string => crypto.createHash('sha256').update(seed).digest('base64url').slice(0, 32); await webpush.sendNotification(sub, body, { TTL: 86_400, urgency: 'high', topic: hashTopic(`${type}-${contextId}`), // toujours ≤ 32 chars URL-safe }); ``` **Notes** : - `base64url` (Node `crypto` natif depuis 16.x) produit un encoding URL-safe (`A-Za-z0-9_-`) - Tronquer à 32 chars **après** encoding base64url, pas avant le hash - Test unitaire : assert `topic.length <= 32` ET `topic.match(/^[A-Za-z0-9_-]+$/)` pour toutes les seeds réalistes - Contexte technique : Web Push / RFC 8030 — RL799_V2 28-04-2026 --- ## Lib npm avec types annoncés mais non embarqués ### Risques - Certaines libs Node prétendent embarquer leurs types TS depuis une version donnée mais le package npm publié ne les contient pas - `@types/` DefinitelyTyped existe mais peut être legacy, non maintenu, ou en conflit avec les exports réels du package ### Symptômes - `Could not find a declaration file for module ''. … Try \`npm i --save-dev @types/\`` - TS7016 après `pnpm add ` alors que la doc annonce que les types sont embarqués ### Bonnes pratiques / mitigations Créer une déclaration TS locale minimaliste qui couvre uniquement la surface consommée par le projet : ```typescript // apps/api/src/types/web-push.d.ts (exemple) declare module 'web-push' { export interface PushSubscriptionLike { endpoint: string; keys: { p256dh: string; auth: string }; } export interface RequestOptions { TTL?: number; urgency?: 'very-low' | 'low' | 'normal' | 'high'; topic?: string; } export function setVapidDetails(subject: string, publicKey: string, privateKey: string): void; export function sendNotification( sub: PushSubscriptionLike, payload?: string | Buffer | null, options?: RequestOptions, ): Promise<{ statusCode: number; body: string; headers: Record }>; const _default: { setVapidDetails: typeof setVapidDetails; sendNotification: typeof sendNotification }; export default _default; } ``` **Bénéfices** : - on est maître du contrat utilisé (si la lib évolue, on étend volontairement) - pas de dépendance `@types/*` legacy - documentable : commentaire JSDoc en tête `Pourquoi pas @types/` **Préventif** : - `tsconfig.json` doit `include` le dossier `src/types/**/*.d.ts` - documenter en commentaire en tête du `.d.ts` POURQUOI on a écrit ça soi-même - Contexte technique : TypeScript / npm — RL799_V2 28-04-2026 --- ## Form HTML POST dans un mail = neutralisé par tous les clients ### Risques - Un `
` placé dans le corps HTML d'un mail transactionnel est **neutralisé par tous les clients mail majeurs** — c'est une mesure anti-phishing universelle, pas un bug - Toute donnée structurée doit transiter par **l'URL** d'un GET (query string ou path), donc visible côté visiteur ### Symptômes | Client | Comportement réel sur `` | | --- | --- | | Gmail web | Rewrite l'action en GET, body en query string | | Gmail iOS/Android | Bouton inactif ou ouvre en GET | | Outlook web | Strip le `` complètement | | Apple Mail (macOS/iOS) | Désactive le submit, bouton no-op | | Thunderbird | Bloqué par sécurité | ### Bonnes pratiques / mitigations Mitigations pour ne pas exposer la donnée dans l'URL navigable : 1. **Pattern token signé court** (HMAC ou JWT) : encode la donnée dans un token opaque dans la query string, échangé immédiatement côté client contre un état serveur, puis `history.replaceState()` pour nettoyer l'URL (cf. `pattern-magic-link-url-clean` dans `patterns/auth.md`) 2. **Token one-shot DB** : génère un token aléatoire stocké en DB, consommé à la 1ʳᵉ requête, expire ensuite 3. **Cookie de session courte** : le 1ᵉʳ hit set un cookie httpOnly puis redirige vers une URL clean À documenter dans toute spec de magic link / RSVP / one-shot URL pour éviter qu'un dev parte sur un POST mail. - Contexte technique : email transactionnel — RL799_V2 30-04-2026 --- ## env vars frontend-facing — fail-fast strict hors dev (pas de fallback `localhost`) ### Risques - Un mail prod qui contient un lien `http://localhost:3000/foo` parce que `APP_URL` n'a pas été défini sur l'instance prod - Aucun signal serveur, aucune erreur au déploiement, aucune trace en logs. L'utilisateur final clique → page introuvable - Le fallback dev-friendly (`process.env.APP_URL ?? 'http://localhost:3000'`) cache l'erreur de config en non-dev ### Symptômes - URL `localhost` dans des emails reçus par des utilisateurs réels - Détection uniquement par un humain qui reçoit le mail, pas par le serveur ### Bonnes pratiques / mitigations ```typescript export const getBaseUrl = (): string => { const raw = process.env.APP_URL; if (raw !== undefined && raw !== '') return raw.replace(/\/+$/, ''); if (process.env.NODE_ENV === 'development') return 'http://localhost:3000'; throw new Error('APP_URL non configuré (requis hors dev). Le bouton ... pointerait vers un host invalide.'); }; ``` - Dev local : fallback silencieux (workflow attendu) - Prod / staging / test : throw au premier appel → erreur visible dans les logs du dispatch - Le throw au boot du dispatch est préférable à un mail dégradé silencieux **Variantes à étendre** : tout helper qui construit une URL frontend depuis le backend (reset password, invitation, convocation, notification mail) doit utiliser le même helper centralisé. Une seule source de vérité par projet — éviter le doublon `APP_URL` + `APP_BASE_URL`. **Test** : couvrir les 4 cas (env défini avec slash, env défini sans slash, env undefined NODE_ENV=dev → fallback, env undefined NODE_ENV=prod → throw). - Contexte technique : config / mails transactionnels — RL799_V2 29-04-2026 --- ## Fonction `deleteOlderThan` exposée sans cron caller — dette silencieuse ### Risques - Une fonction de purge existe dans un repository (`deleteOlderThan(days)`, `purgeOlderThan(date)`) avec un commentaire du type "préparation pour future politique de rétention" mais aucun caller ne l'invoque jamais en prod - À faible volume c'est invisible ; à mesure que la table grossit, l'index sur `(userId, createdAt)` ou `(createdAt)` se dégrade linéairement et ralentit les queries les plus chaudes (dashboard) ### Symptômes - Fonction de purge avec JSDoc "non exposé via API", aucun caller documenté - `EXPLAIN ANALYZE` révèle un scan d'index dégradé sur une table jamais purgée — diagnostic difficile car la cause est invisible côté code applicatif ### Bonnes pratiques / mitigations À l'ouverture de toute fonction `delete*OlderThan`, vérifier : 1. Caller documenté dans le JSDoc (route admin ? cron ? script manuel ?) 2. Cron actif (crontab, scheduler in-process, job BullMQ) qui l'invoque réellement 3. Audit log écrit à chaque exécution (sinon impossible de savoir si la purge tourne en prod) 4. Endpoint admin `GET /maintenance/stats` exposant `total` + `oldestRow` pour observer la croissance Si la rétention est métier (RGPD 12/24 mois), exposer un endpoint admin `POST /maintenance/purges` avec un mode `dryRun` (retourne les compteurs sans supprimer pour valider la politique avant de tirer). - Contexte technique : backend / rétention — RL799_V2 05-05-2026 --- ## Couplage framework (NestJS) dans `shared/utils/` ### Risques - Un helper utilitaire dans `shared/utils/` jette directement une `HttpException` NestJS (ou un autre objet framework) - L'util devient non réutilisable hors contexte HTTP (workers, jobs cron, CLI), force les tests à mocker le framework, et l'appelant perd la possibilité de différencier les causes d'échec (ex: `degraded` Redis down vs `exceeded` vraie limite) ### Symptômes - `import { HttpException } from '@nestjs/common'` dans un fichier `shared/utils/` - Test d'un util obligé d'instancier ou mocker un contexte HTTP ### Bonnes pratiques / mitigations Le helper retourne un union discriminé framework-agnostic ; le service Nest traduit en exception : ```typescript // shared/utils/daily-quota.ts (zéro import @nestjs/common) export type DailyQuotaResult = | { status: 'ok'; count: number } | { status: 'degraded' } | { status: 'exceeded'; count: number }; // modules/community/community.service.ts const result = await consumeDailyQuota({ ... }); if (result.status === 'exceeded') { throw new HttpException({ error: { code: 'QUOTA_EXCEEDED' } }, HttpStatus.TOO_MANY_REQUESTS); } ``` - Règle : `shared/utils/` reste framework-agnostic. Seul `Logger` est toléré comme dépendance framework (instrumentation transverse). - **Signal review** : import d'un type de transport (`HttpException`, `Response`) dans un fichier `utils/`. - Contexte technique : architecture en couches — app-alexandrie 13-05-2026 --- ## Cache in-process stale dans les tests qui mutent la DB directement ### Risques - Un test mute un modèle via `prisma..update()` direct en fixture, mais les lectures applicatives passent par un cache in-process (TTL, Map module-level, getter memoizé) - Le cache stale fait que le test échoue, ou pire passe pour la mauvaise raison : un test "no-op si pas de X" peut passer parce que le cache stale ne voit jamais le X posé en fixture, masquant un vrai bug ### Symptômes - Test sur un service consommant un cache qui échoue sur une assertion d'effet de bord (mail envoyé, status changé) au lieu d'une assertion logique (test attend `false`, reçoit `false`) - Mutation Prisma directe en fixture sans invalidation du cache correspondant ### Bonnes pratiques / mitigations - Identifier les caches in-process du projet (chercher `cached`, `invalidate*Cache`, getters memoizés, Map module-level) - Exporter l'invalidator de chaque cache (`invalidateCache()`) — utile aux tests ET au code applicatif pour les writes hors handlers normaux - Appeler les invalidators nécessaires dans le `beforeEach` (pas `beforeAll` : la suite peut faire plusieurs mutations) ET immédiatement après chaque mutation directe - Documenter explicitement dans le setup pourquoi l'invalidation est nécessaire - **Pattern de détection** : si un test échoue sur l'effet de bord alors que la logique semble correcte, suspecter le cache stale en premier - Contexte technique : tests / cache in-process — RL799_V2 13-05-2026 --- ## `AuditLog.userId NOT NULL` incompatible avec les actions publiques sans auth ### Risques - Un endpoint public (sans auth) déclenche une mutation auditable (ex: désabonnement public via token), le réflexe est d'écrire dans `AuditLog` - Mais si `AuditLog.userId` a une FK `NOT NULL` sur `User`, on ne peut pas créer une ligne audit pour un acteur anonyme — la FK lève ### Symptômes - Erreur de contrainte FK lors d'un `auditLog.create` dans un handler public sans `userId` authentifié - Action anonyme auditable bloquée par le modèle ### Bonnes pratiques / mitigations Trois options selon le contexte métier : 1. **Logger structuré** (pipeline externe ELK/Sentry, pas la DB) : `logger.info({ type, event, profileId, outcome })`. Zéro friction, mais rétention dépendante des pipelines logs. Choix par défaut RL799. 2. **User système** (`id: 'system'`, un seul row réservé) utilisé comme `userId` des actions anonymes. Audit DB cohérent, mais pollue la table User et complique les queries. 3. **Relâcher la FK** en `userId String?`. Modèle propre, mais tous les call sites doivent gérer le nullable + retro-compat. - Documenter explicitement le choix (JSDoc du handler + catalogue audit : "action publique non auditée en DB — tracée via `logger.info`") - À évaluer avant prod : si une obligation réglementaire impose l'audit DB strict, l'option 1 ne suffit pas → basculer en 2 ou 3 - Les actions admin équivalentes (avec `userId` authentifié) restent dans `AuditLog` - Contexte technique : audit / actions publiques — RL799_V2 13-05-2026 --- ## `http.Server.keepAliveTimeout = 0` ne désactive PAS le keep-alive ### Risques - `keepAliveTimeout = 0` en Node.js signifie "pas de timer de fermeture" : la connexion keep-alive est gardée indéfiniment, pas fermée. Le serveur continue de répondre `Connection: keep-alive` - Utilisé en croyant "couper le keep-alive", `= 0` fait le CONTRAIRE de l'intention courante ### Symptômes - Code de test/prod posant `server.keepAliveTimeout = 0` comme "kill switch" du keep-alive — probablement du code mort qui ne fait rien - Le header `Connection` reste `keep-alive` malgré le réglage ### Bonnes pratiques / mitigations - Pour réellement répondre `Connection: close`, poser l'en-tête via middleware ou fermer explicitement les sockets — pas via `keepAliveTimeout = 0` - Ne jamais utiliser `= 0` comme désactivation du keep-alive ; vérifier empiriquement avant de s'y fier : ```js const s = require('http').createServer((q, r) => r.end('ok')); s.listen(0, () => { s.keepAliveTimeout = 0; require('http').get({ port: s.address().port }, res => console.log(res.headers.connection)); // => "keep-alive", PAS "close" }); ``` - Contexte technique : Node.js / HTTP — app-alexandrie 21-05-2026 --- ## Upsert idempotent + filtre de liste sur attribut d'activité = pollution DB / désync client ### Risques - Un endpoint upsert crée une ressource composite (DM, follow, room) sans attribut d'activité (`lastMessageAt`, `participantCount`), et l'endpoint de liste filtre sur cet attribut (`lastMessageAt: { not: null }`) - Deux problèmes : (1) pollution DB silencieuse — un attaquant crée N ressources vides invisibles dans son UI ; (2) désynchronisation client → état illégal si le mobile dépend du store de liste pour des métadonnées (ex: `peerUserId`) et ne peut donc pas opérer sur la ressource fraîchement créée ### Symptômes - Ressources vides accumulées en DB, jamais visibles côté client (filtre activité) - Client incapable d'envoyer le 1er message / d'agir sur une ressource créée mais sans activité ### Bonnes pratiques / mitigations - **Garbage collect** côté backend : job périodique supprimant les ressources vides depuis > X minutes (le plus propre) - Ou retirer le filtre activité côté liste (exposer aussi les ressources vides — impact UI à arbitrer) - Ou rendre l'écran de détail auto-suffisant : passer les métadonnées critiques en query param (`/messages/[id]?peerUserId=X`) ou exposer un `GET /resource/:id` qui retourne tout le contexte indépendamment du store de liste - **Garde-fou de review** : à chaque ajout d'un endpoint upsert (`POST /resource`), auditer l'endpoint `GET /list` correspondant — si la liste a un filtre activité, l'écran de détail DOIT pouvoir s'auto-suffire - Contexte technique : backend / upsert + REST — app-alexandrie 27-05-2026 --- ## Suppression de champ DB : le typecheck ne couvre PAS les objets construits via `.map()` ### Risques - Après le retrait d'un champ d'un modèle (Prisma ou autre), `tsc` vert ne prouve PAS que tous les call-sites sont nettoyés - L'excess-property-check de TypeScript ne s'applique qu'aux LITTÉRAUX d'objet directs, pas aux objets renvoyés par un callback `.map()`/`.reduce()` (typés "assignable", propriété en trop tolérée) - Un `createMany({ data: items.map(i => ({ champRetiré: i.x })) })` compile et casse au runtime (Prisma : "Unknown argument") ### Symptômes - Typecheck vert (seeds inclus) mais erreur runtime "Unknown argument 'X'" sur un seed/fixture utilisant `.map()` - Champ retiré du modèle mais encore présent dans un callback de construction d'objet ### Bonnes pratiques / mitigations - À chaque retrait de champ, faire un GREP textuel du nom du champ sur tout le repo (seeds, fixtures, scripts inclus) — ne pas se fier au seul typecheck - Lancer le lint/tests sur les seeds et scripts, pas seulement sur les fichiers de la story (ces fichiers accumulent de la dette non vérifiée) - Distinct de « Divergence schéma Prisma / spec story » (champ déclaré dans une story mais absent du schema) : ici le champ existait, a été retiré, et reste référencé via `.map()` - Contexte technique : TypeScript / Prisma — app-alexandrie 02-06-2026 --- ## Gate de seuil sur la valeur entrante au lieu de l'état cumulé ### Risques - Quand un compteur de progression est "non-régressif" (on garde le max), un gate basé sur ce compteur qui lit la valeur du PAYLOAD courant au lieu de la valeur CUMULÉE refuse à tort une action déjà débloquée - Un renvoi d'une valeur plus basse (autre device, rejeu, reset client) bloque une action légitime ### Symptômes - Gate "≥ seuil" qui échoue alors que l'utilisateur a déjà dépassé le seuil sur un autre device - Calcul du `merged = max(persisté, payload)` situé APRÈS le gate au lieu d'avant ### Bonnes pratiques / mitigations - Tout gate basé sur un compteur non-régressif doit porter sur la valeur CUMULÉE (`max(persisté, payload)`), pas sur le seul payload - Calculer le `merged` AVANT le gate, pas après - Contexte technique : backend / progression — app-alexandrie 02-06-2026 --- ## Flag de capacité global non réconcilié lors d'un transfert/réassignation ### Risques - Une capacité utilisateur (`isPractitioner`, `isModerator`) est un BOOLÉEN global dérivé de relations N..1 (anime un pack, modère un forum) - Lors d'un transfert de la relation, le code pose le flag sur le nouveau titulaire mais ne le retire jamais de l'ancien → le flag "colle" et reste à `true` pour d'anciens titulaires, état incohérent qui s'accumule ### Symptômes - Ex-titulaire qui conserve une capacité globale sans plus rien animer/modérer - Réassignation qui ne touche qu'un seul côté de la relation ### Bonnes pratiques / mitigations - Tout transfert de relation doit RÉCONCILIER les deux côtés : poser le flag sur le nouveau ET le retirer de l'ancien s'il ne détient plus aucune relation qui le justifie - Calculer la rétrogradation APRÈS le transfert (la relation courante ne compte plus), dans la même transaction : ```ts if (previous && previous !== next) { await transfer(next); const stillJustified = (await count({ packs: { practitioner: previous } })) > 0 || (await count({ forums: { moderator: previous } })) > 0; if (!stillJustified) await demote(previous); } ``` - **Test obligatoire** : réassigner → l'ancien perd le flag s'il n'a plus rien, le garde s'il anime encore autre chose - Contexte technique : backend / capacités RBAC — app-alexandrie 03-06-2026 --- ## Garde-fou d'un seed destructif (TRUNCATE) — fail-safe obligatoire ### Risques - Un seed qui TRUNCATE toute la base est destructif : exécuté par erreur sur une prod ou une DB distante = perte de données ### Symptômes - Seed avec `TRUNCATE`/`deleteMany` global sans garde-fou, ou garde-fou exécuté après la connexion DB - Garde-fou fail-open (accepte par défaut, refuse sur liste noire) ### Bonnes pratiques / mitigations Règles non négociables pour un seed destructif : 1. Le garde-fou s'exécute AVANT toute connexion DB et AVANT le truncate (sinon il truncate puis refuse) 2. Liste BLANCHE d'hôtes locaux (`localhost`/`127.0.0.1`/`::1`/`db`/`postgres`) ; tout host non listé → REFUS (fail-safe, jamais fail-open) 3. `DATABASE_URL` absente/malformée → REFUS (pas de crash, pas d'accept) 4. Refus aussi si `NODE_ENV=production` 5. Bypass uniquement par flag explicite (`--force`/`SEED_FORCE=1`), jamais activable par accident 6. Tester le garde-fou : prod→refus, DB distante→refus, URL absente→refus, locale→accept, `--force`→accept - Extraire le garde-fou en fonction PURE (`evaluateSeedGuard`) testable sans I/O - Contexte technique : seed / sécurité données — app-alexandrie 03-06-2026 --- ## Migration flag stocké → valeur dérivée : retirer l'ancien flag, pas le laisser mort ### Risques - On remplace un flag booléen stocké (`User.isPractitioner` écrit à chaque assignation) par un calcul dérivé (`count(packs animés) > 0`) exposé via les entitlements - Si l'ancien flag stocké reste écrit sans être lu, c'est du code mort trompeur + une fausse source de vérité concurrente qui peut diverger du calcul dérivé ### Symptômes - Colonne/flag encore écrit dans le code mais lu par personne (dette invisible) - Deux sources de vérité concurrentes pour la même information ### Bonnes pratiques / mitigations - À la bascule, soit supprimer la colonne/le flag stocké et tout code qui l'écrit, soit documenter explicitement pourquoi il survit - Vérifier par grep que plus AUCUNE logique d'accès ne lit l'ancien flag avant de considérer la migration terminée - Le calcul dérivé (source de vérité = relations) est plus robuste car il ne diverge jamais - Contexte technique : backend / source de vérité — app-alexandrie 04-06-2026 --- ## Bypass d'autorisation sur une liste = lookup batché (éviter le N+1) ### Risques - Ajouter un "bypass admin" (rôle court-circuitant une garde) sur un chemin traitant une LISTE d'utilisateurs invite le réflexe `ids.map(id => isAdmin(id))`, qui réintroduit un N+1 silencieux (un `findUnique` par élément), précisément là où le code avait factorisé en `findMany` ### Symptômes - `Promise.all(ids.map(() => fetchUnitaire()))` dans un helper d'autorisation appelé sur une collection - Un appel DB par élément de liste pour une vérification de rôle/flag ### Bonnes pratiques / mitigations - Tout helper d'autorisation dérivé du rôle/d'un flag, appelé sur une collection (interlocuteurs, membres, destinataires), doit exposer une variante BATCH : ```ts const getAdminIdSet = async (ids: string[]): Promise> => { const rows = await prisma.user.findMany({ where: { id: { in: ids }, role: 'ADMIN' }, select: { id: true }, }); return new Set(rows.map(r => r.id)); }; ``` - **Garde-fou de review** : si un nouveau `Promise.all(ids.map(() => fetchUnitaire()))` apparaît, exiger la version batch - Contexte technique : backend / N+1 autorisation — app-alexandrie 04-06-2026 --- ## `expiresAt`/`exp` : epoch en secondes (OIDC/JWT) vs millisecondes (`Date.now()`) ### Risques - Les standards OIDC/JWT (`exp`, `iat`, `expires_in`) sont en SECONDES ; `Date.now()`, `new Date().getTime()` et la plupart des APIs JS sont en MILLISECONDES - Comparer les deux sans conversion ne lève AUCUNE erreur (deux `number`) mais donne un résultat absurde : un `expiresAt` en secondes (~1.7e9) est TOUJOURS `<= Date.now()` en ms (~1.7e12) → tout est jugé "expiré" - Le bug est aggravé par le découpage en lots (un lot écrit le champ, un autre le lit avec la mauvaise unité) et reste invisible tant que le chemin est dormant (derrière un flag off) ### Symptômes - `expiresAt <= Date.now()` ou `< Date.now()` sur un champ issu d'un token/claim OIDC - Tout est jugé expiré dès l'activation du flag ; aucun test ne couvre le chemin dormant ### Bonnes pratiques / mitigations 1. **Comparer en secondes** : `expiresAt <= Math.floor(Date.now() / 1000)`, jamais `<= Date.now()` 2. **Documenter l'unité** dans le type/JSDoc au point d'écriture ET de lecture (`/** epoch en SECONDES */`) 3. **Vérifier la cohérence end-to-end** quand écriture et lecture sont dans des lots/PR différents : tracer qui écrit, dans quelle unité, qui lit 4. **Signal review** : tout `<= Date.now()` / `< Date.now()` sur un champ issu d'un token/claim OIDC est suspect par défaut - Contexte technique : auth / OIDC / unités de temps — RL799_V2 14-06-2026 --- ## Wrapper fail-safe catch-all qui noie les pannes anormales sous les échecs attendus ### Risques - Un repo/service rendu non-bloquant par un `try/catch → return { ok: false }` global traite à l'identique deux causes opposées : l'échec ATTENDU/bénin (collision `@unique` P2002 sur un rejeu) et la panne INATTENDUE (connexion DB perdue, timeout, deadlock — anormal, mérite alerte ops) - Une vraie panne devient indiscernable d'un cas nominal dans les logs, le diagnostic est noyé ### Symptômes - Wrapper qui retourne un booléen `ok` opaque alors que plusieurs causes d'échec ont des implications ops différentes - Logs uniformes pour une collision attendue et une perte de connexion DB ### Bonnes pratiques / mitigations Qualifier l'échec avant de l'avaler : 1. Le wrapper bas-niveau remonte un discriminant SANS rethrow (il reste non-bloquant) : `{ ok: false, collision: code === 'P2002', errorCode: code }` 2. L'appelant module le NIVEAU de log selon le discriminant : `warn` pour l'attendu/bénin, `error` pour la panne inattendue (qui doit remonter au monitoring) 3. Ne jamais se contenter d'un booléen `ok` opaque — un champ de plus dans le type de retour garde le fail-safe ET la visibilité - Cas vécu : `setKeycloakSubForUser` (RL799 K1.4) — catch-all renvoyant `collision` pour toute erreur, corrigé en remontant `errorCode` + log modulé. - Contexte technique : observabilité / fail-safe — RL799_V2 15-06-2026 --- ## Retrait asymétrique front/back — route backend supprimée, call-sites frontend orphelins ### Risques - Supprimer une route backend (cutover, dépréciation, refonte) sans retirer ses call-sites frontend produit des 404 silencieux - Un frontend qui appelle la route via une URL en STRING (`fetch('/api/x')`) continue de COMPILER (pas d'import cassé) mais tape dans le vide → 404 runtime - Si aucun test ne couvre ce parcours bout-en-bout, la suite reste 100% verte malgré le bug ### Symptômes - 404 runtime sur un parcours utilisateur alors que `tsc`/`vue-tsc` et la suite de tests sont verts - Route supprimée côté backend mais référencée par un service/composant frontend ### Bonnes pratiques / mitigations 1. **Retrait SYMÉTRIQUE** : retirer le handler backend ET le service/composant/route frontend dans le même lot. Grep `'/api/'` côté frontend AVANT de considérer le retrait fait 2. **Préférer un 410 Gone à une suppression pure** quand le frontend ne peut pas être nettoyé immédiatement : un 410 avec message clair est une transition lisible (toast affiché), un 404 est opaque. Traiter TOUTES les routes du même retrait de façon homogène 3. **La couverture verte ne prouve PAS le retrait complet** : ajouter/garder un test asserant que le parcours client est soit retiré (route absente, bouton absent), soit géré (410 + message) 4. Attention aux composants PARTAGÉS : une page servant deux modes (reset-password ET invitation) ne doit pas être supprimée si un seul mode meurt — découper finement - Contexte technique : retrait d'API / front-back — RL799_V2 15-06-2026 --- ## Keycloak `start --optimized` incompatible avec un theme/provider monté en volume runtime ### Risques - `--optimized` indique à Keycloak de démarrer SANS re-évaluer les options build-time, en supposant un `kc.sh build` préalable ayant FIGÉ la config dans l'image (theme/provider inclus au build) - Monter un theme en volume runtime (`./themes/x:/opt/keycloak/themes/x:ro`) avec une image non-buildée et `--optimized` provoque soit un refus de démarrer ("The build time option … was changed, please rebuild"), soit un démarrage qui IGNORE le theme (liste figée au build) ### Symptômes - Keycloak refuse de démarrer après ajout d'un theme/provider en volume - Theme monté en volume mais non pris en compte (liste des thèmes figée) ### Bonnes pratiques / mitigations - **Theme/provider en VOLUME runtime → `command: start`** (sans `--optimized`) : Keycloak lit la config et scanne les volumes au démarrage - **Theme/provider DANS l'image → `kc.sh build` puis `start --optimized`** (boot plus rapide, mais rebuild d'image à chaque changement) - Plus largement, pour toute appliance mêlant options build-time et runtime : ne pas combiner `--optimized` (qui présuppose un build) avec une config injectée au runtime. Vérifier au déploiement réel, pas seulement à la lecture du compose - Bonus sécurité : épingler la version d'image et confirmer qu'elle matche la version installée avant un `up` — un up/downgrade Keycloak déclenche une migration de schéma potentiellement destructive - Contexte technique : Keycloak / Docker Compose — RL799_V2 16-06-2026 --- ## Helpers de comparaison de dates — garder contre `NaN` explicitement ### Risques - Un helper qui accepte `Date | string` et convertit via `new Date(str)` peut recevoir une date invalide (`new Date('invalid')`) - `NaN > x` et `NaN < x` sont TOUJOURS `false` en JS : une date invalide passée à un filtre de fenêtre temporelle produit un `false` silencieux (événement ignoré) au lieu d'une erreur explicite ### Symptômes - Helper de fenêtre temporelle qui retourne `false` sans raison apparente pour certaines entrées - `localDayKey`/comparaison qui produit `NaN` non détecté ### Bonnes pratiques / mitigations - Tester `isNaN(d.getTime())` avant toute comparaison numérique sur une date convertie : ```ts if (isNaN(event.getTime())) throw new Error('Date invalide passée à isEventInSeason'); ``` - Placer le garde en tête du helper, avant toute comparaison `>`/`<` - Cas vécu : `isEventInSeason` dans `packages/shared/src/utils/season.ts`, corrigé en revue v2-3-1. - Contexte technique : dates / validation — RL799_V2 19-06-2026 --- ## Pattern "entité active" : utiliser le champ `status`, jamais reconstruire depuis les bornes temporelles ### Risques - Quand un modèle a un champ `status` (enum `active/archived`, `active/ended`), recoder la requête "trouve l'entité active" via `{ startDate: { lte: now }, endDate: { gte: now } }` au lieu de `{ status: 'active' }` crée une divergence - Ce critère daté : (1) casse avec les données de test où les bornes sont incomplètes/null, (2) diverge silencieusement du service existant si on oublie de les synchroniser, (3) échoue quand la logique "qui est active" change (ex: suspension manuelle) ### Symptômes - Deux services pour la même sémantique avec des critères différents (`status` vs bornes datées) - Query datée qui ne trouve jamais l'entité en test (seed avec `endDate: null`) ### Bonnes pratiques / mitigations - La source de vérité de l'activité est le champ `status`, pas les bornes de dates : `where: { status: 'active' }` - Les bornes restent utiles pour des requêtes analytiques ("quelles saisons couvraient cette date ?") mais pas pour "trouve l'entité courante" - **Signal review** : `{ startDate: { lte: now }, endDate: { gte: now } }` dans un repo dont le modèle possède un champ `status` - Cas vécu : `hospitalierVeilleRepository.getActiveSeason` (bornes datées) divergeait de `seasonRepository.getActiveSeason` (`status`). - Contexte technique : Prisma / source de vérité — RL799_V2 20-06-2026 --- ## Anti-énumération : endpoint à codes différenciés sur un userId cible doit être rate-limité ### Risques - Un endpoint authentifié qui accepte un `:targetUserId` (ou équivalent) et renvoie des codes d'erreur DISTINCTS selon l'état du target (existence `404 USER_NOT_FOUND` vs `403` access denied, abonnement, relation sociale) permet l'énumération - Un attaquant peut spammer le endpoint sur 10 000 userIds différents pour reconstituer le graphe social, les entitlements, ou la présence (user existe / supprimé) — même sans écriture ### Symptômes - Endpoint authentifié sans rate-limit qui expose des relations (follow, blocages, packs partagés), un état calculé (entitlements, scores), ou un signal de présence - Rate-limit présent sur le `GET /eligibility/:targetUserId` mais absent sur le `POST /.../messages` jumeau qui renvoie les mêmes bits d'info via ses codes d'erreur ### Bonnes pratiques / mitigations - **Heuristique d'audit** pour tout nouvel endpoint authentifié : "que peut faire un attaquant qui spam ce endpoint sur 10 000 userIds ?". Si la réponse révèle une information dérivée par accumulation (relation, état calculé, présence), rate-limit obligatoire. Le critère n'est pas "écriture vs lecture" mais "exposition d'information dérivée" - Cibler en particulier : `POST //with/:targetUserId/...`, `GET //eligibility/:targetUserId`, tout endpoint distinguant `404 USER_NOT_FOUND` d'un `403 access denied` selon l'existence du user - Limite type : 60 req/min/user via Redis `incrWithExpireAt`, dégradation permissive si Redis KO - **Clé Redis COMMUNE entre endpoints jumeaux** (`-rate::`) : sinon l'attaquant multiplie sa surface en alternant entre `getEligibility` et le `POST` jumeau - Implémentation type : méthode `assertXxxRateLimit(userId, now)` appelée en première instruction du handler ; constante de limite dans `packages/contracts/.../.schemas.ts` (réutilisable côté mobile pour hint UX) - Contexte technique : sécurité / anti-énumération — app-alexandrie 13-05-2026