PD-286 — Plan d'implémentation¶

Story : Export probatoire multi-volumes (au-delà de 768MB, jusqu'à 10GB) Stack : ProbatioVault-backend (NestJS + TypeORM + PostgreSQL) + ProbatioVault-app (React Native + Expo SDK 54 + TypeScript) Baseline : Étend l'export PD-85 (src/modules/export/) avec partitionnement en volumes — conserve la rétrocompatibilité legacy single-volume (INV-286-05). Gate 3 v2 : GO (verdict-step3-v2.yaml). Les ambiguïtés résiduelles (canonicalisation cross-runtime, source d'horloge TTL, taille totale max calculée vs déclarée) sont reportées en §8 (Hypothèses) et §9 (Vigilance).

1. Découpage en composants¶

1.1 Backend (ProbatioVault-backend/src/modules/export/)¶

1.2 App (ProbatioVault-app/src/export/)¶

1.3 Tests (backend/test/ et app/src/__tests__/)¶

2. Flux techniques¶

2.1 Flux nominal A — single-volume legacy (totalSize ≤ 805_306_368)¶

Client → POST /exports/complaint-file {complaintId}
Backend ExportService.export()
  ├── validate ownership (existant PD-85)
  ├── compute totalSize = Σ proof.bytes
  ├── if totalSize ≤ VOLUME_MAX_BYTES AND ∀ proof : proof.bytes ≤ VOLUME_MAX_BYTES
  │     → ExportStateMachine.transition(REQUESTED → PLANNED_SINGLE)
  │     → ExportManifestBuilder.build() (PD-85 inchangé)
  │     → réponse legacy : {exportId, manifest, signedUrls[], chronology, ...}
  └── ExportAudit.appendStart(exportId, volumes_count=1)

App orchestrator
  ├── détecte absence de `volumes[]` → branche legacy PD-85
  ├── télécharge signedUrls, vérifie hash (existant)
  └── pvproof-assembler.assemble() → .pvproof unique

2.2 Flux nominal B — multi-volumes (totalSize > 805_306_368 OU preuve atomique > 805_306_368)¶

Backend ExportService.export()
  ├── validate ownership
  ├── compute totalSize
  ├── if totalSize > MAX_TOTAL_EXPORT_BYTES → throw 413 EXPORT_TOTAL_LIMIT_EXCEEDED
  ├── if ∃ proof : proof.bytes > MAX_TOTAL_EXPORT_BYTES → throw 413 PROOF_TOO_LARGE
  ├── ExportPartitioner.partition(proofs) → Volume[]
  │     - tri preuves par taille décroissante (déterministe)
  │     - pour chaque preuve : si proof.bytes > VOLUME_MAX_BYTES → volume dédié exceptionnel (1 preuve)
  │     - sinon : ajoute au volume courant si Σ ≤ VOLUME_MAX_BYTES, sinon ouvre nouveau volume
  │     - assigne volumeIndex 0..N-1 sans trou ni doublon (INV-286-06)
  ├── ExportStateMachine.transition(REQUESTED → PLANNED_MULTI)
  ├── pour chaque volume v :
  │     - manifest_partial = build(volume.proofs)
  │     - v.integrityHash = SHA3-256(JCS(manifest_partial \ {integrityHash}))
  │     - v.signedUrl = StorageSigner.sign(file_v, ttl=SIGNED_URL_TTL)
  │     - v.manifest = manifest_partial (avec integrityHash)
  ├── manifestRootHash = SHA3-256(JCS({volumes: [{volumeIndex, integrityHash, estimatedBytes}], totalVolumes, exportId}))
  ├── ExportAudit.appendStart(exportId, volumes_count=N, integrityHash[])
  └── return ComplaintFileResponseDto {exportId, totalVolumes, volumes: [ExportVolumeDto], manifestRootHash, ...legacy fields nullables}

App orchestrator
  ├── détecte volumes[] → state DOWNLOADING
  ├── tri local par volumeIndex ascendant (déterministe quel que soit l'ordre serveur — voir §9)
  ├── for v in volumes (séquentiel, abort sur first failure) :
  │     ├── api-client.fetchVolume(v.signedUrl) → bytes
  │     ├── volume-verifier.verify(bytes, v.manifest, v.integrityHash) :
  │     │     - recompute = SHA3-256(JCS(v.manifest \ {integrityHash}))
  │     │     - if recompute !== v.integrityHash → throw HashMismatch → state FAILED
  │     ├── pvproof-assembler.appendVolume(bytes, v.manifest)
  ├── state DOWNLOADING → ASSEMBLING
  ├── pvproof-assembler.finalize(volumes_count=N, assembled_from=volumes.map(...))
  ├── state ASSEMBLING → COMPLETED
  └── ExportAudit (côté serveur via callback) : appendEnd(exportId, status=COMPLETED)

2bis. Diagramme de dépendances agents (step 6b)¶

graph LR
    C1[C1 export-partitioner]
    C2[C2 export-multi-dto]
    C3[C3 export-manifest-multi]
    C4[C4 export-state-machine-backend]
    C5[C5 export-controller-multi]
    C6[C6 export-audit-multi]

    C7[C7 app-export-orchestrator-multi]
    C8[C8 app-volume-verifier]
    C9[C9 app-pvproof-assembler-multi]
    C10[C10 app-export-api-client]

    C11[C11 tests]

    C2 --> C5
    C2 --> C10
    C1 --> C5
    C3 --> C5
    C4 --> C5
    C5 --> C6

    C10 --> C7
    C8 --> C7
    C9 --> C7

    C5 --> C11
    C6 --> C11
    C7 --> C11

    subgraph Wave1 ["Wave 1 — Foundations (parallèle)"]
        C2
        C4
    end

    subgraph Wave2 ["Wave 2 — Backend services (parallèle)"]
        C1
        C3
        C10
        C8
        C9
    end

    subgraph Wave3 ["Wave 3 — Intégration"]
        C5
        C7
    end

    subgraph Wave4 ["Wave 4 — Audit + Tests"]
        C6
        C11
    end

Cohérence avec PD-286-code-contracts.yaml : un nœud = un module YAML. Les waves sont reprises dans dependencies_graph.waves.

2ter. Vérification couverture du diagramme d'état (§5bis spec)¶

3. Mapping invariants → mécanismes¶

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

5. Mapping tests → mécanismes + observables¶

Périmètre de test¶

Tous les niveaux sont couverts, aucune exclusion contractuelle. Couverture minimale 80% lignes + 80% branches sur C1-C10.

6. Gestion des erreurs¶

6.1 Erreurs métier (HTTP 4xx) — émises par C5¶

6.2 Erreurs internes (HTTP 5xx) — émises par C5/C2¶

6.3 Erreurs côté app¶

6.4 Anti-catch-absorb (learning 2026-03-08)¶

Tout catch qui appelle l'audit DOIT propager l'erreur :

// CORRECT — pattern obligatoire dans C5/C6
try {
  await this.export(exportId);
} catch (err) {
  await this.exportAudit.appendEnd(exportId, 'FAILED', { error: err.message });
  throw err;
}

// INTERDIT (forbidden YAML)
.catch(err => this.logger.error(`audit failed: ${err.message}`));

7. Impacts sécurité¶

7.1 Risques et mitigations¶

7.2 Journalisation¶

Logs structurés (JSON) avec corrélation exportId :

INTERDIT : log de manifest complet, log de signedUrl complète, log de integrityHash complet (uniquement les 8 premiers chars pour debug).

7.3 Conformité¶

• WORM audit (INV-286-09) : append-only, hash chain (réutilise pattern audit existant), corrélation exportId. Conserve la conformité probatoire PD-85.
• Rétention temp files : politique existante PD-85 réutilisée (Q-286-03 ouverte côté produit, ne bloque pas l'implémentation — cf. §9).
• TTL bornes config : SIGNED_URL_TTL et EXPORT_SESSION_TTL (1h..72h, défaut 24h) ; démarrage service refusé si valeur hors bornes (fail-closed).

8. Hypothèses techniques¶

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

9.1 Dette technique reconnue¶

• Q-286-03 (rétention) : politique post-FAILED/EXPIRED non chiffrée par produit. Plan retient la politique PD-85 existante par défaut. Ticket de suivi à ouvrir si l'audit RGPD demande une durée explicite.
• Q-286-04 (TTL prod) : valeurs déployées non confirmées. Plan retient les défauts spec (24h/24h). Configurable par env, audité au démarrage (fail-closed si hors bornes).
• Worker EXPIRED : nouveau cron 30s à provisionner sur ProbatioVault-backend. Réutilise patron de worker existant (@nestjs/schedule) si déjà présent, sinon création.

9.2 Pièges connus¶

• integrityHash case-sensitive (§5.1) : test négatif explicite TC-NEG-02 avec hash en majuscules. Régression facile si une lib normalise en majuscules — couvert par regex stricte /^[0-9a-f]{64}$/ côté backend ET app (C2 + C10).
• JCS RFC 8785 cross-runtime : lib npm canonicalize la plus utilisée n'est PAS officiellement RFC 8785 conforme sur tous les edge cases (NaN, -0, surrogates Unicode). Plan impose la lib partagée interne (cf. H-PD286-PLAN-01) et bloque tout import direct de canonicalize ou autre alternative.
• Ordre de tri volumes[] (review §3.14) : la spec n'impose pas l'ordre dans la réponse. Plan impose : backend renvoie volumes[] triés par volumeIndex ascendant ; app re-trie défensivement (validation Zod refuse trous, doublons, mais pas désordre serveur). Couvre l'ambiguïté review.
• Diagramme d'état spec §5bis incomplet (review §3.15) : certaines transitions interdites (ex: PLANNED_MULTI → PLANNED_SINGLE) ne sont visibles que dans le texte §4. Le code C4 doit s'aligner sur le texte, pas sur le diagramme. Test TC-INV-10 itère sur le produit cartésien complet.
• assembled_from[] cardinalité : INV-286-08 impose cardinalité = totalVolumes. Vérifié à la finalisation par pvproof-assembler ; throw si divergence (fail-closed).

9.3 Cohérence avec PD-85¶

PD-286 étend PD-85 sans le casser. Tous les fichiers existants (complaint-file.controller.ts, export.service.ts, pvproof-assembler.ts, state-machine.ts) sont étendus, jamais réécrits intégralement. Les tests PD-85 doivent continuer à passer (TC-NR-01..05).

9.4 Mécanismes cross-module¶

Aucune modification d'autres modules.

PD-286 modifie uniquement src/modules/export/ côté backend et src/export/ côté app, ainsi que src/__tests__/ et test/. Aucun guard/middleware/interceptor n'est ajouté sur les routes d'autres modules. La consommation des entités proofs (lecture seule via le service existant PD-85) ne change pas.

10. Hors périmètre¶

• Configuration utilisateur/admin des seuils VOLUME_MAX_BYTES et MAX_TOTAL_EXPORT_BYTES (figés au build).
• Modification du format conteneur .pvproof (seul pvproof.json interne enrichi).
• Téléchargement parallèle des volumes (séquentiel uniquement par décision spec §2).
• Reprise d'export après FAILED/EXPIRED sur le même exportId (nouvelle requête obligatoire).
• Modification des guards auth/premium et du rate limiting (PD-85 inchangé).
• Modification de la pipeline de validation des preuves (entrée du partitionnement = preuves déjà validées).
• Optimisation du stockage temporaire (réutilise le même backend storage que PD-85).
• Bumping du pvproof_format_version à 2 — décision conditionnelle au résultat de TC-NR-02 (cf. H-PD286-PLAN-04). Si bumping nécessaire, story de suivi.