mirror of
https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech
synced 2026-04-27 23:08:16 +02:00
capitalisation: intégration 33 propositions RL799_V2 (triage 2026-04-07)
Backend: 21 entrées (general, prisma, contracts, auth, patterns) Frontend: 9 entrées (navigation, tests, general, performance, patterns) Workflow: 5 entrées (story-tracking) Nouveau fichier: backend/patterns/general.md 95_a_capitaliser.md purgé. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
MaksTinyWorkshop
@@ -8,11 +8,11 @@ Avant toute proposition backend, identifie le fichier dont le nom et la descript
|
||||
|
||||
| Fichier | Domaine | Entrées clés |
|
||||
|---------|---------|--------------|
|
||||
| `auth.md` | Auth, sessions, guards, accès | AuthN/AuthZ dispersée, guard global manquant, null-check request.user, AdminRoleGuard sans @RequireAdminRole, GET sans contrôle accès, cookie après révocation, mock session sans expiresAt, buildApp partagé e2e |
|
||||
| `contracts.md` | Contrats, validation, codes erreur | Contrats implicites, erreurs non standardisées, duplication constantes, schema orphelin, code erreur générique 409, ForbiddenException pour validation |
|
||||
| `prisma.md` | Prisma, DB, transactions, migrations | @unique nullable, TOCTOU transaction, OR tenantId null, nextOrder race condition, tenantId sans FK, schema divergence spec, getter manquant, init module build, clearAllMocks imbriqué, cursor non validé |
|
||||
| `auth.md` | Auth, sessions, guards, accès | AuthN/AuthZ dispersée, guard global manquant, null-check request.user, AdminRoleGuard sans @RequireAdminRole, GET sans contrôle accès, cookie après révocation, mock session sans expiresAt, buildApp partagé e2e, champ absent JWT, email login vs contact |
|
||||
| `contracts.md` | Contrats, validation, codes erreur | Contrats implicites, erreurs non standardisées, duplication constantes, schema orphelin, code erreur générique 409, ForbiddenException pour validation, process.env direct, statut métier non propagé |
|
||||
| `prisma.md` | Prisma, DB, transactions, migrations | @unique nullable, TOCTOU transaction, OR tenantId null, nextOrder race condition, tenantId sans FK, schema divergence spec, getter manquant, init module build, clearAllMocks imbriqué, cursor non validé, enum-like String, migration manuelle hors git, relation 1:1 sans unique |
|
||||
| `stripe.md` | Stripe, paiements, webhooks, subscriptions | billing_cycle_anchor vs current_period_end, list() sans has_more, concurrence trial→payant, non-idempotence, 200 pendant processing |
|
||||
| `nestjs.md` | NestJS, controllers, providers | TooManyRequestsException NestJS 11, controller corrompu insertions, repository dead layer, interface provider incomplète |
|
||||
| `redis.md` | Redis, cache, quotas, TTL | Thrash connexion sous charge, entitlements TTL > SLA, compteurs in-memory, TTL heure locale ±12h |
|
||||
| `nextjs.md` | Next.js, build, routing | Prisma init au chargement module, server-only dans repositories, redirect boucle infinie feature flags |
|
||||
| `general.md` | Observabilité, migrations, performance | Observabilité insuffisante, migrations non reproductibles, upsert N+1 provider |
|
||||
| `general.md` | Observabilité, migrations, performance, architecture | Observabilité insuffisante, migrations non reproductibles, upsert N+1, authorize-after-fetch, valeur sentinelle DTO, idempotence endpoint, fichier orphelin, mélange Date UTC/locale, champ fantôme Zod, catch vide, params non validés, cast TS brut, chevauchement temporel, TOCTOU, biais agrégation, couplage types erreur, service HTTP-aware, count sans filtre, env top-level |
|
||||
|
||||
@@ -5,8 +5,8 @@ bucket: risques
|
||||
tags: [auth, guards, request-user, sessions, admin]
|
||||
applies_to: [implementation, review, debug]
|
||||
severity: high
|
||||
validated_on: 2026-03-24
|
||||
source_projects: [app-alexandrie]
|
||||
validated_on: 2026-04-07
|
||||
source_projects: [app-alexandrie, RL799_V2]
|
||||
---
|
||||
|
||||
# Backend — Risques & vigilance : Auth
|
||||
@@ -234,3 +234,52 @@ it('retourne 403 si subscription inactive', async () => {
|
||||
- **Règle** : ne jamais tenter de surcharger un mock partagé dans un `it` — créer un `buildApp` isolé avec `app.close()` en fin de test
|
||||
|
||||
- Contexte technique : NestJS / Jest e2e — app-alexandrie 24-03-2026
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-champ-metier-absent-jwt"></a>
|
||||
## Champ métier absent du JWT — découplage silencieux frontend/backend
|
||||
|
||||
### Risques
|
||||
|
||||
- Le frontend lit un champ dans `decodeJwtPayload(token)` qui n'est jamais émis par le service d'authentification
|
||||
- Le comportement est silencieux — `undefined` est traité comme `''`, aucune erreur visible, l'UI se dégrade sans signal d'alerte
|
||||
|
||||
### Symptômes
|
||||
|
||||
- `decodeJwtPayload(token).field` retourne `undefined` pour tous les utilisateurs réels
|
||||
- Filtres de grade/rôle côté UI entièrement inopérants (rank=0, aucune tab affichée)
|
||||
|
||||
### Bonnes pratiques / mitigations
|
||||
|
||||
- Toute donnée lue via `decodeJwtPayload` côté frontend doit être explicitement émise dans le payload JWT côté backend
|
||||
- Lors de l'ajout d'un champ à `JwtPayload` (type TypeScript), vérifier immédiatement que le service d'authentification inclut ce champ à l'émission
|
||||
- Ajouter un test d'intégration login → decode qui vérifie la présence des champs critiques dans le token retourné
|
||||
- **Signal review** : un champ apparaît dans le type `JwtPayload` côté frontend sans modification correspondante dans `authService.ts`
|
||||
|
||||
- Contexte technique : JWT / auth — RL799_V2 02-04-2026
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-email-login-vs-contact-annuaire"></a>
|
||||
## Confusion email login / email de contact dans un endpoint annuaire
|
||||
|
||||
### Risques
|
||||
|
||||
- Le mapping de l'endpoint annuaire utilise `email: user.email` (email de login, toujours présent) alors que l'intention est d'exposer un email de contact optionnel
|
||||
- Même un utilisateur à bas privilège peut récupérer les emails de login de tous les membres
|
||||
|
||||
### Symptômes
|
||||
|
||||
- `email: user.email` dans le mapping d'un endpoint de type "annuaire" ou "liste membres"
|
||||
- Emails de connexion exposés à tous les utilisateurs authentifiés
|
||||
|
||||
### Bonnes pratiques / mitigations
|
||||
|
||||
- Dans tout endpoint annuaire ou profil public, distinguer explicitement :
|
||||
- **email de login** : identifiant de compte, JAMAIS exposé à un tiers dans un endpoint annuaire
|
||||
- **email de contact** : champ optionnel dans le profil ou la table directory, exposé uniquement s'il est renseigné
|
||||
- Si le modèle ne dispose pas encore d'un champ email de contact distinct, renvoyer `undefined` pour le champ email dans l'annuaire
|
||||
- **Signal review** : `email: user.email` dans le mapping d'un endpoint annuaire
|
||||
|
||||
- Contexte technique : auth / annuaire — RL799_V2 02-04-2026
|
||||
|
||||
@@ -5,8 +5,8 @@ bucket: risques
|
||||
tags: [contracts, zod, validation, error-codes, requestid]
|
||||
applies_to: [analysis, implementation, review, debug]
|
||||
severity: high
|
||||
validated_on: 2026-03-24
|
||||
source_projects: [app-alexandrie]
|
||||
validated_on: 2026-04-07
|
||||
source_projects: [app-alexandrie, RL799_V2]
|
||||
---
|
||||
|
||||
# Backend — Risques & vigilance : Contracts
|
||||
@@ -198,3 +198,27 @@ Tableau de correspondance :
|
||||
- **Checklist review** : rechercher `process.env` dans `src/` hors `config/` ou `main.ts` — tout hit est suspect.
|
||||
|
||||
- Contexte technique : NestJS / ConfigService — 30-03-2026
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-statut-metier-non-propage-contrat"></a>
|
||||
## Nouveau statut métier non propagé dans le contrat partagé
|
||||
|
||||
### Risques
|
||||
|
||||
- Un repository ou service crée une nouvelle valeur pour un champ enum-like (ex: `'absent_auto'` pour un champ `status: String`) sans la déclarer dans le type DTO ni le schema Zod du package shared
|
||||
- Le champ Prisma étant un `String` sans contrainte DB, l'écriture passe, mais toute lecture avec validation Zod rejetterait la donnée
|
||||
|
||||
### Symptômes
|
||||
|
||||
- String literal non présent dans le type union ou le schema Zod du DTO correspondant
|
||||
- `catch {}` vide dans les repositories qui avalent les erreurs de validation sans log
|
||||
|
||||
### Bonnes pratiques / mitigations
|
||||
|
||||
Quand un repository ou service crée une nouvelle valeur pour un champ enum-like :
|
||||
1. Ajouter la valeur au type DTO dans `packages/shared` (ou équivalent)
|
||||
2. Ajouter la valeur au schema de validation Zod correspondant
|
||||
3. Vérifier que les endpoints de lecture qui parsent ces données acceptent la nouvelle valeur
|
||||
|
||||
- Contexte technique : Zod / contrats partagés — RL799_V2 03-04-2026
|
||||
|
||||
@@ -70,3 +70,371 @@
|
||||
- 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-authorize-after-fetch"></a>
|
||||
## 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
|
||||
|
||||
- Contexte technique : backend général — RL799_V2 02-04-2026
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-valeur-sentinelle-dto-date"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-endpoint-idempotent-sans-doublon"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-fichier-orphelin-echec-persistance"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-melange-date-locale-utc-seed"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-champ-fantome-zod-non-persiste"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-catch-vide-sans-logging"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-params-route-non-valides"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-cast-ts-brut-valeurs-db"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-creation-ressource-temporelle-sans-chevauchement"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-toctou-operations-conditionnelles"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-biais-agregation-moyenne-ratio"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-couplage-semantique-types-erreur"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-service-http-aware"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-count-sans-filtre-user"></a>
|
||||
## 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
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-env-top-level-module"></a>
|
||||
## 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
|
||||
|
||||
@@ -5,8 +5,8 @@ bucket: risques
|
||||
tags: [prisma, transactions, tenant, schema, race-condition]
|
||||
applies_to: [implementation, review, debug, architecture]
|
||||
severity: high
|
||||
validated_on: 2026-03-23
|
||||
source_projects: [app-template-resto, app-alexandrie]
|
||||
validated_on: 2026-04-07
|
||||
source_projects: [app-template-resto, app-alexandrie, RL799_V2]
|
||||
---
|
||||
|
||||
# Backend — Risques & vigilance : Prisma
|
||||
@@ -338,3 +338,49 @@ if (cursor) {
|
||||
3. **Signal review** : tout cast `as EnumType` sur une valeur issue de Prisma = dette à corriger immédiatement.
|
||||
|
||||
- Contexte technique : Prisma / PostgreSQL — app-alexandrie 31-03-2026
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-migration-manuelle-hors-git"></a>
|
||||
## Migration appliquée manuellement hors git
|
||||
|
||||
### Risques
|
||||
|
||||
- Une migration Prisma appliquée via DDL direct + `migrate resolve --applied` produit un fichier `migration.sql` qui peut rester untracked dans git
|
||||
- Quiconque clone le repo et lance `prisma migrate deploy` n'a pas la migration
|
||||
|
||||
### Symptômes
|
||||
|
||||
- `??` (untracked) dans `git status` sur le dossier `prisma/migrations/`
|
||||
- `prisma migrate status` rapporte un drift entre le schéma et l'état de la DB
|
||||
|
||||
### Bonnes pratiques / mitigations
|
||||
|
||||
Checklist minimale après `prisma migrate resolve --applied` :
|
||||
- `git status` → vérifier que `prisma/migrations/<nom>/migration.sql` est présent et tracké
|
||||
- `git add prisma/migrations/<nom>/` si untracked
|
||||
- Valider que `prisma migrate status` rapporte la migration comme appliquée sans drift
|
||||
|
||||
- Contexte technique : Prisma / migrations manuelles — RL799_V2 02-04-2026
|
||||
|
||||
---
|
||||
|
||||
<a id="risque-relation-1-1-sans-unique"></a>
|
||||
## Relation 1:1 métier sans contrainte `@unique` en DB
|
||||
|
||||
### Risques
|
||||
|
||||
- Un mapping métier 1:1 (ex: planche tracée → document généré) implémenté avec un simple index + `findFirst` crée un risque de backlinks non déterministes en cas d'incohérence de données
|
||||
|
||||
### Symptômes
|
||||
|
||||
- Champ de référence nullable seulement indexé, puis lecture via `findFirst`
|
||||
- Le code suppose l'unicité mais la base ne l'impose pas
|
||||
|
||||
### Bonnes pratiques / mitigations
|
||||
|
||||
- Poser une contrainte `@unique` (nullable) sur la référence quand la relation métier est 1:1
|
||||
- Préférer `findUnique` / lecture déterministe
|
||||
- **Signal review** : si le code suppose l'unicité, la base doit l'imposer explicitement
|
||||
|
||||
- Contexte technique : Prisma / contraintes DB — RL799_V2 06-04-2026
|
||||
|
||||
Reference in New Issue
Block a user