PD-241 — Retour d'expérience (REX)¶
1. Résumé¶
| Champ | Valeur |
|---|---|
| Story ID | PD-241 |
| Titre | Déconnexion utilisateur (logout) |
| Epic | PD-182 AUTH |
| Projet | ProbatioVault-backend |
| Date livraison | 2026-02-08 |
| Verdict Gate 8 | GO |
2. Périmètre livré¶
Fonctionnalités implémentées¶
- Endpoint
POST /auth/logoutavec authentification JWT obligatoire - Invalidation de la session Keycloak via Admin API
- Révocation du refresh token si présent dans le body
- Format d'erreur contractuel
{error: "ERR-241-*", message: "..."} - Gestion explicite des échecs Keycloak (502 Bad Gateway)
Fichiers créés/modifiés¶
| Fichier | Type |
|---|---|
src/modules/auth/dto/logout.dto.ts | Nouveau |
src/modules/auth/errors/logout.errors.ts | Nouveau |
src/modules/auth/filters/logout-exception.filter.ts | Nouveau |
src/modules/auth/auth.controller.ts | Modifié |
src/modules/auth/auth.service.ts | Modifié |
src/modules/auth/mfa/services/keycloak-admin.service.ts | Modifié |
test/auth/logout.e2e-spec.ts | Nouveau (17 tests) |
3. Conformité spécification¶
Invariants¶
| ID | Règle | Conforme |
|---|---|---|
| INV-241-01 | JWT requis | ✅ |
| INV-241-02 | Invalidation session Keycloak | ✅ |
| INV-241-03 | Invalidation refresh token | ✅ |
| INV-241-04 | Format erreur | ✅ |
| INV-241-05 | Erreur explicite échec Keycloak | ✅ |
| INV-241-06 | Effacement local (hors périmètre) | N/A |
Critères d'acceptation¶
| ID | Critère | Couvert |
|---|---|---|
| CA-241-01 | Rejet sans JWT | ✅ TC-ERR-01 |
| CA-241-02 | Session Keycloak invalidée | ✅ TC-NOM-01 |
| CA-241-03 | Refresh token révoqué | ✅ TC-NOM-02 |
| CA-241-04 | Erreur Keycloak explicite | ✅ TC-ERR-02 |
| CA-241-05 | Format | ✅ TC-ERR-03 |
4. Difficultés rencontrées¶
D-01 : Couverture de tests e2e absente initialement¶
Constat : Le premier cycle d'acceptabilité a identifié l'absence de tests e2e (R-TEST-03).
Résolution : Création de test/auth/logout.e2e-spec.ts avec 17 tests couvrant tous les scénarios contractuels.
Impact : Une itération supplémentaire de l'étape 7 (acceptabilité) a été nécessaire.
D-02 : TC-ERR-01 et TC-ERR-03 non couverts¶
Constat : Les tests unitaires ne couvraient pas le comportement du guard JWT (TC-ERR-01) ni le format contractuel des erreurs (TC-ERR-03).
Résolution : Couverture via les tests e2e qui valident le comportement end-to-end.
Impact : Les tests unitaires seuls sont insuffisants pour valider les guards et filters.
D-03 : Formatage des erreurs logout¶
Constat : Le HttpExceptionFilter global ne suffisait pas pour garantir le format {error: "ERR-241-*", message: "..."}.
Résolution : Création d'un LogoutExceptionFilter dédié avec mapping explicite des exceptions.
Impact : Chaque domaine fonctionnel nécessite potentiellement son propre filter pour un formatage spécifique.
5. Écarts acceptés¶
| ID | Description | Justification |
|---|---|---|
| R-CODE-01 | Timeout 5s non garanti | Contrainte technique v3 |
| R-CODE-02 | Mélange types erreurs | Cohérent avec existant |
| R-CODE-03 | Audit failure isolation | Amélioration future |
| R-SEC-01 | Pas anti-replay refresh | Hors périmètre spec |
| R-SEC-02 | Pas rate limiting | Hors périmètre spec |
6. Enseignements¶
E-01 : Les tests e2e sont indispensables pour les flux d'authentification¶
Les tests unitaires avec mocks ne peuvent pas valider le comportement des guards NestJS ni des exception filters. Les tests e2e sont nécessaires pour vérifier le flux complet.
E-02 : L'atomicité session + refresh token est critique¶
La spécification exige que si le refresh token est présent et que sa révocation échoue, le logout DOIT échouer (INV-241-03). Cette atomicité doit être vérifiée explicitement dans les tests.
E-03 : Le formatage d'erreur contractuel nécessite un filter dédié¶
Pour garantir le format {error: "ERR-241-*", message: "..."} sur toutes les erreurs d'un domaine, un filter dédié est plus maintenable que de modifier le filter global.
7. Hypothèses validées¶
| ID | Hypothèse | Statut |
|---|---|---|
| H-241-01 | Keycloak Admin API supporte DELETE /users/{id}/sessions | ✅ Validé |
| H-241-02 | Refresh token transmis dans body JSON | ✅ Validé |
| H-241-03 | Circuit breaker existant compatible | ✅ Validé |
| H-241-04 | Logout idempotent | ✅ Validé |
8. Impacts processus¶
Recommandations pour les stories futures¶
-
Inclure les tests e2e dès l'étape 6 : Ne pas attendre l'acceptabilité pour identifier les lacunes de couverture.
-
Prévoir un filter dédié pour chaque domaine fonctionnel : Le format d'erreur contractuel est plus facilement garanti par un filter spécifique.
-
Documenter les dépendances hors périmètre : PD-241 dépend de PD-106 pour l'effacement local — cette dépendance doit être tracée.
9. Métriques¶
| Métrique | Valeur |
|---|---|
| Estimation plan | 5.5h |
| Durée réelle (workflow) | ~24h |
| Itérations Gate 3 | 2 |
| Itérations Gate 5 | 3 |
| Itérations Gate 8 | 1 |
| Tests créés | 5 unit + 17 e2e |
| Lignes de code | ~350 |
Généré par Claude Orchestrateur — 2026-02-09