Plan d'implémentation — PD-63¶

Story : PD-63 — GET /documents/:id/download Date : 2026-02-20 Auteur : Claude (Orchestrateur) Version : v2 — Corrections Gate 5 v1

1. Analyse de l'existant¶

1.1 Base PD-46 (DONE)¶

L'endpoint GET /documents/:id/download est déjà implémenté par PD-46 :

1.2 Deltas PD-63 vs PD-46¶

PD-63 ajoute/modifie les éléments suivants :

2. Découpage en composants¶

2.1 Module Download (modifications)¶

src/modules/documents/download/
├── download.controller.ts      # Pas de modification
├── download.service.ts         # Δ1: fail-closed
├── download.errors.ts          # Δ2, Δ8: nouveaux codes
├── download.constants.ts       # Pas de modification
├── download.dto.ts             # Pas de modification
├── download.module.ts          # Pas de modification
├── interceptors/
│   └── audit-reject.interceptor.ts  # Δ9: journaliser rejets précoces
└── guards/
    └── document-access.guard.ts # Δ3, Δ4, Δ5: partage + B2B + statuts

2.2 Module Audit (modifications)¶

src/modules/documents/audit/
└── audit-download.service.ts   # Δ7: schéma enrichi

2.3 Entity DocumentSecure (modifications)¶

src/modules/documents/entities/
└── document-secure.entity.ts   # Δ6: 5 champs (deleted_at, deletion_reason, legal_lock, legal_lock_reason, legal_lock_until)

2.4 Migration (nouveau)¶

src/database/migrations/
└── YYYYMMDDHHMMSS-add-document-status-fields.ts  # Δ6 (5 champs)

2.5 Diagrammes Mermaid¶

Graphe de dépendances des composants¶

graph TD
    subgraph "Module Download"
        CTRL["download.controller.ts"]
        SVC["download.service.ts"]
        ERR["download.errors.ts"]
        GUARD["document-access.guard.ts"]
        INTCPT["audit-reject.interceptor.ts"]
    end

    subgraph "Module Audit"
        AUDIT["audit-download.service.ts"]
    end

    subgraph "Module Documents"
        ENTITY["document-secure.entity.ts"]
        MIG["migration: add-document-status-fields"]
    end

    subgraph "Externe"
        S3["s3-presign.service.ts"]
        JWT["OidcJwtAuthGuard"]
        DB[(PostgreSQL)]
    end

    CTRL -->|"@UseGuards"| JWT
    CTRL -->|"@UseGuards"| GUARD
    CTRL -->|"@UseInterceptors"| INTCPT
    CTRL --> SVC
    SVC --> S3
    SVC -->|"fail-closed Δ1"| AUDIT
    GUARD -->|"check owner/partage/B2B Δ3-Δ5"| ENTITY
    GUARD --> DB
    INTCPT -->|"log rejets 401/403/404 Δ9"| AUDIT
    SVC --> ERR
    GUARD --> ERR
    ENTITY -->|"5 champs Δ6"| MIG
    MIG --> DB

Diagramme de séquence — Téléchargement nominal (owner)¶

sequenceDiagram
    actor Client
    participant CTRL as download.controller
    participant JWT as OidcJwtAuthGuard
    participant GUARD as document-access.guard
    participant SVC as download.service
    participant AUDIT as audit-download.service
    participant S3 as s3-presign.service

    Client->>CTRL: GET /documents/:id/download
    CTRL->>JWT: canActivate()
    JWT-->>CTRL: ✓ JWT valide

    CTRL->>GUARD: canActivate()
    GUARD->>GUARD: check owner (PD-46)
    GUARD->>GUARD: check statut document (Δ5)
    GUARD-->>CTRL: ✓ accès autorisé

    CTRL->>SVC: getDownloadUrl(documentId, userId)
    SVC->>AUDIT: emit(DOWNLOAD_REQUESTED)
    alt Audit OK
        AUDIT-->>SVC: ✓
        SVC->>S3: getSignedUrl(GetObjectCommand, TTL=300s)
        S3-->>SVC: presignedUrl
        SVC-->>CTRL: { url, expiresIn: 300 }
        CTRL-->>Client: 200 { url, expiresIn }
    else Audit KO (fail-closed Δ1)
        AUDIT-->>SVC: ✗ erreur
        SVC-->>CTRL: ERR-63-11 (503)
        CTRL-->>Client: 503 Service Unavailable
    end

Diagramme de séquence — Rejet précoce (intercepteur Δ9)¶

sequenceDiagram
    actor Client
    participant INTCPT as audit-reject.interceptor
    participant JWT as OidcJwtAuthGuard
    participant AUDIT as audit-download.service

    Client->>INTCPT: GET /documents/:id/download
    INTCPT->>JWT: canActivate()
    JWT-->>INTCPT: ✗ 401 Unauthorized

    INTCPT->>AUDIT: emit(DOWNLOAD_REJECTED, { reason: "401", documentId })
    AUDIT-->>INTCPT: ✓
    INTCPT-->>Client: 401 Unauthorized

3. Mapping Invariants → Mécanismes¶

4. Mapping Critères → Tests¶

4b. Mapping ERR → Mécanismes/Tâches¶

5. Plan de tâches¶

Phase 0 — Vérifications préalables (go/no-go)¶

Règle : Si un critère échoue, escalader avant Phase 1. Ne pas bloquer l'implémentation sans décision explicite.

Phase 1 — Migration et Entity (Δ6)¶

Champs migration : - deleted_at TIMESTAMP NULL - deletion_reason VARCHAR(50) NULL - legal_lock BOOLEAN DEFAULT false - legal_lock_reason VARCHAR(50) NULL - legal_lock_until TIMESTAMP NULL

Phase 2 — Codes d'erreur (Δ2, Δ8)¶

Phase 3 — Guard enrichi (Δ3, Δ4, Δ5)¶

Note tâche 8 : Pour statut ARCHIVED, vérifier accessibilité S3 via HEAD Object. Si non accessible (Glacier non restauré), retourner ERR-63-10 (503).

Phase 4 — Audit fail-closed (Δ1, Δ7)¶

Phase 5 — Intercepteur audit global (Δ9)¶

Phase 6 — Tests d'intégration¶

Total : 16 tâches (+ 4 vérifications Phase 0)

6. Code Contracts¶

Voir fichier séparé PD-63-code-contracts.yaml.

7. Contraintes techniques¶

7.1 Dépendances inter-PD¶

7.2 Framework de test¶

• Runner : Jest (existant)
• Tests d'intégration : Avec services réels (PostgreSQL, Redis)
• Mocks : S3 via mock-aws-sdk
• Environnement CI : DATABASE_URL, REDIS_URL, S3_* vars

7.3 Compatibilité ESM/CJS¶

• Projet en CommonJS (pas d'ESM)
• Pas de dépendance ESM-only identifiée

8. Hypothèses d'implémentation¶

9. Points de vigilance¶

10. Estimation¶

Généré par : Claude (Orchestrateur) Date : 2026-02-20 Version : v2 — Corrections Gate 5 v1

Corrections appliquées (Gate 5 v1)¶