PD-279 — Plan d'implémentation¶

1. Découpage en composants¶

1b. Équivalence terminologique¶

2. Flux techniques¶

2.1 Flux A — Restitution (POST /documents/:id/restitute)¶

Client → RestitutionController.restitute(id)
  │
  ├─ 1. ParseUUIDPipe (validation format) → 400 si invalide
  │
  └─ RestitutionService.restitute(documentId, actorId)
       │
       ├─ 2. Lecture document via DataSource (SELECT ... FOR UPDATE)
       │     → 404 si inexistant
       │
       ├─ 3. Vérification ownership (document.userId === actorId)
       │     → 403 si non owner
       │
       ├─ 4. Vérification état courant
       │     ├─ Si déjà RESTITUTED → 200 idempotent (retour body actuel, pas d'attestation)
       │     └─ Si != SEALED → 409 INVALID_SOURCE_STATE
       │
       ├─ 5. Vérification legal_lock
       │     → 409 DOCUMENT_UNDER_LEGAL_LOCK si true
       │
       ├─ 6. Vérification geo_copy_count >= 2
       │     → 409 INSUFFICIENT_GEO_COPIES si < 2
       │
       ├─ 7. Calcul SLA
       │     restituted_at = NOW() UTC
       │     restitution_deadline = restituted_at + restitution_max_duration
       │
       ├─ 8. Transaction ACID (QueryRunner)
       │     ├─ UPDATE documents SET status=RESTITUTED, restituted_at, restitution_deadline
       │     └─ INSERT lifecycle_log (type=RESTITUTION, actor_id, security_level, timestamp_utc)
       │
       ├─ 9. Post-commit : AuditLogService.logAsync(document.restitute)
       │
       └─ 10. HTTP 200 + body document mis à jour

2.2 Flux B — Retour de restitution (POST /documents/:id/return-from-restitution)¶

Client → RestitutionController.returnFromRestitution(id)
  │
  ├─ 1. ParseUUIDPipe → 400 si invalide
  │
  └─ RestitutionService.returnFromRestitution(documentId, actorId)
       │
       ├─ 2. Lecture document (SELECT ... FOR UPDATE)
       │     → 404 si inexistant
       │
       ├─ 3. Vérification ownership → 403
       │
       ├─ 4. Vérification état courant
       │     ├─ Si déjà SEALED → 200 idempotent
       │     └─ Si != RESTITUTED → 409 INVALID_SOURCE_STATE
       │
       ├─ 5. Transaction ACID
       │     ├─ UPDATE documents SET status=SEALED
       │     └─ INSERT lifecycle_log (type=RETURN_FROM_RESTITUTION, actor_id, security_level, timestamp_utc)
       │
       ├─ 6. Post-commit : AuditLogService.logAsync(document.return_from_restitution)
       │
       └─ 7. HTTP 200 + body document

2.3 Flux C — Contrôle destruction cross-module¶

Module Destruction (routes existantes — 3 routes per INV-279-10)
  │
  ├─ Route 1 : POST /destruction/batches (inclusion)
  │     EligibilityService.selectEligible() ou méthode d'inclusion
  │     Ajouter : vérification explicite status !== 'RESTITUTED' AVANT inclusion
  │     Si RESTITUTED → HTTP 409 DOCUMENT_RESTITUTED_DESTRUCTION_FORBIDDEN
  │     (NB : le filtre SQL `status=EXPIRED` exclut RESTITUTED implicitement,
  │      mais INV-279-10 exige un rejet EXPLICITE avec code erreur, pas un filtre silencieux)
  │
  ├─ Route 2 : POST /destruction/batches/:id/execute (exécution)
  │     EligibilityService.reVerifyEligibility()
  │     Ajouter : if status === 'RESTITUTED' → HTTP 409 DOCUMENT_RESTITUTED_DESTRUCTION_FORBIDDEN
  │     (double vérification anti-race-condition per INV-279-10)
  │
  └─ Route 3 : DELETE /documents/:id (soft-delete)
       DocumentsController.delete() ou service associé
       Ajouter : vérification status RESTITUTED → HTTP 409 DOCUMENT_RESTITUTED_DESTRUCTION_FORBIDDEN

2.4 Flux D — SLA Scheduler (async)¶

RestitutionSlaScheduler (BullMQ cron job)
  │
  ├─ 1. SELECT documents WHERE status=RESTITUTED AND restitution_deadline IS NOT NULL
  │
  ├─ 2. Pour chaque document :
  │     ├─ elapsed_ratio = (NOW - restituted_at) / (restitution_deadline - restituted_at)
  │     │
  │     ├─ Si elapsed_ratio >= 0.80 et alerte non émise
  │     │     → IntegrityJournalService.appendEntry(OPS_ALERT_SENT, {type: 'RESTITUTION_SLA_80'})
  │     │     → AuditLogService.logAsync(document.restitution_sla_alert)
  │     │
  │     ├─ Si elapsed_ratio >= 1.00 et escalade non émise
  │     │     → IntegrityJournalService.appendEntry(SLA_EXCEEDED, {type: 'RESTITUTION_SLA_100'})
  │     │     → AuditLogService.logAsync(document.restitution_sla_escalation)
  │     │
  │     └─ Si NOW > restitution_deadline et RESTITUTION_OVERDUE non émis
  │           → IntegrityJournalService.appendEntry(SLA_EXCEEDED, {type: 'RESTITUTION_OVERDUE'})
  │           → AuditLogService.logAsync(document.restitution_overdue)
  │
  └─ 3. Idempotence : payload_digest inclut document_id + seuil → pas de doublon

2b. Diagrammes Mermaid¶

Graphe de dépendances des composants¶

graph TD
    C1["C1 — Migration DDL"]
    C2["C2 — DocumentStatus enum"]
    C3["C3 — State machine extension"]
    C4["C4 — RestitutionService"]
    C5["C5 — RestitutionController"]
    C6["C6 — RestitutionConfig"]
    C7["C7 — RestitutionSlaScheduler"]
    C8["C8 — Destruction guard extension"]
    C9["C9 — Audit integration"]
    C10["C10 — JournalEventType extension"]
    C11["C11 — Error codes"]
    C12["C12 — Tests"]
    C13["C13 — TLA+ model update"]

    C1 --> C2
    C2 --> C3
    C2 --> C4
    C3 --> C4
    C6 --> C4
    C9 --> C4
    C10 --> C4
    C11 --> C4
    C4 --> C5
    C4 --> C7
    C2 --> C8
    C3 --> C8
    C4 --> C12
    C5 --> C12
    C7 --> C12
    C8 --> C12
    C13 --> C12

Séquence — Flux A : Restitution (POST /documents/:id/restitute)¶

sequenceDiagram
    participant Client
    participant RestitutionController as C5 — RestitutionController
    participant RestitutionService as C4 — RestitutionService
    participant DB as PostgreSQL (QueryRunner)
    participant IntegrityJournal as IntegrityJournalService
    participant AuditLog as AuditLogService

    Client->>RestitutionController: POST /documents/:id/restitute
    RestitutionController->>RestitutionController: ParseUUIDPipe (400 si invalide)
    RestitutionController->>RestitutionService: restitute(documentId, actorId)
    RestitutionService->>DB: SELECT ... FOR UPDATE
    alt Document inexistant
        DB-->>RestitutionService: null
        RestitutionService-->>Client: 404 DOCUMENT_NOT_FOUND
    end
    DB-->>RestitutionService: document
    RestitutionService->>RestitutionService: Gardes (ownership, état, legal_lock, geo_copy_count)
    alt Garde échouée
        RestitutionService-->>Client: 403 / 409 (error_code)
    end
    alt Déjà RESTITUTED
        RestitutionService-->>Client: 200 idempotent (pas d'attestation)
    end
    RestitutionService->>RestitutionService: Calcul SLA (restituted_at, deadline)
    RestitutionService->>DB: BEGIN transaction
    RestitutionService->>DB: UPDATE status=RESTITUTED, restituted_at, deadline
    RestitutionService->>IntegrityJournal: appendEntry(RESTITUTION, actor_id, security_level)
    RestitutionService->>DB: COMMIT
    RestitutionService->>AuditLog: logAsync(document.restitute)
    RestitutionService-->>Client: 200 + document mis à jour

Séquence — Flux B : Retour de restitution (POST /documents/:id/return-from-restitution)¶

sequenceDiagram
    participant Client
    participant RestitutionController as C5 — RestitutionController
    participant RestitutionService as C4 — RestitutionService
    participant DB as PostgreSQL (QueryRunner)
    participant IntegrityJournal as IntegrityJournalService
    participant AuditLog as AuditLogService

    Client->>RestitutionController: POST /documents/:id/return-from-restitution
    RestitutionController->>RestitutionController: ParseUUIDPipe (400 si invalide)
    RestitutionController->>RestitutionService: returnFromRestitution(documentId, actorId)
    RestitutionService->>DB: SELECT ... FOR UPDATE
    DB-->>RestitutionService: document
    RestitutionService->>RestitutionService: Gardes (ownership, état RESTITUTED)
    alt Garde échouée
        RestitutionService-->>Client: 403 / 409 (error_code)
    end
    alt Déjà SEALED
        RestitutionService-->>Client: 200 idempotent (pas d'attestation)
    end
    RestitutionService->>DB: BEGIN transaction
    RestitutionService->>DB: UPDATE status=SEALED
    RestitutionService->>IntegrityJournal: appendEntry(RETURN_FROM_RESTITUTION, actor_id, security_level)
    RestitutionService->>DB: COMMIT
    RestitutionService->>AuditLog: logAsync(document.return_from_restitution)
    RestitutionService-->>Client: 200 + document mis à jour

Séquence — Flux C : Contrôle destruction cross-module¶

sequenceDiagram
    participant Client
    participant DestructionController as DestructionController / DocumentsController
    participant EligibilityService as C8 — EligibilityService
    participant DB as PostgreSQL

    Client->>DestructionController: POST /destruction/batches (ou execute, ou DELETE)
    DestructionController->>EligibilityService: selectEligible() / reVerifyEligibility() / delete()
    EligibilityService->>DB: SELECT status FROM documents WHERE id = :id
    DB-->>EligibilityService: status
    alt status = RESTITUTED
        EligibilityService-->>Client: 409 DOCUMENT_RESTITUTED_DESTRUCTION_FORBIDDEN
    else status != RESTITUTED
        EligibilityService->>EligibilityService: Continuer flux destruction normal
    end

Séquence — Flux D : SLA Scheduler (async)¶

sequenceDiagram
    participant Cron as BullMQ Cron
    participant Scheduler as C7 — RestitutionSlaScheduler
    participant DB as PostgreSQL
    participant IntegrityJournal as IntegrityJournalService
    participant AuditLog as AuditLogService

    Cron->>Scheduler: Déclenchement planifié
    Scheduler->>DB: SELECT documents WHERE status=RESTITUTED AND deadline IS NOT NULL
    DB-->>Scheduler: documents[]
    loop Pour chaque document
        Scheduler->>Scheduler: Calcul elapsed_ratio
        alt elapsed_ratio >= 0.80 (alerte non émise)
            Scheduler->>IntegrityJournal: appendEntry(OPS_ALERT_SENT, RESTITUTION_SLA_80)
            Scheduler->>AuditLog: logAsync(restitution_sla_alert)
        end
        alt elapsed_ratio >= 1.00 (escalade non émise)
            Scheduler->>IntegrityJournal: appendEntry(SLA_EXCEEDED, RESTITUTION_SLA_100)
            Scheduler->>AuditLog: logAsync(restitution_sla_escalation)
        end
        alt NOW > deadline (OVERDUE non émis)
            Scheduler->>IntegrityJournal: appendEntry(SLA_EXCEEDED, RESTITUTION_OVERDUE)
            Scheduler->>AuditLog: logAsync(restitution_overdue)
        end
    end

3. Mapping invariants → mécanismes¶

Note : La double vérification destruction (inclusion + exécution) est couverte par INV-279-10 ci-dessus. L'état terminal EXPIRED (aucune transition sortante vers RESTITUTED) est couvert par INV-279-07 (matrice de transitions explicite).

4. Mapping critères d'acceptation → mécanismes¶

5. Mapping tests (TC-*) → mécanismes + observables¶

6. Gestion des erreurs¶

Stratégie de propagation : Les erreurs métier sont des exceptions NestJS (ConflictException pour 409, ForbiddenException pour 403, NotFoundException pour 404) avec payload structuré { error_code, message, details? }. Un ExceptionFilter spécifique normalise le format de réponse.

7. Impacts sécurité¶

8. Hypothèses techniques¶

Résolution HT-279-02 (geo_copy_count)¶

Le champ geo_copy_count n'existe pas dans l'entité DocumentSecure. Deux approches :

1. Ajout d'une colonne geo_copy_count integer NOT NULL DEFAULT 0 dans la migration PD-279 — simple mais couple le concept de réplication géo au document.
2. Service de résolution qui compte les copies géo via un service externe (OVH Object Storage multi-région) — plus propre architecturalement mais ajoute une dépendance réseau dans le flux de garde.

Décision : Approche 1 (colonne) car la spécification traite geo_copy_count comme un attribut du document. Un trigger ou un job de synchronisation met à jour cette valeur en amont (hors périmètre PD-279). La migration PD-279 ajoute la colonne avec DEFAULT 0, ce qui signifie que les gardes de restitution refuseront par défaut (geo_copy_count < 2) tant que le mécanisme de comptage amont n'a pas initialisé la valeur — comportement fail-safe conforme à l'esprit ISO 14641.

Résolution HT-279-03 (security_level)¶

Le champ security_level sera passé en paramètre à la méthode restitute()/returnFromRestitution() depuis le contexte d'authentification (JWT claims ou profil utilisateur). Si non disponible, utiliser la valeur par défaut du document (niveau de sécurité du coffre-fort associé). Le service récupère cette information depuis le contexte existant @CurrentUser() decorator.

9. Points de vigilance (risques, dette, pièges)¶

9b. Dépendances inter-PD¶

10. Hors périmètre¶

• État DISPOSED : STUB planifié en PD-280, transition RESTITUTED→DISPOSED interdite dans PD-279.
• NF Z42-013 DIP : Couvert par PD-278.
• Restitution multi-destinataire : Non spécifié, non implémenté.
• Frontend/mobile : Aucune hypothèse UI dans cette story.
• Mécanisme de comptage geo_copy_count : Seule la colonne et la garde sont implémentées. Le mécanisme de mise à jour du compteur est hors périmètre (STUB).
• Notification utilisateur : Les événements SLA sont des alertes opérationnelles, pas des notifications end-user.

11. Mécanismes cross-module¶

12. Périmètre de test¶

Tous les niveaux de test sont couverts sauf performance (justification : volumétrie faible). Aucune exclusion de composant.

13. Ordonnancement des composants¶

Phase 1 — Fondations (C1, C2, C3, C6, C9, C10, C11)
  Migration + enum extension + state machine + config + types audit/journal + error DTOs

Phase 2 — Core métier (C4, C5)
  RestitutionService + RestitutionController

Phase 3 — Cross-module (C8)
  Extension destruction guard

Phase 4 — SLA async (C7)
  RestitutionSlaScheduler

Phase 5 — Vérification formelle (C13)
  TLA+ model update

Phase 6 — Tests (C12)
  Suite complète unitaire + intégration + E2E + formel