feat(sprint-1.5): rediseño visual PDF ROI + identidad InQ (Etapas 4-7)

- Header/footer compartidos con paleta InQ naranja en los 3 PDFs (Etapa 4) - Layout híbrido portrait+landscape en PDFs Actual/Automatizado: página 2 landscape para diagrama BPMN heatmap (Etapa 5) - Página 1 PDF ROI rediseñada: header denso, banner narrativo, KPI Hero con gradiente naranja→magenta, grid 2×2 de KPIs secundarios, Top 3 actividades por ahorro (Etapa 6) - Páginas 2-5 PDF ROI con identidad InQ: tabla con paleta naranja, análisis del ahorro, nota metodológica, trayectoria del ahorro acumulado con gráfico SVG nativo (Etapa 7) - 500 tests verdes (+ 34 tests nuevos del Sprint 1.5) - BACKLOG.md, TECH_DEBT.md, OBSERVATIONS.md: sistema de planificación reemplaza TODO.md Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-17 20:45:01 -03:00
parent 63c4fbac99
commit 2f4633a33c
20 changed files with 4163 additions and 117 deletions
--- a/sprints/sprint-1-5/ETAPA_6_PROMPT.md
+++ b/sprints/sprint-1-5/ETAPA_6_PROMPT.md
@@ -0,0 +1,480 @@
+# Sprint 1.5 — Etapa 6: PDF ROI — Rediseño de página 1 con identidad InQ
+
+> **Objetivo:** transformar la página 1 del PDF ROI en la "página de discusión" del reporte. Implementa KPI Hero con gradiente naranja → magenta, banner narrativo, KPIs secundarios con paleta InQ, y Top 3 actividades por ahorro. La trayectoria del ahorro se posterga a Etapa 7.
+>
+> **Pre-requisitos:** Etapas 1-5 cerradas. Módulo `pdf-sections-shared.ts` con header/footer compartidos. Layout híbrido funcionando en PDFs Actual/Automatizado.
+>
+> **Etapa siguiente:** Etapa 7 — PDF ROI páginas 2-5 (tabla con paleta, trayectoria del ahorro, transparencia rediseñada, nota metodológica).
+
+---
+
+## 1. Decisión arquitectónica de esta etapa
+
+**El PDF ROI pasa de 4 páginas a 5 páginas.**
+
+| Página | Contenido actual (Etapa 5) | Contenido nuevo (Etapa 6) |
+|---|---|---|
+| 1 | KPIs (header simple) | **Rediseño completo: header denso + banner + KPI Hero + 4 KPIs + Top 3** |
+| 2 | Comparación por actividad | Comparación por actividad (sin cambios — Etapa 7) |
+| 3 | Análisis del ahorro | Análisis del ahorro (sin cambios — Etapa 7) |
+| 4 | Nota metodológica | Nota metodológica (sin cambios — Etapa 7) |
+| 5 | — | NUEVA: trayectoria del ahorro acumulado (Etapa 7) |
+
+**En Etapa 6 solo tocamos la página 1.** Las páginas 2-4 quedan iguales que en Etapa 5. La página 5 se agrega en Etapa 7.
+
+---
+
+## 2. Alcance estricto
+
+### Sí entra
+- ✅ Rediseño completo de la página 1 del PDF ROI con la estructura del brief sección 3.2
+- ✅ Header denso de página 1 con metadata integrada (proceso, cliente, fecha)
+- ✅ Banner narrativo con resumen ejecutivo en `#FFF8ED` y border-left naranja
+- ✅ KPI Hero con gradiente naranja → magenta (cifra de Ahorro proyectado a N años)
+- ✅ Grid 2x2 de KPIs secundarios con paleta `#FEF3E2` (Ahorro/ejecución, Ahorro anual, Payback, ROI anual)
+- ✅ Top 3 actividades por ahorro con barras horizontales naranjas
+- ✅ Footer estándar (sin cambios, ya creado en Etapa 4)
+
+### NO entra
+- ❌ Trayectoria del ahorro acumulado (gráfico SVG nativo) — Etapa 7
+- ❌ Cambios en página 2 (Comparación por actividad) — Etapa 7
+- ❌ Cambios en página 3 (Análisis del ahorro) — Etapa 7
+- ❌ Cambios en página 4 (Nota metodológica) — Etapa 7
+- ❌ Rediseño de PDFs Actual y Automatizado — Etapa 8
+- ❌ Resolver fórmulas truncadas o Unicode roto — Sprint 2
+
+---
+
+## 3. Decisiones ya tomadas (no consultar de nuevo)
+
+| Decisión | Justificación |
+|---|---|
+| Gradiente KPI Hero: `linear-gradient(135deg, #F59845 0%, #ED3E8F 100%)` | Brief sección 2.2 |
+| KPI Hero muestra el ahorro acumulado a N años (no por ejecución) | El número que importa al ejecutivo |
+| KPIs secundarios: Ahorro/ejecución, Ahorro anual, Payback, ROI anual | Brief sección 3.2 |
+| Top 3 con barras horizontales naranjas, sin grid pesado | Visual ligero, foco en magnitud relativa |
+| Banner narrativo con `#FFF8ED` + border-left 3px `#F59845` | Brief sección 2.3 |
+| Trayectoria del ahorro POSTERGADA a página 5 (Etapa 7) | Decisión Camino B de planificación previa |
+| PDF ROI pasa a 5 páginas (con `Página X de 5` en footers) | Consecuencia del Camino B — se aplica desde Etapa 6 con placeholder en página 5 |
+| Sin carátula | Brief sección 3.1 — info integrada en header denso |
+
+---
+
+## 4. Estructura visual de la página 1 (nueva)
+
+Layout vertical de la página 1 (de arriba hacia abajo):
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ HEADER DENSO (15% del alto)                             │
+│                                                          │
+│ InQ ROI                            UN PRODUCTO DE       │
+│                                    InQ                  │
+│ ANÁLISIS DE RETORNO DE INVERSIÓN  InQuality             │
+│                                                          │
+│ ─────────────────────────────────────────────────  3px  │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│ STRIP DE METADATA (5% del alto, fondo #FAFBFC)          │
+│ Proceso: medium-with-gateways  |  Cliente: —  |  Fecha  │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│ BANNER NARRATIVO (10% del alto, fondo #FFF8ED + border) │
+│ ▌ Resumen ejecutivo: automatización de 3 actividades   │
+│ ▌ sobre proceso de 11 etapas. Frecuencia 5.000/año,    │
+│ ▌ horizonte 3 años, inversión USD 80.000.              │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│ KPI HERO (25% del alto, gradiente naranja → magenta)    │
+│                                                          │
+│   AHORRO PROYECTADO A 3 AÑOS                            │
+│   USD 8.020.000                                         │
+│   neto de inversión · 101× retorno                      │
+│                                                          │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│ GRID 2x2 KPIs SECUNDARIOS (20% del alto, fondo #FEF3E2)│
+│                                                          │
+│ ┌─────────────────┐  ┌─────────────────┐                │
+│ │ AHORRO POR EJEC.│  │ AHORRO ANUAL    │                │
+│ │ USD 540         │  │ USD 2.700.000   │                │
+│ │ ↓ 90% vs actual │  │ × 3 años        │                │
+│ └─────────────────┘  └─────────────────┘                │
+│ ┌─────────────────┐  ┌─────────────────┐                │
+│ │ PAYBACK         │  │ ROI ANUAL       │                │
+│ │ < 1 mes         │  │ 3.375%          │                │
+│ │ Dentro horizonte│  │ retorno anual   │                │
+│ └─────────────────┘  └─────────────────┘                │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│ TOP 3 AHORROS (20% del alto)                            │
+│                                                          │
+│ TOP 3 ACTIVIDADES POR AHORRO                            │
+│                                                          │
+│ Analizar riesgo crediticio  ████████████ USD 216 (40%)  │
+│ Recepcionar solicitud       ████████████ USD 216 (40%)  │
+│ Calcular score crediticio   ██████       USD 108 (20%)  │
+└─────────────────────────────────────────────────────────┘
+
+┌─────────────────────────────────────────────────────────┐
+│ FOOTER (5% del alto)                                    │
+│ InQ ROI · Powered by InQuality · — · 17 may 2026       │
+│                                          Página 1 de 5  │
+└─────────────────────────────────────────────────────────┘
+```
+
+**Proporciones aproximadas:** header 15%, metadata 5%, banner 10%, hero 25%, grid 20%, top 3 20%, footer 5%.
+
+Si en la práctica algún bloque no entra con esas proporciones, **PARÁ y consultá**. NO comprimas elementos arbitrariamente.
+
+---
+
+## 5. Especificación detallada por bloque
+
+### 5.1 Header denso de página 1
+
+```
+Layout: flex justify-between, border-bottom 3px solid #F59845
+Padding-bottom: 12mm
+Margin-bottom: 14mm
+
+Izquierda (60% ancho):
+  Línea 1: "InQ ROI"
+    - Tamaño: 22pt
+    - Peso: 700 (bold)
+    - Color: #F59845 (inq-orange)
+    - Tracking: -0.5pt
+  Línea 2: "ANÁLISIS DE RETORNO DE INVERSIÓN"
+    - Tamaño: 9pt
+    - Peso: 500
+    - Color: #94A3B8 (text-tertiary)
+    - Letter-spacing: 1.5pt
+    - Margin-top: 4mm
+
+Derecha (40% ancho):
+  Línea 1: "UN PRODUCTO DE"
+    - Tamaño: 9pt
+    - Color: #94A3B8
+    - Letter-spacing: 1pt
+    - Align: right
+  Línea 2: "InQ"
+    - Tamaño: 16pt
+    - Peso: 700
+    - Color: #475569 (text-secondary)
+    - Align: right
+  Línea 3: "InQuality"
+    - Tamaño: 9pt
+    - Color: #64748B
+    - Align: right
+```
+
+**Importante:** "InQ" siempre I-n-Q (regla no negociable de marca).
+
+### 5.2 Strip de metadata
+
+```
+Fondo: #FAFBFC
+Padding: 8mm horizontal, 5mm vertical
+Border-radius: 4mm
+Layout: grid 3 columnas (proceso 2fr, cliente 1fr, fecha 1fr)
+Margin-bottom: 8mm
+
+Cada celda:
+  Label (top): 8pt, color #94A3B8, uppercase, letter-spacing 1pt
+  Valor (bottom): 11pt, peso 500, color #0F172A
+```
+
+**Datos a mostrar:**
+- Proceso: nombre del proceso BPMN (ej. "medium-with-gateways")
+- Cliente: "—" si no hay cliente configurado (se completa cuando agregemos campo cliente en Sprint 2)
+- Fecha: fecha de simulación formato "17 mayo 2026"
+
+### 5.3 Banner narrativo
+
+```
+Fondo: #FFF8ED (inq-orange-lighter)
+Border-left: 3px solid #F59845
+Padding: 10mm 12mm
+Border-radius: 0 4mm 4mm 0
+Margin-bottom: 10mm
+
+Texto:
+  - Tamaño: 11pt
+  - Line-height: 1.55
+  - Color: #475569 (text-secondary)
+  - Peso: 400 (regular)
+
+Contenido (plantilla):
+  "Análisis de retorno de inversión para automatización del proceso
+   [nombreProceso], con frecuencia anual de [N.NNN] ejecuciones,
+   horizonte de [N] años e inversión estimada de USD [N.NNN].
+   
+   Resultado: ahorro de USD [N.NNN] por ejecución ([NN]% de reducción).
+   La inversión se recupera en [formatPayback], dentro del horizonte
+   de análisis."
+```
+
+Usar la función `formatPayback` ya implementada en Etapa 2.
+
+### 5.4 KPI Hero (gradiente naranja → magenta)
+
+```
+Fondo: linear-gradient(135deg, #F59845 0%, #ED3E8F 100%)
+Padding: 16mm 18mm
+Border-radius: 6mm
+Margin-bottom: 10mm
+Altura aproximada: 50mm
+
+Label superior:
+  - Texto: "AHORRO PROYECTADO A [N] AÑOS"
+  - Tamaño: 10pt
+  - Peso: 500
+  - Color: white con opacity 0.9
+  - Letter-spacing: 1.2pt
+  - Margin-bottom: 6mm
+
+Cifra principal:
+  - Texto: "USD 8.020.000" (formateado con formatCurrency)
+  - Tamaño: 30pt
+  - Peso: 700
+  - Color: white
+  - Tracking: -1pt
+  - Margin-bottom: 4mm
+
+Subtítulo:
+  - Texto: "neto de inversión · [N.N]× retorno"
+  - Tamaño: 11pt
+  - Color: white con opacity 0.85
+  - Peso: 400
+```
+
+**Implementación técnica del gradiente en jsPDF:**
+
+jsPDF NO soporta gradientes nativos. Hay dos opciones:
+
+**Opción A — Renderizar como imagen embedida (recomendado):**
+1. Crear un canvas en JS con el gradiente usando `CanvasRenderingContext2D.createLinearGradient()`
+2. Dibujar texto sobre el canvas
+3. Convertir canvas a base64 PNG
+4. Embed en jsPDF con `doc.addImage()`
+
+**Opción B — Simulación con múltiples rectángulos:**
+- Dibujar ~50 rectángulos verticales de 4mm cada uno, cada uno con color interpolado
+- Visualmente aceptable pero menos suave
+- Más rápido de implementar pero menos calidad
+
+**Elegí Opción A.** Justificación: el KPI Hero es el elemento visual más importante del PDF. Vale la pena el costo técnico de hacerlo bien. La Opción B se ve "computada", no "diseñada".
+
+Si Opción A tiene complicación técnica que requiere más de 1 hora, **PARÁ y consultá**.
+
+### 5.5 Grid 2x2 de KPIs secundarios
+
+```
+Layout: grid 2 columnas × 2 filas
+Gap: 4mm horizontal, 4mm vertical
+Margin-bottom: 10mm
+
+Cada card:
+  Fondo: #FEF3E2 (inq-orange-light)
+  Padding: 8mm 10mm
+  Border-radius: 4mm
+  
+  Label superior:
+    - Tamaño: 8pt
+    - Peso: 500
+    - Color: #92400E (inq-orange-dark)
+    - Letter-spacing: 1pt
+    - Uppercase
+    - Margin-bottom: 4mm
+  
+  Cifra:
+    - Tamaño: 16pt
+    - Peso: 700 (bold para WCAG)
+    - Color: #0F172A (text-primary)
+    - Font-family: mono (para alineación de números)
+  
+  Delta/contexto:
+    - Tamaño: 9pt
+    - Peso: 500
+    - Color: #B45309 (inq-orange-dark)
+    - Margin-top: 3mm
+```
+
+**Contenido de cada card:**
+
+| Card | Label | Cifra | Delta/contexto |
+|---|---|---|---|
+| 1 | AHORRO POR EJECUCIÓN | `formatCurrency(savingsPerExec)` | `↓ {savingsPercent}% vs. actual` |
+| 2 | AHORRO ANUAL | `formatCurrency(annualSavings)` | `× {horizonYears} años` |
+| 3 | PAYBACK | `formatPayback(paybackMonths)` | `Dentro del horizonte` o `Fuera` |
+| 4 | ROI ANUAL | `formatPercent(roi.annualizedRoi, 0)` | `retorno anual` |
+
+### 5.6 Top 3 actividades por ahorro
+
+```
+Margin-bottom: 8mm
+
+Título:
+  - Texto: "TOP 3 ACTIVIDADES POR AHORRO"
+  - Tamaño: 9pt
+  - Peso: 500
+  - Color: #94A3B8
+  - Letter-spacing: 1.2pt
+  - Uppercase
+  - Margin-bottom: 6mm
+
+Cada fila (3 filas):
+  Layout: grid 3 columnas
+    Col 1 (40%): nombre actividad
+    Col 2 (40%): barra horizontal
+    Col 3 (20%): cifra + porcentaje
+  Margin-bottom: 4mm
+
+Nombre actividad:
+  - Tamaño: 10pt
+  - Color: #0F172A
+  - Truncar a 32 caracteres con "..."
+
+Barra horizontal:
+  - Altura: 6mm
+  - Fondo de la barra: #FED7AA (inq-orange-100)
+  - Fill: #F59845 (inq-orange)
+  - Ancho de fill: proporcional al ahorro (la actividad #1 tiene ancho completo, las demás proporcionales)
+  - Border-radius: 1mm
+
+Cifra + porcentaje:
+  - Texto: "USD 216 (40%)"
+  - Tamaño: 10pt
+  - Peso: 500
+  - Color: #B45309
+  - Font-family: mono
+  - Align: right
+```
+
+**Cálculo del ancho de la barra:**
+- Buscar el ahorro máximo entre las 3 actividades
+- Ancho de cada barra = (ahorro / ahorro_max) × ancho_max_disponible
+- Esto hace que la actividad #1 siempre tenga la barra completa, lo cual es intuitivo
+
+---
+
+## 6. Validaciones automatizadas mandatorias
+
+Antes de `present_files`, ejecutá y confirmá:
+
+```
+PDF ROI debe cumplir:
+
+1. Cantidad de páginas: 5 (era 4 en Etapa 5, ahora 5 con placeholder página 5)
+   NOTA: la página 5 va vacía o con texto "Trayectoria del ahorro 
+   (rediseño en Etapa 7)". NO dejar página 4 sin nota metodológica.
+
+2. Orientaciones: 5 páginas en portrait
+
+3. Footers correctos:
+   - Página 1: "Página 1 de 5"
+   - Página 2: "Página 2 de 5"
+   - Página 3: "Página 3 de 5"
+   - Página 4: "Página 4 de 5"
+   - Página 5: "Página 5 de 5"
+
+4. Página 1 contiene los siguientes elementos detectables:
+   - Texto "ANÁLISIS DE RETORNO DE INVERSIÓN" en header
+   - Texto "AHORRO PROYECTADO A 3 AÑOS" en KPI Hero
+   - Texto "TOP 3 ACTIVIDADES POR AHORRO"
+   - Al menos 3 nombres de actividades
+   - Análisis de píxeles confirma:
+     - Gradiente naranja → magenta (al menos 100 píxeles naranja Y al menos 50 píxeles magenta)
+     - Paleta naranja InQ en cards (al menos 500 píxeles #FEF3E2 o similar)
+     - Color blanco prominente en KPI Hero (texto sobre gradiente)
+
+5. Tamaño de página 1: significativamente mayor que Etapa 5 
+   (esperado 35-60 KB vs ~10 KB anterior, por imagen del gradiente embedida)
+
+6. Validaciones globales sin regresión:
+   - "InQ ROI" presente
+   - "Powered by InQuality" presente
+   - "Process Cost Platform" ausente
+   - "v0.1.0" ausente
+   - "INQ", "Inq", "inq" (mayúsculas/minúsculas erróneas) ausentes
+
+7. PDFs Actual y Automatizado: SIN CAMBIOS respecto a Etapa 5
+   - Sigue siendo 4 páginas cada uno
+   - Orientaciones: ['portrait', 'landscape', 'portrait', 'portrait']
+   - Tamaños similares a Etapa 5
+
+8. Tests previos verdes: >= 476
+```
+
+Si CUALQUIER validación falla, NO uses `present_files`. Reportá qué falló.
+
+---
+
+## 7. Entregables (Definition of Done)
+
+```
+[ ] Página 1 del PDF ROI rediseñada según especificación de §4 y §5
+[ ] PDF ROI tiene 5 páginas (página 5 con placeholder de trayectoria)
+[ ] Footer de TODAS las páginas dice "Página X de 5"
+[ ] KPI Hero con gradiente naranja → magenta visible y legible
+[ ] Grid 2x2 con paleta naranja InQ aplicada
+[ ] Top 3 con barras horizontales proporcionales al ahorro
+[ ] Banner narrativo con border-left naranja
+[ ] Header denso con metadata integrada
+[ ] PDFs Actual y Automatizado NO modificados
+[ ] 8 validaciones automatizadas confirmadas
+[ ] PDFs presentados con present_files
+[ ] Tests previos verdes (476+) sin regresiones
+[ ] Tests nuevos para los componentes de página 1 ROI (al menos 4 casos)
+[ ] npm run build limpio
+[ ] Decisiones tomadas por iniciativa documentadas (Patrón C.6 — 
+    con criterios explícitos: si cambia layout, paginación, o contenido 
+    visible más allá del scope, es mínimo Nivel 2)
+```
+
+---
+
+## 8. Reporte final a entregar
+
+1. **Tabla de archivos modificados/creados**
+2. **8 validaciones automatizadas confirmadas**
+3. **Cantidad final de tests verdes**
+4. **PDF ROI presentado con `present_files`** + PDFs Actual y Automatizado para confirmar no-regresión
+5. **Captura específica de página 1 del ROI**: detalle visual del KPI Hero y Top 3 si es posible
+6. **Hallazgos no esperados**
+7. **Decisiones tomadas por iniciativa** según política CLAUDE.md, con clasificación explícita por nivel
+
+---
+
+## 9. Reglas operativas
+
+1. **Solo tocar página 1 del PDF ROI.** Las otras 3 páginas existentes quedan iguales. La página 5 es placeholder.
+
+2. **NO tocar PDFs Actual y Automatizado.** El alcance de Etapa 6 es solo el PDF ROI.
+
+3. **NO resolver fórmulas truncadas ni Unicode.** Esos hallazgos están en TODO para Sprint 2. Si te tienta arreglarlos, pará — no es Etapa 6.
+
+4. **Si el gradiente requiere más de 1 hora de implementación técnica, consultá.** No quemes 3 horas peleándote con canvas → PNG → addImage. Si bloqueás, presentá alternativas.
+
+5. **Política de iniciativa proactiva (CLAUDE.md), con criterios explícitos refinados después de Etapa 5:**
+   - Si el cambio modifica cantidad de páginas, layout, o contenido visible más allá del scope: mínimo Nivel 2
+   - Si choca con una restricción explícita del prompt (ej. "NO entra"): Nivel 3 — consultar antes
+   - Si afecta marca, datos, dependencias o arquitectura: Nivel 3 — consultar antes
+   - Si nada de lo anterior: Nivel 1 — ejecutar y mencionar al final si fueron varios cambios acumulados
+
+6. **Si encontrás contradicción** entre prompt y código: PARÁ y consultá.
+
+---
+
+## 10. Esta es la etapa visualmente más importante del Sprint
+
+La página 1 del PDF ROI es **el primer artefacto que un cliente de InQuality va a ver del producto en una reunión**. Es la "página de discusión" del reporte. Tiene que verse profesional, identitaria, y comunicar el valor en 5 segundos.
+
+Si algo de la especificación visual no te queda claro, **es mejor consultar que improvisar**. El brief y los mockups previos son ground truth — no inventes interpretaciones nuevas.
+
+Cuando termines, validá vos mismo abriendo el PDF en Preview antes de declarar la etapa terminada. Si vos no pondrías eso al frente de un cliente bancario, retrabaja antes de present_files.