HTML como Fuente de Verdad: Generación de PDFs Legales con Node.js

En el desarrollo de software empresarial, tarde o temprano te enfrentas al requisito temido: "El sistema debe exportar este reporte a PDF".

Si vienes del mundo frontend, tu primer instinto puede ser usar window.print(). Si eres backend, quizás pienses en librerías como PDFKit o fpdf. Pero cuando el requisito escala a "Documentos legales con validez jurídica, diseño pixel-perfect y firmas digitales", las herramientas convencionales se quedan cortas.

En nuestro trabajo con sistemas gubernamentales, como el caso de OFICRI, aprendimos que la única forma de mantener la cordura y la calidad es tratar a los PDFs no como documentos binarios, sino como páginas web estáticas.

El Problema de las Librerías Tradicionales

Durante la fase de arquitectura, evaluamos las opciones estándar del mercado para Node.js. Encontramos dos grandes grupos de problemas:

1. La Pesadilla del Diseño Imperativo

Librerías como PDFKit te obligan a "dibujar" el documento programáticamente:

// El enfoque doloroso
doc.fontSize(12).text('Informe Técnico', 100, 100);
doc.image('logo.png', 400, 50, { width: 100 });
doc.moveTo(100, 150).lineTo(500, 150).stroke();

Este enfoque es frágil. Si el cliente pide mover el logo 10px a la derecha, tienes que recompilar y adivinar coordenadas. Mantener esto es insostenible a largo plazo.

2. Limitaciones de Estilo

Intentar replicar un layout complejo (tablas con bordes específicos, tipografías corporativas, márgenes exactos) usando primitivas de dibujo es reinventar la rueda. CSS ya resolvió el problema del diseño visual hace décadas. ¿Por qué no usarlo?

La Solución: Chrome como Motor de Renderizado

Decidimos invertir la ecuación: en lugar de aprender una API de PDF oscura, usaríamos HTML + CSS para diseñar los documentos y dejaríamos que un navegador real se encargara de la conversión.

Para esto, elegimos Puppeteer, una librería de Node.js que controla una instancia de Chrome/Chromium "Headless" (sin interfaz gráfica).

Arquitectura de Generación

El flujo que implementamos es lineal y robusto:

1. Datos Crudos: Obtenemos la información de la base de datos (MySQL).
2. Plantilla Lógica: Usamos Handlebars para inyectar estos datos en una estructura HTML.
3. Renderizado: Puppeteer abre ese HTML, carga los estilos y ejecuta la impresión a PDF.

// src/services/DocumentBuilderService.js (Simplificado)
const puppeteer = require('puppeteer');
const hbs = require('handlebars');
 
async function generarDictamen(data) {
  // 1. Compilar plantilla
  const htmlContent = hbs.compile(templateString)(data);
 
  // 2. Iniciar navegador (Optimizado para servidor)
  const browser = await puppeteer.launch({
    headless: 'new',
    args: ['--no-sandbox', '--disable-setuid-sandbox'] // Crítico para Docker/Linux
  });
 
  const page = await browser.newPage();
  
  // 3. Cargar contenido
  await page.setContent(htmlContent, { waitUntil: 'networkidle0' });
 
  // 4. Imprimir
  const pdfBuffer = await page.pdf({
    format: 'A4',
    printBackground: true, // Importante para colores de fondo
    margin: { top: '2.5cm', bottom: '2.5cm', left: '2.5cm', right: '2.5cm' }
  });
 
  await browser.close();
  return pdfBuffer;
}

Retos Técnicos y Optimizaciones

Implementar esto en producción (especialmente en entornos Linux sin interfaz gráfica) trajo sus propios desafíos.

1. Gestión de Fuentes y Assets

Chrome Headless en un servidor Ubuntu no tiene las mismas fuentes que tu MacBook. Si el documento legal exige "Times New Roman" o "Arial", y el servidor no la tiene, el PDF saldrá roto.

Solución: Inyectar fuentes y recursos críticos (logos, firmas) directamente en el HTML como Base64. Esto hace que el HTML sea autocontenido y no dependa de archivos externos o del sistema operativo.

<!-- Inyección de fuente en Base64 -->
<style>
  @font-face {
    font-family: 'Roboto';
    src: url(data:font/truetype;charset=utf-8;base64,AAEAAAARAQAABAAQRkZJRwAA...) format('truetype');
  }
</style>
 
<!-- Inyección de imagen -->
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." />

2. Rendimiento y "Zombies"

Lanzar una instancia de Chrome consume mucha RAM. Si generas 100 reportes simultáneos, puedes tumbar el servidor.

Estrategia:

• Usar una única instancia del navegador (browser) y abrir/cerrar pestañas (pages) para cada petición, en lugar de lanzar un navegador nuevo por petición.
• Implementar un sistema de colas si el volumen es muy alto.
• Asegurar que browser.close() se ejecute siempre, incluso si hay errores, usando bloques try/finally.

3. CSS para Impresión

El CSS en pantalla no se comporta igual que en papel. Usamos media queries específicas y unidades absolutas (cm, mm, pt) en lugar de píxeles para asegurar precisión física.

@media print {
  .page-break { 
    page-break-after: always; 
  }
  
  /* Evitar que una tabla se corte a la mitad de una fila */
  tr {
    page-break-inside: avoid;
  }
}

Por Qué Vale la Pena

Aunque configurar Puppeteer en un entorno Dockerizado requiere más trabajo inicial que instalar una librería simple, el retorno de inversión es masivo:

1. Iteración Rápida: Cambiar el diseño del PDF es tan fácil como editar un archivo HTML. No hay que recompilar ni calcular coordenadas.
2. Fidelidad Visual: Lo que ves en el navegador es lo que obtienes en el PDF. Podemos usar Flexbox, Grid, y todas las herramientas modernas de CSS.
3. Mantener al Cliente Feliz: Cuando piden un cambio de formato "urgente", podemos entregarlo en minutos, no horas.

En proyectos críticos donde el documento final es la "verdad" que se archiva o se presenta ante un juez, la precisión no es negociable. Usar tecnologías web estándar para resolver problemas de impresión antiguos ha sido una de nuestras mejores decisiones de arquitectura.