Fiche Express Programme — Génération PDF

Summary

A Pro (or Admin) requests a formatted PDF brochure for an entire Programme (new-build development). The system fetches programme data along with the Pro’s branding, renders a dedicated HTML template, and converts it to PDF via Puppeteer. Only download mode is currently available — email delivery is stubbed and returns 501. The Pro receives personalized agency branding in the output; Admin callers fall back to default SeaLion branding. The PDF is capped at 4 MB.

State Diagram

stateDiagram-v2
    state "Requête reçue" as RequestReceived
    state "Vérification mode email" as EmailModeCheck
    state "Non implémenté" as NotImplemented
    state "Chargement données" as DataFetch
    state "Programme introuvable" as ProgrammeNotFound
    state "Session pro invalide" as ProNotFound
    state "Rendu HTML" as HtmlRender
    state "Génération PDF" as PdfGeneration
    state "Vérification taille" as SizeCheck
    state "PDF trop lourd" as TooLarge
    state "Téléchargement" as Download

    [*] --> RequestReceived
    RequestReceived --> EmailModeCheck: request received
    EmailModeCheck --> NotImplemented: mode = email
    NotImplemented --> [*]
    EmailModeCheck --> DataFetch: mode = download
    DataFetch --> ProgrammeNotFound: programme missing
    DataFetch --> ProNotFound: pro session invalid
    ProgrammeNotFound --> [*]
    ProNotFound --> [*]
    DataFetch --> HtmlRender: data fetched
    HtmlRender --> PdfGeneration
    PdfGeneration --> SizeCheck
    SizeCheck --> TooLarge: PDF > 4 MB
    TooLarge --> [*]
    SizeCheck --> Download: PDF <= 4 MB
    Download --> [*]: PDF streamed to browser

Steps

1. Authentication (Actor: system)

Every request passes through authenticateProOrAdmin. A valid Pro or Admin JWT is required.

Triggers: Incoming POST request to /:programmeId/generate Outcome: request.proId or request.adminId populated; 401 if missing

2. Body Validation (Actor: system)

The request body is validated against generateFicheProgrammeBodySchema. Required fields: mode (download | email), selectedDispositifs (array of financing scheme keys). Optional: email, message.

Triggers: Auth passed Outcome: Typed body available

3. Email Mode Guard (Actor: system)

If mode = email, the route immediately returns 501 EMAIL_COMING_SOON. Email delivery for programme fiches is not yet implemented.

Triggers: Body validated Outcome: 501 response for email mode; download mode continues

4. Data Fetch (Actor: system)

buildFicheProgrammeData({ programmeId, proId, selectedDispositifs }) queries the database for the programme and the Pro’s profile. Admin callers pass proId = null and get SeaLion default branding. ProgrammeNotFoundError and ProNotFoundError are caught and mapped to HTTP errors.

Triggers: Download mode confirmed Outcome: Structured data object with programme, lots, and pro; errors mapped to 404 / 401

5. HTML Rendering (Actor: system)

renderFicheProgrammeHtml(data) produces a complete HTML page for the programme — cover, description, available lots with pricing, selected financing schemes, and Pro branding.

Triggers: Data fetch succeeded Outcome: HTML string ready for PDF conversion

6. PDF Generation (Actor: system)

renderHtmlToPdf(html) launches Puppeteer headless, renders the HTML, and prints to PDF.

Triggers: HTML rendered Outcome: Buffer containing the PDF bytes

7. Size Check & Download (Actor: system)

The PDF buffer is checked against the 4 MB cap. If within limits, the response is sent with Content-Type: application/pdf and Content-Disposition: attachment. Filename format: SeaLion_{Programme}_Fiche_{YYYY-MM-DD}.pdf.

Triggers: PDF generated Outcome: Browser downloads the PDF; 413 PDF_TOO_LARGE if cap exceeded

Error States

• Email mode requested → 501, EMAIL_COMING_SOON — “L’envoi par email sera disponible prochainement”
• Programme not found → 404, PROGRAMME_NOT_FOUND — “Programme introuvable”
• Pro session invalid (proId in token does not resolve) → 401, PRO_NOT_FOUND — “Session invalide”
• PDF exceeds 4 MB → 413, PDF_TOO_LARGE — “PDF trop volumineux”

Related Processes

• fiche-express-lot — same PDF pipeline scoped to a single Lot, with email delivery and floor-plan support already implemented
• registration — prerequisite: Pro must be registered and active to access this route