motor-de-encuestas/sprints/sprint-4/ETAPA_4A_PROMPT.md

ETAPA 4A — Modelo de datos: instance_id en answers

1. Objetivo

Agregar la columna instance_id a la tabla answers y cambiar la constraint única para soportar múltiples respuestas a la misma pregunta (una por instancia de vínculo familiar). Es el cambio de base que habilita todo el wizard v3.

2. Contexto previo

• v3 se desarrolla en main. v2 está preservado en v2.1.0-stable.
• La tabla answers actual tiene constraint UNIQUE (response_id, question_id).
• El wizard v3 genera múltiples respuestas para las preguntas 4.2 y 4.3 (una por cada familiar declarado en 4.1). Sin instance_id, esas respuestas colisionan.
• Las preguntas no-vinculadas (la gran mayoría) usan instance_id = 'default'.

3. DECISIONES YA TOMADAS — no consultar de nuevo

• Nombre de la columna: instance_id, tipo text, DEFAULT 'default', NOT NULL.
• Nueva constraint: UNIQUE (response_id, question_id, instance_id).
• Para preguntas normales: instance_id = 'default'.
• Para instancias de vínculo: instance_id = 'familiar_1', 'familiar_2', etc.
• Esto es una migración nueva, NO modifica migraciones existentes.
• NO se migran datos v2 — el seed v3 arranca limpio (etapa posterior).

4. Tareas

4.1 Nueva migración

Crear supabase/migrations/20260620000001_add_instance_id.sql:

-- Sprint 4 (v3.0.0) — instance_id para respuestas multi-instancia
-- Habilita el mini-wizard de vínculos familiares (una respuesta por familiar)

-- 1. Agregar la columna con default para filas existentes
ALTER TABLE public.answers
  ADD COLUMN IF NOT EXISTS instance_id text NOT NULL DEFAULT 'default';

-- 2. Eliminar la constraint única vieja (nombre real verificado en DB)
ALTER TABLE public.answers
  DROP CONSTRAINT IF EXISTS answers_response_id_question_id_key;

-- 3. Crear la nueva constraint que incluye instance_id
ALTER TABLE public.answers
  ADD CONSTRAINT answers_response_question_instance_key
  UNIQUE (response_id, question_id, instance_id);

-- 4. Índice para consultas por instancia (análisis de vínculos)
CREATE INDEX IF NOT EXISTS idx_answers_instance
  ON public.answers (question_id, instance_id)
  WHERE instance_id != 'default';

4.2 Verificar el nombre real de la constraint actual

ANTES de escribir el DROP, verificar el nombre exacto de la constraint única actual de answers. El nombre asumido es answers_response_id_question_id_key (convención Postgres), pero confirmar con:

SELECT conname FROM pg_constraint
WHERE conrelid = 'public.answers'::regclass AND contype = 'u';

Si el nombre difiere, ajustar el DROP CONSTRAINT en la migración. NO ejecutar la migración en producción — solo crear el archivo.

4.3 Actualizar DATA_MODEL.md

Documentar el cambio en DATA_MODEL.md: la tabla answers ahora tiene instance_id y la nueva constraint. Explicar el patrón 'default' vs 'familiar_N'.

5. Entregables (DoD)

• Migración 20260620000001_add_instance_id.sql creada.
• Nombre real de la constraint actual verificado y usado en el DROP.
• DATA_MODEL.md actualizado con el nuevo esquema de answers.
• La migración es idempotente (IF EXISTS / IF NOT EXISTS).
• NO ejecutada en producción.

6. Qué reportar

Verificado:
- Migración creada ✓
- Nombre real de constraint actual: [nombre]
- DATA_MODEL.md actualizado ✓
- Idempotencia confirmada ✓

Asumido:
- [supuestos sobre el esquema]

NO ejecutado en producción (pendiente aprobación del director).

7. Qué NO hacer

• ❌ No ejecutar la migración en la DB de producción.
• ❌ No modificar migraciones existentes.
• ❌ No tocar el seed todavía (es la etapa 4B).
• ❌ No migrar datos de v2.
• ❌ No tocar la rama v2.1.0-stable.

8. Versionado

Commit sugerido al cerrar:

feat(data): agregar instance_id a answers para multi-instancia [4A]

Habilita respuestas múltiples por pregunta (mini-wizard de vínculos).
Nueva constraint UNIQUE(response_id, question_id, instance_id).
Parte del Sprint 4 hacia v3.0.0.