Migração: PDF → HTML/CSS + Puppeteer

Resumo

Substituir o fluxo atual (upload PDF → pdf-lib overlay) por: upload DOCX → backend converte para HTML → usuário seleciona texto e atribui variáveis no HTML → backend substitui variáveis e gera PDF via Puppeteer.

Fase 1: Backend (Node.js)

1.1 Dependências

bash

npm install mammoth puppeteer jsdom dompurify
npm install -D @types/dompurify

mammoth (v1.8+): conversão DOCX → HTML preservando formatação
puppeteer (v23+): renderização HTML → PDF com Chromium headless
jsdom + dompurify: sanitização e manipulação do HTML no servidor

1.2 Schema do banco (Template)

Alterações no model/schema existente:

typescript

// ANTES
{
  pdfId: string       // ← REMOVER
  pdfPath: string     // ← REMOVER
  content: string     // ← REMOVER
  variablesMapping: VariableMapping[]  // ← REMOVER
  variables: TemplateVariable[]        // mantém
}

// DEPOIS
{
  htmlContent: string  // ← NOVO: HTML completo com markers <span data-var="...">
  variables: TemplateVariable[]  // mantém (metadados: type, required, source)
}

Migration SQL/Mongo (se aplicável):

Adicionar coluna/campo htmlContent: text/string
Remover colunas/campos pdfId, pdfPath, content, variablesMapping
Templates existentes precisarão ser recriados (não há conversão automática PDF → HTML)

1.3 Endpoint: `POST /templates/upload-docx`

Substitui POST /templates/upload-pdf

Request:

Content-Type: multipart/form-data

file: <arquivo .docx>  (obrigatório, max 10MB)
fileName: string        (obrigatório)

Validações:

MIME: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Extensão: .docx
Tamanho máximo: 10MB

Response (200):

json

{
  "htmlContent": "<h1>Título</h1><p>Conteúdo convertido...</p>",
  "fileName": "contrato-servicos.docx"
}

Erros:

400: arquivo inválido, não é DOCX, ou excede tamanho
422: falha na conversão (DOCX corrompido)
500: erro interno

Implementação de referência:

typescript

import mammoth from 'mammoth'
import { JSDOM } from 'jsdom'
import createDOMPurify from 'dompurify'

// Configurar DOMPurify no servidor (não tem DOM nativo)
const window = new JSDOM('').window
const DOMPurify = createDOMPurify(window)

async function convertDocxToHtml(fileBuffer: Buffer): Promise<string> {
  // styleMap preserva estilos do DOCX que mammoth ignora por padrão
  const options = {
    buffer: fileBuffer,
    styleMap: [
      "p[style-name='Title'] => h1:fresh",
      "p[style-name='Heading 1'] => h1:fresh",
      "p[style-name='Heading 2'] => h2:fresh",
      "p[style-name='Heading 3'] => h3:fresh",
      "p[style-name='List Paragraph'] => li:fresh",
      "r[style-name='Strong'] => strong",
      "r[style-name='Emphasis'] => em",
    ],
    // Preservar imagens embutidas como base64
    convertImage: mammoth.images.imgElement(function (image) {
      return image.read('base64').then(function (imageBuffer) {
        return {
          src: `data:${image.contentType};base64,${imageBuffer}`,
        }
      })
    }),
  }

  const result = await mammoth.convertToHtml(options)

  // Logar warnings de conversão para debug
  if (result.messages.length > 0) {
    console.warn('Mammoth conversion warnings:', result.messages)
  }

  // Sanitizar HTML para prevenir XSS
  const cleanHtml = DOMPurify.sanitize(result.value, {
    ALLOWED_TAGS: [
      'h1',
      'h2',
      'h3',
      'h4',
      'h5',
      'h6',
      'p',
      'br',
      'hr',
      'strong',
      'b',
      'em',
      'i',
      'u',
      's',
      'strike',
      'ul',
      'ol',
      'li',
      'table',
      'thead',
      'tbody',
      'tr',
      'td',
      'th',
      'span',
      'div',
      'a',
      'img',
      'sub',
      'sup',
      'blockquote',
      'pre',
      'code',
    ],
    ALLOWED_ATTR: [
      'href',
      'target',
      'src',
      'alt',
      'width',
      'height',
      'class',
      'style',
      'colspan',
      'rowspan',
      // Atributos custom para markers de variáveis (usado pelo frontend)
      'data-var',
      'data-var-id',
    ],
  })

  return cleanHtml
}

// Controller/Route handler
export async function uploadDocx(req, res) {
  const file = req.file // multer middleware
  if (!file) {
    return res.status(400).json({ error: 'Arquivo DOCX obrigatório' })
  }

  const validMime = 'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
  if (file.mimetype !== validMime) {
    return res.status(400).json({ error: 'Formato inválido. Envie um arquivo .docx' })
  }

  if (file.size > 10 * 1024 * 1024) {
    return res.status(400).json({ error: 'Arquivo excede o tamanho máximo de 10MB' })
  }

  try {
    const htmlContent = await convertDocxToHtml(file.buffer)
    const fileName = req.body.fileName || file.originalname

    return res.json({ htmlContent, fileName })
  } catch (error) {
    console.error('Erro na conversão DOCX → HTML:', error)
    return res.status(422).json({ error: 'Falha ao converter o documento. Verifique se o arquivo DOCX é válido.' })
  }
}

Configuração de rota (Express):

typescript

import multer from 'multer'

const upload = multer({
  storage: multer.memoryStorage(),
  limits: { fileSize: 10 * 1024 * 1024 },
})

router.post('/templates/upload-docx', upload.single('file'), uploadDocx)

1.4 Endpoint: `POST /contracts/generate-pdfs`

Modifica o endpoint existente para usar HTML + Puppeteer em vez de retornar referências a PDFs estáticos.

Request:

json

{
  "templateId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "groups": [
    {
      "groupId": "group-001",
      "groupName": "Grupo Prestador A",
      "variableValues": {
        "contratante_nome": "Empresa ABC Ltda",
        "contratante_cnpj": "12.345.678/0001-90",
        "valor_contrato": "R$ 50.000,00"
      }
    },
    {
      "groupId": "group-002",
      "groupName": "Grupo Prestador B",
      "variableValues": {
        "contratante_nome": "Empresa ABC Ltda",
        "contratante_cnpj": "12.345.678/0001-90",
        "valor_contrato": "R$ 30.000,00"
      }
    }
  ]
}

Response (200):

json

[
  {
    "groupId": "group-001",
    "groupName": "Grupo Prestador A",
    "pdfUrl": "https://storage.example.com/contracts/group-001-uuid.pdf"
  },
  {
    "groupId": "group-002",
    "groupName": "Grupo Prestador B",
    "pdfUrl": "https://storage.example.com/contracts/group-002-uuid.pdf"
  }
]

Erros:

400: templateId ausente ou groups vazio
404: template não encontrado
422: template sem htmlContent
500: falha na geração do PDF

Implementação de referência:

typescript

import puppeteer, { type Browser } from 'puppeteer'

// ============================================================
// 1. SINGLETON DO BROWSER (reutilizar entre requests)
// ============================================================

let browserInstance: Browser | null = null

async function getBrowser(): Promise<Browser> {
  if (!browserInstance || !browserInstance.connected) {
    browserInstance = await puppeteer.launch({
      headless: true,
      args: [
        '--no-sandbox',
        '--disable-setuid-sandbox',
        '--disable-dev-shm-usage', // Evita crash em containers Docker
        '--disable-gpu',
        '--font-render-hinting=none', // Melhor renderização de fontes
      ],
    })
  }
  return browserInstance
}

// Cleanup ao encerrar o processo
process.on('SIGTERM', async () => {
  if (browserInstance) await browserInstance.close()
})

// ============================================================
// 2. SUBSTITUIÇÃO DE VARIÁVEIS NO HTML
// ============================================================

function substituteVariables(htmlContent: string, variableValues: Record<string, string>): string {
  // Usa regex para substituir os markers sem precisar de DOM parser
  // Formato do marker: <span data-var="nome_variavel" data-var-id="uuid" class="variable-marker">texto original</span>
  //
  // O marker é substituído apenas pelo texto do valor, sem o span wrapper.
  // Isso garante que o PDF final não tenha markup de edição.

  let result = htmlContent

  for (const [varName, value] of Object.entries(variableValues)) {
    if (!value) continue

    // Regex que captura o span completo com data-var="varName"
    // Flags: g (global), s (dotall para . incluir \n)
    const regex = new RegExp(`<span[^>]*data-var="${escapeRegex(varName)}"[^>]*>[^<]*</span>`, 'gs')

    result = result.replace(regex, escapeHtml(value))
  }

  return result
}

function escapeRegex(str: string): string {
  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
}

function escapeHtml(str: string): string {
  return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
}

// ============================================================
// 3. WRAPPER HTML PARA O PUPPETEER
// ============================================================

// O htmlContent do template é apenas o body.
// Este wrapper adiciona a estrutura completa do documento
// com CSS que garante fidelidade ao layout A4.

function wrapHtmlForPdf(bodyContent: string): string {
  return `<!DOCTYPE html>
<html lang="pt-BR">
<head>
  <meta charset="UTF-8">
  <style>
    /* Reset */
    *, *::before, *::after {
      box-sizing: border-box;
      margin: 0;
      padding: 0;
    }

    /* Página A4 */
    @page {
      size: A4;
      margin: 20mm 15mm 20mm 15mm;
    }

    body {
      font-family: 'Times New Roman', Times, serif;
      font-size: 12pt;
      line-height: 1.5;
      color: #000;
      background: #fff;
      -webkit-print-color-adjust: exact;
      print-color-adjust: exact;
    }

    /* Tipografia */
    h1 { font-size: 24pt; font-weight: bold; margin: 0 0 12pt; }
    h2 { font-size: 18pt; font-weight: bold; margin: 0 0 10pt; }
    h3 { font-size: 14pt; font-weight: bold; margin: 0 0 8pt; }
    h4 { font-size: 12pt; font-weight: bold; margin: 0 0 6pt; }

    p { margin: 0 0 6pt; }

    /* Listas */
    ul, ol { margin: 0 0 6pt 24pt; }
    li { margin-bottom: 3pt; }

    /* Tabelas */
    table {
      border-collapse: collapse;
      width: 100%;
      margin: 6pt 0;
    }
    td, th {
      border: 1px solid #666;
      padding: 4pt 8pt;
      vertical-align: top;
    }
    th {
      background: #f0f0f0;
      font-weight: bold;
    }

    /* Texto formatado */
    strong, b { font-weight: bold; }
    em, i { font-style: italic; }
    u { text-decoration: underline; }

    /* Imagens */
    img {
      max-width: 100%;
      height: auto;
    }

    /* Quebra de página */
    .page-break {
      page-break-after: always;
    }
  </style>
</head>
<body>
  ${bodyContent}
</body>
</html>`
}

// ============================================================
// 4. GERAÇÃO DO PDF COM PUPPETEER
// ============================================================

async function generatePdfBuffer(htmlContent: string): Promise<Buffer> {
  const browser = await getBrowser()
  const page = await browser.newPage()

  try {
    const fullHtml = wrapHtmlForPdf(htmlContent)

    await page.setContent(fullHtml, {
      waitUntil: 'networkidle0', // Aguarda imagens base64 carregarem
      timeout: 30000,
    })

    const pdfBuffer = await page.pdf({
      format: 'A4',
      printBackground: true,
      preferCSSPageSize: true,
      margin: {
        top: '20mm',
        bottom: '20mm',
        left: '15mm',
        right: '15mm',
      },
    })

    return Buffer.from(pdfBuffer)
  } finally {
    await page.close() // Sempre fechar a page, mesmo em caso de erro
  }
}

// ============================================================
// 5. CONTROLLER / ROUTE HANDLER
// ============================================================

export async function generateContractPdfs(req, res) {
  const { templateId, groups } = req.body

  // Validações
  if (!templateId) {
    return res.status(400).json({ error: 'templateId é obrigatório' })
  }
  if (!groups || !Array.isArray(groups) || groups.length === 0) {
    return res.status(400).json({ error: 'groups deve ser um array com pelo menos 1 item' })
  }

  // Buscar template
  const template = await TemplateModel.findById(templateId)
  if (!template) {
    return res.status(404).json({ error: 'Template não encontrado' })
  }
  if (!template.htmlContent) {
    return res.status(422).json({ error: 'Template não possui conteúdo HTML' })
  }

  try {
    // Gerar PDFs em paralelo (limitado a 3 concurrent para não sobrecarregar)
    const results = []

    for (const group of groups) {
      const { groupId, groupName, variableValues } = group

      // 1. Substituir variáveis
      const filledHtml = substituteVariables(template.htmlContent, variableValues || {})

      // 2. Gerar PDF
      const pdfBuffer = await generatePdfBuffer(filledHtml)

      // 3. Fazer upload do PDF para storage (S3, GCS, etc.)
      const fileName = `contracts/${templateId}/${groupId}-${Date.now()}.pdf`
      const pdfUrl = await uploadToStorage(pdfBuffer, fileName, 'application/pdf')
      // ↑ uploadToStorage é a função já existente no seu backend

      results.push({ groupId, groupName, pdfUrl })
    }

    return res.json(results)
  } catch (error) {
    console.error('Erro ao gerar PDFs:', error)
    return res.status(500).json({ error: 'Falha ao gerar os PDFs do contrato' })
  }
}

Configuração de rota:

typescript

router.post('/contracts/generate-pdfs', generateContractPdfs)

1.5 Endpoints a remover

GET /templates/recent-pdfs: não há mais PDFs recentes (fluxo mudou para DOCX)
POST /templates/upload-pdf: substituído por upload-docx

1.6 Endpoints a modificar

POST /templates e PUT /templates/:id

O payload agora envia htmlContent em vez de pdfId:

typescript

// ANTES
{
  name: string
  description?: string
  pdfId: string               // ← REMOVER
  variables?: TemplateVariable[]
  variablesMapping?: VariableMapping[]  // ← REMOVER
  status?: TemplateStatus
}

// DEPOIS
{
  name: string
  description?: string
  htmlContent: string          // ← NOVO
  variables?: TemplateVariable[]
  status?: TemplateStatus
}

GET /templates/:id

O response agora retorna htmlContent em vez de pdfId/pdfPath:

typescript

// ANTES
{
  id, name, description,
  pdfId: string,          // ← REMOVER
  pdfPath: string,        // ← REMOVER
  variables, variablesMapping, status
}

// DEPOIS
{
  id, name, description,
  htmlContent: string,    // ← NOVO
  variables, status
}

1.7 Considerações de deploy

Docker / Puppeteer: Puppeteer precisa de Chromium. Em containers Docker, adicionar:

dockerfile

# Instalar dependências do Chromium
RUN apt-get update && apt-get install -y \
  chromium \
  fonts-liberation \
  fonts-noto-cjk \
  libatk-bridge2.0-0 \
  libdrm2 \
  libxss1 \
  libxtst6 \
  --no-install-recommends \
  && rm -rf /var/lib/apt/lists/*

# Usar Chromium do sistema (evita download automático)
ENV PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium

Fontes customizadas: Se os contratos usam fontes específicas (Arial, Calibri, etc.), instalar no container:

dockerfile

# Fontes Microsoft (Arial, Times, Courier, etc.)
RUN apt-get update && apt-get install -y fonts-liberation ttf-mscorefonts-installer

Memória:

Cada page do Puppeteer consome ~50-100MB de RAM
O singleton do browser reutiliza o processo Chromium
Em alto volume, considerar pool de browsers ou fila de jobs

Performance:

Conversão DOCX → HTML: ~100-500ms
Geração PDF via Puppeteer: ~1-3s por documento
Para contratos com muitos grupos, os PDFs são gerados sequencialmente para não exceder a memória

Fase 2: Types (Frontend): JÁ IMPLEMENTADO

Arquivo: `src/domain/template/types.ts`

Removido: NormalizedPosition, VariableMapping

Adicionado:

typescript

export type UploadDocxResponse = {
  htmlContent: string
  fileName: string
}

Template modificado: htmlContent: string em vez de pdfPath/pdfId/variablesMapping

Fase 3: Services (Frontend): JÁ IMPLEMENTADO

uploadDocxService substitui uploadTemplatePdfService
getRecentPdfsService removido

Fase 4: Store: JÁ IMPLEMENTADO

htmlContent ref substitui pdfFile, pdfUrl, pdfId, pdfPath, totalPages, variableMappings
addVariable() recebe (variableName, originalText, markerId) e insere marker no HTML
removeVariableMarker() remove span do HTML via DOMParser

Fase 5: Composable: JÁ IMPLEMENTADO

useHtmlEditor.ts criado com seleção de texto, inserção/remoção de markers, zoom
usePdfEditor.ts deletado

Fase 6: Componentes: JÁ IMPLEMENTADO

DocxUploader.vue criado
HtmlEditor.vue criado
EditorContainer.vue atualizado
PdfEditor.vue, PdfUploader.vue, RecentPdfList.vue deletados

Fase 7: Preview no contrato: JÁ IMPLEMENTADO

usePdfOverlay.ts agora faz substituição de variáveis via DOMParser no frontend (preview instantâneo)
ContractTemplateDetail.vue renderiza preview HTML com v-html
VuePDF e pdf-lib removidos do fluxo

Fase 8: Mocks: JÁ IMPLEMENTADO

Mock data usa htmlContent com <span data-var="..." class="variable-marker"> markers
Handler upload-docx adicionado
Handler recent-pdfs removido

Formato dos markers de variáveis no HTML

O frontend insere variáveis no HTML como spans com data attributes:

html

<span data-var="nome_completo" data-var-id="var_nome_completo_1706234567" class="variable-marker"> João da Silva </span>

data-var: nome da variável (chave para substituição)
data-var-id: ID único do marker (para remoção individual)
class="variable-marker": classe CSS para highlight visual no editor
Conteúdo do span: texto original selecionado pelo usuário

Na geração do PDF, o backend substitui o span inteiro pelo valor da variável (texto puro).

Verificação

Frontend

[ ] Upload de DOCX → HTML renderizado corretamente no editor
[ ] Selecionar texto → atribuir variável → span marcado no HTML
[ ] Salvar template → htmlContent com markers persistido
[ ] Carregar template existente → markers visíveis no editor
[ ] No contrato: atribuir valores → preview com variáveis substituídas

Backend

[ ] POST /templates/upload-docx → converte DOCX para HTML limpo
[ ] POST /templates → salva htmlContent no banco
[ ] GET /templates/:id → retorna htmlContent
[ ] POST /contracts/generate-pdfs → substitui variáveis + gera PDF fiel ao layout
[ ] PDF gerado com formatação preservada (títulos, negrito, tabelas, listas)
[ ] PDF gerado com margens A4 corretas

Migração: PDF → HTML/CSS + Puppeteer ​

Resumo ​

Fase 1: Backend (Node.js) ​

1.1 Dependências ​

1.2 Schema do banco (Template) ​

1.3 Endpoint: POST /templates/upload-docx ​

1.4 Endpoint: POST /contracts/generate-pdfs ​

1.5 Endpoints a remover ​

1.6 Endpoints a modificar ​

1.7 Considerações de deploy ​

Fase 2: Types (Frontend): JÁ IMPLEMENTADO ​

Arquivo: src/domain/template/types.ts ​

Fase 3: Services (Frontend): JÁ IMPLEMENTADO ​

Fase 4: Store: JÁ IMPLEMENTADO ​

Fase 5: Composable: JÁ IMPLEMENTADO ​

Fase 6: Componentes: JÁ IMPLEMENTADO ​

Fase 7: Preview no contrato: JÁ IMPLEMENTADO ​

Fase 8: Mocks: JÁ IMPLEMENTADO ​

Formato dos markers de variáveis no HTML ​

Verificação ​

Frontend ​

Backend ​

Migração: PDF → HTML/CSS + Puppeteer

Resumo

Fase 1: Backend (Node.js)

1.1 Dependências

1.2 Schema do banco (Template)

1.3 Endpoint: `POST /templates/upload-docx`

1.4 Endpoint: `POST /contracts/generate-pdfs`

1.5 Endpoints a remover

1.6 Endpoints a modificar

1.7 Considerações de deploy

Fase 2: Types (Frontend): JÁ IMPLEMENTADO

Arquivo: `src/domain/template/types.ts`

Fase 3: Services (Frontend): JÁ IMPLEMENTADO

Fase 4: Store: JÁ IMPLEMENTADO

Fase 5: Composable: JÁ IMPLEMENTADO

Fase 6: Componentes: JÁ IMPLEMENTADO

Fase 7: Preview no contrato: JÁ IMPLEMENTADO

Fase 8: Mocks: JÁ IMPLEMENTADO

Formato dos markers de variáveis no HTML

Verificação

Frontend

Backend