Pipeline di generazione PDF

QuoteNode genera documenti PDF pronti per la stampa dai dati offerta usando una pipeline in due fasi: rendering HTML via Thymeleaf e conversione PDF via Gotenberg.

Panoramica della pipeline

Offer Snapshot (JSON)
       │
       ▼
Thymeleaf Template Engine
       │
       ▼
HTML Document
       │
       ▼
Gotenberg
       │
       ▼
PDF File

Rendering basato su snapshot

I PDF vengono sempre renderizzati da snapshot immutabili, mai da dati offerta live. Quando un’offerta viene inviata:

1. il sistema cattura uno snapshot JSON completo
2. lo snapshot include cliente, righe, prezzi, cambi, branding e impostazioni template
3. lo snapshot viene memorizzato e versionato

Questo garantisce che il PDF rappresenti esattamente cio che e stato offerto in quel momento.

Sistema di template

Famiglie di template

L’implementazione attuale include la famiglia CLASSIC_B2B_TECHNICAL. Sono previste varianti future come MINIMAL_B2B, B2C_FRIENDLY, MULTI_CURRENCY e SERVICE_HOURS.

Struttura template

Ogni template PDF contiene:

• header
• meta section
• tabella articoli
• riepilogo totali
• condizioni commerciali
• blocco firma
• footer

Colonne configurabili

La tabella articoli puo essere controllata per offerta tramite impostazioni template, come showSku, showImages, showDescription, showUnit, showVatColumn, priceMode e discountDisplay.

Integrazione branding

Il PDF applica automaticamente il branding del tenant:

• logo
• primary color
• accent color
• dettagli aziendali
• titolo offerta custom
• eventuale badge Powered by

Modalita di elaborazione

Sincrona

Per offerte con meno di 50 righe:

1. la richiesta API genera il PDF
2. Thymeleaf produce l’HTML
3. Gotenberg converte in PDF
4. il PDF ritorna nella stessa risposta HTTP

Asincrona

Per offerte grandi o server sotto carico:

1. l’API restituisce 202 Accepted con un jobId
2. viene creato un record PdfJob
3. un worker elabora il job
4. a successo, il PDF viene salvato e l’utente notificato
5. a fallimento, si applicano retry con backoff

Storage e retention

I PDF generati vengono salvati con metadati in generated_documents:

• filename
• file size
• checksum SHA-256
• snapshot version
• timestamp di creazione

La retention predefinita e di 365 giorni, configurabile.

Integrazione branding

Il PDF applica automaticamente logo, colori, dati societari, titolo documento e badge opzionali definiti dal tenant e dal template scelto.

Configurazione Gotenberg

Gotenberg gira come container separato e fornisce rendering CSS moderno, paginazione e supporto a header e footer, mentre il backend comunica con esso via HTTP.

Riepilogo commerciale

Il PDF finale include normalmente subtotal, shipping, breakdown IVA e totale finale, cosi da rimanere coerente con quanto l’operatore vede nel builder dell’offerta.

Condizioni e chiusura del documento

I template PDF possono includere condizioni commerciali, blocchi firma e footer amministrativi, cosi da produrre un documento pronto all’uso per il cliente.

Integrita del file

I PDF salvati vengono accompagnati da metadati e checksum, utili per audit, troubleshooting e verifiche di integrita nel tempo.

Motivazione architetturale

Separare il rendering HTML dalla conversione PDF rende il sistema piu leggibile, piu testabile e piu facile da mantenere quando cambiano branding o template.