PD-21 — Retour d'Expérience (REX)¶

Document : Retour d'expérience sur l'implémentation Date de rédaction : 2025-12-23 Statut : ACCEPTÉ (v2)

1. Synthèse¶

1.1 Objectif initial¶

Implémenter un système de traitement asynchrone de jobs avec BullMQ garantissant : - Non-interférence avec le flux principal (API synchrone) - Sémantique d'exécution déterministe et vérifiable (au plus une fois) - Traçabilité consultable des états et événements - Sécurité explicite du backend Redis - Diagnosabilité post-incident compatible avec les exigences probatoires NF Z42-013

1.2 Résultat final¶

ACCEPTÉ après correction de deux écarts : - E-01 (BLOQUANT) : Queues contractuelles absentes - E-02 (MAJEUR) : Unicité d'exécution non garantie sans idempotence

L'implémentation finale couvre tous les invariants de la spécification (I-1 à I-7) et les critères d'acceptation (CA-1 à CA-5).

2. Écarts constatés et résolutions¶

2.1 E-01 — Invariant des queues contractuelles (BLOQUANT)¶

Problème identifié : La spécification exigeait 4 queues contractuelles (DEFAULT, BACKUP, EXPORT, BLOCKCHAIN) mais seule la queue DEFAULT était implémentée initialement.

Cause racine : Interprétation initiale que les queues métier (BACKUP, EXPORT, BLOCKCHAIN) seraient ajoutées par les PDs respectifs (PD-45, PD-48, PD-55). La relecture de la spécification a montré que ces queues étaient contractuelles pour PD-21.

Résolution appliquée : - Ajout des queues BACKUP, EXPORT, BLOCKCHAIN dans queue-names.ts - Mise à jour du mapping job-type-queue-map.ts pour router les job types vers leurs queues - Enregistrement des 4 queues dans jobs.module.ts via BullModule.registerQueue()

Fichiers modifiés : - queue-names.ts - job-type-queue-map.ts - jobs.module.ts

2.2 E-02 — Unicité d'exécution ambiguë (MAJEUR)¶

Problème identifié : L'invariant I-2 "exécution au plus une fois" était garanti au niveau BullMQ (attempts: 1) mais les retries via Prefect créaient de nouveaux jobs avec le même payload, sans contrôle d'idempotence effectif.

Cause racine : La clé d'idempotence (idempotencyKey) était optionnelle dans le DTO et non vérifiée par les processors. Un retry Prefect pouvait produire un effet métier dupliqué (ex: double ancrage blockchain).

Résolution appliquée (Option B du plan d'implémentation) : - Ajout de la méthode abstraite getIdempotencyKey(job): string | null dans BaseProcessor - Vérification d'idempotence obligatoire dans handleJob() AVANT markRunning() - Enregistrement automatique de l'effet après succès via recordEffect() - Jobs déjà traités marqués SKIPPED avec référence au job original - Création de l'entité JobEffect avec contrainte UNIQUE sur (key, effect_type)

Fichiers modifiés/créés : - base.processor.ts - Méthode abstraite + vérification - job-effect.entity.ts - Table d'idempotence - jobs.service.ts - Méthodes checkIdempotency() et recordEffect()

3. Analyse des décisions de conception¶

3.1 Retries explicites via Prefect (I-3)¶

Décision : Aucun retry implicite dans BullMQ (attempts: 1). Les retries sont orchestrés par un flow Prefect schedulé (jobs_dlq_retry_flow).

Avantages : - Traçabilité complète : chaque retry crée un nouveau job avec parent_job_id - Auditabilité : décisions de retry documentées dans Prefect - Flexibilité : politiques de retry configurables par type de job - Conformité I-3 : jamais de ré-exécution implicite sans trace

Inconvénients : - Latence : retry non instantané (délai du prochain run Prefect, par défaut 15 min) - Complexité opérationnelle : nécessite Prefect fonctionnel

Verdict : Décision maintenue. La latence est acceptable pour les jobs asynchrones et la traçabilité l'emporte.

3.2 Idempotence obligatoire vs optionnelle¶

Options évaluées : - Option A : idempotencyKey obligatoire dans le DTO (validation) - Option B : getIdempotencyKey() abstraite dans BaseProcessor (contrat TypeScript)

Choix retenu : Option B

Justification : - Tous les jobs ne nécessitent pas d'effet irréversible à protéger - Le contrat TypeScript force chaque processor à prendre une décision explicite - Retourner null est une décision consciente ("pas d'effet à protéger") - Permet une granularité fine par type de job

3.3 Politique de rétention formalisée (I-5)¶

Décision : - PostgreSQL (job_history) : 30 jours - Redis (BullMQ completed/failed) : 7 jours - Table job_effects : 90 jours (purge en cascade) - Purge automatique via flow Prefect jobs_purge_flow (cron 0 3 * * *)

Justification : - 30 jours DB : suffisant pour audit et diagnostic post-incident - 7 jours Redis : économie mémoire, les états terminaux sont en DB - 90 jours effets : permet de bloquer les retries tardifs accidentels

3.4 Health check hybride (I-6)¶

Architecture retenue : - Réactif : événements BullMQ/ioredis (error, ready, close) - Proactif : endpoint /health/redis pollé par Prefect (redis_health_flow)

Avantages : - Détection instantanée des déconnexions (événements) - Vérifications périodiques complètes (TLS, AUTH, mémoire, latence) - Alertes Prefect Events pour escalade

4. Points de vigilance pour maintenance¶

4.1 Extension des queues¶

Lors de l'ajout d'une nouvelle queue : 1. Ajouter dans QUEUE_NAMES (queue-names.ts) 2. Mettre à jour JOB_TYPE_TO_QUEUE (job-type-queue-map.ts) 3. Enregistrer dans BullModule.registerQueue() (jobs.module.ts) 4. Créer le processor héritant de BaseProcessor

Attention : Les queues ne peuvent PAS être créées dynamiquement (invariant).

4.2 Implémentation d'un nouveau processor¶

Chaque processor DOIT : 1. Hériter de BaseProcessor 2. Implémenter process(job) avec la logique métier 3. Implémenter getIdempotencyKey(job) pour définir la clé d'idempotence 4. Utiliser handleJob() comme point d'entrée (pas process() directement)

Exemple :

@Processor(QUEUE_NAMES.BLOCKCHAIN)
export class BlockchainAnchorProcessor extends BaseProcessor<BlockchainData> {
  getIdempotencyKey(job: Job<JobData<BlockchainData>>): string | null {
    // Clé = hash du document à ancrer
    return job.data.payload.documentHash;
  }

  async process(job: Job<JobData<BlockchainData>>): Promise<JobResult> {
    // Logique d'ancrage...
    const txHash = await this.blockchainService.anchor(job.data.payload.documentHash);
    return this.succeeded({ txHash });
  }
}

4.3 Monitoring essentiel¶

Métriques à surveiller : - jobs_pending_count : nombre de jobs en attente par queue - jobs_failed_count : jobs échoués (alerte si > seuil) - jobs_processing_duration_p95 : latence de traitement - redis_memory_percent : utilisation mémoire Redis (alerte > 80%) - redis_latency_ms : latence ping Redis (alerte > 100ms)

4.4 Graceful shutdown¶

Le worker doit gérer proprement l'arrêt : 1. Arrêter d'accepter de nouveaux jobs 2. Attendre la fin des jobs en cours (timeout configurable) 3. Marquer les jobs non terminés comme FAILED avec raison explicite

5. Leçons apprises¶

5.1 Ce qui a bien fonctionné¶

1. Spécification rigoureuse : Les invariants clairs (I-1 à I-7) ont guidé l'implémentation et facilité l'acceptabilité.

2. Architecture modulaire : Séparation claire entre JobsService (producer), BaseProcessor (consumer), et RedisHealthService (monitoring).

3. Pattern Prefect : Réutilisation du pattern audit_dlq_retry.py pour les retries, cohérence avec l'existant.

4. Traçabilité native : L'entité JobHistory avec ses timestamps et champs de retry offre une vue complète du cycle de vie.

5.2 Ce qui pourrait être amélioré¶

1. Queues contractuelles explicites : La distinction entre queues "core PD-21" et "hypothétiques futures PDs" aurait dû être plus claire dans la spec initiale.

2. Idempotence by design : L'invariant I-7 aurait dû être explicite dès la v1 de la spécification, pas ajouté après audit.

3. Tests d'intégration Redis : Les tests unitaires mockent Redis. Des tests d'intégration avec Redis réel en CI seraient bénéfiques.

4. Documentation des flows Prefect : Les flows Python (jobs_dlq_retry.py, jobs_purge.py, redis_health.py) sont spécifiés mais non implémentés dans ce PR. Créer un ticket de suivi.

5.3 Recommandations pour les futures PDs¶

1. Définir les invariants d'idempotence dès la conception pour tout système avec effets irréversibles.

2. Séparer clairement périmètre "infrastructure" vs "métier" dans la spécification.

3. Prévoir l'acceptabilité dès le début : les critères CA-x doivent être des tests automatisés.

4. Documenter les hypothèses explicitement : tout ce qui n'est pas dit ne doit pas être inféré.

6. Métriques de livraison¶

7. Travaux restants (hors périmètre PD-21)¶

8. Conclusion¶

PD-21 a livré une infrastructure robuste de traitement asynchrone conforme aux exigences probatoires NF Z42-013. Les deux écarts identifiés lors de l'acceptabilité (E-01 et E-02) ont conduit à une implémentation plus solide :

• E-01 a renforcé le contrat sur les queues, évitant une dérive future.
• E-02 a instauré l'idempotence obligatoire, protégeant contre les effets dupliqués sur retry.

La base est prête pour accueillir les processors métier des PDs suivants (PD-45, PD-48, PD-55, PD-72).

Fin du REX — Document validé le 2025-12-23