PD-84 — Plan d'implémentation¶

Story : PD-84 — Encadrement contractuel de l'offre gratuite pour dossiers probatoires mineurs Version : 1.1.0 Date : 2026-02-24 Spec : PD-84-specification.md v1.3.0 Tests : PD-84-tests.md v1.3.0

Phase 0 — Go/No-Go¶

Verdict Go/No-Go : GO

Aucune dépendance bloquante. Le champ User.plan existe déjà. L'audit PD-31, le RLS et le framework de test sont opérationnels.

Contraintes techniques¶

Dépendances inter-PD¶

Framework de test¶

• Runner : Jest (CommonJS natif, pas de dépendance ESM)
• Tests unitaires : mocks TypeORM repositories + NestJS Test.createTestingModule()
• Tests d'intégration : PostgreSQL réel avec RLS, advisory locks testables
• Tests de concurrence (TC-LIM-01/02) : barrière de synchronisation via Promise.all() + réinitialisation entre itérations
• Tests SLA (TC-SLA-01) : injectable ClockProvider pour mesure p95

Compatibilité ESM/CJS¶

• Aucune dépendance ESM-only identifiée pour PD-84
• Runner Jest standard suffit (pas besoin de Vitest)

1. Découpage en composants¶

COMP-01 — Freemium Module (src/modules/freemium/)¶

Responsabilité : Module NestJS dédié aux règles freemium PD-84. Orchestration des quotas, gestion des dossiers probatoires, capabilities calculées, transition de plan.

COMP-02 — Entités & Migrations (src/database/)¶

Responsabilité : Schéma PostgreSQL pour ProbatoryFolder, extension User.plan, types audit PD-84.

COMP-03 — DTOs & Validation (src/modules/freemium/dto/)¶

Responsabilité : Validation des entrées, sérialisation des réponses.

COMP-04 — Exceptions PD-84 (src/modules/freemium/exceptions/)¶

Responsabilité : Codes erreur métier PD-84 avec mapping HTTP.

COMP-05 — Extension Audit PD-31¶

Responsabilité : Ajout des types d'action audit spécifiques PD-84 dans l'enum existant.

COMP-06 — Configuration¶

Responsabilité : Variables d'environnement PD-84.

2. Flux techniques¶

2.1 Flux nominal — Création d'un dossier (POST /folders)¶

Client → JwtAuthGuard → RlsMiddleware → FolderController.create()
  │
  ├─ 1. Extraire userId du JWT (@CurrentUser)
  ├─ 2. Valider CreateFolderDto (class-validator pipe)
  │    └─ category ∉ FolderCategory → 400 INVALID_FOLDER_CATEGORY
  ├─ 3. FolderService.createFolder(userId, dto)
  │    └─ Transaction sérialisée (pg_advisory_xact_lock sur hash(userId)):
  │        ├─ a. Charger User.plan
  │        ├─ b. Si plan === FREE: compter dossiers ACTIVE du user
  │        │    └─ count >= FREEMIUM_MAX_ACTIVE_FOLDERS → throw QUOTA_FOLDER_LIMIT_REACHED
  │        ├─ c. Si plan === PREMIUM: pas de vérification quota
  │        ├─ d. INSERT ProbatoryFolder (status=ACTIVE, sealed_document_count=0)
  │        └─ e. AuditLogService.logAsync(FOLDER_CREATE, folderId, metadata)
  └─ 4. Retourner 201 + FolderResponseDto

2.2 Flux nominal — Ajout de document scellé (POST /folders/{folderId}/documents)¶

Client → JwtAuthGuard → RlsMiddleware → FolderOwnerGuard → FolderDocumentController.addDocument()
  │
  ├─ 1. Extraire userId + folderId
  ├─ 2. FolderDocumentService.addDocument(userId, folderId, dto)
  │    └─ Transaction sérialisée (pg_advisory_xact_lock sur hash(folderId)):
  │        ├─ a. Charger ProbatoryFolder avec lock FOR UPDATE
  │        │    └─ folder.status === CLOSED_READ_ONLY → throw FOLDER_CLOSED_READ_ONLY
  │        ├─ b. Charger User.plan
  │        ├─ c. Si plan === FREE: vérifier sealed_document_count
  │        │    └─ count >= FREEMIUM_MAX_DOCUMENTS → throw QUOTA_DOCUMENT_LIMIT_REACHED
  │        ├─ d. Si plan === PREMIUM: pas de vérification quota document
  │        ├─ e. Déléguer scellement à DepositService (PD-60/PD-79) — même pipeline FREE/PREMIUM
  │        ├─ f. Incrémenter sealed_document_count (+1 atomique)
  │        └─ g. AuditLogService.logAsync(DOCUMENT_SEAL, documentId, {folderId, plan})
  └─ 3. Retourner 201 + DocumentResponseDto (avec probatory_seal_ref, integrity_state, anchoring_state)

2.3 Flux nominal — Clôture d'un dossier (POST /folders/{folderId}/close)¶

Client → JwtAuthGuard → RlsMiddleware → FolderOwnerGuard → FolderController.close()
  │
  ├─ 1. Extraire userId + folderId
  ├─ 2. FolderService.closeFolder(userId, folderId)
  │    └─ Transaction atomique :
  │        ├─ a. Charger ProbatoryFolder avec lock FOR UPDATE
  │        ├─ b. folder.status === CLOSED_READ_ONLY → throw 409 FOLDER_ALREADY_CLOSED (idempotence)
  │        ├─ c. UPDATE status = CLOSED_READ_ONLY, closed_at = NOW()
  │        └─ d. AuditLogService.logAsync(FOLDER_CLOSE, folderId, {sealed_document_count, closed_reason})
  └─ 3. Retourner 200 + FolderResponseDto

2.4 Flux nominal — Transition de plan (PUT /account/plan)¶

Client → JwtAuthGuard → PlanStubGuard → PlanController.changePlan()
  │
  ├─ 1. PlanStubGuard vérifie ENABLE_PLAN_STUB === true
  │    └─ Si false → 404 Not Found (endpoint invisible en production)
  ├─ 2. Valider ChangePlanDto (plan_type: FREE | PREMIUM)
  ├─ 3. PlanService.changePlan(userId, planType)
  │    └─ Transaction :
  │        ├─ a. Charger User.plan courant
  │        ├─ b. Si identique → retourner directement (idempotent)
  │        ├─ c. UPDATE User.plan = newPlan, premium_activated_at = NOW() (si PREMIUM)
  │        └─ d. AuditLogService.logAsync(PLAN_CHANGE, userId, {from, to})
  └─ 4. Retourner 200 + { plan_type, capabilities }

SLA — Garantie par construction (MAJ-01)¶

L'architecture de transition de plan est entièrement synchrone : un seul UPDATE User.plan + COMMIT dans la même transaction PostgreSQL. Les capabilities sont calculées à la volée depuis User.plan (pas de cache, pas de propagation asynchrone). Par conséquent :

• SLA p95 < 5s : garanti par construction — une transaction PostgreSQL UPDATE + COMMIT prend typiquement < 50ms.
• PLAN_STATE_INCONSISTENT (HTTP 500) : garde-fou théorique pour un timeout de transaction > PLAN_PROPAGATION_TIMEOUT_MS (30s). En architecture synchrone, ce cas ne se produit pas, mais le code le gère par défense en profondeur.
• TC-SLA-01 : mesure p95 sur N=50 transitions réelles (pas de mock). Le test valide que l'architecture synchrone tient la SLA spécifiée. L'instrumentation est intégrée au PlanService.changePlan() : le temps est mesuré entre le début de la transaction et le COMMIT, puis loggé dans l'événement audit PLAN_CHANGE (champ duration_ms dans les metadata).
• Pas d'observabilité externe requise : la SLA est une propriété structurelle de l'architecture, pas un objectif d'exploitation nécessitant un monitoring dédié.

2.5 Flux nominal — Export refusé en FREE (POST /folders/{folderId}/exports/*)¶

Client → JwtAuthGuard → RlsMiddleware → FolderOwnerGuard → ExportController.exportComposite()
  │
  ├─ 1. Charger User.plan
  ├─ 2. Si plan === FREE → throw PREMIUM_REQUIRED (422)
  │    └─ AuditLogService.logAsync(EXPORT_REFUSED, folderId, {plan, export_type, reason})
  └─ 3. Si plan === PREMIUM → 501 Not Implemented (PD-85 pas implémenté)

2.6 Flux nominal — Capabilities (GET /capabilities)¶

Client → JwtAuthGuard → CapabilityController.getCapabilities()
  │
  ├─ 1. Charger User.plan
  ├─ 2. CapabilityService.computeCapabilities(plan)
  │    └─ FREE  → { can_export_composite: false, can_export_structured_archive: false, ... }
  │    └─ PREMIUM → { can_export_composite: true, can_export_structured_archive: true, ... }
  └─ 3. Retourner 200 + CapabilityResponseDto

2.7 Flux downgrade PREMIUM → FREE¶

PUT /account/plan { "plan_type": "FREE" }
  │
  ├─ 1. PlanService.changePlan(userId, FREE)
  │    ├─ UPDATE User.plan = FREE
  │    └─ Audit PLAN_CHANGE (PREMIUM → FREE)
  ├─ 2. Effets immédiats (calcul à la volée, aucune action batch) :
  │    ├─ GET /capabilities → toutes capabilities false
  │    ├─ POST /folders → refusé si count(ACTIVE) > 3
  │    ├─ POST /folders/{id}/documents → refusé si sealed_document_count > 100
  │    └─ POST /folders/{id}/exports/* → refusé PREMIUM_REQUIRED
  └─ 3. Dossiers et documents existants : AUCUNE suppression, AUCUNE modification

2.8 Diagrammes Mermaid¶

2.8.1 Graphe de dépendances entre composants¶

graph TD
    subgraph "COMP-01 — Freemium Module"
        FC[FolderController]
        FDC[FolderDocumentController]
        EC[ExportController]
        PC[PlanController]
        CC[CapabilityController]
        FS[FolderService]
        FDS[FolderDocumentService]
        CS[CapabilityService]
        PS[PlanService]
        QG[QuotaGuard]
        FOG[FolderOwnerGuard]
        PSG[PlanStubGuard]
    end

    subgraph "COMP-02 — Entités & Migrations"
        PF[ProbatoryFolder Entity]
        PT[PlanType Enum]
        FSE[FolderStatus Enum]
        FCE[FolderCategory Enum]
        MIG[Migration PD-84]
    end

    subgraph "COMP-03 — DTOs"
        CFD[CreateFolderDto]
        ADD[AddDocumentDto]
        CPD[ChangePlanDto]
        FRD[FolderResponseDto]
        CRD[CapabilityResponseDto]
    end

    subgraph "COMP-04 — Exceptions"
        FEX[FreemiumException]
    end

    subgraph "COMP-05 — Audit Extension"
        AAT[AuditActionType]
    end

    subgraph "Services externes (PD existants)"
        ALS[AuditLogService — PD-31]
        DS[DepositService — PD-60/PD-79]
        RLS[RLS Middleware — PD-15]
        JWT[JwtAuthGuard — PD-28]
    end

    FC --> FS
    FC --> CFD
    FC --> FRD
    FDC --> FDS
    FDC --> ADD
    EC --> CS
    EC --> FEX
    PC --> PS
    PC --> CPD
    PC --> PSG
    CC --> CS
    CC --> CRD

    FS --> PF
    FS --> QG
    FS --> ALS
    FS --> FEX
    FDS --> PF
    FDS --> DS
    FDS --> ALS
    FDS --> FEX
    CS --> PT
    PS --> ALS
    PS --> PT
    PS --> FEX

    FOG --> PF
    FOG --> RLS

    FC --> JWT
    FDC --> JWT
    FDC --> FOG
    EC --> JWT
    EC --> FOG
    PC --> JWT
    CC --> JWT

    PF --> FSE
    PF --> FCE
    PF --> MIG

2.8.2 Diagramme de séquence — Création dossier + ajout document + clôture (flux nominal)¶

sequenceDiagram
    participant C as Client
    participant JWT as JwtAuthGuard
    participant RLS as RlsMiddleware
    participant FC as FolderController
    participant FS as FolderService
    participant PG as PostgreSQL
    participant ALS as AuditLogService<br/>(PD-31)

    Note over C,ALS: Flux 2.1 — Création dossier (POST /folders)
    C->>JWT: POST /folders {display_name, category}
    JWT->>RLS: userId extrait du JWT
    RLS->>FC: create(userId, dto)
    FC->>FS: createFolder(userId, dto)
    FS->>PG: pg_advisory_xact_lock(hash(userId))
    FS->>PG: SELECT COUNT(*) FROM probatory_folders<br/>WHERE owner_user_id = userId AND status = 'ACTIVE'
    alt count < 3 (FREE) ou PREMIUM
        FS->>PG: INSERT probatory_folders (status=ACTIVE)
        FS->>ALS: logAsync(FOLDER_CREATE, folderId)
        FS-->>FC: FolderResponseDto
        FC-->>C: 201 Created
    else count >= 3 (FREE)
        FS->>ALS: logAsync(QUOTA_FOLDER_REFUSED)
        FS-->>FC: throw QUOTA_FOLDER_LIMIT_REACHED
        FC-->>C: 422 + code erreur + upgrade CTA
    end

2.8.3 Diagramme de séquence — Ajout document scellé¶

sequenceDiagram
    participant C as Client
    participant FOG as FolderOwnerGuard
    participant FDC as FolderDocumentController
    participant FDS as FolderDocumentService
    participant PG as PostgreSQL
    participant DS as DepositService<br/>(PD-60)
    participant ALS as AuditLogService<br/>(PD-31)

    Note over C,ALS: Flux 2.2 — Ajout document (POST /folders/{id}/documents)
    C->>FOG: POST /folders/{folderId}/documents
    FOG->>PG: Vérifier ownership (RLS + check explicite)
    FOG->>FDC: addDocument(userId, folderId, dto)
    FDC->>FDS: addDocument(userId, folderId, dto)
    FDS->>PG: pg_advisory_xact_lock(hash(folderId))
    FDS->>PG: SELECT probatory_folders FOR UPDATE
    alt folder.status = CLOSED_READ_ONLY
        FDS-->>FDC: throw FOLDER_CLOSED_READ_ONLY
        FDC-->>C: 422
    else folder.status = ACTIVE
        FDS->>PG: Vérifier sealed_document_count (FREE)
        alt count < 100 ou PREMIUM
            FDS->>DS: createDeposit(dto, folderId)
            DS-->>FDS: deposit result (seal_ref, integrity, anchoring)
            FDS->>PG: UPDATE sealed_document_count += 1
            FDS->>ALS: logAsync(DOCUMENT_SEAL)
            FDS-->>FDC: DocumentResponseDto
            FDC-->>C: 201 Created
        else count >= 100 (FREE)
            FDS->>ALS: logAsync(QUOTA_DOCUMENT_REFUSED)
            FDS-->>FDC: throw QUOTA_DOCUMENT_LIMIT_REACHED
            FDC-->>C: 422 + message Premium
        end
    end

2.8.4 Diagramme de séquence — Transition de plan (upgrade/downgrade)¶

sequenceDiagram
    participant C as Client
    participant PSG as PlanStubGuard
    participant PC as PlanController
    participant PS as PlanService
    participant CS as CapabilityService
    participant PG as PostgreSQL
    participant ALS as AuditLogService<br/>(PD-31)

    Note over C,ALS: Flux 2.4 — PUT /account/plan
    C->>PSG: PUT /account/plan {plan_type: PREMIUM}
    alt ENABLE_PLAN_STUB = false
        PSG-->>C: 404 Not Found (endpoint invisible)
    else ENABLE_PLAN_STUB = true
        PSG->>PC: changePlan(userId, dto)
        PC->>PS: changePlan(userId, PREMIUM)
        PS->>PG: SELECT User.plan
        alt plan identique (idempotent)
            PS-->>PC: plan inchangé
        else plan différent
            PS->>PG: UPDATE User.plan = PREMIUM,<br/>premium_activated_at = NOW()
            PS->>ALS: logAsync(PLAN_CHANGE, {from: FREE, to: PREMIUM})
        end
        PC->>CS: computeCapabilities(PREMIUM)
        CS-->>PC: {can_export_composite: true, ...}
        PC-->>C: 200 + {plan_type, capabilities}
    end

3. Mapping invariants → mécanismes¶

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

5. Mapping tests (TC-*) → mécanismes + observables¶

6. Gestion des erreurs¶

6.1 Codes erreur PD-84¶

6.2 Pattern d'exception¶

// Même pattern que MerkleException (PD-237)
export type FreemiumErrorCode =
  | 'QUOTA_FOLDER_LIMIT_REACHED'
  | 'QUOTA_DOCUMENT_LIMIT_REACHED'
  | 'PREMIUM_REQUIRED'
  | 'FOLDER_CLOSED_READ_ONLY'
  | 'FOLDER_ALREADY_CLOSED'
  | 'INVALID_FOLDER_CATEGORY'
  | 'FOLDER_NOT_FOUND'
  | 'PLAN_STATE_INCONSISTENT';

export class FreemiumException extends HttpException {
  constructor(code: FreemiumErrorCode, message: string) { ... }
}

6.3 Audit des erreurs¶

Chaque erreur métier de type refus (quota, export, plan) génère un événement audit via AuditLogService.logAsync(). L'audit est non-bloquant : si PD-31 est indisponible, le refus est retourné au client et l'événement est en queue BullMQ pour retry. Ceci respecte INV-84-03 (la constitution de dossier n'est jamais bloquée par l'audit) et le cadrage SEC-84-03/ECT-v2-03.

7. Impacts sécurité¶

7.1 Risques et mitigations¶

7.2 Journalisation¶

Événements auditables PD-84 à ajouter à AuditActionType :

Note : FOLDER_CREATE existe déjà dans AuditActionType.

7.3 RGPD¶

• PD-84 ne collecte aucune donnée personnelle supplémentaire au-delà de owner_user_id (déjà couvert par PD-15).
• Le champ account_role (MINOR, LEGAL_GUARDIAN, OTHER) est ajouté comme colonne nullable dans la migration PD-84 mais n'est utilisé par aucun service PD-84. Sa valorisation et sa gestion RGPD (consentement parental < 16 ans) relèvent de l'epic PD-185.
• Le contenu des preuves reste chiffré côté client (INV-84-12, hérité PD-60).

8. Hypothèses techniques¶

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

9.1 Risques¶

1. Migration du champ User.plan : Le champ actuel est un string ('free'). La migration vers un enum PostgreSQL doit gérer les valeurs existantes ('free' → 'FREE', 'premium' → 'PREMIUM'). Prévoir un script de backfill dans la migration.

2. Atomicité des quotas sous concurrence : Les TC-LIM-01 et TC-LIM-02 exigent un résultat déterministe sur 30 itérations. Le pg_advisory_xact_lock doit utiliser un hash stable (bigint) du userId/folderId. Utiliser hashCode(uuid) via une fonction PL/pgSQL ou un hash côté application.

3. Couplage avec PD-60 pour le scellement : PD-84 ajoute un folderId au flow de dépôt. Si l'interface DepositService change dans une story ultérieure, PD-84 doit être mis à jour. Minimiser le couplage en passant le folderId comme métadonnée optionnelle.

4. TC-SLA-01 (N=50) : Le test de performance SLA nécessite un environnement stable (pas de contention CI). Prévoir une tolérance ou un marqueur @Slow pour l'exécuter séparément.

5. TC-06 (test UI) : Ce test valide des éléments visuels ("bouton grisé", "CTA visible"). En l'absence de frontend, il sera couvert côté API uniquement (vérification du JSON retourné). Le test E2E complet relève de l'application mobile (PD-185 epic).

9.2 Dette technique identifiée¶

1. Champ account_role : La spec définit MINOR, LEGAL_GUARDIAN, OTHER. La migration PD-84 crée la colonne account_role (enum PostgreSQL account_role_type, nullable, default NULL) sur la table users. Aucun service PD-84 ne lit ni ne conditionne sur ce champ — il prépare les stories suivantes de l'epic PD-185. La valorisation du champ relèvera du flux d'inscription mineur (PD-185).

2. Champ closed_reason : Modélisé dans la spec (section 3.1) mais jamais peuplé par les endpoints PD-84 (AMB-v2-03). Il sera nullable en base, prêt pour enrichissement futur.

3. Export PREMIUM : Les endpoints export retournent PREMIUM_REQUIRED en FREE et 501 Not Implemented en PREMIUM (PD-85 pas encore implémenté). C'est un stub explicite.

9.3 Pièges à éviter¶

1. Ne PAS toucher au pipeline de scellement PD-60/PD-79 : PD-84 ajoute des gardes de quota en amont du scellement. Le scellement lui-même est identique FREE/PREMIUM.

2. Ne PAS persister CapabilityState : C'est une vue calculée (ECT-06). Toute persistance introduirait un risque de désynchronisation.

3. Ne PAS ajouter de cron/scheduler de reset quota : INV-84-04 interdit toute remise à zéro périodique.

4. crypto.randomUUID() : Utiliser pour tout identifiant (pas Math.random()). Convention backend existante.

10. Hors périmètre¶

Checklist INV/CA pre-Gate 5¶

Couverture : 15/15 INV couverts, 14/14 CA couverts. Aucune ligne vide.