Documentación — Gestor de flujos

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

Diseñador de flujo (BPMN): catálogo con eliminación solo en borrador; Start/User/Service Task, Exclusive Gateway, End Event, Sequence Flow y pantallas en User Task.
Gestión de actividades: instanciar flujos listos, resolver tareas manuales (Aceptar/Rechazar) y ejecutar automáticas.
Reporte: avance, filtros y traza de cada instancia.

Entidades (modelo conceptual)

Entidad	Descripción
TipoFlujo	Categoría (texto libre en el mock, ej. Aprobación).
Flujo	Tipo, nombre, descripción, estado (borrador \| listo \| deprecado), versión al confirmar, lineageId, supersedesFlowId.
ParametroEntrada	Clave, etiqueta, tipo (texto, numero, fecha, si_no), obligatorio.
Nodo BPMN	inicio, manual, automatica, gateway, fin
Sequence Flow	Origen, destino, condición (siempre \| aceptar \| rechazar)
Pantalla	Una por User Task
BloquePantalla	titulo, texto, dato, comentario; orden definido.
Instancia	Copia del flujo al iniciar, valores de entrada, estado, paso actual.
PasoInstancia	Actividad resuelta con decisión y comentario.
Traza	Eventos 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

Mock editable en prototipo/; snapshots congelados en prototipo/versiones/YYYY-MM-DD_HHmm_etiqueta/.
Índice: versiones.html · versiones.md.
Antes de cambios grandes: nuevo snapshot + bitácora; regenerar con build-mock.ps1.
Raíz del repo: ver README.md; reglas de app futura en .cursor/rules/_fase-app/.
SemVer (lib/version.ts) solo aplica con la app Next.js.

Líneas BPMN en el diseñador

Tipo	Ejecuta en Gestión	Notas
Sequence Flow	Sí	Puertos, herramienta o panel Propiedades
Message Flow	No	Solo diagrama
Association	No	Enlace visual

Flujo nuevo: incluye Start y End en el lienzo.

Compuertas: catálogo de siete tipos BPMN en paleta/context pad/propiedades; solo Compuerta Exclusiva activa; demás marcadas Futuro.

Viewport diseñador: teléfono bloqueado («Esto no se puede hacer en tu dispositivo…»); recomendado ≥1024×768; avisos en PC baja resolución y tablet.

UI canvas-first: paneles Elementos y Propiedades cerrados por defecto; toggles en la barra del lienzo (todos los anchos); flyouts en escritorio; al seleccionar nodo se abre Propiedades. Secciones internas colapsables con scroll.

Start/End Event: siempre dentro del pool; pueden estar en lanes distintos.

Estudio: Camino (BPMN), Pantalla (formularios User Task), Automatización (REST/SOAP/GraphQL/conectores); contexto de instancia y trazas de integración.

Context pad: menús siempre horizontales/verticales; en gateway el rombo no inclina el pad.

Lienzo: pool con nombre y títulos de lane verticales; ancho del pool proporcional al viewport; encuadre automático al abrir y al resize; zoom/pan; pantalla completa reajusta la vista.

Subconjunto BPMN 2.0

Start Event — parámetros; salida siempre.
User Task — pantalla; salida siempre al gateway.
Exclusive Gateway — salidas aceptar y rechazar.
Service Task — salida siempre.
End Event — sin salidas.

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 u OIDC/NextAuth).

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)

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

Detalle: migraciones versionadas en Git; setup documentado al iniciar Supabase en un repo de implementación.

Fuera de alcance (fase mock actual)

Proyecto Next.js, Tailwind, i18n, Zod y cliente Supabase.
Docker, supabase init y migraciones hasta pedir implementar.
Asignación por usuario/rol y acciones automáticas reales (email, webhooks).
Diseñador avanzado (zoom, minimapa, historial ilimitado).