# 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.