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

[RESOLVED] Truncamiento de líneas largas en notas metodológicas

Estado actual: los caracteres Unicode rotos (Σ → £, − → ") fueron resueltos en Etapa 8 mediante reescritura a ASCII puro (SUM, x, -). Decisión arquitectónica: la notación ASCII se mantiene como solución permanente porque alinea con terminología financiera/Excel.

Pendiente: verificar si todavía hay líneas largas que se truncan en margen derecho cuando una fórmula excede el ancho de página portrait.

Acción: test E2E que valide ancho de cada línea de notas metodológicas en los 3 PDFs. Si hay truncamiento, evaluar:

• Opción A: usar doc.splitTextToSize() para wrap automático
• Opción B: reformular fórmulas problemáticas en múltiples líneas en el texto fuente

Resultado: auditado en Sprint 2 Etapa 5-6. Dos líneas variables corregidas con splitTextToSize (topResource.resourceName en drawAnalysisSection y top3 en análisis ROI). Resto sin riesgo confirmado. 7 tests nuevos cubren el comportamiento. Sprint cerrado en: Sprint 2 Etapas 5-6.

---

Deuda media — afecta DX o evolución del producto

[INVESTIGATING] Clave de localStorage del auth E2E vs producción

Estado actual: contradicción no resuelta entre dos hechos empíricos verificados:

• En producción, ProfileSheet.getAccessToken() lee supabase.auth.token y funciona correctamente (Sprint 5 Etapa 4).
• En E2E, auth-setup.ts escribe la sesión bajo sb-${projectRef}-auth-token y el smoke test "app header shows user avatar" pasa. Hipótesis: el cliente Supabase de la app (src/lib/supabase.ts) y el de auth-setup.ts podrían estar usando storageKey distinto. La documentación inline en auth-setup.ts explica el comportamiento observado pero no reconcilia la contradicción. Impacto: si el auth E2E no funciona realmente (sesión vacía), todos los specs con storageState serían inválidos — pasarían por ausencia de assertions fuertes, no porque el auth funcione. Acción: en Sprint 6, comparar el localStorage real en producción vs el auth-state.json del E2E. Ejecutar un spec que haga una query autenticada a Supabase y afirme que devuelve datos reales del usuario de test. Archivos afectados: tests/e2e/setup/auth-setup.ts, src/lib/supabase.ts. Origen: Sprint 5 Etapa 6 diagnóstico de auth-setup.

[BACKLOG] getCurrentUser() en SupabaseAuthService — sin callers activos

Estado actual: SupabaseAuthService.getCurrentUser() usa getSession() directamente (sin timeout, sin processLock workaround). Es la única excepción documentada a la regla — justificada porque necesita el objeto sesión completo, no solo una barrera. Sin callers activos hoy. Impacto si no se resuelve: ninguno mientras no tenga callers. Si en el futuro algún flujo llama getCurrentUser(), podría colgar el processLock si el servidor no responde. Solución propuesta: cuando adquiera callers reales, evaluar si supabase.auth.getUser() (token de localStorage, sin lock) es suficiente para ese caso. Archivos afectados: src/auth/SupabaseAuthService.ts (~línea 27, comentario explicativo presente). Origen: OBSERVATIONS Sprint 5 Etapa 1 — ítem prometido que faltaba registrar acá.

[BACKLOG] setTimeout(350) en ProfileSheet — candidato a limpieza

Estado actual: ProfileSheet.handleSave() difiere updateUser 350ms como mitigación de la race condition con Radix. El fix definitivo vive en src/components/ui/sheet.tsx (cleanup defensivo de pointer-events). El setTimeout es redundante pero inofensivo. Solución propuesta: eliminar el setTimeout, verificar que el fix en sheet.tsx sea suficiente por sí solo. Archivos afectados: src/components/ProfileSheet.tsx. Origen: Sprint 5 Etapa 4G (fix intermedio que quedó al resolverse la causa raíz en 4H).

[RESOLVED] E2E specs con Dexie directo — reescribir para Supabase

Resultado: export-pdf.spec.ts (test "Heatmap con gradiente real") y validate-dod-etapa4.spec.ts reescritos para inyectar datos vía @supabase/supabase-js con SUPABASE_SERVICE_ROLE_KEY (bypasa RLS), en lugar de IndexedDB directo. afterAll borra el proceso creado por cada test (cascada en activities/simulations). Si SUPABASE_SERVICE_ROLE_KEY no está configurada en .env.test, ambos tests hacen test.skip() con mensaje descriptivo en vez de fallar — ver .env.example. Diagnóstico previo de auth-setup.ts confirmó que la storageKey (sb-${projectRef}-auth-token) ya era correcta (no era parte del problema): @supabase/supabase-js's createClient() sobrescribe el STORAGE_KEY default de auth-js con esa clave calculada desde la URL. Sprint cerrado en: Sprint 5 Etapa 6.

[RESOLVED] E2E flakiness — "Guardar cambios" button timing en ActivityPanel

Resultado: agregado data-testid="save-activity-btn" al botón en ActivityPanel.tsx. Specs afectados (payback-etapa-2.spec.ts, export-roi.spec.ts) reemplazan el click directo por waitForSelector(':not([disabled])') → click → waitForSelector('[disabled]') (confirma que el guardado se procesó). Confirmado estable en 3 corridas consecutivas sin fallos. GlobalSettingsPanel.tsx tiene el mismo patrón isDirty/disabled en su botón "Guardar configuración" pero no se tocó — fuera del scope de Etapa 6; queda como ítem nuevo abajo. Sprint cerrado en: Sprint 5 Etapa 6.

[BACKLOG] GlobalSettingsPanel — mismo patrón de flakiness potencial que ActivityPanel

Estado actual: GlobalSettingsPanel.tsx tiene un botón "Guardar configuración" con el mismo guard disabled={!isDirty} que ActivityPanel.tsx tenía antes de Etapa 6. La función configureGlobal() en payback-etapa-2.spec.ts y export-roi.spec.ts sigue usando getByRole('button', { name: /Guardar/i }).click() sin esperar a que se habilite — el mismo riesgo de flakiness, no confirmado como activo todavía. Impacto: potencial, no confirmado. Estos specs pasaron 3/3 en Etapa 6 sin tocar esta función. Solución propuesta: agregar data-testid="save-global-btn" a GlobalSettingsPanel.tsx y aplicar el mismo patrón de waitForSelector que se usó para save-activity-btn. Costo: bajo. Mismo patrón ya validado. Origen: Sprint 5 Etapa 6 — detectado durante el diagnóstico, explícitamente fuera del scope del prompt (solo ActivityPanel.tsx listado en archivos a modificar).

[BACKLOG] 9 specs adicionales con el mismo patrón flaky de "Guardar" sin data-testid

Estado actual: además de los 2 specs corregidos en Etapa 6, otros 9 archivos (sprint-1-5-final.spec.ts, screenshots-etapa-3.spec.ts, etapa-4-pdfs.spec.ts a etapa-9-badge.spec.ts, etapa-11-polish.spec.ts) usan el mismo getByRole('button', { name: /Guardar/i }).click() sin esperar a isDirty. No confirmados como flaky activamente — fuera del scope explícito de Etapa 6 (que listaba solo 2 archivos a modificar). Impacto: riesgo de flakiness latente, no confirmado. Solución propuesta: aplicar el mismo patrón waitForSelector('[data-testid="save-activity-btn"]:not([disabled])') ahora que el testid existe en producción. Costo: bajo, mecánico — mismo cambio repetido 9 veces. Origen: Sprint 5 Etapa 6 — identificado durante el grep de diagnóstico, no aplicado por respeto al scope explícito del prompt.

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

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

Resultado: offset ajustado con padding: [0,0,0,8] y offset: [4,0]. Sin colisión con eje Y. Sprint cerrado en: Sprint 2 Etapa 3.

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

Resultado: verificado en Sprint 2 Etapa 3 — la línea ya arrancaba en -investment (roi.annualSavings * y - investment, y=0 → -investment). Ítem cerrado sin cambio de código. Sprint cerrado en: Sprint 2 Etapa 3.

---

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.

---

Anotaciones rápidas antes de pasar a Etapa 10

[RESOLVED] Tamaño del badge ⚡ — evaluar aumentar

Resultado: evaluado en Sprint 2 Etapa 3 (16px) y ajustado a 20×20px en fix post-validación visual. Sin colisión en nodos de evento. Director aprobó visualmente. Sprint cerrado en: Sprint 2 Etapa 3 + fix.

[INVESTIGATING] Toggle automatable + Guardar requerido para badge

Estado: comportamiento intencional. Switch del ActivityPanel cambia visualmente, pero el badge en BpmnCanvas solo aparece después de "Guardar". Decisión actual (Sprint 1.5): mantener como está. Es UX deliberada. Acción: revisar en Sprint 2 con feedback real de uso en talleres. Si genera confusión recurrente, evaluar Opción B (indicador visual de "pendiente de guardar") o Opción C (auto-save).

[RESOLVED] Badge ⚡ naranja en BpmnCanvas — Etapa 9

Resultado: badge rediseñado con identidad InQ, hex hardcodeados eliminados, 526 tests verdes. Sprint cerrado en: Sprint 1.5 Etapa 9.

[RESOLVED] Refinamientos página 1 PDF ROI — Etapa 11

Resultado: KPI Hero 26pt, banner con bold naranja oscuro, grid 2×2 uniforme 9/18/9pt, Top 3 con título 11pt. Esquinas redondeadas via canvas clip con fondo blanco opaco. Sprint cerrado en: Sprint 1.5 Etapa 11.