Geracao de PDF

Os PDF do QuoteNode sao documentos comerciais de primeira classe, nao uma exportacao secundaria.

Visao geral do pipeline

Snapshot da proposta (JSON)
       |
       v
Motor de templates Thymeleaf
  |-- fragmentos de layout
  |-- CSS inline compativel com Gotenberg
  |-- imagens embebidas em Base64
  `-- suporte de paginacao
       |
       v
Documento HTML completo
       |
       v
Gotenberg
       |
       v
PDF final com metadados e checksum

Rendering baseado em snapshot

Os PDFs sao sempre gerados a partir de snapshots imutaveis, nunca diretamente dos dados live da proposta.

Quando a proposta e enviada:

1. o sistema captura um snapshot JSON completo
2. esse snapshot inclui cliente, linhas, pricing, FX, branding e configuracao de template
3. o snapshot e armazenado e versionado

Isto garante que o PDF representa exatamente o que foi proposto naquele momento, mesmo que o catalogo ou o branding mudem depois.

Estrutura do template

Um PDF inclui normalmente:

• cabecalho
• dados do destinatario
• tabela de itens
• totais
• condicoes comerciais
• footer

As tabelas de itens tambem podem variar por template, incluindo colunas configuraveis como SKU, imagens, unidade, IVA e modo de apresentacao de preco.

Familias de template

O sistema pode suportar familias como layouts tecnicos, variantes mais minimalistas e formatos mais visuais, mantendo a mesma base de dados documental.

Colunas configuraveis

Cada proposta pode controlar se o PDF mostra SKU, imagens, unidade, descricao, coluna de IVA e modo de desconto.

Integracao com branding

Logotipo, cores, titulos e informacao comercial do tenant entram automaticamente no PDF para manter coerencia de marca.

Modos de processamento

Modo sincrono

Para propostas pequenas:

1. o pedido HTTP desencadeia a geracao
2. o Thymeleaf renderiza HTML
3. o Gotenberg converte para PDF
4. a resposta volta no mesmo pedido

Modo assincrono

Para propostas grandes ou periodos de carga:

1. a API devolve 202 Accepted com jobId
2. e criado um registo de job na base de dados
3. um worker processa o PDF em background
4. em caso de sucesso, o PDF e armazenado e o utilizador pode ser notificado
5. em caso de falha, aplicam-se retries com backoff

Armazenamento e retention

Os PDFs gerados podem ser armazenados com metadados numa tabela dedicada, incluindo nome, tamanho, checksum, versao de snapshot e data de criacao.

Isto ajuda em auditoria, troubleshooting e em workflows onde o mesmo documento precisa de ser descarregado mais tarde sem nova renderizacao.

Integridade e retencao

Os ficheiros gerados sao acompanhados por:

• nome unico
• tamanho em bytes
• checksum SHA-256
• versao de snapshot usada
• data de criacao

Os PDFs podem ser retidos durante um periodo configuravel. Mesmo quando o ficheiro deixa de estar presente, os metadados continuam uteis para auditoria.

Branding e geracao

O PDF aplica automaticamente branding do tenant:

• logotipo
• cor principal
• cor de acento
• dados comerciais da empresa
• titulo customizado da proposta
• badge “Powered by” quando aplicavel

Esta integracao garante coerencia entre builder interno, PDF final e paginas publicas.

Configuracao do Gotenberg

O Gotenberg corre como um contentor dedicado baseado em Chromium. O backend comunica com ele por HTTP, o que evita dependencias diretas do browser no processo Java e isola melhor a parte de rendering.