PD-3 — Infrastructure de files de tâches asynchrones (Redis / BullMQ)¶

Epic : PD-193 INFRA

1. Objectif¶

Définir les exigences contractuelles relatives à la mise à disposition d’une infrastructure de gestion de files de tâches asynchrones destinée à supporter les traitements applicatifs utilisant BullMQ.

La présente spécification vise à garantir la fiabilité, la persistance, la visibilité et l’exploitabilité de ces traitements, en cohérence avec les exigences de robustesse, de continuité de service et de confiance utilisateur du produit ProbatioVault.

2. Périmètre / Hors périmètre¶

Inclus¶

• Mise à disposition d’un service de gestion de files de tâches asynchrones supportant BullMQ.
• Persistance de l’état des tâches (en attente, en cours, exécutées, en échec).
• Tolérance aux incidents affectant un composant isolé du service.
• Détection et signalement explicites de toute anomalie affectant l’exécution des tâches.
• Supervision opérationnelle du service (état, activité, anomalies).

Exclu¶

• Définition de l’architecture applicative consommatrice des files.
• Implémentation de la logique métier des tâches.
• Choix d’un fournisseur cloud, d’un hébergeur ou d’un mode de déploiement.
• Optimisation fine des performances applicatives.

3. Définitions¶

4. Invariants (non négociables)¶

5. Flux nominaux¶

Flux FN-01 — Enregistrement et exécution nominale¶

1. Une tâche est enregistrée dans la file.
2. La tâche est prise en charge par un worker.
3. La tâche est exécutée.
4. L’état final de la tâche est persisté et consultable.

Flux FN-02 — Interruption et reprise¶

1. Une tâche est en cours d’exécution.
2. Une interruption du service survient.
3. La tâche reste identifiable avec un état cohérent.
4. Le service se rétablit automatiquement.
5. La tâche reprend ou bascule dans un état d’échec explicite.

5b. Diagrammes¶

Diagramme d’états — Cycle de vie d’une tâche¶

Représente les transitions d’état d’une tâche asynchrone, garantissant qu’aucun état n’est ambigu (INV-02) et que tout état terminal est observable (INV-01, INV-04).

stateDiagram-v2
    [*] --> WAITING : Enregistrement dans la file
    WAITING --> ACTIVE : Prise en charge par un worker
    ACTIVE --> COMPLETED : Exécution réussie
    ACTIVE --> FAILED : Échec d’exécution (INV-04 — signal explicite)
    ACTIVE --> STALLED : Interruption du service (INV-03 — état persistant)
    STALLED --> ACTIVE : Reprise automatique après rétablissement
    STALLED --> FAILED : Échec après épuisement des tentatives
    COMPLETED --> [*]
    FAILED --> [*]

    note right of WAITING : INV-01 — tâche jamais perdue silencieusement
    note right of ACTIVE : INV-02 — état observable à tout moment
    note right of STALLED : INV-03 — état persistant face à interruption

Diagramme de séquence — Flux nominal (FN-01) et interruption (FN-02)¶

Représente les interactions multi-services entre l’application, la file BullMQ, le worker et Redis. Couvre le flux nominal et le scénario de reprise après interruption.

sequenceDiagram
    participant App as Application
    participant Queue as BullMQ Queue
    participant Redis as Redis (persistance)
    participant Worker as Worker

    rect rgb(220, 240, 220)
        note over App, Worker: FN-01 — Enregistrement et exécution nominale
        App->>Queue: add(job)
        Queue->>Redis: PERSIST état WAITING (INV-03)
        Redis-->>Queue: ACK
        Queue-->>App: jobId
        Worker->>Queue: getNextJob()
        Queue->>Redis: UPDATE état → ACTIVE (INV-02)
        Worker->>Worker: Exécution de la tâche
        Worker->>Queue: moveToCompleted(jobId)
        Queue->>Redis: UPDATE état → COMPLETED (INV-01)
    end

    rect rgb(255, 230, 230)
        note over App, Worker: FN-02 — Interruption et reprise
        Worker->>Queue: getNextJob()
        Queue->>Redis: UPDATE état → ACTIVE
        Worker-xWorker: Interruption du service
        Note over Redis: État ACTIVE persisté (INV-03)
        Queue->>Redis: Détection stall timeout
        Redis-->>Queue: Job STALLED identifié (INV-04)
        Queue->>Redis: UPDATE état → ACTIVE (retry)
        Worker->>Queue: getNextJob() (après rétablissement)
        Worker->>Worker: Reprise de la tâche
        alt Exécution réussie
            Worker->>Queue: moveToCompleted(jobId)
        else Échec après retries
            Worker->>Queue: moveToFailed(jobId, error)
            Queue->>Redis: UPDATE état → FAILED (INV-04)
        end
    end

6. Cas d’erreur¶

7. Critères d’acceptation (testables)¶

8. Scénarios de test (Given / When / Then)¶

TC-01 — Exécution nominale¶

• Given une tâche enregistrée
• When le service fonctionne normalement
• Then la tâche est exécutée et son état final est observable

TC-02 — Interruption et reprise¶

• Given une tâche en cours d’exécution
• When une interruption survient
• Then la tâche reste identifiable et le service se rétablit automatiquement

9. Hypothèses explicites¶

10. Points à clarifier¶

• Définition précise de la volumétrie cible.
• Modalités exactes de restitution de l’information utilisateur.
• Liste exhaustive des processus applicatifs consommateurs.

Références¶

• Epic : PD-193 INFRA
• JIRA : PD-3
• Repos concernés : infra / backend
• Documents associés : index.md
• User Stories liées : PD-21 (Setup BullMQ pour jobs asynchrones), PD-23 (Inscription utilisateur avec validation), PD-24 (Authentification SRP-6a, phase 1)