# BRIEF — Sprint 4: Formulario Wizard v3

> Versión objetivo: **3.0.0** · Rama de trabajo: `main` · Preservación: `v2.1.0-stable`

---

## Objetivo en una frase
Reescribir el formulario de encuesta como un wizard pregunta-por-pantalla con
mini-wizard anidado para vínculos familiares, sobre un nuevo instrumento de 10
secciones, habilitando análisis de datos multi-instancia.

---

## Alcance (qué entra)
- Nuevo modelo de datos: columna `instance_id` en `answers`, nueva constraint única
- Nuevo instrumento v3 (10 secciones, ~38 preguntas base + preguntas por instancia)
- Motor de wizard: grafo de pantallas, navegación, estado, instancias dinámicas
- Componente de pantalla única (una pregunta por pantalla)
- Mini-wizard anidado para vínculos familiares (pregunta 4.1 → instancias)
- Autocomplete de barrios desde dataset INE/DGEEC (`geo_paraguay.json`)
- Subtítulos del "porqué" por sección
- Submit actualizado para enviar `instance_id` por answer
- Barra de progreso dinámica
- RPCs nuevas para preguntas de vínculo con instancias
- Seed v3 limpio (sin migración de datos v2)

---

## Fuera de alcance (explícito)
- ❌ Migración de datos v2.1 → v3 (se decide más adelante, cuando v3 esté estable)
- ❌ Tocar la rama `v2.1.0-stable`
- ❌ RE Index (sprint posterior)
- ❌ Informe descargable (sprint posterior)
- ❌ Autenticación de `/admin/responses` (TECH-DEBT-008)
- ❌ Backup remoto S3 (TECH-DEBT-006)

---

## Decisiones ya tomadas (no renegociar)
1. v3 se desarrolla en `main`. v2 queda preservado en `v2.1.0-stable` + tag `v2.1.0`.
2. v3 arranca con seed limpio — sin datos migrados.
3. `instance_id text DEFAULT 'default'` en `answers`. Constraint:
   `UNIQUE (response_id, question_id, instance_id)`.
4. Wizard pregunta-por-pantalla para TODO el formulario tras el consentimiento.
5. Mini-wizard de familiares: una pregunta por pantalla, con badge de contexto
   "Familiar X de N".
6. Numeración desde Sección 1 (no "Sección A").
7. Barrio: autocomplete para ciudades con datos INE, texto libre para el resto.
8. Texto de consentimiento: el del Excel del instrumento v3 (Sección 1).
9. Versionado SemVer + CHANGELOG + tags de Git en cada versión estable.
10. 2-3 familiares es el caso típico; soportar N sin límite duro.

---

## Criterios de éxito (checklist)
- [ ] El formulario funciona end-to-end como wizard, una pregunta por pantalla
- [ ] El mini-wizard de familiares genera instancias correctamente (verificable en DB)
- [ ] Los datos se guardan con `instance_id` correcto por familiar
- [ ] El dashboard sigue funcionando (las preguntas no-instancia usan `instance_id='default'`)
- [ ] Las nuevas RPCs agregan datos de vínculo por instancia
- [ ] El autocomplete de barrios funciona para las ciudades principales
- [ ] La validación visual del wizard coincide con el mockup aprobado
- [ ] `v2.1.0-stable` permanece intacta y restaurable

---

## Etapas del Sprint 4

| Etapa | Nombre | Entregable | Dependencia |
|---|---|---|---|
| **4.0** | Preservación v2 | Tag v2.1.0, rama stable, dump, CHANGELOG | — |
| **4A** | Modelo de datos | Migración `instance_id` + constraint | 4.0 |
| **4B** | Seed v3 | Instrumento v3 completo en seed.sql + geo JSON | 4A |
| **4C** | Motor del wizard | Grafo de pantallas, estado, navegación (lógica) | 4B |
| **4D** | Componente de pantalla | UI una-pregunta-por-pantalla + secciones | 4C |
| **4E** | Mini-wizard instancias | Vínculos 4.1 + pantallas por familiar | 4D |
| **4F** | Autocomplete barrios | Campo barrio con dataset INE | 4D |
| **4G** | Submit con instance_id | Guardado correcto multi-instancia | 4E |
| **4H** | RPCs de vínculo | Agregados de datos por instancia en dashboard | 4G |
| **4I** | Validación e2e + tag v3.0.0 | QA visual completo + release | todas |

---

## Orden de ejecución
4.0 → 4A → 4B → 4C → 4D → (4E ∥ 4F) → 4G → 4H → 4I

Las etapas 4E y 4F pueden ir en paralelo si hay capacidad; si no, 4E primero
(es la más crítica), 4F después.

---

## Notas de versionado por etapa
- Cada etapa cierra con un commit versionado descriptivo.
- Las versiones `3.0.0-alpha.N` se pueden usar para hitos intermedios si se
  despliega a un entorno de prueba.
- El tag `v3.0.0` se crea solo en la etapa 4I, cuando todo está validado.