102 lines
5.0 KiB
Markdown
102 lines
5.0 KiB
Markdown
# ADR-005 — Esquema declarativo de formularios y estrategia de dos fases
|
|
|
|
> Para agregar a `ARCHITECTURE.md` (o `docs/adr/`). Estado: **Aceptada**.
|
|
> Fecha: 2026-06-20 · Sprint 4 · Versión objetivo 3.0.0
|
|
|
|
---
|
|
|
|
## Contexto
|
|
|
|
El producto es un **motor de formularios/flujos de encuesta**. La aplicación
|
|
actual (encuesta "Mapeo de Cuidadores") es su primer caso de uso real, pero la
|
|
arquitectura debe servir al producto, no solo a este formulario.
|
|
|
|
El rediseño a wizard v3 introduce lógica de flujo significativamente más compleja
|
|
que v2: recorridos ramificados (cuidador completo / solo niño / sin vínculo),
|
|
mini-wizard de instancias de vínculo familiar (preguntas que se repiten N veces,
|
|
una por familiar), y saltos condicionales de sección.
|
|
|
|
Existe una restricción de negocio: dos clientes inminentes en 10-20 días requieren
|
|
la encuesta funcionando para validación.
|
|
|
|
El esquema actual de `questions` ya posee una base declarativa:
|
|
- `conditional_rules` JSONB con operadores `eq` / `eq_any` y acción `show`
|
|
- Auto-target implícito (la regla afecta a la pregunta que la porta)
|
|
- Tipos de pregunta extensibles vía CHECK constraint
|
|
|
|
## Problema
|
|
|
|
¿Dónde reside la lógica del flujo del formulario? Tres anti-patrones a evitar:
|
|
1. **Lógica en el presentador** (frontend con reglas hardcodeadas) — impide
|
|
reutilización, genera bugs de sincronización de estado, no escala al producto.
|
|
2. **Lógica dispersa en columnas sueltas** de la base — deuda técnica; no soporta
|
|
evolución a flujos más complejos sin migrar el esquema entero.
|
|
3. **Sobre-ingeniería prematura** — construir un motor genérico universal para
|
|
casos hipotéticos antes de conocerlos, retrasando el deadline real.
|
|
|
|
## Decisión
|
|
|
|
**La lógica del flujo vive en una capa de definición declarativa (datos),
|
|
interpretada por un motor en el backend, y renderizada por un frontend sin reglas
|
|
de negocio.**
|
|
|
|
Se adopta una **estrategia de dos fases**:
|
|
|
|
### Fase 1 (Sprint 4 — para el deadline)
|
|
- El formulario de cuidadores se define como **esquema declarativo persistido**,
|
|
extendiendo el `conditional_rules` JSONB existente y agregando campos
|
|
declarativos de instanciación a `questions`.
|
|
- Se construye un motor de resolución de flujo **para este formulario** (interpreta
|
|
el esquema; calcula qué pantalla sigue desde esquema + estado).
|
|
- El frontend wizard es un **renderer** del esquema, sin reglas de negocio.
|
|
- NO se construye el intérprete genérico universal todavía.
|
|
|
|
### Fase 2 (sprints posteriores — post-deadline, registrada en BACKLOG)
|
|
- Se extrae el intérprete a un **motor genérico de formularios**.
|
|
- El formulario de cuidadores, ya definido como esquema, se vuelve el primer caso
|
|
de prueba del motor — sin reescribir el contrato.
|
|
|
|
### Diseño técnico del esquema (Fase 1)
|
|
Se extiende `questions` en lugar de crear una tabla de definición separada:
|
|
- `conditional_rules` extendido con nuevos operadores (`not_in`, acción `hide`)
|
|
para expresar saltos como "Ninguno → salta a sección final".
|
|
- Nuevos campos declarativos para instanciación:
|
|
- `instance_generator` — marca la pregunta que genera instancias (ej. 4.1)
|
|
- `instance_of` — código del generador del que depende una pregunta (ej. 4.2 → "4.1")
|
|
- Representación de secciones con nombre y descripción (el "porqué").
|
|
|
|
## Alternativas consideradas
|
|
|
|
1. **Lógica en el frontend (rechazada):** rápida para este formulario, pero viola
|
|
el principio de producto, no escala, y reproduce los bugs de sincronización ya
|
|
vistos en el mockup.
|
|
2. **Columnas sueltas tipo `is_instanced` (rechazada):** resuelve hoy, genera deuda;
|
|
no soporta flujos más complejos sin migración de esquema.
|
|
3. **Motor genérico universal ahora (rechazada):** arquitectónicamente deseable como
|
|
fin, pero sobre-ingeniería antes del deadline y con un solo caso de uso conocido
|
|
(diseñar en el vacío). Se difiere a Fase 2 cuando haya más casos que informen el
|
|
diseño abstracto.
|
|
4. **Tabla de definición de flujo separada (diferida):** posible mejor forma para el
|
|
motor genérico, pero para un solo formulario es sobre-ingeniería. Se reevalúa en
|
|
Fase 2.
|
|
|
|
## Consecuencias
|
|
|
|
**Positivas:**
|
|
- Entrega la encuesta en plazo sin generar retrabajo estructural.
|
|
- La lógica en datos habilita guardado parcial, reanudación, validación consistente
|
|
y progreso preciso — mejor UX, fuente única de verdad del estado.
|
|
- La Fase 2 es generalización del intérprete, no reescritura del contrato.
|
|
- El esquema declarativo es versionable y auditable.
|
|
|
|
**Negativas / deuda intencional:**
|
|
- Fase 1 es más trabajo que parchear el formulario actual.
|
|
- El motor de Fase 1 es específico a este formulario (no genérico) — deuda
|
|
registrada en BACKLOG, asumida conscientemente, no oculta.
|
|
- Extender `conditional_rules` puede requerir reevaluación cuando lleguen flujos
|
|
con lógica que el vocabulario actual de operadores no exprese.
|
|
|
|
## Cumplimiento (cómo se verifica)
|
|
- Revisión de código: el frontend wizard NO contiene reglas de flujo del negocio.
|
|
- El flujo es reproducible desde el esquema persistido.
|
|
- La deuda de Fase 2 figura en `BACKLOG.md`. |