PDF-Generierungspipeline

QuoteNode erzeugt druckfertige PDF-Dokumente aus Angebotsdaten über eine zweistufige Pipeline: HTML-Rendering mit Thymeleaf und anschließende PDF-Konvertierung durch Gotenberg.

Pipeline-Überblick

Angebots-Snapshot (JSON)
        │
        ▼
Thymeleaf Template Engine
  ├── Layout-Fragmente (Header, Positionstabelle, Summen, Footer)
  ├── Inline-CSS für Gotenberg-Kompatibilität
  ├── Produktbilder als base64-URIs
  └── Paginierung (Seite X/Y)
        │
        ▼
HTML-Dokument (vollständig, in sich geschlossen)
        │
        ▼
Gotenberg (Chromium-basierter Container)
        │
        ▼
PDF-Datei (gespeichert mit SHA-256-Checksumme)

Snapshot-basiertes Rendering

PDFs werden immer aus unveränderlichen Snapshots und nie aus Live-Daten gerendert. Beim Versand eines Angebots:

1. erstellt das System einen vollständigen JSON-Snapshot des Angebotszustands,
2. enthält dieser Snapshot Kundendaten, alle Positionen, Preise, FX-Kurse, Branding und Template-Einstellungen,
3. wird der Snapshot gespeichert und versioniert.

So ist sichergestellt, dass ein PDF immer exakt das zeigt, was zu diesem Zeitpunkt tatsächlich angeboten wurde — unabhängig von späteren Änderungen an Katalog, Kundendaten oder Branding.

Vorlagensystem

Vorlagenfamilien

Aktuell ist die Familie CLASSIC_B2B_TECHNICAL implementiert. Weitere Varianten sind geplant:

• MINIMAL_B2B
• B2C_FRIENDLY
• MULTI_CURRENCY
• SERVICE_HOURS

Struktur einer Vorlage

Jede PDF-Vorlage besteht aus:

• Header — Verkäuferlogo, Firmenname, Adresse und Kontakt
• Metabereich — Empfängeradresse, Angebotsnummer, Ansprechpartner, Datum und Gültigkeit
• Positionstabelle — konfigurierbare Spalten mit Preisdetails
• Summenbereich — Zwischensumme, Rabatte, Versand, MwSt.-Breakdown und Endsumme
• Geschäftsbedingungen — Zahlungsbedingungen, Garantie, Lieferung, Transport
• Signaturbereich — Raum für Freigaben
• Footer — Register- und Unternehmensdaten

Konfigurierbare Spalten

Die Positionstabelle wird über Template-Einstellungen pro Angebot gesteuert:

Einstellung	Wirkung
showSku	SKU-Spalte ein- oder ausblenden
showImages	Produktbilder in der Tabelle anzeigen
imageSize	Small (60px), medium (90px) oder none
showDescription	Produktbeschreibungen anzeigen
showUnit	Einheitsspalte anzeigen
showVatColumn	MwSt.-Spalte anzeigen
priceMode	NET, GROSS oder NET+VAT+GROSS
discountDisplay	BAKED_IN, SHOW_COLUMN oder HIDDEN

Branding-Integration

Das PDF übernimmt automatisch die Branding-Konfiguration des Tenants:

• Logo — Firmenlogo im Header
• Primärfarbe — für Header, Linien und Akzente
• Akzentfarbe — für sekundäre Elemente
• Firmendaten — Name, Adresse, Telefon, E-Mail, Registerangaben
• Eigener Dokumenttitel — Override des Standardtitels
• “Powered by”-Badge — sichtbar in der Free Edition, entfernbar ab Pro

Verarbeitungsmodi

Synchron

Für Angebote mit weniger als 50 Positionen:

1. löst der API-Request die PDF-Erzeugung direkt aus,
2. Thymeleaf rendert HTML, Gotenberg wandelt in PDF um,
3. der PDF-Stream wird in derselben HTTP-Response zurückgegeben.

Zielwert: p95 unter 3 Sekunden.

Asynchron

Für große Angebote oder unter Last:

1. liefert das API HTTP 202 mit jobId,
2. ein PdfJob wird mit Status PENDING gespeichert,
3. ein Worker übernimmt den Job,
4. bei Erfolg wird das PDF gespeichert und der Benutzer benachrichtigt,
5. bei Fehler erfolgt Retry mit Backoff,
6. dauerhaft fehlerhafte Jobs landen in einer Dead-Letter-Queue.

Speicherung und Retention

Erzeugte PDFs werden als Dateien mit Metadaten in generated_documents gespeichert:

• Dateiname,
• Dateigröße,
• SHA-256-Checksumme,
• Snapshot-Version,
• Erzeugungszeitpunkt.

Standard-Retention: 365 Tage. Danach können Dateien bereinigt werden, während Metadaten aus Audit-Gründen erhalten bleiben.

Gotenberg-Konfiguration

Gotenberg läuft als separater Docker-Container und nutzt Chromium für HTML-zu-PDF:

• präzises Rendering moderner CSS-Layouts,
• Paginierung mit konfigurierbaren Rändern,
• Unterstützung für A4, Letter und benutzerdefinierte Formate,
• Header/Footer-Rendering inklusive Seitennummern.

Das Backend spricht Gotenberg über dessen HTTP-API an. Direkte Chromium-Steuerung ist nicht nötig.