inq-roi-simulador-web/TECH_DEBT.md

TECH_DEBT — InQ ROI

Deuda técnica, refactors postergados y decisiones arquitectónicas pendientes. Requiere consulta entre director y técnico para resolver. No incluye features de producto (ver BACKLOG.md) ni hallazgos de sprint actual (ver OBSERVATIONS.md).

---

Convención de etiquetas

• [SPRINT-2] — Comprometido para resolución en el próximo sprint
• [BACKLOG] — Disponible para asignar
• [DEFERRED] — Pospuesto, requiere decisión arquitectónica
• [INVESTIGATING] — Necesita análisis técnico antes de planear

Cada ítem incluye:

• Estado actual del problema
• Causa raíz hipotetizada
• Impacto si no se resuelve
• Solución propuesta
• Archivos afectados (cuando aplica)

---

Deuda crítica — afecta calidad del entregable

[SPRINT-2] Fórmulas truncadas + caracteres Unicode rotos en notas metodológicas de PDFs

Estado: las fórmulas matemáticas largas se cortan en el margen derecho. Los caracteres Σ (sumatoria) y − (menos matemático) renderizan como £ (libra) y " (comilla) respectivamente.

Ejemplo 1 — PDFs Actual/Automatizado, página 4:

"Costo directo por actividad = (costo_fijo + £(recurso × costo_hora 
 × tiempo × utilización / 60)"

Faltan )) y × probabilidad_de_ejecución.

Ejemplo 2 — PDF ROI, página 4:

"...Probabilidades calculada"

Falta del grafo BPMN.

Causa raíz hipotetizada:

• jsPDF con fuente WinAnsi por defecto no soporta esos puntos Unicode (Σ, −)
• Falta wrapping automático de líneas largas

Impacto: afecta credibilidad del entregable. Cliente ve fórmula incompleta o caracteres extraños.

Severidad: alta — es deuda consciente aceptada como bug heredado durante Sprint 1.5.

Solución propuesta para Sprint 2:

• Etapa dedicada a "PDF: font embedding y text wrapping"
• Embeber Roboto Unicode completo con doc.addFileToVFS() + doc.addFont()
• Usar doc.splitTextToSize() para todas las notas metodológicas
• Tests que validen que ninguna línea supera el ancho disponible

Workaround temporal (si surge demo o entrega urgente antes de Sprint 2):

• Reformular fórmulas como multi-línea en el texto fuente
• Costo: 10-15 min de trabajo
• Soluciona el síntoma sin embeber fuente

Archivos afectados:

• src/lib/export/pdf-sections.ts (notas metodológicas Actual/Automatizado)
• src/lib/export/pdf-sections-roi.ts (nota metodológica ROI)

---

Deuda media — afecta DX o evolución del producto

[INVESTIGATING] Dexie live queries (sincronización store ↔ db)

Estado actual: la invalidación del resultado de simulación se garantiza vía ESLint rule (no-restricted-imports) + convención: todas las mutaciones pasan por useProcessStore.

Riesgo a futuro: si en Sprint 2 la grilla de edición masiva requiere escrituras de alta frecuencia directas a IndexedDB (por performance), la convención actual no escala.

Solución a evaluar: migración a live queries de Dexie que invaliden el store automáticamente.

Acción pendiente: análisis técnico de costo/beneficio cuando se planee la grilla de edición masiva.

Origen: auditoría de Mayo 2026.

[BACKLOG] Indicador visual en reporte de actividades automatable

Estado: Sprint 1 usa solo leyenda de texto para diferenciar actividades automatables. Acción: evaluar si el cliente necesita más claridad visual (borde punteado o ícono diferenciador) cuando compara Actual vs Automatizado en reuniones. Decidir con feedback de uso real.

[BACKLOG] Paleta del heatmap — saturado vs pastel

Estado: los colores saturados actuales (#10B981, #F59E0B, #EF4444) funcionan bien en pantallas grandes de talleres InQuality. El brief de Sprint 1.5 propuso pasteles "más consultivos" (#BBF7D0, #FED7AA, #FECACA).

Decisión actual: mantener saturados (Sprint 1.5 Etapa 1).

Impacto del cambio futuro: requiere recalibrar tests E2E de análisis de píxeles (umbrales de verde/ámbar/rojo).

Acción: decidir con feedback real de uso en talleres InQuality. Sprint 3-4.

---

Refinamientos UX

[BACKLOG] Mejorar animación de expansión de sección "Automatización" en ActivityPanel

Estado: actualmente usa max-h trick (funciona, pero la aceleración no es lineal en los últimos píxeles).

Solución sofisticada: useRef + scrollHeight para animar a la altura real del contenido.

Costo: medio. Beneficio: micro-pulido visual.

[BACKLOG] Label "Payback" superpuesto con eje Y en CumulativeSavingsChart (web)

Estado: bug visual menor. El texto del marker vertical "Payback · X meses" se superpone con los labels del eje Y.

Solución: ajustar offset del label del marker payback.

Costo: 10 min en próxima etapa que toque el componente.

Prioridad: baja, no afecta funcionalidad.

[BACKLOG] CumulativeSavingsChart — empezar en -inversión, no en 0 (web)

Estado: el gráfico web parte de (Año 0, 0). Decisión arquitectónica: cambiar a (Año 0, -inversión) para ser financieramente honesto.

Justificación: mostrar el punto inicial como -USD 80.000 hace visible el "valle de retorno". La línea cruza el cero exactamente en el mes de payback. Es la representación estándar en análisis financiero.

Impacto: consistencia con el chart del PDF (que ya se implementó así en Sprint 1.5 Etapa 7).

Archivos: src/features/report/CumulativeSavingsChart.tsx.

---

Refinamientos visuales del PDF — derivados de validaciones de Sprint 1.5

Estos hallazgos surgieron en validaciones visuales del director durante Sprint 1.5. Se difirieron a "polish final" del mismo sprint o a Sprint 2.

[SPRINT-1.5 — POLISH FINAL] Refinamientos página 1 PDF ROI

KPI Hero:

• Spacing entre label "AHORRO PROYECTADO A 3 AÑOS" y la cifra
• Tamaño de la cifra (evaluar reducir ligeramente)
• Esquinas redondeadas (si se logra técnicamente — jsPDF no hace clip en addImage)

Banner narrativo:

• Destacar tipográficamente cifras y palabras clave (negrita en USD, %, meses)
• Considerar bullets o estructura más visual

Grid 2x2 KPIs secundarios:

• Inconsistencia tipográfica detectada — investigar y armonizar
• Verificar que los 4 cards sigan el mismo patrón visual

Top 3 actividades:

• Aumentar tamaño del título "TOP 3 ACTIVIDADES POR AHORRO"
• Agregar fondo claro a las barras para mejor contraste
• Reconsiderar diseño completo del bloque

---

Decisiones arquitectónicas tomadas en Sprint 1.5 (cerradas, archivadas)

Sección informativa. Estas decisiones ya están aplicadas en el código. Se mantienen acá como referencia.

Subtítulo "Análisis de retorno de inversión" solo en página 1 ROI

Decidido: página 1 tiene subtítulo descriptivo, páginas 2-4 no. Patrón estándar de reportes financieros (página 1 con título extendido).

KPI cards en página 1 de PDFs Actual/Automatizado — color naranja

Decidido: el KPI "Costo total" se migró a naranja durante refactor de Sprint 1.5. Antes era azul. Decisión retroactiva del audit.

ComparisonTable — actividades no automatizables muestran em dash

Decidido: en filas donde isAutomatable === false, mostrar "—" (em dash) en columnas Ahorro y % Ahorro en lugar de "USD 0,00" y "0,0%". Aplicado en Sprint 1.5.

Versión "v0.1.0" en footer — fuera de PDFs, presente en web

Decidido: la versión es útil para usuarios internos en web. En PDFs entregados a clientes genera dudas de estabilidad. Aplicado en Sprint 1.5.