motor-de-encuestas/sprints/sprint-2/ETAPA_2A_PROMPT.md

# ETAPA 2A — Motor del formulario (render + lógica condicional, sin persistir)

> Prompt versionado (Patrón B.1). Primera pieza de cara al usuario. Claude Code lo ejecuta tras leer
> `CLAUDE.md`, `DATA_MODEL.md`, `SEED_SPEC.md`, `ADR-002`, `sprints/sprint-2/BRIEF.md` y este prompt.

## 1. Objetivo
Construir el motor del formulario: una app Next.js que **lee** la encuesta live desde Supabase con la
`anon` key, renderiza las **44 preguntas** (instrumento v2) con el widget correcto por tipo, ejecuta la lógica condicional,
valida, es mobile-first y accesible (WCAG AA), no pierde lo cargado al refrescar, y al enviar muestra
un **resumen de respuestas**. **NO escribe nada en la base** (eso es 2B).

## 2. Contexto previo
La fundación de datos (Sprint 1) está cerrada y verificada en Cloud: esquema, RLS, seed real de **44
preguntas** (instrumento v2, Jun 2026), k-anonimato. El proyecto Supabase está linkeado. Todavía no existe app frontend — esta
etapa la scaffolding. `responses.consent_record_id` es `NOT NULL`, por eso 2A **no** persiste: la
escritura requiere el consentimiento, que es 2B. El mockup `formulario_mapeo.html` (en el historial
del proyecto) es el contrato visual: replicar su look y flujo, pero leyendo del esquema, no hardcoded.

## 3. Decisiones ya tomadas (no consultar de nuevo)
- Stack: **Next.js (App Router)** + **react-hook-form + zod** + **@supabase/supabase-js** (o
  `@supabase/ssr`). Sin librería de gráficos (eso es Sprint 3).
- El cliente usa la **`anon` key** (pública, respeta RLS), desde `NEXT_PUBLIC_SUPABASE_URL` y
  `NEXT_PUBLIC_SUPABASE_ANON_KEY` en `.env.local`. **El `service_role` NUNCA va a una variable
  `NEXT_PUBLIC_` ni al cliente** (regla 9 de CLAUDE.md).
- `options`: **array** para `single_choice`/`multiple_choice`; **objeto** `{min,max,min_label,max_label}`
  para `rating` (3.5, 4.3); **null** para `text_short`/`text_long`. Manejar las tres formas.
- Tipos de widget: `single_choice`→radio, `multiple_choice`→checkbox, `rating`→escala 1-5,
  `text_long`→textarea, `text_short`→`<input type="text">` de una línea (A1/A2/A3: País, Ciudad, Sede).
- Condicionales: cada pregunta dependiente trae `conditional_rules` con `{if_question, op:'eq',
  value:'Sí', action:'show'}`. Triggers: **1.1** (→1.2–1.5), **1.6** (→1.7–1.12), **1.13** (→1.14–1.16).
  Con "No"/"Prefiero no decir" ocultar **y limpiar** las respuestas del bloque.
- 6.2 = `multiple_choice` con `max_select=3` (impedir marcar más de 3).
- 2A **no** escribe `responses`/`answers`/`consent_records`. Al enviar → pantalla de resumen.

## 4. Tareas
1. Scaffolding de la app Next.js (App Router) en el repo. Setear el cliente Supabase con la `anon`
   key desde `.env.local`. Crear `.env.example` (sin valores) documentando las dos variables.
2. Leer desde Supabase (anon) la encuesta `status='live'` + sus 44 `questions` ordenadas por
   `position`, con sus `options`, `type`, `max_select`, `is_sensitive`, `conditional_rules`.
   (Si la encuesta seed no está `live`, dejar documentado que el director debe setearla a `live`, o
   leer por id — NO cambiar el estado desde el cliente.)
3. Renderizar cada tipo con su widget: `single_choice`→radios, `multiple_choice`→checkboxes (con tope
   `max_select`), `rating`→escala 1-5 (usando el objeto options), `text_long`→textarea,
   `text_short`→input de una línea (A1/A2/A3).
4. Motor de lógica condicional data-driven: evaluar `conditional_rules` para mostrar/ocultar; al
   ocultar un bloque, limpiar sus valores.
5. Validación con zod (tipos correctos; respetar `max_select`; `required` según el campo `required`
   de cada pregunta — hoy todas `false`, así que validación liviana).
6. UX: mobile-first fluida, replicando el contrato visual del mockup (secciones, progreso, estados de
   opción). Accesibilidad WCAG 2.2 AA: HTML semántico, `<label>` asociado a cada input, navegación y
   operación completa por teclado, foco visible, contraste suficiente, y anunciar a lectores de
   pantalla la aparición/desaparición de los bloques condicionales (`aria-expanded`/`aria-live`).
7. Resiliencia lite: persistir las respuestas en progreso en `localStorage` (clave por `survey_id`)
   para sobrevivir un refresh; limpiar al enviar. No guardar nada identificable.
8. Al enviar: validar y mostrar una **pantalla de resumen** con las respuestas dadas. NO llamar a la
   base para escribir.

## 5. Definition of Done
- [ ] `npm run dev` levanta la app y carga la encuesta desde Supabase (anon).
- [ ] Se renderizan las **44 preguntas**; los 3 bloques condicionales aparecen/desaparecen con 1.1/1.6/1.13.
- [ ] 6.2 no deja marcar más de 3; rating (3.5/4.3) funciona con el formato objeto; A1/A2/A3 son inputs de texto.
- [ ] Navegable y operable solo con teclado; pasa una auditoría a11y básica (axe o Lighthouse) sin errores AA.
- [ ] Refresh conserva lo cargado; enviar limpia el almacenamiento y muestra el resumen.
- [ ] `npm run build` limpio; ninguna variable `NEXT_PUBLIC_` contiene el `service_role`.
- [ ] `git diff --name-only HEAD` solo con archivos de la app nueva + `.env.example`.

## 6. Validaciones automatizadas mandatorias (antes de entregar)
- La carga lee **44** preguntas desde la base (logear el conteo), no un número hardcodeado.
- Las **13 condicionales** se evalúan desde `conditional_rules` (no con `if` cableados por código).
- `max_select` de 6.2 se respeta en runtime (test o verificación manual reproducible).
- `npm run build` sin errores.
- Auditoría a11y (axe-core o `lighthouse`) sobre la página del formulario: **0 violaciones de nivel AA**.
- Grep de seguridad: `service_role` NO aparece en ningún archivo del cliente ni en `NEXT_PUBLIC_*`.
- Si CUALQUIERA falla: NO declarar lista la etapa. Reportar y esperar.

## 7. Qué reportar
- **Verificado:** conteo de preguntas cargadas, resultado de la auditoría a11y (con la herramienta y
  el puntaje/violaciones), confirmación de que el build pasa, salida del grep de `service_role`.
- **Asumido / Hallazgos / Decisiones por iniciativa** (clasificadas por nivel).
- **`git diff --name-only HEAD`** pegado.
- Indicar cómo levantar la app localmente para que el director la abra (el comando y la URL).

## 8. Qué NO hacer
- NO escribir en `responses`, `answers` ni `consent_records` (es 2B).
- NO construir el flujo de consentimiento ni el dashboard.
- NO hardcodear las preguntas: todo se lee del esquema.
- NO poner el `service_role` en el cliente ni en variables `NEXT_PUBLIC_`.
- NO recolectar ni guardar nada identificable del respondente (sin `respondent_id`, sin fingerprinting,
  sin claves de localStorage que identifiquen a la persona). El anonimato es la premisa.
- NO cambiar el estado de la encuesta (`draft`/`live`) desde el cliente.
- Ante conflicto entre una restricción y "que compile/funcione": **detenerse y reportar**.