Documentación del prototipo

Modelo conceptual y arquitectura objetivo

← Mock

Markdown: documentacion.md · Bitácora: bitacora.html · bitacora.md

Propósito

Este prototipo HTML valida el diseño de un gestor de flujos de trabajo antes de implementarlo con Supabase. Separa la definición del flujo (diseñador) de la ejecución (instancias, traza y reporte). El mock sigue vigente; la app Next.js es la fase siguiente.

Menú del mock

Entidades (modelo conceptual)

EntidadDescripción
TipoFlujoCategoría (texto libre en el mock, ej. Aprobación).
FlujoTipo, nombre, descripción, estado (borrador | listo), versión.
ParametroEntradaClave, etiqueta, tipo (texto, numero, fecha, si_no), obligatorio.
Nodo BPMNinicio, manual, automatica, gateway, fin
Sequence FlowOrigen, destino, condición (siempre | aceptar | rechazar)
PantallaUna por User Task
BloquePantallatitulo, texto, dato, comentario; orden definido.
InstanciaCopia del flujo al iniciar, valores de entrada, estado, paso actual.
PasoInstanciaActividad resuelta con decisión y comentario.
TrazaEventos inmutables para auditoría y reporte.

Diagrama entidad-relación (referencia Supabase)

TipoFlujo 1 —— * Flujo
Flujo 1 —— * ParametroEntrada
Flujo 1 —— * Nodo
Flujo 1 —— * Transicion
Nodo * —— * ParametroEntrada  (UsoDato)
Nodo 1 —— 0..1 Pantalla  (solo actividad manual)
Pantalla 1 —— * BloquePantalla
ParametroEntrada 1 —— * BloquePantalla  (bloques tipo dato)
Flujo 1 —— * Instancia
Instancia 1 —— * PasoInstancia
Nodo 1 —— * PasoInstancia
Instancia 1 —— * Traza

Tablas sugeridas (implementación futura)

flujo.flujos (id, tipo, nombre, descripcion, estado, version, created_at)
flujo.parametros_entrada (id, flujo_id, clave, etiqueta, tipo, obligatorio)
flujo.nodos (id, flujo_id, kind, nombre, descripcion, pos_x, pos_y)
flujo.nodo_parametros (nodo_id, parametro_id)
flujo.transiciones (id, flujo_id, from_nodo_id, to_nodo_id, condicion)
flujo.pantallas (id, nodo_id)
flujo.bloques_pantalla (id, pantalla_id, orden, tipo, texto, parametro_id)
ejecucion.instancias (id, flujo_id, flujo_snapshot jsonb, estado, input_values jsonb, current_nodo_id, started_at, finished_at, created_by)
ejecucion.pasos_instancia (id, instancia_id, nodo_id, estado, comentario, at)
ejecucion.trazas (id, instancia_id, tipo, mensaje, decision, comentario, data_shown jsonb, at)

Persistencia del mock

Claves localStorage: gestor_flujos_prototipo_v2 (datos) y gestor_flujos_theme_v1 (tema). Ejemplo «Aprobación de gasto» con User Task → Exclusive Gateway.

Procedimiento de versionado del mock

Subconjunto BPMN 2.0

Arquitectura objetivo (implementación futura)

Tres capas; la implementación arranca contra Supabase local (Docker), no contra la nube.

Presentación — Next.js, React 19, App Router, Server Components, Tailwind CSS, responsive, idiomas ES / EN / PT. Pantallas equivalentes al mock (diseñador con pantallas manuales, gestión, reporte).
Negocio (API First) — API Routes de Next.js; reglas en validation y motor del prototipo; validación Zod. Auth productiva por definir (Supabase Auth vs NextAuth/Azure AD — alinear con supabase-hooks.mdc al implementar).
Datos — Postgres vía Supabase CLI (supabase start); schemas flujo y ejecucion; RLS en migraciones; cloud después con el mismo historial.
Mock HTML (actual) → Implementación → Supabase local + migraciones → Supabase Cloud

Migraciones

Esquema y políticas solo en supabase/migrations (supabase migration new). No editar el Studio como fuente de verdad.

Anexo — Checklist Supabase (fase futura)

  1. Migración en Git antes de cualquier DDL.
  2. npx supabase migration new → validar → npx supabase db push en DESA.
  3. Regenerar lib/supabase/types.ts y correr npm run verify.
  4. No DDL en stage/prod desde el IDE; merge + deploy.

Detalle completo: regla Cursor supabase-migrations.mdc. Setup: docs/setup/supabase-setup.md (a crear).

Fuera de alcance (fase mock actual)