# 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).
```