Pipeline de generacion de PDF

QuoteNode genera documentos PDF listos para imprimir a partir de datos de oferta usando un pipeline de dos etapas: render HTML mediante Thymeleaf y conversion a PDF mediante Gotenberg.

Vision general del pipeline

Offer Snapshot (JSON)
       │
       ▼
Thymeleaf Template Engine
  ├── Layout fragments (header, items table, totals, footer)
  ├── CSS inline para compatibilidad con Gotenberg
  ├── Imagenes de producto embebidas como URIs base64
  └── Soporte de paginacion (Page X/Y)
       │
       ▼
HTML Document (complete, self-contained)
       │
       ▼
Gotenberg (contenedor basado en Chromium)
       │
       ▼
PDF File (guardado con checksum SHA-256)

Render basado en snapshots

Los PDF siempre se renderizan desde snapshots inmutables, nunca desde datos vivos de la oferta. Cuando una oferta se envia:

1. el sistema captura un snapshot JSON completo del estado de la oferta
2. el snapshot incluye datos del cliente, lineas, precios, tipos FX, branding y ajustes de plantilla
3. el snapshot se almacena y versiona con snapshot_version

Esto garantiza que el PDF representa exactamente lo ofertado en esa fecha, aunque despues cambien precios, datos del cliente o branding.

Sistema de plantillas

Familias de plantillas

La implementacion actual incluye la familia CLASSIC_B2B_TECHNICAL. Hay variantes futuras planificadas:

• MINIMAL_B2B
• B2C_FRIENDLY
• MULTI_CURRENCY
• SERVICE_HOURS

Estructura de la plantilla

Cada plantilla PDF consta de:

• Header - logo del vendedor, nombre de empresa, direccion y datos de contacto
• Meta section - direccion del destinatario, numero de oferta, comercial, fecha y validez
• Items table - columnas configurables con detalles de precio
• Totals summary - subtotal, descuentos, shipping, desglose de IVA y total final
• Trading conditions - terminos de pago, garantia, entrega y transporte
• Signature block - espacio para firmas de aprobacion
• Footer - datos de registro de la empresa

Columnas configurables

Las columnas de la tabla de items se controlan por oferta mediante ajustes de plantilla:

Ajuste	Efecto
showSku	Muestra u oculta la columna SKU
showImages	Muestra fotos de producto en la tabla
imageSize	Tamano small, medium o none
showDescription	Incluye descripciones de producto
showUnit	Muestra la unidad de medida
showVatColumn	Muestra la columna de IVA
priceMode	Modo NET, GROSS o NET+VAT+GROSS
discountDisplay	BAKED_IN, SHOW_COLUMN o HIDDEN

Integracion de branding

El PDF aplica automaticamente el branding del tenant:

• Logo - PNG o SVG en la cabecera
• Primary color - para cabeceras, bordes y acentos
• Accent color - para elementos secundarios
• Company details - nombre, direccion, telefono, email y registro
• Custom offer title - override del encabezado por defecto
• Powered by badge - visible en la edicion Free y eliminable en Pro+

Modos de procesamiento

Sincrono (por defecto)

Para ofertas con menos de 50 lineas:

1. la peticion API dispara la generacion PDF
2. Thymeleaf genera HTML y Gotenberg lo convierte a PDF
3. el stream PDF vuelve en la misma respuesta HTTP
4. objetivo SLA: p95 inferior a 3 segundos

Asincrono

Para ofertas grandes o servidores cargados:

1. la API responde HTTP 202 con jobId
2. se crea un registro PdfJob en PostgreSQL con estado PENDING
3. un worker toma el trabajo mediante patron SKIP LOCKED
4. si tiene exito, se guarda el PDF, se actualiza el estado y se envia una notificacion
5. si falla, se reintenta con backoff exponencial
6. los fallos permanentes pasan a una tabla DLQ

Almacenamiento y retencion

Los PDF generados se almacenan como ficheros con metadatos en generated_documents:

• Filename - identificador unico
• File size - tamano en bytes
• SHA-256 checksum - verificacion de integridad
• Snapshot version - referencia al snapshot usado
• Created at - momento de generacion

Politica de retencion: por defecto, los PDF se retienen durante 365 dias. Despues, el fichero puede limpiarse pero el registro de metadatos se conserva para auditoria.

Configuracion de Gotenberg

Gotenberg corre como un contenedor Docker separado. Usa Chromium para la conversion HTML a PDF y ofrece:

• render preciso de CSS moderno
• paginacion con margenes configurables
• soporte de tamanos de pagina, como A4 o Letter
• cabeceras y pies con numeracion de paginas

El backend se comunica con Gotenberg mediante su API HTTP. No hace falta controlar Chromium directamente.