PD-286 — Livrable agent-developer — Module C2 export-multi-dto¶

Story : PD-286 — Export probatoire multi-volumes (jusqu'à 10 GB) Module : C2 export-multi-dto Périmètre fichiers : src/modules/export/dto/{export-volume,manifest-root,complaint-file-response,index}.ts Wave plan : Wave 1 (Foundations, parallèle avec C4) Stack : NestJS + class-validator 0.14 + class-transformer 0.5 + @nestjs/swagger 7

1. Contexte¶

Le module C2 fournit la couche DTO contractuelle pour l'export multi-volumes :

• ExportVolumeDto : volume unitaire dans la réponse (volumeIndex, integrityHash, estimatedBytes, signedUrl, manifest partiel typé ManifestDto).
• ManifestRootDto + VolumeReferenceDto : manifest racine multi-volumes (consommé par C3 export-manifest-multi).
• Extension de ComplaintFileResponseDto (PD-85) avec trois champs optionnels : volumes?, totalVolumes?, manifestRootHash?.
• Validation cross-field INV-286-06 inline (IsValidVolumesShape).

Aucune logique métier (ni partition, ni hash, ni I/O). C2 est purement déclaratif (DTO + validation) et est consommé par C5 (controller/service) et C3 (manifest builder) en aval.

2. Fichiers produits¶

Aucun fichier hors périmètre n'a été modifié.

3. Couverture des invariants¶

4. Couverture des forbidden¶

5. Décisions architecturales¶

Format conforme au schéma architectural_decisions du code contract (PD-XX-code-contracts.yaml).

Décision D1 — Sérialisation conditionnelle via undefined natif (pas class-transformer @Expose)¶

• Décision : Utiliser des champs ?: TypeScript sans valeur d'initialisation, sans @Exclude/@Expose ni groupe class-transformer.
• Rationale : JSON.stringify omet nativement les clés undefined ; la solution est byte-stable, sans dépendance à un mécanisme de groupes class-transformer qui ajouterait du couplage avec la couche service. Le ClassSerializerInterceptor global (déjà actif via main.ts) ne touche pas aux champs sans décorateur particulier.
• Alternatives considérées :
• @Expose({ groups: ['multi'] }) + activation conditionnelle dans le service via instanceToPlain(dto, { groups: ['multi'] }).
• Deux DTO distincts LegacyComplaintFileResponseDto vs MultiVolumeComplaintFileResponseDto en union type.
• Trade-offs :
• Avantages : zéro changement requis dans C5 (le service peut produire l'instance sans configurer de groupes), TC-NR-01 byte-stable garanti, pas de risque d'oubli de groupe.
• Inconvénients : repose sur la discipline du service (ne pas faire dto.volumes = null ni dto.volumes = [] en legacy). Le validateur IsValidVolumesShape rattrape null/[] mais pas un assignement explicite à null côté sérialisation.

Décision D2 — Validateur cross-field IsValidVolumesShape inline (pas de fichier validators/ séparé)¶

• Décision : Implémenter le validateur custom directement dans complaint-file-response.dto.ts via @ValidatorConstraint + registerDecorator.
• Rationale : Le validateur est spécifique à ce DTO (couplage fort avec le champ frère totalVolumes). Le sortir dans dto/validators/ ajouterait un import circulaire et ne serait pas réutilisé ailleurs.
• Alternatives considérées :
• Validateur séparé dans dto/validators/is-valid-volumes-shape.validator.ts.
• Validation déléguée intégralement à C1 ExportPartitioner (pas de validation au niveau DTO).
• Trade-offs :
• Avantages : auto-suffisance du fichier DTO, pas de fragmentation. Defense-in-depth (C1 valide aussi en runtime, mais le DTO bloque dès la sérialisation).
• Inconvénients : complaint-file-response.dto.ts croît un peu (~160 lignes au total).

Décision D3 — Réutilisation de ManifestDto (PD-85) pour le champ manifest du volume¶

• Décision : ExportVolumeDto.manifest!: ManifestDto, sans créer de type VolumeManifestDto distinct.
• Rationale : Un manifest partiel a la même structure qu'un manifest complet — c'est un manifest sur un sous-ensemble de preuves. Créer un alias n'apporterait pas de garantie supplémentaire et complexifierait C3.
• Alternatives considérées :
• type VolumeManifestDto = ManifestDto (alias).
• Sous-ensemble strict (sans proofCount).
• Trade-offs :
• Avantages : cohérence avec PD-85, pas de duplication de schéma, IntegrityHashComputer (PD-85) réutilisable tel quel par C3.
• Inconvénients : import croisé complaint-file-response.dto.ts ↔ export-volume.dto.ts (cf. §6 Vigilance).

Décision D4 — Constantes regex/limites partagées dans manifest-root.dto.ts¶

• Décision : HEX_64_LOWER_REGEX, UUID_V4_LOWER_REGEX, UUID_V4_ANY_CASE_REGEX, MAX_TOTAL_EXPORT_BYTES exportés depuis manifest-root.dto.ts et réutilisés par les autres fichiers.
• Rationale : Source unique de vérité pour les bornes contractuelles §5.1. Évite toute divergence entre fichiers.
• Alternatives considérées : Constantes dans export.constants.ts. Rejeté car ce fichier appartient à la couche métier (PD-85) et ne devrait pas porter des regex DTO.
• Trade-offs : Léger couplage des DTO entre eux ; acceptable car ils appartiennent au même module.

Décision D5 — Pas de @Transform sur integrityHash/manifestRootHash¶

• Décision : Aucune transformation appliquée à la lecture des hashes.
• Rationale : Forbidden YAML explicite ("Transformation/normalisation côté DTO d'un integrityHash reçu (toLowerCase, trim) — refuser stricto sensu"). Une normalisation masquerait un bug d'émission backend ou une corruption en transit.
• Trade-offs : Pas de tolérance à la casse. Toute valeur uppercase entrante est rejetée par @Matches.

6. Points de vigilance / dette technique¶

7. Vérification TypeScript¶

cd ProbatioVault-backend
npx tsc --noEmit 2>&1 | grep "src/modules/export/dto"
# (vide — 0 erreur sur le périmètre C2)

L'unique erreur résiduelle remontée par tsc --noEmit (src/modules/merkle/v2/controllers/merkle-proof-v2.controller.ts(16,48)) est pré-existante, hors du périmètre C2, et n'est pas affectée par cette PR.

8. Tests à produire en C11 (référence pour le module tests)¶

C2 ne livre pas de tests (hors scope). Les tests doivent être écrits par C11.

9. Interfaces consommées en aval¶

10. Conformité aux learnings injectés¶

11. Notes pour le merge¶

• 0 modification sur les fichiers hors src/modules/export/dto/.
• 0 régression attendue sur PD-85 : les types existants (ManifestDto, ChronologyDto, SignedUrlDto, etc.) sont inchangés dans leur structure ; seul minorEvidence? reçoit @ApiPropertyOptional (purement déclaratif Swagger, pas d'effet runtime).
• Convention de versioning JSON : la réponse legacy reste byte-identical (TC-NR-01) à condition que C5 ne pose JAMAIS null sur volumes/totalVolumes/manifestRootHash.
• Migration DB / config : aucune. C2 est purement déclaratif TypeScript.