Generación de PDF

---
name: generacion-de-pdf
description: cotizaciones, facturas y reportes que se imprimen igual en cualquier equipo.
---

# Generación de PDF

Instrucciones para el agente que está construyendo esta app. Sigue esta skill cuando
generes cotizaciones, representaciones de facturas, contratos o reportes descargables.

## Cuándo usar esta skill

Actívala en cuanto se cumpla cualquiera de estas condiciones:

- El documento se imprime, firma, envía por correo o archiva fuera de la app.
- El diseño necesita encabezados, pies, numeración y saltos de página reproducibles.
- Debes conservar exactamente qué versión vio o aceptó una persona.
- La exportación debe funcionar sin depender del navegador del cliente.

Si el usuario solo necesita leer una tabla en pantalla, ofrece CSV antes de PDF. Un PDF
no vuelve auditable un reporte ni sustituye los datos estructurados.

## Cómo armarla

Usa plantillas **HTML y CSS de impresión** renderizadas en servidor con **Playwright y
Chromium**. Usa **pdf-lib** únicamente para unir, numerar o estampar PDFs existentes.

1. Separa `datos -> plantilla -> render`. La plantilla recibe un objeto validado y nunca
   consulta la base de datos por su cuenta.
2. Versiona cada plantilla. Guarda versión, idioma, zona horaria, moneda y hash de los
   datos junto al archivo generado para poder reproducirlo.
3. Empaqueta las fuentes y logotipos con el proyecto. Espera a que carguen antes de
   imprimir; no dependas de una URL externa que puede fallar mañana.
4. Define tamaño Carta o A4 explícitamente según el mercado. Prueba márgenes, encabezado,
   pie, tablas largas, filas indivisibles y páginas casi vacías.
5. Formatea fechas, monedas, separadores y nombres legales con locale explícito. No uses
   el locale del servidor.
6. Genera documentos pesados en una cola y guarda el resultado en almacenamiento de
   objetos. Devuelve estado de progreso y una URL firmada, no una petición HTTP eterna.
7. Escapa todo texto del usuario y bloquea URLs arbitrarias en el renderizador. Chromium
   no debe poder leer metadatos internos ni archivos locales.
8. Agrega texto seleccionable y orden de lectura razonable. Una captura gigante dentro
   de un PDF no es un documento accesible ni buscable.

## En qué te vas a trabar

- **Los saltos de página aparecen con datos reales.** Prueba nombres largos, miles de
  filas, una sola fila y textos sin espacios, no solo el ejemplo bonito.
- **Chromium pesa y consume memoria.** Usa un proceso controlado o worker compatible con
  tu hosting y limita concurrencia; no abras un navegador nuevo por cada renglón.
- **La representación fiscal no crea validez fiscal.** Para CFDI conserva el XML
  timbrado y etiqueta el PDF como representación impresa.
- **Fuentes y caracteres fallan por región.** Verifica acentos, ñ, portugués y símbolos
  de moneda con las fuentes realmente incrustadas.

## Qué NO hacer

- No construyas el PDF con coordenadas absolutas para cada texto salvo que llenes un
  formulario fijo existente.
- No generes documentos oficiales únicamente en el navegador.
- No cargues HTML proporcionado por el usuario dentro de Chromium sin sanitizar.
- No sobrescribas un documento ya emitido; genera una nueva versión y conserva el vínculo.

## Checklist

- [ ] La plantilla y su esquema de datos están versionados.
- [ ] Carta y A4 se probaron con contenido mínimo, máximo y multilingüe.
- [ ] Las fuentes están incrustadas y el texto se puede seleccionar.
- [ ] La generación pesada corre fuera de la petición principal y limita concurrencia.
- [ ] El renderizador no puede acceder a red interna, archivos locales ni URLs arbitrarias.
- [ ] Cada archivo conserva hash, versión, locale y datos de origen trazables.
- [ ] El PDF de un CFDI se entrega junto al XML, nunca en su lugar.