PD-3 — Retour d'expérience (REX)¶
1. Résumé exécutif¶
Objectif initial : Définir une infrastructure de files de tâches asynchrones Redis/BullMQ garantissant la fiabilité, persistance, visibilité et exploitabilité des traitements applicatifs.
Résultat obtenu : Module JobsModule livré avec service d'orchestration, health checks, API d'observabilité, et mécanisme de détection force majeure. 8 tests contractuels PASS couvrant les 4 invariants (INV-01 à INV-04).
Verdict d'acceptabilité : ✅ ACCEPTÉ (2026-01-12)
État des tests contractuels :
| Catégorie | PASS | N/A | Total |
|---|---|---|---|
| Nominaux (TC-NOM-*) | 1 | 1 | 2 |
| Erreurs (TC-ERR-*) | 2 | 1 | 3 |
| Invariants (TC-INV-*) | 4 | 0 | 4 |
| Documentation (TC-DOC-*) | 0 | 1 | 1 |
| Non-régression (TC-NR-*) | 0 | 2 | 2 |
| Adversariaux (TC-NEG-*) | 1 | 1 | 2 |
| Total | 8 | 6 | 14 |
2. Points fluides¶
-
Spécification claire et structurée : Les 4 invariants (INV-01 à INV-04) étaient explicites et non ambigus, facilitant le mapping vers les mécanismes techniques.
-
Mapping tests → implémentation direct : Le plan d'implémentation détaillant le mapping TC-* → mécanismes a permis une implémentation ciblée.
-
BullMQ bien documenté : La bibliothèque dispose d'une documentation exhaustive, réduisant les incertitudes sur les comportements (stalled jobs, retry, événements).
-
Tests unitaires avec mocks ioredis : L'utilisation de
ioredis-mocka permis d'exécuter les tests contractuels sans Redis réel en CI. -
Health checks NestJS : L'intégration avec
@nestjs/terminuspour le health check Redis était native.
3. Points difficiles¶
-
TC-INV-03 (persistance après restart) : Test nécessitant un Redis réel. Résolu par création d'un test d'intégration séparé (
pd3-persistence.integration.spec.ts) exécuté uniquement en CI avec service Redis. -
Erreur Watchman macOS : Les tests Jest ne s'exécutaient pas en local à cause d'une erreur watchman. Résolu par
"watchman": falsedans la config Jest. -
Nommage queue BullMQ : BullMQ n'autorise pas les
:dans les noms de queue. Erreur découverte lors de l'écriture du test d'intégration. -
Frontière tests unitaires / intégration : Définir quels tests nécessitent Redis réel vs mock a demandé plusieurs itérations.
-
Tests E2E/chaos hors CI : Les tests TC-NOM-02, TC-ERR-02, TC-NR-*, TC-NEG-01 nécessitent des scénarios kill process/restart service non automatisables en CI standard.
4. Hypothèses révélées tardivement¶
| ID | Hypothèse découverte | Impact |
|---|---|---|
| H-T1 | Les tests d'intégration Redis requièrent un service externe en CI | Ajout service redis:7-alpine dans .gitlab-ci.yml |
| H-T2 | Jest watchman pose problème sur macOS avec certaines configurations | Désactivation globale watchman |
| H-T3 | BullMQ a des restrictions sur les caractères des noms de queue | Adaptation du nommage des queues de test |
| H-T4 | Les tests E2E nécessitant restart de services ne sont pas automatisables en CI classique | Tests marqués N/A, validés manuellement |
5. Invariants complexes¶
| Invariant | Complexité | Commentaire |
|---|---|---|
| INV-01 | Moyenne | Vérifié via removeOnComplete: false et audit des états. Dépend de la configuration Redis AOF. |
| INV-02 | Faible | Implémenté via API /jobs/:queue/:jobId/status et méthode getJobStatus(). |
| INV-03 | Élevée | Requiert Redis réel pour validation. Test d'intégration créé. Dépend de AOF, stalledInterval, Systemd. |
| INV-04 | Faible | Implémenté via listeners on('failed'), on('stalled') et logs structurés. |
TC-INV-03 est le test le plus sensible aux régressions car il dépend de : - Configuration Redis AOF (appendonly yes) - Configuration BullMQ (stalledInterval, lockDuration) - Politique restart Systemd - Bonne fermeture des connexions (queue.close())
6. Dette technique¶
| Dette | Justification | Impact |
|---|---|---|
| Pas de métriques Prometheus | Hors scope MVP, Bull Board optionnel | Monitoring limité à logs/API |
| Tests E2E/chaos manuels | Non automatisables en CI standard | Couverture automatisée partielle |
| Pas de Bull Board UI | Optionnel (CA-02 satisfait via API) | Pas d'interface graphique monitoring |
| Runbooks non validés formellement (TC-DOC-01) | Validation manuelle hors CI | Documentation non certifiée |
7. Risques résiduels¶
| Risque | Probabilité | Impact | Mitigation |
|---|---|---|---|
| Redis AOF désactivé en production | Faible | Critique | Vérification config Terraform |
| Worker crash sans graceful shutdown | Moyenne | Modéré | Jobs stalled récupérés automatiquement |
| Queue saturée non détectée | Faible | Modéré | Alertes à configurer (post-MVP) |
| Regression INV-03 si config modifiée | Moyenne | Élevé | Test intégration en CI |
| Force majeure non détectée (checkpoint manquant) | Faible | Élevé | Mécanisme checkDataIntegrity() implémenté |
8. Améliorations de processus¶
| Suggestion | Bénéfice attendu |
|---|---|
| Distinguer tests unit/intégration dès la spec | Évite les itérations sur la stratégie de test |
| Documenter les contraintes de nommage des libs | Évite les erreurs runtime découvertes tard |
| Prévoir un environnement CI avec services (Redis, PG) | Permet les tests d'intégration dès le départ |
| Standardiser la gestion watchman dans le template projet | Évite les blocages locaux récurrents |
| Créer un template de test d'intégration Redis | Réutilisable pour futures US BullMQ |
9. Enseignements clés¶
-
Séparer explicitement les tests unitaires (mocks) des tests d'intégration (services réels) dès la conception pour éviter les ambiguïtés sur la couverture.
-
Les invariants de persistance (INV-03) nécessitent des tests d'intégration ; les mocks ne peuvent pas valider le comportement réel de Redis.
-
Les tests E2E impliquant restart/kill de processus restent difficiles à automatiser en CI et doivent être validés manuellement ou via outils spécialisés (Chaos Monkey).
-
La configuration Jest (watchman, testRegex) impacte significativement l'exécution locale et doit être stabilisée tôt dans le projet.
-
Le mapping invariants → mécanismes → tests dans le plan d'implémentation est un accélérateur d'implémentation à maintenir pour les futures User Stories.