Aller au contenu

PD-13 — Retour d'expérience

📚 Navigation User Story | Document | | | ---------- | -- | | 📋 [Spécification](PD-13-specification.md) | | | 🛠️ [Plan d'implémentation](PD-13-plan.md) | | | ✅ [Critères d'acceptation](PD-13-acceptability.md) | | | 📝 **Retour d'expérience** | *(ce document)* | [← Retour à backend-core](../PD-186-epic.md) · [↑ Index User Story](index.md)

1. Résumé exécutif

La User Story PD-13 visait à initialiser le projet backend NestJS avec une architecture modulaire, TypeScript strict, outils de qualité (ESLint, Prettier, SonarQube), CI/CD GitLab et conteneurisation Docker. L'implémentation fournit une base solide avec tous les modules métier, une CI/CD très complète (incluant CloudHSM), mais présente 4 écarts MAJEURS (Dockerfile non fonctionnel, validation env absente, couverture 80% vs 85%, module jobs incomplet) et 1 écart MINEUR (ADR manquant). Verdict : ACCEPTÉ AVEC RÉSERVES.

2. Points fluides

  • Architecture modulaire : tous les modules métier créés (auth, crypto, documents, audit, storage, jobs, blockchain, vault)
  • Common utilities : structure complète avec decorators, filters, guards, interceptors, pipes
  • TypeScript strict : mode strict activé avec path aliases (@/, @config/, @common/, @modules/)
  • CI/CD GitLab complète : 7 stages (validate, migrate, test, security, sonar, build, docker, deploy)
  • Intégration CloudHSM : jobs dédiés pour validation HSM, tests avec HSM, compilation pkcs11js
  • Tests configurés : Jest avec coverage, tests unitaires, intégration, e2e
  • Qualité code : ESLint avec eslint-plugin-security, Prettier, SonarQube
  • Modules métier riches : auth avec controllers, services, DTOs, entities, strategies, middleware
  • Scripts npm complets : lint, format, type-check, test, build, migrations, docs
  • Sécurité Docker : utilisateur non-root, healthcheck, dumb-init pour PID 1

3. Points difficiles

Difficulté Contexte
Dockerfile multistage npm ci --only=production suivi de npm run build échoue car TypeScript/Nest CLI sont en devDependencies
CloudHSM intégration Nécessite node:20-bookworm (GLIBC 2.32+), compilation pkcs11js avec Python, configuration VPN
Couverture branches Atteindre 85% difficile avec code défensif et early returns
Module jobs Dépendance BullMQ/Redis non initialisée dans cette US fondatrice

4. Hypothèses révélées tardivement

Hypothèse initiale Réalité découverte
npm ci --only=production suffisant pour builder FAUX — TypeScript, Nest CLI requis pour npm run build
@nestjs/config valide automatiquement FAUX — Validation Joi doit être configurée explicitement
Couverture 85% facilement atteignable FAUX — Branches à 80% dues à guards et early returns
Module jobs simple à initialiser FAUX — Dépend de Redis/BullMQ non configurés dans cette US
CloudHSM compatible Alpine FAUX — SDK 5 requiert GLIBC 2.32+ (Debian Bookworm)

5. Invariants complexes à implémenter

Invariant Complexité
TypeScript strict Tous les fichiers doivent compiler sans any implicite
ESLint 0 erreur Règles security peuvent bloquer patterns courants
Path aliases cohérents Synchroniser tsconfig.json, jest moduleNameMapper, nest-cli.json
CI/CD multi-environnement dev (HSM), staging, production avec règles différentes
Docker non-root Permissions fichiers, ports > 1024, healthcheck

6. Dette technique

Dette Impact Priorité
Dockerfile phase builder Image non construisible en l'état HAUTE
Validation env absente Variables invalides non détectées au démarrage HAUTE
Couverture branches 80% Non-conformité spec 85% MOYENNE
Module jobs vide Pas de service ni test, juste module.ts MOYENNE
ADR non créé Documentation architecture absente BASSE
excludes coverage 15+ patterns exclus pour atteindre seuils BASSE

7. Risques résiduels

Risque Probabilité Impact Mitigation suggérée
Docker build échoue Élevée ÉLEVÉ Corriger Dockerfile : installer devDeps pour build
Env var invalide en prod Moyenne ÉLEVÉ Ajouter validation Joi dans ConfigModule
Régression couverture Moyenne MOYEN CI fail si coverage < seuil
Module jobs inutilisable Faible MOYEN Compléter dans PD dédiée (BullMQ)
CloudHSM timeout CI Moyenne MOYEN wake-hsm job + allow_failure

8. Améliorations processus

Amélioration Bénéfice attendu
Tester Dockerfile dans CI Détecter erreur build avant merge
Template module minimal Garantir service + test pour chaque module
Validation env obligatoire Échec rapide si config invalide
Séparer US foundation/métier Ne pas mélanger init projet et modules complexes
ADR template automatique Créer docs/adr/000-template.md dès l'init

9. Enseignements clés

  1. Le Dockerfile doit être testé — Un npm ci --only=production && npm run build ne fonctionne pas car les outils de build (TypeScript, Nest CLI) sont en devDependencies. Le Dockerfile doit installer toutes les dépendances pour builder, puis copier uniquement les artefacts.

  2. La validation des variables d'environnement est critique — Sans schéma Joi, une variable manquante ou invalide ne sera détectée qu'au runtime, potentiellement en production. ConfigModule.forRoot() doit inclure un validationSchema.

  3. Les seuils de couverture doivent être alignés — La spec demande 85% global, le code configure 80% branches. Cette incohérence crée de la confusion et de la dette.

  4. Chaque module doit être complet — Un module sans service ni test (jobs) n'est pas utilisable et crée de la dette. Mieux vaut ne pas créer le dossier que de le laisser vide.

  5. L'intégration CloudHSM complexifie la CI — Les contraintes GLIBC, Python pour pkcs11js, et VPN nécessitent des jobs dédiés et une image Debian (pas Alpine). Cette complexité était sous-estimée.