PD-279 — Restitution ISO 14641 d’un document archivé (état RESTITUTED)¶

1. Objectif¶

Spécifier contractuellement l’ajout du statut RESTITUTED et des transitions de restitution d’un document archivé, afin d’aligner le backend avec ISO 14641 §11.3 et de satisfaire l’ASSUME TLA+ AnchorAssume_States, sans ambiguïté fonctionnelle, temporelle, ni de traçabilité.

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

Inclus¶

• Ajout du statut RESTITUTED au cycle de vie documentaire.
• Transition SEALED -> RESTITUTED via POST /documents/:id/restitute.
• Transition retour RESTITUTED -> SEALED via POST /documents/:id/return-from-restitution.
• Vérification des gardes métier: ownership, legal_lock=false, geo_copy_count >= 2, état source valide.
• Journalisation obligatoire des transitions dans lifecycle_log et journal d’audit.
• SLA de restitution: durée max configurable, calcul de deadline, alerte à 80%, escalade à 100%.
• Interdiction de destruction d’un document RESTITUTED (rejet HTTP 409 côté module destruction).
• Migration BD réversible (up/down), incluant extension d’enum + champs temporels.

Exclu¶

• Formalisation complète de l’état DISPOSED (traitée hors de cette story).
• NF Z42-013 DIP (PD-278).
• Restitution multi-destinataire.
• Refonte des flux hors restitution (capture, sealing, expiration), sauf impacts explicitement listés ici.

3. Définitions¶

• DocumentStatus: statut métier du document (PENDING, SEALED, RESTITUTED, EXPIRED).
• RESTITUTED: document archivé restitué temporairement à son originateur.
• Originateur / Owner: utilisateur propriétaire du document.
• legal_lock: verrou juridique interdisant les actions de restitution.
• geo_copy_count: nombre de copies géo-distribuées validées.
• lifecycle_log: registre d’attestations de transitions d’état.
• JournalEventType: type d’événement d’audit applicatif.
• SLA restitution: durée maximale autorisée entre restitution et retour en archivage.
• Deadline restitution: restituted_at + restitution_max_duration.
• État terminal (dans ce périmètre): état sans transition sortante autorisée par cette spécification.

4. Invariants (non négociables)¶

5. Flux nominaux¶

5.1 Modèle de données (formats et contraintes contractuelles)¶

Définitions centralisées; les sections 5.2, 6, 7, 8 y font référence sans redéfinition.

Bornes numériques obligatoires¶

5.2 Machine à états (transitions explicites, incluant retours)¶

Portée: modèle documentaire concerné par restitution (PENDING, SEALED, RESTITUTED, EXPIRED).

• PENDING:
• PENDING -> *: INTERDITE dans ce périmètre (transitions hors restitution inchangées, hors périmètre de cette story).
• SEALED:
• SEALED -> RESTITUTED: AUTORISÉE si INV-279-02.
• SEALED -> SEALED: INTERDITE (pas d’opération no-op de restitution).
• SEALED -> EXPIRED et autres: hors périmètre, inchangé par cette story.
• RESTITUTED:
• RESTITUTED -> SEALED: AUTORISÉE si INV-279-03.
• RESTITUTED -> DISPOSED: INTERDITE (INV-279-06).
• RESTITUTED -> RESTITUTED: INTERDITE.
• RESTITUTED -> PENDING/EXPIRED: INTERDITE dans ce périmètre.
• EXPIRED (terminal pour ce périmètre):
• EXPIRED -> *: INTERDITE (état terminal, résolution manuelle uniquement).

Comportement downgrade/retour RESTITUTED -> SEALED: - Données de preuve (lifecycle_log, audit) conservées. - SLA restitution clos (plus d’alerte/escalade active sur la fenêtre terminée). - Protections d’archive SEALED réappliquées immédiatement.

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

Ordre d’évaluation des gardes (priorité stricte) : 1. Authentification → 401 Unauthorized 2. Validation document_id → 400 Bad Request 3. Existence document → 404 Not Found 4. Ownership (owner) → 403 Forbidden 5. État courant SEALED → 409 Conflict (error_code: INVALID_SOURCE_STATE) 6. Idempotence : si déjà RESTITUTED → 200 OK (pas de nouvelle attestation, retour état actuel) 7. legal_lock=false → 409 Conflict (error_code: DOCUMENT_UNDER_LEGAL_LOCK) 8. geo_copy_count >= 2 → 409 Conflict (error_code: INSUFFICIENT_GEO_COPIES)

Flux nominal (gardes satisfaites, pas idempotent) : 1. Le système calcule restituted_at=now_utc et restitution_deadline=restituted_at + restitution_max_duration. 2. Le système persiste atomiquement: - status=RESTITUTED - restituted_at - restitution_deadline - attestation lifecycle_log(type=RESTITUTION, actor_id, security_level, timestamp_utc). 3. Le système émet l’événement d’audit correspondant. 4. Réponse HTTP 200.

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

Ordre d’évaluation des gardes (priorité stricte) : 1. Authentification → 401 Unauthorized 2. Validation document_id → 400 Bad Request 3. Existence document → 404 Not Found 4. Ownership (owner) → 403 Forbidden 5. État courant RESTITUTED → 409 Conflict (error_code: INVALID_SOURCE_STATE) 6. Idempotence : si déjà SEALED → 200 OK (pas de nouvelle attestation, retour état actuel)

Flux nominal (gardes satisfaites, pas idempotent) : 1. Le système persiste atomiquement: - status=SEALED - attestation lifecycle_log(type=RETURN_FROM_RESTITUTION, actor_id, security_level, timestamp_utc). 2. Le système émet l’événement d’audit correspondant. 3. Réponse HTTP 200.

5.5 Flux nominal C — Contrôle destruction cross-module¶

Routes protégées (liste exhaustive) : - POST /destruction/batches — inclusion d’un document dans un batch de destruction - POST /destruction/batches/:id/execute — exécution d’un batch de destruction - DELETE /documents/:id — soft-delete direct d’un document

Garde : À CHAQUE route ci-dessus, le système DOIT vérifier document.status : 1. Si status=RESTITUTED, la destruction est refusée avec HTTP 409 (error_code: DOCUMENT_RESTITUTED_DESTRUCTION_FORBIDDEN). 2. Événement d’audit de refus enregistré. 3. Le contrôle s’applique à l’inclusion dans le batch ET à l’exécution (double vérification anti-race-condition).

5.6 SLA temporels (checklist complète)¶

5.7 Stratégie de migration DDL (modification colonne/enum existant)¶

5.8 Atomicité multi-composant¶

5.9 Contraintes inter-modules¶

5bis. Diagrammes Mermaid¶

5bis.1 Machine a etats — Cycle de vie documentaire (perimetre restitution)¶

Transitions autorisees et interdites conformement a INV-279-07 (matrice explicite).

stateDiagram-v2
    [*] --> PENDING

    PENDING --> SEALED : capture + sealing\n(hors perimetre PD-279)

    SEALED --> RESTITUTED : POST /documents/:id/restitute\n[owner AND legal_lock=false\nAND geo_copy_count>=2]\n(INV-279-02)

    RESTITUTED --> SEALED : POST /documents/:id/return-from-restitution\n[owner]\n(INV-279-03)

    SEALED --> EXPIRED : expiration\n(hors perimetre PD-279)

    state RESTITUTED {
        direction LR
        [*] --> actif
        actif --> alerte_80pct : elapsed >= 80% SLA\n(INV-279-05)
        alerte_80pct --> escalade_100pct : elapsed >= 100% SLA\n(INV-279-05)
        escalade_100pct --> overdue : RESTITUTION_OVERDUE emis\npas de transition auto
    }

    note right of RESTITUTED
        INV-279-06 : destruction INTERDITE
        INV-279-11 : idempotence (200 si deja RESTITUTED)
    end note

    note right of EXPIRED
        Etat terminal dans ce perimetre
        (INV-279-07)
    end note

5bis.2 Sequence — Flux A : Restitution nominale (POST /documents/:id/restitute)¶

Evaluation des gardes en ordre strict (§5.3), atomicite transaction + audit post-commit (INV-279-09).

sequenceDiagram
    participant Client
    participant API as DocumentController
    participant Guard as RestitutionGuard
    participant Service as DocumentService
    participant DB as PostgreSQL
    participant Audit as AuditService
    participant SLA as SLA Worker

    Client->>API: POST /documents/:id/restitute
    API->>Guard: authenticate + validate UUID
    Guard-->>API: 401/400 si invalide

    API->>Service: restitute(documentId, actorId)
    Service->>DB: SELECT document (id, status, owner_id, legal_lock, geo_copy_count)

    alt document inexistant
        DB-->>Service: null
        Service-->>Client: 404 DOCUMENT_NOT_FOUND
    else not owner
        Service-->>Client: 403 NOT_DOCUMENT_OWNER
    else status = RESTITUTED (idempotence INV-279-11)
        Service-->>Client: 200 OK (etat actuel, pas de nouvelle attestation)
    else status != SEALED
        Service-->>Client: 409 INVALID_SOURCE_STATE
    else legal_lock = true
        Service-->>Client: 409 DOCUMENT_UNDER_LEGAL_LOCK
    else geo_copy_count < 2
        Service-->>Client: 409 INSUFFICIENT_GEO_COPIES
    else gardes OK
        Service->>DB: BEGIN TRANSACTION
        Service->>DB: UPDATE status=RESTITUTED, restituted_at, restitution_deadline
        Service->>DB: INSERT lifecycle_log (RESTITUTION, actor_id, security_level, timestamp)
        Note over Service,DB: Atomicite ACID (INV-279-09)
        Service->>DB: COMMIT
        Service->>Audit: emit audit event (post-commit, at-least-once)
        Service->>SLA: planifier alerte 80% + escalade 100% (INV-279-05)
        Service-->>Client: 200 OK {status: RESTITUTED, restituted_at, restitution_deadline}
    end

5bis.3 Sequence — Flux B : Retour de restitution (POST /documents/:id/return-from-restitution)¶

Gardes simplifiees (§5.4) : pas de verification geo_copy_count (INV-279-03).

sequenceDiagram
    participant Client
    participant API as DocumentController
    participant Service as DocumentService
    participant DB as PostgreSQL
    participant Audit as AuditService

    Client->>API: POST /documents/:id/return-from-restitution
    API->>Service: returnFromRestitution(documentId, actorId)
    Service->>DB: SELECT document (id, status, owner_id)

    alt document inexistant
        Service-->>Client: 404 DOCUMENT_NOT_FOUND
    else not owner
        Service-->>Client: 403 NOT_DOCUMENT_OWNER
    else status = SEALED (idempotence INV-279-11)
        Service-->>Client: 200 OK (etat actuel, pas de nouvelle attestation)
    else status != RESTITUTED
        Service-->>Client: 409 INVALID_SOURCE_STATE
    else gardes OK
        Service->>DB: BEGIN TRANSACTION
        Service->>DB: UPDATE status=SEALED
        Service->>DB: INSERT lifecycle_log (RETURN_FROM_RESTITUTION, actor_id, security_level, timestamp)
        Note over Service,DB: Atomicite ACID (INV-279-09)
        Service->>DB: COMMIT
        Service->>Audit: emit audit event (post-commit)
        Note over Service: SLA clos — plus d’alerte/escalade active (§5.2)
        Service-->>Client: 200 OK {status: SEALED}
    end

5bis.4 Sequence — Flux C : Garde cross-module destruction (INV-279-10)¶

Double verification anti-race-condition a l’inclusion ET a l’execution (§5.5).

sequenceDiagram
    participant Client
    participant Destruction as DestructionModule
    participant DocService as DocumentService
    participant DB as PostgreSQL
    participant Audit as AuditService

    rect rgb(255, 240, 240)
        Note over Client,Audit: Phase 1 — Inclusion dans batch (POST /destruction/batches)
        Client->>Destruction: POST /destruction/batches {document_ids}
        Destruction->>DocService: getStatus(documentId)
        DocService->>DB: SELECT status FROM documents WHERE id = :id
        DB-->>DocService: status

        alt status = RESTITUTED
            Destruction->>Audit: emit refus destruction (INV-279-04)
            Destruction-->>Client: 409 DOCUMENT_RESTITUTED_DESTRUCTION_FORBIDDEN
        else status != RESTITUTED
            Destruction-->>Client: 200 OK (batch cree)
        end
    end

    rect rgb(255, 240, 240)
        Note over Client,Audit: Phase 2 — Execution batch (POST /destruction/batches/:id/execute)
        Client->>Destruction: POST /destruction/batches/:id/execute
        loop pour chaque document du batch
            Destruction->>DocService: getStatus(documentId)
            DocService->>DB: SELECT status FROM documents WHERE id = :id
            DB-->>DocService: status
            alt status = RESTITUTED (race condition detectee)
                Destruction->>Audit: emit refus destruction (INV-279-06)
                Note over Destruction: Document exclu du batch, 409
            end
        end
    end

6. Cas d’erreur¶

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

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

• ST-279-01 Restitution nominale
• Given un document SEALED, owner authentifié, geo_copy_count=2, legal_lock=false
• When POST /documents/:id/restitute

• Then HTTP 200, statut RESTITUTED, restituted_at et restitution_deadline renseignés, attestation RESTITUTION créée.

• ST-279-02 Restitution refusée copies insuffisantes

• Given un document SEALED avec geo_copy_count=1
• When POST /documents/:id/restitute

• Then HTTP 409, statut inchangé, aucune attestation de transition.

• ST-279-03 Restitution refusée legal lock

• Given un document SEALED avec legal_lock=true
• When POST /documents/:id/restitute

• Then HTTP 409, statut inchangé, audit de refus.

• ST-279-04 Restitution refusée non owner

• Given un document SEALED appartenant à un autre utilisateur
• When POST /documents/:id/restitute

• Then HTTP 403.

• ST-279-05 Retour nominal

• Given un document RESTITUTED dont l’appelant est owner
• When POST /documents/:id/return-from-restitution

• Then HTTP 200, statut SEALED, attestation RETURN_FROM_RESTITUTION créée.

• ST-279-06 Retour refusé mauvais état

• Given un document SEALED
• When POST /documents/:id/return-from-restitution

• Then HTTP 409.

• ST-279-07 Interdiction destruction

• Given un document RESTITUTED
• When appel de l’endpoint de destruction

• Then HTTP 409, aucune destruction effective.

• ST-279-08 SLA événements

• Given un document RESTITUTED avec SLA configuré à 30 jours
• When le temps atteint 24 jours (80%) puis 30 jours (100%)

• Then une alerte 80% puis une escalade 100% sont émises et tracées.

• ST-279-09 Vérification TLA+

• Given code et modèle mis à jour
• When exécution de la vérification AnchorAssume_States
• Then résultat PASS.

9. Hypothèses explicites¶

10. Contraintes techniques et points à clarifier¶

10.1 Contraintes techniques (stack réelle, obligatoire)¶

• Projet cible: ProbatioVault-backend.
• Stack contractuelle: NestJS + TypeORM + PostgreSQL.
• Endpoints exposés via module documents backend.
• Migration via mécanisme TypeORM du backend.
• Aucune hypothèse frontend/mobile dans cette story.

10.2 Points à clarifier (statut)¶

Références¶

• Epic : PD-279-iso14641-restituted
• JIRA : PD-279
• Repos concernés : ProbatioVault-backend (principal), ProbatioVault-doc (normes/TLA+)
• Documents associés :
• ProbatioVault-doc/docs/normes/iso-14641/formal/ISO_14641.tla
• ISO 14641 §11.3
• ISO 14641 §5.5.8
• PD-250 (destruction), PD-251 (intégrité), PD-81 (SLA temporels)