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: catálogo, lienzo, parámetros de entrada, conexiones y pantallas de actividades manuales.
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), versión.
ParametroEntrada	Clave, etiqueta, tipo (texto, numero, fecha, si_no), obligatorio.
Nodo	inicio \| manual \| automatica \| fin; posición; datos que consume.
Transicion	Origen, destino, condición (siempre \| aceptar \| rechazar).
Pantalla	Una por actividad manual.
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

Clave localStorage: gestor_flujos_prototipo_v1. Incluye un flujo de ejemplo «Aprobación de gasto» listo para instanciar.

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; Supabase Auth en la app productiva.

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, supabase db reset). No editar el Studio como fuente de verdad.

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).