PD-30 — Retrospective¶
1. Contexte¶
| Champ | Valeur |
|---|---|
| Story ID | PD-30 |
| Titre | Configurer session management avec Redis |
| Domaine | auth-identity |
| Projet | ProbatioVault-backend |
| Date de completion | 2026-02-19 |
2. Analyse des Learnings PD-30¶
2.1 Learnings spécifiques à cette story¶
| ID | Learning | Tags |
|---|---|---|
| L-30-01 | Redis mocks must include smembers/sadd for index sets | #redis #testing #mocks |
| L-30-02 | Package uuid@11 required explicitly for v7 (transitive non fiable) | #uuid #dependencies |
| L-30-03 | overrideGuard(Class) > overrideGuard('token') for NestJS DI | #nestjs #testing #di |
2.2 Écarts de Gate¶
| Gate | v1 Score | v2 Score | Delta | Cause principale |
|---|---|---|---|---|
| Gate 3 | 7.5 | 9.0 | +1.5 | ECT-01/02/03 : Specs incomplètes Redis fallback |
| Gate 5 | 6.75 | 8.5 | +1.75 | 5 MAJEURS : Code contracts incomplets |
| Gate 8 | 6.75 | 8.6 | +1.85 | Tests 73% → 100%, mocks incomplets |
3. Patterns Récurrents (Cross-Story)¶
3.1 Pattern "Mock Signature Drift" (6 occurrences)¶
Stories concernées : PD-30, PD-107, PD-28, PD-245, PD-106, PD-241
Symptôme : Les mocks divergent des implémentations réelles, causant des échecs de tests ou des faux positifs en Gate 8.
Exemples : - PD-30 : Redis mocks manquent smembers, sadd, pipeline.setex - PD-107 : Singletons nécessitent jest.doMock + factory - PD-245 : Absence de afterEach(jest.restoreAllMocks) cause pollution
Signal CLAUDE.md :
### Testing / Mocking (OBLIGATOIRE)
**Règle transversale** : Les mocks DOIVENT utiliser `jest.Mocked<Interface>` pour typage strict et `afterEach(jest.restoreAllMocks)` pour isolation.
**Checklist avant soumission Gate 8** :
- [ ] Mocks typés avec `jest.Mocked<T>` ou `jest.MockedFunction<T>`
- [ ] `afterEach(jest.restoreAllMocks)` présent dans tous les describe
- [ ] Signatures de constructeur vérifiées vs mocks
- [ ] Pour Redis : smembers, sadd, pipeline.setex si utilisation de sets/pipelines
3.2 Pattern "Redis Resilience" (4 occurrences)¶
Stories concernées : PD-30, PD-238, PD-28, PD-23
Symptôme : Redis en mode dégradé cause des comportements imprédictibles sans fallback explicite.
Exemples : - PD-238 : "Redis fallback in-memory implementation with TTL" - PD-28 : "revocation store in-memory suffisant MVP mais Redis pour production" - PD-23 : "Rate limiting requires Redis/PostgreSQL from start"
Signal CLAUDE.md :
### Redis Resilience (auth-identity)
**Règle** : Tout module utilisant Redis DOIT implémenter un fallback in-memory avec TTL.
**Pattern obligatoire** :
1. Circuit breaker pour détecter indisponibilité Redis
2. Fallback LRU cache avec TTL = 80% du TTL Redis
3. Reconciliation LWW (Last-Write-Wins) au recovery
4. Observable Prometheus `redis_fallback_active_total`
3.3 Pattern "NestJS Guard Override" (3 occurrences)¶
Stories concernées : PD-30, PD-28, PD-22
Symptôme : Les guards NestJS avec injection de dépendances échouent quand testés avec des tokens string.
Exemples : - PD-30 : overrideGuard(Class) > overrideGuard('token') - PD-28 : "Guards composites NestJS difficiles tester"
Signal CLAUDE.md :
### NestJS Guards Testing
**Règle** : Toujours utiliser `overrideGuard(RealClass)` et non `overrideGuard('STRING_TOKEN')`.
**Raison** : Les providers avec injection sont résolus par classe, pas par token string.
3.4 Pattern "Transitive Dependencies" (3 occurrences)¶
Stories concernées : PD-30, PD-26, PD-107
Symptôme : Les dépendances transitives (hoistées) ne sont pas fiables pour les tests ou l'exécution.
Exemples : - PD-30 : uuid via typeorm non fiable → npm install uuid@11 explicite - PD-26 : jose v6 ESM-only nécessite Vitest au lieu de Jest
Signal CLAUDE.md :
### Dependency Management
**Règle** : Toujours installer explicitement les packages utilisés directement, même si disponibles transitoirement.
**Exemples** :
- `uuid` : Installer `uuid@11` même si typeorm l'inclut
- `jose` : Vérifier ESM/CJS avant choix du test runner
3.5 Pattern "Fail-Closed Security" (4 occurrences)¶
Stories concernées : PD-238, PD-239, PD-26, PD-22
Symptôme : Comportement permissif par défaut lors d'erreurs de sécurité.
Exemples : - PD-238 : "timing-safe comparison (crypto.timingSafeEqual)" - PD-239 : "secret validation fail-closed" - PD-26 : "fail-closed JWKS signal observable critique (HTTP 503)"
Signal CLAUDE.md :
Déjà documenté dans CLAUDE.md (Section "Quality Gates NON NÉGOCIABLES").
4. Recommandations¶
4.1 Améliorations priorité haute (applicables immédiatement)¶
| Action | Fichier cible | Impact attendu |
|---|---|---|
| Ajouter checklist mocks dans prompt 7a | templates/prompts/7a-review-tests.md | Réduire Gate 8 itérations |
| Ajouter section "Dépendances de test" | templates/prompts/6b-agent-task.md | Éviter uuid/ESM surprises |
4.2 Améliorations priorité moyenne (prochaine story auth-identity)¶
| Action | Fichier cible | Impact attendu |
|---|---|---|
| Template mock typé | templates/code/mock-template.ts | Standardiser mocks |
| Matrice INV → tests obligatoire | templates/outputs/PD-XX-acceptability.md | Traçabilité accrue |
4.3 Signaux CLAUDE.md (nécessite validation humaine)¶
Les patterns 3.1, 3.2, 3.3, 3.4 justifient des ajouts au CLAUDE.md :
- Section "Testing / Mocking" : Checklist mocks obligatoire
- Section "Redis Resilience" : Pattern fallback systématique
- Section "NestJS Guards" : Règle overrideGuard
- Section "Dependencies" : Règle installation explicite
5. Métriques Domaine auth-identity¶
5.1 Stories récentes¶
| Story | Gates | Score final | Durée | Itérations totales |
|---|---|---|---|---|
| PD-30 | 3+5+8 | 8.6 | 8h | 6 |
| PD-31 | 3+5+8 | 8.18 | 14h | 3 |
| PD-241 | 3+5+8 | ~8.0 | ~10h | 6 |
| PD-239 | 3+5+8 | 8.0 | ~8h | 5 |
| PD-238 | 3+5+8 | ~8.0 | ~12h | 6 |
5.2 Tendances¶
- Convergence : Score final moyen 8.2/10 (bon)
- Itérations : Moyenne 5.2 itérations (amélioration possible)
- Patterns récurrents : Testing/Mocking = 40% des écarts Gate 8
6. Conclusion¶
PD-30 confirme les patterns récurrents du domaine auth-identity :
- Testing reste le point faible principal (mocks, isolation)
- Redis resilience est désormais bien maîtrisé (learnings PD-238)
- NestJS DI nécessite une documentation explicite
Recommandation principale : Ajouter une checklist "Mocking alignment" dans le prompt de review tests (7a) pour réduire les itérations Gate 8.
Rétrospective générée le 2026-02-19 par Claude (Étape 10)