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

ETAPA 4B — Esquema declarativo del formulario v3 + seed

1. Objetivo

Definir el formulario de cuidadores v3 como un esquema declarativo persistido: extender el modelo de questions para soportar instanciación y nuevos operadores de flujo, y cargar el instrumento completo (10 secciones) en el seed. La lógica del flujo vive en estos datos, no en el frontend (ver ADR-005).

2. Contexto previo

• ADR-005 define la arquitectura: esquema declarativo, frontend renderer sin reglas.
• instance_id ya existe en answers (Etapa 4A).
• El esquema actual de questions ya tiene conditional_rules JSONB con operadores eq / eq_any y acción show, auto-target implícito.
• El contenido exacto del instrumento v3 está validado en el mockup aprobado (wizard_formulario_mapeo_v3.html) y en el Excel Formulario_Mapeo_Corregido.xlsx.
• El dataset de barrios está en geo_paraguay_full.json (va a public/data/).

3. DECISIONES YA TOMADAS — no consultar de nuevo

• Se EXTIENDE el modelo existente, no se crea tabla de definición separada (ADR-005).
• Nuevos campos declarativos en questions:
  • instance_generator boolean DEFAULT false — marca la pregunta que genera instancias (4.1)
  • instance_of text DEFAULT NULL — código del generador del que depende (4.2/4.3 → '4.1')
• Nuevos operadores en conditional_rules: agregar acción hide y operador para expresar el salto "Ninguna de las anteriores → salta a sección final".
• Secciones con nombre y descripción (el "porqué"): representación a definir por Claude Code según lo más limpio (tabla sections o registros con metadata) — proponer antes de ejecutar.
• v3 arranca con seed LIMPIO, sin datos migrados.
• El contenido de preguntas es EXACTAMENTE el del mockup validado.

4. Tareas

4.1 Migración de esquema declarativo

Crear supabase/migrations/20260620000002_form_schema_v3.sql:

• Agregar instance_generator boolean NOT NULL DEFAULT false a questions.
• Agregar instance_of text a questions (nullable).
• Documentar (comentario SQL) el vocabulario extendido de conditional_rules: operadores eq, eq_any, not_in; acciones show, hide.
• Idempotente (IF NOT EXISTS).

4.2 Representación de secciones

Proponer e implementar cómo persistir las 10 secciones con su nombre y descripción ("Texto de ayuda" del Excel). Reportar la propuesta antes de ejecutar si implica cambio de esquema. Las descripciones de sección están en el BRIEF y el mockup.

4.3 Seed v3 del instrumento

Reescribir el seed del survey (o crear seed v3 separado) con las 10 secciones y todas las preguntas EXACTAMENTE como el mockup validado:

• Sección 1: Consentimiento (2 checkboxes: requerido + opcional)
• Sección 2: Datos generales (2.1-2.7)
• Sección 3: Prevalencia discapacidad propia (3.1-3.5; 3.1='No' oculta 3.2-3.5)
• Sección 4: Vinculación familiar (4.1 generador de instancias; 4.2 y 4.3 instance_of='4.1')
• Sección 5: Responsabilidad (5.1-5.4; ocultas si "solo niño sin discapacidad")
• Sección 6: Intensidad (6.1-6.4; idem)
• Sección 7: Impacto laboral (7.1-7.6; idem)
• Sección 8: Impacto económico (8.1-8.4)
• Sección 9: Conciencia organizacional (9.1-9.4)
• Sección 10: Comentarios (10.1)
• Flujo "Ninguna de las anteriores" en 4.1 → salta a Sección 10.
• Todas las opciones, hints ("Podés marcar más de una opción"), y flags is_sensitive exactamente como el mockup.

4.4 Dataset geográfico

Copiar geo_paraguay_full.json a public/data/geo_paraguay.json del repo.

4.5 Actualizar SEED_SPEC.md

Documentar el instrumento v3 completo como contrato (Principio 4 / AP.11).

5. Entregables (DoD)

• Migración de esquema declarativo creada (campos de instanciación).
• Propuesta de representación de secciones reportada (y aplicada si se aprueba).
• Seed v3 con las 10 secciones, contenido exacto del mockup.
• instance_generator y instance_of correctamente seteados en 4.1/4.2/4.3.
• Flujo declarativo: 3.1='No' oculta 3.2-3.5; "Ninguno" en 4.1 salta a S10; "solo niño" oculta S5-S7.
• geo_paraguay.json en public/data/.
• SEED_SPEC.md actualizado.
• NO ejecutado en producción (solo archivos).

6. Qué reportar

Verificado:
- Migración de esquema creada ✓
- Representación de secciones: [propuesta]
- Seed v3: N preguntas, 10 secciones ✓
- instance_generator/instance_of correctos ✓
- Reglas de flujo declarativas: [listar las 3 reglas principales]
- geo JSON en public/data ✓
- SEED_SPEC.md actualizado ✓

Asumido:
- [supuestos sobre representación de secciones y operadores]

NO ejecutado en producción.

7. Qué NO hacer

• ❌ No ejecutar en producción (lo aplica el director vía CLI del VPS).
• ❌ No poner lógica de flujo en el frontend (es la etapa 4D y será renderer).
• ❌ No migrar datos v2.
• ❌ No tocar v2.1.0-stable.
• ❌ No construir el motor genérico (Fase 2).

8. Versionado

Commit sugerido:

feat(schema): esquema declarativo + seed v3 del formulario [4B]

Extiende questions con instance_generator/instance_of.
Instrumento v3 completo (10 secciones) como datos declarativos.
Flujo del formulario en el esquema, no en presentación (ADR-005).