Aller au contenu

PD-79 — Plan d'Implementation

Metadata

Champ Valeur
Story ID PD-79
Version 1.0
Date 2026-02-16
Auteur Claude (Orchestrateur)

1. Resume executif

PD-79 etend le module de depot probatoire PD-60 avec une categorie documentaire B2C_EVIDENCE_MINOR. L'implementation repose sur:

  • Extension declarative : nouveau champ category optionnel dans le DTO
  • Configuration externalisee : table document_category_configs pour les regles par categorie
  • Service dedie : CategoryConfigService pour la resolution et validation
  • Zero modification du moteur probatoire : meme transaction, meme audit, meme JWS

2. Architecture cible

                    ┌──────────────────────┐
                    │ DepositController    │
                    │ POST /documents/     │
                    │      upload          │
                    └──────────┬───────────┘
                               │ dto.category?
                    ┌──────────────────────┐
                    │ CategoryConfigService │◄── Cache TTL 60s
                    │ - resolve(category)   │
                    │ - assertMimeAllowed   │
                    │ - assertSizeAllowed   │
                    └──────────┬───────────┘
                               │ ResolvedCategoryConfig
                    ┌──────────────────────┐
                    │ DepositService        │
                    │ - createDeposit()    │
                    │ (PD-60 inchange)     │
                    └──────────────────────┘

3. Decisions techniques explicites (QO)

ID Question Decision Justification
QO-79-01 Detection MIME Magic bytes via file-type package Plus fiable que Content-Type header, bloque fichiers deguises
QO-79-02 Cache config In-memory TTL 60s Evite requete DB a chaque upload, refresh adequat pour config
QO-79-03 Interruption stream oversize Via Multer limits.fileSize + middleware Coupe le stream AVANT reception complete
QO-79-04 Extension DTO Champ category optionnel avec default Compatibilite ascendante clients PD-60
QO-79-05 Storage columns Ajout document_category, detected_mime_type, uploaded_size_bytes Tracabilite complete sans modifier colonnes existantes

4. Decomposition en taches

Phase 1 : Infrastructure (4 taches)

T Description Agent Fichiers Dependances
T1 Migration: table document_category_configs + colonnes extension deposits agent-developer migrations/1739000000000-AddCategoryConfig.ts -
T2 Entite DocumentCategoryConfig agent-developer entities/document-category-config.entity.ts T1
T3 Extension entite Deposit (3 colonnes) agent-developer entities/deposit.entity.ts T1
T4 Seed data categories (DEFAULT + B2C_EVIDENCE_MINOR) agent-developer seeds/category-config.seed.ts T2

Phase 2 : Services (3 taches)

T Description Agent Fichiers Dependances
T5 CategoryConfigService (resolve, validate MIME, validate size) agent-developer services/category-config.service.ts T2
T6 Extension DepositService (integration CategoryConfigService) agent-developer services/deposit.service.ts T5
T7 Extension CreateDepositDto (champ category optionnel) agent-developer dto/create-deposit.dto.ts -

Phase 3 : Controller et validation (2 taches)

T Description Agent Fichiers Dependances
T8 Extension DepositController (validation MIME/taille pre-service) agent-developer controllers/deposit.controller.ts T5, T7
T9 Middleware taille maximale configurable par categorie agent-developer middleware/category-size.middleware.ts T5

Phase 4 : Audit (1 tache)

T Description Agent Fichiers Dependances
T10 Extension audit avec champs B2C (documentCategory, detectedMimeType, etc.) agent-developer services/deposit-audit.service.ts T6

Phase 5 : Tests (3 taches)

T Description Agent Fichiers Dependances
T11 Tests unitaires CategoryConfigService agent-qa-unit services/category-config.service.spec.ts T5
T12 Tests integration upload avec categories agent-qa-integration controllers/deposit.controller.integration.spec.ts T8
T13 Tests securite (magic bytes bypass, timing) agent-qa-security __tests__/security/deposit-category.security.spec.ts T8

5. Ordre d'execution

gantt
    title PD-79 Execution Order
    dateFormat  YYYY-MM-DD
    section Phase 1
    T1 Migration           :t1, 2026-02-16, 1d
    T2 Entity Config       :t2, after t1, 1d
    T3 Entity Deposit Ext  :t3, after t1, 1d
    T4 Seed Data           :t4, after t2, 1d
    section Phase 2
    T5 CategoryConfigSvc   :t5, after t2, 1d
    T6 DepositSvc Ext      :t6, after t5, 1d
    T7 DTO Extension       :t7, 2026-02-16, 1d
    section Phase 3
    T8 Controller Ext      :t8, after t6 t7, 1d
    T9 Middleware          :t9, after t5, 1d
    section Phase 4
    T10 Audit Extension    :t10, after t6, 1d
    section Phase 5
    T11 Tests Unit         :t11, after t5, 1d
    T12 Tests Integration  :t12, after t8, 1d
    T13 Tests Security     :t13, after t8, 1d

Chemin critique : T1 → T2 → T5 → T6 → T8 → T12


6. Dependances externes

Package Version Usage Justification
file-type ^19.0.0 Detection MIME via magic bytes ESM-only, async, fiable pour images/audio/video

Note : file-type v19+ est ESM-only. Utiliser import dynamique dans CommonJS.


7. Mapping invariants → implementation

Invariant Implementation Verification
INV-79-01 (zero-knowledge) Herite de PD-60 (storagePath opaque, pas de buffering) Inchange
INV-79-02 (pas de non-scelle persistant) Herite de PD-60 (transaction englobante) Inchange
INV-79-03 (immutabilite) Herite de PD-60 (insert-only) Inchange
INV-79-04 (tracabilite) Herite de PD-60 + extension audit B2C T10
INV-79-05 (portabilite) Herite de PD-60 (JWS) Inchange
INV-79-06 (SLA < 1s) Cache config + stream validation pre-upload T9 + tests perf

8. Risques et mitigations

Risque Probabilite Impact Mitigation
file-type ESM incompatibilite Moyenne Majeur Import dynamique await import('file-type')
Performance detection MIME Faible Mineur Detection sur premiers 4100 bytes seulement
Regression PD-60 Faible Majeur Suite de non-regression complete (TC-79-NR-*)

9. Criteres de sortie

  • Migration executee sans erreur
  • Tests unitaires T11 verts (coverage >= 80%)
  • Tests integration T12 verts (tous CA-79-* couverts)
  • Tests securite T13 verts (bypass magic bytes detecte)
  • Tests non-regression PD-60 verts (aucune rupture)
  • Pipeline GitLab vert (lint + types + tests + Sonar)
  • p95 scellement <= 1000ms (TC-79-PERF-001)

10. Estimation

Phase Effort estime
Phase 1 (Infrastructure) 2h
Phase 2 (Services) 3h
Phase 3 (Controller) 2h
Phase 4 (Audit) 1h
Phase 5 (Tests) 4h
Total 12h

11. Artefacts produits

Artefact Type Destination
PD-79-plan.md Documentation docs/epics/b2c-mineurs/PD-79-evidence-upload/
PD-79-code-contracts.yaml Specification docs/epics/b2c-mineurs/PD-79-evidence-upload/
Migration TypeORM Code src/database/migrations/
CategoryConfigService Code src/modules/documents/services/
Tests Code src/modules/documents/**/*.spec.ts