inq-roi-simulador-web/sprints/sprint-1-5/ETAPA_2_PROMPT.md

GO — Etapa 2: Helper formatPayback + aplicación

Tu plan original tenía 7 it.todo listos. Esta etapa los convierte en tests reales, implementa el helper y lo aplica en 3 lugares.

═══════════════════════════════════════════════════════════════════════ PRE-TAREAS (actualizar artefactos de Etapa 1) ═══════════════════════════════════════════════════════════════════════

Antes de implementar formatPayback, hacé estas 3 actualizaciones rápidas:

1. Actualizar etapa-1-audit.md — fila de GatewayPanel.tsx: Cambiar la categoría de las 5 referencias blue-* de GatewayPanel de "Mantener azul funcional / Evaluar en Sprint 2" a:

   "Decisión arquitectónica: mantener azul informativo. No es color de marca, es semántica funcional (info banner, valor inmutable, patrón Bootstrap/Tailwind estándar). NO migrar."

2. Actualizar etapa-1-audit.md — agregar fila al final de la sección "Hallazgos — Hex hardcodes" para el donut chart:

   | chart-options.ts:123 | #3b82f6 → naranja | Composición directo/overhead | en donut. Decisión visual: el sector "directo" va en naranja InQ | #F59845. El sector "overhead" NO debe ser otro naranja (pierde | contraste) — usar slate-400 (#94A3B8) o naranja muy claro | (#FED7AA). Decisión final en Etapa 3 mirando el render. |

3. Verificar contraste WCAG de #F59845 sobre blanco. Ejecutá:

   node -e " const hex = '#F59845'; const r = parseInt(hex.slice(1,3), 16) / 255; const g = parseInt(hex.slice(3,5), 16) / 255; const b = parseInt(hex.slice(5,7), 16) / 255; const lin = (c) => c <= 0.03928 ? c/12.92 : Math.pow((c+0.055)/1.055, 2.4); const L1 = 0.2126lin(r) + 0.7152lin(g) + 0.0722*lin(b); const L2 = 1; const ratio = (L2 + 0.05) / (L1 + 0.05); console.log('Contrast ratio:', ratio.toFixed(2), ':1'); console.log('AA normal text (4.5):', ratio >= 4.5 ? 'PASS' : 'FAIL'); console.log('AA large text (3.0):', ratio >= 3.0 ? 'PASS' : 'FAIL'); "

   Anotá el resultado en etapa-1-audit.md como nueva sección "Accesibilidad — Contraste de marca". Si el resultado es FAIL para AA normal, agregá las 4 opciones de remediación al audit:

   A) Aceptar contraste sub-WCAG en CTAs (riesgo accesibilidad) B) Oscurecer naranja a #D97706 para CTAs (rompe marca parcialmente) C) Usar texto oscuro #451A03 en CTAs sobre naranja (cambia look) D) Forzar font-weight: 700 en CTAs primarios (cumple AA large)

   Marcá la opción D como propuesta a implementar en Etapa 3 cuando rediseñemos KPI cards y CTAs. NO modificar componentes en esta etapa.

═══════════════════════════════════════════════════════════════════════ DECISIONES YA TOMADAS (no consultar de nuevo) ═══════════════════════════════════════════════════════════════════════

Confirmadas con el usuario:

Payback negativo → "Sin payback (costo aumenta)" (caso donde costo automatizado > costo actual, escenario matemáticamente posible pero indica error de configuración o automatización inviable)

Texto del formato → usar caracteres compactos "<" y "~" (universales y legibles en KPI cards)

Pluralización → siempre plural incluso con decimales ("1.0 meses", no "1.0 mes")

═══════════════════════════════════════════════════════════════════════ TAREA PRINCIPAL — IMPLEMENTAR formatPayback ═══════════════════════════════════════════════════════════════════════

1. Implementar formatPayback en src/lib/format.ts:

   function formatPayback(months: number): string { if (Number.isNaN(months) || !isFinite(months)) { return "No recupera en horizonte"; } if (months < 0) { return "Sin payback (costo aumenta)"; } if (months === 0) { return "Inmediato"; } if (months < 0.1) { return "< 1 día"; } if (months < 1) { return < 1 mes (${months.toFixed(2)} meses); } if (months < 12) { return ${months.toFixed(1)} meses; } if (months < 24) { const years = (months / 12).toFixed(1); return ${months.toFixed(1)} meses (~${years} años); } return ${(months / 12).toFixed(1)} años; }

2. Convertir los 7 it.todo existentes en tests reales:

   • formatPayback(0) === "Inmediato"
   • formatPayback(0.05) === "< 1 día"
   • formatPayback(0.5) === "< 1 mes (0.50 meses)"
   • formatPayback(6) === "6.0 meses"
   • formatPayback(15) === "15.0 meses (~1.3 años)"
   • formatPayback(30) === "2.5 años"
   • formatPayback(Infinity) === "No recupera en horizonte"

3. Agregar 5 tests de edge cases:

   • formatPayback(-1) === "Sin payback (costo aumenta)" // payback negativo: costo automatizado supera al actual
   • formatPayback(-100) === "Sin payback (costo aumenta)" // negativo grande: mismo comportamiento
   • formatPayback(NaN) === "No recupera en horizonte" // NaN cae en el primer guard
   • formatPayback(11.95) === "11.9 meses" // verificar que el borde con 12 no salta a "1.0 años" prematuramente
   • formatPayback(12.0) === "12.0 meses (~1.0 años)" // exactamente en el umbral

   Total: 12 tests verdes en tests/lib/format-payback.test.ts

═══════════════════════════════════════════════════════════════════════ APLICACIÓN EN 3 LUGARES ═══════════════════════════════════════════════════════════════════════

a) RoiKpiBar.tsx (web app):

• Reemplazar el formato actual del KPI "PAYBACK" por formatPayback(months)
• El KPI card debe mostrar el string completo
• PROBLEMA POTENCIAL: strings largos como "15.0 meses (~1.3 años)" pueden desbordar la card. Soluciones:
  • Opción 1: reducir font-size del valor a 14px en el card de payback (solo en ese card, no en los otros KPIs)
  • Opción 2: usar 2 líneas — primera línea cifra principal, segunda línea texto secundario en font-size menor

PROBÁ ambas y mostrame screenshot de cada una en Etapa 3. Por ahora implementá la opción 1 (más simple, mantiene grilla consistente).

b) src/lib/export/pdf-sections-roi.ts → drawRoiKpiCards:

• Aplicar formatPayback en la KPI card del PDF
• Verificar ancho: el card actual mide ~120px en página A4. String "15.0 meses (~1.3 años)" en font 16px puede no entrar. Si es así, reducir font-size de esa card específica a 14px.
• Probar con paybacks de distintos rangos: 0.5, 6, 15, 30 meses para ver el comportamiento.

c) src/lib/export/csv-export.ts:

• En la línea de metadata "# Payback (meses): X.XX" reemplazar el número crudo por formatPayback formateado
• AGREGAR una segunda línea inmediatamente después: "# Payback (meses, raw): X.XXXX" Esto preserva compatibilidad con integraciones futuras de BI/Excel que necesiten el valor numérico crudo.

d) BONUS — verificar TransparencySection:

El detector de ROI inusual (Etapa 3 de Sprint 1) menciona payback en alguno de sus 4 casos. Verificá si el texto incluye payback formateado o crudo. Si es crudo, aplicar formatPayback también ahí.

═══════════════════════════════════════════════════════════════════════ ENTREGABLES ═══════════════════════════════════════════════════════════════════════

[ ] etapa-1-audit.md actualizado con 3 correcciones (GatewayPanel, donut chart, contraste WCAG) [ ] formatPayback implementado en src/lib/format.ts [ ] 12 tests verdes en tests/lib/format-payback.test.ts [ ] formatPayback aplicado en RoiKpiBar.tsx [ ] formatPayback aplicado en pdf-sections-roi.ts (drawRoiKpiCards) [ ] formatPayback aplicado en csv-export.ts (con doble línea: formateado + raw para compatibilidad) [ ] TransparencySection verificado y actualizado si aplica [ ] 443 tests previos + 12 nuevos = 455+ tests verdes [ ] npm run build limpio [ ] Screenshot del RoiKpiBar mostrando un payback de 10.6 meses (caso del PDF roi-realistic) [ ] PDF de muestra generado con setup realista del brief: - medium-with-gateways - 3 automatizables, $200/$20 costos - 5000 ejecuciones/año, 3 años, USD 80.000 inversión - Resultado esperado: payback ~10.6 meses (NO "0.0 meses") → guardar como tests/e2e/output/payback-formatted-sample.pdf

═══════════════════════════════════════════════════════════════════════ REPORTE FINAL A PRESENTAR ═══════════════════════════════════════════════════════════════════════

1. Resultado del cálculo de contraste WCAG (PASS/FAIL para AA normal y AA large)
2. Confirmación de las 3 actualizaciones del audit
3. Tabla de tests con resultados (12 verdes esperados)
4. Screenshot del RoiKpiBar con payback formateado
5. PDF de muestra presentado con present_files para que el usuario abra en Preview y valide visualmente
6. Cantidad final de tests verdes
7. Cualquier desbordamiento de UI/PDF detectado y cómo se resolvió

NO arranques Etapa 3 sin mi OK explícito.

Go.