motor-de-encuestas/TECH_DEBT.md

# TECH_DEBT.md — Deuda técnica registrada

> Ítems identificados durante el desarrollo. Cada ítem documenta qué falta, por qué
> no se hizo ahora, y qué trigger habilitaría su resolución.

---

## [TECH-DEBT-001] Ranking widget para 6.2

- **Estado:** 6.2 es actualmente `multiple_choice` max_select=3. El widget muestra
  frecuencia simple (top 8).
- **Deuda:** cuando el tipo pase a `ranking` con JSONB `{rank1, rank2, rank3}`, el
  widget debe reescribirse para mostrar ponderación por posición.
- **Trigger:** decisión del director sobre el tipo de 6.2 en próxima versión del
  instrumento (anotada en SEED_SPEC.md § Decisiones pendientes).

---

## [TECH-DEBT-002] KPI NPS Cuidador

- **Estado:** el instrumento actual no tiene pregunta NPS. El KPI fue eliminado del
  dashboard en Etapa 2E.
- **Para implementar:** agregar en próxima versión del instrumento:
  "En una escala de 0 a 10, ¿qué tan probable es que recomiendes esta empresa a otra
  persona cuidadora?"
- **Trigger:** decisión de incluir NPS en el instrumento v2.

---

## [TECH-DEBT-003] Brecha de políticas (oferta vs. demanda)

- **Estado:** el instrumento captura solo demanda (6.2 = apoyos que ayudarían).
  No captura qué políticas la empresa ya ofrece. W6 muestra solo demanda.
- **Para implementar:** agregar en próxima versión del instrumento:
  "¿Qué apoyos para el cuidado ofrece tu empresa hoy?" (multi-select con las mismas
  opciones de 6.2 + "Ninguno" + "No lo sé").
- **Trigger:** decisión de agregar la pregunta de oferta al instrumento.

---

## [TECH-DEBT-004] Intención directa de salida laboral

- **Estado:** el instrumento no pregunta directamente por intención de dejar el
  empleo. W8 usa indicador compuesto (4.3 + 5.1 + 5.2) renombrado a "Saturación".
- **Para implementar:** agregar en próxima versión:
  "En los últimos 6 meses, ¿pensaste en dejar este empleo por razones relacionadas
  al cuidado?" (Sí/Frecuentemente · Sí/A veces · No · Prefiero no decir).
- **Trigger:** validación metodológica de que el indicador compuesto no es suficiente
  para medir intención de salida.

---

## [TECH-DEBT-005] qi_city / qi_country — migración pendiente

- **Estado:** A1 (Departamento) y A2 (Ciudad) se guardan en `answers`. Las columnas
  `qi_city` y `qi_country` en `responses` son NULL. Sprint 3 las necesita para
  segmentación avanzada.
- **Para implementar:** migration futura que agregue extracción de A1/A2 en el insert
  y extienda la whitelist de `agg_segment`.
- **Trigger:** inicio de Sprint 3 (dashboard avanzado con filtros de ciudad).

---

## [TECH-DEBT-006] Ranking widget para 2.1

- **Estado:** Etapa 3I2 (Cambio 5) cambió 2.1 ("¿Quién es el/la responsable principal
  del cuidado?") de `single_choice` a `multiple_choice`. Permite selección múltiple
  pero sin orden de prioridad — pierde la noción de "responsable principal" cuando
  el respondente marca más de una opción.
- **Deuda:** implementar widget de ranking para 2.1 con el orden:
  Principal cuidador soy yo > secundario instituto > principal pagado > secundario
  familiar (mismo patrón que TECH-DEBT-001 para 6.2).
- **Trigger:** decisión del director sobre el tipo de 2.1 en próxima versión del
  instrumento.

---

## [TECH-DEBT-008] /admin/responses sin autenticación

- **Estado:** RESUELTO (27 jun 2026, ETAPA_AUTH).
- **Descripción:** la vista de control `/admin/responses` no tenía auth. Se implementó
  login con Supabase Auth (`@supabase/ssr`), `middleware.ts` protegiendo
  `/admin/:path*` y `/dashboard/:path*` con redirect a `/login` sin sesión, y la página
  migrada de `service_role` a la sesión del usuario (`anon` key + RLS). Sigue
  excluyendo preguntas `is_sensitive=true` y `text_long` — ese diseño no cambió.
- **Nota:** la vista no distingue roles dentro de staff todavía (todo usuario con fila
  en `user_roles` ve lo mismo). Diferenciar `platform_admin` de `org_admin` ahí sería
  una etapa nueva, no parte de este cierre.

---

## [TECH-DEBT-010] E9 lee modalidad por JOIN a `answers` en vez de `qi_modalidad`

- **Estado:** ABIERTO — decisión consciente, no un descuido.
- **Descripción:** `rpc_me_segmentacion` (E9, Mirada Empresa) segmenta por nivel
  organizacional y por modalidad de trabajo. El nivel (`2.6`) sí se promovió a
  `responses.qi_sector` en el submit (Etapa 4G) — E9 lee de ahí directo. La
  modalidad (`2.7`) NO tiene una columna `qi_modalidad` equivalente — promoverla
  hubiera significado reabrir `rpc_submit_response`, ya verificada contra
  Postgres real en 4G. Para no reabrirla, E9 resuelve modalidad con un JOIN a
  `answers`/`questions` por `code='2.7'` en tiempo de consulta.
- **Costo del JOIN vs. la columna:** una pasada extra por `answers`/`questions`
  en cada llamada a E9 — aceptable para el volumen actual (decenas/cientos de
  respuestas por encuesta), pero más lento que leer una columna denormalizada
  si el dataset crece mucho o si la segmentación por modalidad se usa con
  frecuencia en varios widgets.
- **Acción si se decide promover:** agregar `qi_modalidad text` a `responses`,
  poblarla en `rpc_submit_response` (requiere re-verificar esa RPC contra
  Postgres real, igual que se hizo en 4G), y migrar E9 a leerla directo —
  mismo patrón que se usó para `qi_sector`.
- **Trigger:** evaluar si la Mirada País/Humana también necesitan segmentar por
  modalidad con frecuencia — si varias RPCs repiten el mismo JOIN, conviene
  promoverla de una vez en lugar de cada RPC reimplementando el JOIN.

---

## [TECH-DEBT-011] Sección de pregunta inferida por posición, no modelada como dato

- **Estado:** ABIERTO — decisión consciente, no un descuido. Surgió en
  ETAPA_ADMIN (vista detallada `/admin/responses/[id]`, 27 jun 2026): el prompt
  de etapa asumía columnas `questions.section_number`/`section_title` que NO
  existen. Verificado contra el esquema real (`supabase/migrations/
  20260531000001_create_tables.sql` — única definición de `questions`,
  `20260620000002_form_schema_v3.sql` solo agrega comentarios, ninguna
  migración agrega esas columnas).
- **Descripción:** hoy `questions` no tiene ningún campo que declare "esta
  pregunta pertenece a la sección X". La sección es una fila más en la misma
  tabla, con `type='section'`, intercalada por `position` entre las preguntas
  reales — el código (`lib/form-engine.ts:146-148` en el wizard, y la vista
  detallada de admin) infiere el agrupamiento recorriendo las filas en orden
  de `position` y "abriendo" una sección nueva cada vez que encuentra una fila
  `type='section'`. El título de la sección es el `prompt` de esa fila — no
  hay un campo `title` separado.
- **Por qué es deuda, no solo una curiosidad de modelado:** el motor está
  pensado para ser un "motor de formularios de encuestas" genérico — no toda
  encuesta futura va a tener secciones, y las que las tengan no necesariamente
  van a querer modelarlas como filas-marcador en la misma tabla que las
  preguntas. Hoy CUALQUIER consumidor que necesite agrupar por sección
  (wizard, admin, y a futuro cualquier export/reporte) tiene que reimplementar
  el mismo recorrido secuencial con el mismo supuesto implícito ("la fila
  `type='section'` más cercana hacia atrás en `position` es la sección de esta
  pregunta"). Si esa lógica se necesita en un tercer lugar, ya es momento de
  promoverla a una función compartida — y si el motor crece a encuestas con
  estructuras más ricas (subsecciones, secciones condicionales, secciones que
  no son "preguntas" en absoluto), el modelo actual no escala sin reescribir
  cada consumidor.
- **Alternativa más genérica y escalable (no implementada, propuesta para
  evaluar cuando se priorice):** sacar la sección de `questions.type` y
  modelarla como entidad propia — opción simple: `questions.section_id uuid
  NULL REFERENCES sections(id)` + tabla `sections(id, survey_id, title,
  position)`; opción más liviana sin tabla nueva: `questions.section_title
  text NULL` + `questions.section_position int NULL` poblados directamente en
  cada pregunta (denormalizado, sin fila-marcador `type='section'` separada).
  Cualquiera de las dos deja "pertenece a la sección X" como un hecho
  consultable con una columna, no como un cálculo derivado de recorrer
  `position` — y ninguna asume que toda encuesta tiene secciones (el campo es
  nullable). Migrar implicaría: (1) nueva(s) columna(s)/tabla, (2) backfill
  desde las filas `type='section'` existentes, (3) actualizar
  `lib/form-engine.ts` y la vista detallada de admin para leer el dato en vez
  de inferirlo, (4) decidir si `type='section'` se deprecia o convive.
- **Acción tomada mientras tanto:** la vista detallada de admin
  (`app/admin/responses/[id]/page.tsx`) replica la misma lógica de
  `lib/form-engine.ts` (recorrido secuencial por `position`, abre sección en
  cada `type='section'`) — no inventa columnas nuevas, no diverge del modelo
  actual.
- **Trigger:** si una tercera feature necesita el mismo agrupamiento, extraer
  la lógica a un helper compartido en `lib/` en vez de triplicarla. Si el
  producto efectivamente evoluciona a soportar surveys con estructuras de
  sección más complejas que el caso actual, evaluar la migración a columna/
  tabla explícita antes de seguir apilando consumidores sobre el supuesto
  implícito.