🌐 Read this in English → · Léelo en español (abajo)
ReportBuilder transforma CSVs de huella de carbono ya calculada en informes PDF profesionales OCF y PCF, con modo objetivo y modo asistido por IA. La IA redacta e interpreta, pero los números siempre los calcula el código.
- App en producción: https://reportbuilder-sigma.vercel.app
- PDFs de muestra (salidos de la app desplegada, sin editar): informe OCF (organización) · informe PCF (producto) — ambos del mismo motor
(spec, data); cada número es calculado y propiedad del código. - Recorrido visual de la construcción: docs/build-journey.html — una infografía interactiva de todas las fases, decisiones y del sistema de IA.
Data Hub — conjuntos de datos validados + biblioteca de informes
Builder — vista previa en vivo + Personalizar (marca/tema)
Generar con IA — generación todo-o-nada del informe asesor
PDF — salida con marca, cifras bloqueadas y verificadas
Un guion de presentación de extremo a extremo:
- Abrir la app desplegada — https://reportbuilder-sigma.vercel.app
- Cargar un CSV OCF o PCF desde
sample-data/(el dominio se detecta automáticamente por la forma de las cabeceras). - Revisar la validación en «Ver datos» — la reconciliación pass/fail con los deltas reales.
- Generar el informe objetivo (
Generar informe) — 100% determinista, sin IA. - Generar el informe con IA (
Generar con IA) — interpretación, focos de emisión, conclusiones y recomendaciones redactadas por IA sobre la misma espina objetiva. - Descargar el PDF — un clic, A4 con marca, capturado del mismo árbol de componentes que la preview.
- Mostrar que los números son idénticos en ambos modos — la IA redacta, el código calcula.
ReportBuilder es una herramienta de tres modos sobre una única tubería determinista, para los dos dominios ISO:
Ver datos— inspección en pantalla del dataset (resumen, validación, totales, focos de emisión, tabla cruda). Sin PDF, sin IA.Generar informe(objetivo) — un informe PDF 100% determinista, con copia escrita por código sobre un motor de insights; nunca llama a la IA.Generar con IA(asesor) — inyecta interpretación, análisis de focos de emisión, conclusiones y una matriz de recomendaciones redactadas por IA sobre la misma espina objetiva, mientras cada cifra sigue calculada por código.
Los dos dominios: OCF (Huella de Carbono de Organización, ISO 14064-1 / GHG Protocol) y PCF (Huella de Carbono de Producto, ISO 14067), ambos desde un único motor (spec, data).
El bucle completo es el de un ciclo de entrega real: gestionar datos → validar → generar → refinar → publicar. Las tres superficies (Hub, Builder, vista de informe) están optimizadas para móvil como web responsive, manteniendo el A4 del PDF intacto.
Es la entrega para el reto técnico de una semana de Mappa / Footprint Mappa (Programa Investigo): construida en el stack de Mappa, con datos en vivo desde Xano y desplegada en Vercel. Los informes que produce llevan la marca del cliente final, Relats S.A.U., reconstruida a partir de sus materiales públicos. El brief juzga la entrega menos por número de funcionalidades que por si el autor entiende y puede defender cada decisión: ReportBuilder responde con Path B (configurable por el cliente) + Path C (refinamiento por lenguaje natural con IA) sobre un núcleo correcto y defendible.
El repo está en inglés (lo pide el brief) y el código es JavaScript/JSX, sin TypeScript, como exige el reto. La demo en vivo se hace en español/catalán.
Los CSV contienen emisiones ya calculadas; la app no calcula factores de emisión primarios. El modo IA genera narrativa y recomendaciones cualitativas, no objetivos cuantificados de reducción.
Generar informe (objetivo) |
Generar con IA (asistido) |
|
|---|---|---|
| Quién escribe la prosa | Código (plantillas + motor de insights) | IA (Claude Haiku) |
| Quién calcula los números | Código (insight pack determinista) | Código — la IA solo cita cifras verbatim |
| Recomendaciones / conclusiones | No | Sí (cualitativas, trazables a focos de emisión) |
| Editable en la preview | Sí | No (solo lectura) |
| Política de emisión | Siempre disponible | Todo-o-nada — si cualquier sección requerida falla integridad, error controlado, nunca PDF a medias |
| Llamadas a la IA | Ninguna | Por sección, fundamentadas, validadas |
Otras limitaciones honestas: se acotó como entregable de un solo cliente (Relats) — el spec por defecto es Relats, aún no hay aislamiento por tenant, y la subida de CSV personalizado a preview/PDF es solo de desarrollo en Vercel (la demo va sobre datos de Xano).
Dos objetos lo gobiernan todo, y mantenerlos separados es la decisión de diseño que lo sostiene:
ReportData— los números auditados. Producidos solo por los adaptadores de CSV + la reconciliación, de donde se deriva el insight pack determinista (lib/insight/*): la única fuente de verdad de cada total, cuota y foco de emisión.ReportSpec— todo lo configurable (secciones, tema, marca, copia). Validado por Zod.strict()sin ningún campo numérico. El modo NO es un campo del spec — es un parámetro de render, así el spec se mantiene cero-numérico.
CSV / Xano ─► adaptadores ─► assertReconciled ─► ReportData 🔒 ─► insight pack 🔒 (única fuente de verdad)
│
ReportSpec ─► ReportRenderer ƒ(spec, data) ─► Preview ≡ /print ─► Chromium ─► PDF
▲ (un único árbol de componentes puro)
│
[ai_assisted] motor de recomendaciones (det.) ─► prompts por sección ─► validador híbrido ─► inyección sobre la espina
[Path C] Prompt ─► SpecPatch (Zod, sin números) ─► applyPatch (re-valida · rollback) ─► solo ReportSpec
El renderer es una función pura de (spec, data) que alimenta tanto la preview como la ruta /print, capturada por Chromium serverless pineado — por eso preview y PDF son el mismo artefacto. Dos fronteras se imponen por tests, no por convención: ninguna marca Mappa se filtra al informe Relats, y las claves de Xano nunca llegan al navegador.
➜ La historia completa (muro datos/spec, los dos dominios ISO, formato de CSV, marca multi-marca): docs/architecture.md.
La IA aparece en dos superficies — el botón «Generar con IA» (informe asesor completo) y el chat Ask AI (refinamiento Path C) — y comparten una incapacidad estructural de tocar un número:
- La IA redacta prosa, nunca números. El insight pack determinista es siempre la fuente; la prosa de IA solo puede CITAR cifras del pack verbatim; cualquier cifra fuera del pack se rechaza.
- Todo-o-nada. El informe asistido pre-genera y valida TODAS las secciones requeridas antes de emitir; si cualquiera falla integridad tras reintentos → error controlado en español con dos acciones, nunca una degradación silenciosa ni un PDF a medias.
- Validación híbrida. Los fallos de integridad (cifras inventadas, unidad errónea, claims prohibidos) se bloquean en duro; los cosméticos (ids internos, etiquetas en inglés) se sanean y dejan pasar.
- Totales deterministas. Las recomendaciones se derivan de un motor determinista (
lib/advisory/recommend.js) que corre antes de cualquier IA; cada una es trazable a un foco de emisión. - Modelo:
claude-haiku-4-5en runtime (coste/latencia); Opus solo se usó para construir la app vía subagentes. 1258 tests en verde.
➜ La historia completa (las dos superficies, los guardarraíles con su archivo, por qué no RAG, la tabla de defensibilidad): docs/ai-system.md.
Prerrequisitos: Node 22.17+ (la versión fijada en engines de package.json), y un .env.local con estas claves (solo los nombres — no se comitea ningún valor):
ANTHROPIC_API_KEY=
XANO_API_KEY=
XANO_OCF_URL=
XANO_PCF_URL=
XANO_DATASETS_URL=
XANO_REPORTS_URL=
npm install
npm run dev # http://localhost:3000
npm test # suite Vitest (1258 en verde), incl. los tests guardianes de integridad de datos
npm run build # build de producciónDocs profundas:
- docs/architecture.md — la tubería completa, el muro datos/spec, los dos dominios ISO, el formato de CSV, marca multi-marca.
- docs/ai-system.md — el sistema de IA en profundidad, los guardarraíles y la tabla de defensibilidad.
- docs/build-process.md — el proceso de planificación estructurado, la construcción fase a fase, el tiempo invertido y cómo se usó la IA.
- docs/report-quality.md — los tres modos, la estructura de sección de cada dominio, el motor de insights.
- docs/LANDSCAPE-RESEARCH.md — la encuesta puntuada build/reuse/buy de ~25+ opciones de motor de PDF, con fuentes.
- docs/decisions.md — el registro de decisiones arquitectónicas (9 ADRs).
- docs/pdf-approach.md — los registros de decisión condensados del enfoque de PDF.
Stack tecnológico (el requerido):
| Capa | Elección |
|---|---|
| Framework | Next.js 16 (App Router) + React 19 |
| Estilos | Tailwind v4 + shadcn/ui (new-york) + Radix + Lucide |
puppeteer-core 25.1.0 + @sparticuz/chromium 149 (par pineado, fidelidad total CSS/gráficas) |
|
| Gráficas | Recharts (SVG en DOM real) |
| IA | Vercel AI SDK (ai@6 + @ai-sdk/anthropic@3), claude-haiku-4-5 |
| Backend | Xano (tier gratuito), fetch + caché en servidor, claves nunca en el cliente |
| Deploy | Vercel (Hobby), runtime Node para la ruta del PDF |
| Validación / Tests | Zod (esquema estricto) · Vitest (1258 en verde) |
Construido para el reto técnico de Mappa / Footprint Mappa · Jaime Berdejo · junio 2026.