Objetos, estados y custodios: cómo introducir flujos de trabajo genéricos en un proyecto existente
· 8 min read
architecture workflows fsm elixir programming design
El impulso de automatizar procesos de negocio rara vez surge el primer día de un proyecto desde cero. El primer día tienes dos tablas en la base de datos, un formulario de registro y la placentera ilusión de que la lógica de negocio siempre cabrá en tres funciones limpias.
El impulso llega dos años después.
Para entonces, ya tienes cuentas de clientes, ejecuciones de facturación, tiques de soporte, envíos de inventario y acuerdos legales. También tienes media docena de «procesos» improvisados viviendo como comentarios dentro de acciones de controladores, tareas en segundo plano perdidas comprobando indicadores booleanos en bucles de cron y mensajes airados en Slack preguntando por qué se reembolsó una factura antes de que nadie diera el visto bueno a la devolución.
La dirección tiene una petición simple: «Necesitamos flujos de trabajo» .
En esta encrucijada, los equipos de ingeniería suelen cometer uno de estos dos errores catastróficos:
-
La infección
ad hoc
:
Añaden una columna artesanal
workflow_statusy un puñado de sentencias condicionalescasea cada modelo existente. En tres sprints, cinco equipos independientes han implementado cinco formas incompatibles de mover registros, enviar correos electrónicos y verificar permisos. - El invasor pesado: Compran o despliegan un orquestador BPMN empresarial o un motor de microservicios que exige que cada objeto de dominio se serialice en cargas útiles genéricas de JSON y se canalice a través de un entorno de ejecución externo y ajeno.
Existe una tercera vía: introducir una maquinaria de flujos de trabajo ligera, genérica y agnóstica directamente en tu proyecto existente. Respeta tus modelos de dominio actuales, impone transiciones de estado estrictas, clasifica el acceso mediante custodia ( stewardship ), notifica a las personas adecuadas sin codificar listas de destinatarios a fuego y utiliza plantillas para que añadir tu vigésimo flujo de trabajo sea tan agradable y predecible como añadir el primero.
He aquí el plano de diseño.
Los cuatro pilares de la maquinaria agnóstica
Un motor de flujos de trabajo genérico no necesita saber qué es en realidad una factura, una solicitud de cambios ( pull request ) o el reembolso de un cliente. Solo necesita entender cuatro conceptos ortogonales:
flowchart LR
Subject["Objeto(s) vinculado(s)\n(Realidad de dominio)"] --- Engine["Maquinaria de flujo\n(Núcleo agnóstico)"]
Topology["Estados y transiciones\n(Topología discreta)"] --- Engine
Stewardship["Custodia (Stewardship)\n(Acceso clasificado)"] --- Engine
TWIMC["Notificaciones TWIMC\n(Difusión desacoplada)"] --- Engine
① Objetos vinculados: sujetar la correa, no los datos
El mayor despropósito arquitectónico es permitir que el motor de flujos de trabajo devore o duplique el modelo de dominio. Una
Invoice
(factura) pertenece a tu contexto de facturación. Un
Contract
(contrato) pertenece a tu contexto legal.
La instancia del flujo de trabajo simplemente se vincula al objeto de dominio mediante un identificador polimórfico:
schema "workflow_instances" do
field :template, :string
field :current_state, :string
field :subject_type, :string
field :subject_id, :string
field :context, :map, default: %{}
field :lock_version, :integer, default: 1
timestamps()
end
El objeto de dominio es el sujeto ( subject ). La instancia del flujo de trabajo es el gobernador ( governor ).
El flujo de trabajo sujeta la correa: sabe
dónde
está el sujeto en su ciclo de vida, pero no le dicta su esquema de base de datos. Si un proceso coordina múltiples objetos —digamos, un
Order
(pedido) y tres registros
Shipment
(envío)—, el sujeto principal permanece como ancla, mientras que los identificadores de las entidades relacionadas viajan dentro de la carga útil del
context
transitorio del flujo de trabajo.
② Estados intermedios: coordenadas discretas
Un flujo de trabajo no es un continuo nebuloso; es un grafo finito. Entre el momento en que nace una solicitud y el momento en que concluye, ocupa exactamente un estado discreto en cualquier segundo dado.
Las transiciones entre estados deben ser:
- Explícitas: Solo se pueden recorrer las aristas declaradas en el grafo.
- Atómicas: El cambio de estado y cualquier mutación concomitante del sujeto triunfan o fracasan juntos dentro de una única transacción de base de datos.
- Validadas: El motor rechaza cualquier evento que no encaje con la coordenada actual.
③ Custodia ( Stewardship ): autorización contextual
Los permisos de grano grueso (como
user.role == :admin
) se desmoronan en cuanto entran en escena los flujos de trabajo humanos reales. ¿Quién tiene permiso para aprobar un informe de gastos? El autor no puede aprobar su propio informe. El jefe de departamento puede aprobar hasta 5.000 $. El departamento legal debe dar su visto bueno si afecta al cumplimiento normativo internacional.
Llamamos a esto Custodia ( Stewardship ): acceso clasificado y regulado por la relación del actor con el sujeto y la transición específica que se intenta realizar.
Bajo la custodia, una acción no se autoriza mediante un rol global estático, sino evaluando tres variables:
- El Actor: ¿Quién llama a la puerta?
- La Transición: ¿Qué arista intenta cruzar?
- El Contexto del Sujeto: ¿Cuál es el mandato del actor con respecto a este objeto específico en este estado específico?
Una transición declara su política de custodia requerida:
:author
,
:designated_reviewer
,
:finance_steward
o
:system_automation
. Si el actor no supera la comprobación de custodia, la transición se rechaza en la puerta antes de que se ejecute una sola línea de código de negocio.
④ Notificaciones TWIMC: To Whom It May Concern (A quien corresponda)
En bases de código degradadas, la lógica de notificación está dispersa por toda la capa de aplicación:
# El camino hacia la locura:
def approve_invoice(invoice, user) do
Invoice.mark_approved!(invoice)
Mailer.send_to_vendor(invoice)
Mailer.send_to_accounting(invoice)
Slack.notify("#finance", "Approved!")
end
Cada nuevo requisito añade otra línea de efectos secundarios enmarañados. Si una notificación falla, ¿se revierte la transacción? Vete a saber.
En una maquinaria de flujos de trabajo genérica, las transiciones emiten un evento estandarizado:
%TransitionEvent{
workflow_id: "wf_9812",
subject: %Invoice{id: 42},
from_state: :pending_review,
to_state: :approved,
event: :approve,
actor: %User{id: 7, role: :manager},
timestamp: ~U[2026-10-21 14:00:00Z]
}
Un despachador TWIMC dedicado captura este evento de forma asíncrona. Consulta las reglas de notificación declaradas para esa transición, resuelve la lista de destinatarios dinámicamente (por ejemplo, el autor del sujeto, los asignados actuales o un webhook externo) y despacha las alertas.
La lógica de transición permanece impoluta y centrada exclusivamente en la validación de estados.
Plantillas de flujo de trabajo: un escudo contra el caos
Si a cada desarrollador se le permite tejer cañerías artesanales de máquinas de estados, tu sistema degenerará rápidamente en una maraña inmantenible de patrones en conflicto.
El antídoto son las Plantillas de flujo de trabajo : especificaciones declarativas que definen el contrato completo de un proceso en un único lugar.
Una plantilla especifica:
- Sujeto de destino: A qué tipo de objeto de dominio se vincula este flujo de trabajo.
- Estados y transiciones: La topología permitida del ciclo de vida.
- Reglas de custodia: Qué actores pueden disparar cada transición.
- Ganchos TWIMC: A quién se notifica cuando ocurre una transición.
- Acciones con efectos secundarios: Devoluciones de llamada ( callbacks ) automáticas que se ejecutan tras transiciones exitosas.
He aquí cómo luce una plantilla declarativa en la práctica:
defmodule MyApp.Workflows.Templates.ExpenseReport do
use MyApp.Workflow.Template,
subject: MyApp.Expenses.Report,
initial: :draft
# Topología de estados
transition :submit, from: :draft, to: :pending_review do
stewardship :author_only
notify :stewards, role: :department_manager
end
transition :approve, from: :pending_review, to: :approved do
stewardship MyApp.Expenses.Stewardship.ReviewerPolicy
action MyApp.Expenses.Actions.SchedulePayment
notify :author
notify :channel, target: "#finance-approvals"
end
transition :reject, from: :pending_review, to: :rejected do
stewardship MyApp.Expenses.Stewardship.ReviewerPolicy
notify :author, template: "expense_rejected"
end
transition :payout, from: :approved, to: :settled do
stewardship :system_automation
notify :author
end
end
Fíjate en lo que acaba de suceder:
- No fue necesaria ninguna migración de base de datos para inventar un nuevo proceso.
- Los estados, las transiciones, las reglas de seguridad y las políticas de comunicación están a la vista de un solo vistazo.
- La lógica de negocio para liquidar pagos o revisar está limpiamente aislada en módulos independientes de acción y políticas.
El ciclo de ejecución
Cuando un actor intenta hacer avanzar un proceso, el motor genérico ejecuta una secuencia disciplinada:
sequenceDiagram
autonumber
actor User as Actor
participant Engine as Workflow Engine
participant Policy as Stewardship Policy
participant Subject as Attached Object (DB)
participant Bus as TWIMC Bus
User->>Engine: advance(instance_id, :approve, actor, params)
Engine->>Engine: Verificar que el estado permite el evento (:pending_review -> :approved)
Engine->>Policy: check_stewardship(actor, transition, subject)
alt No autorizado
Policy-->>Engine: {:error, :unauthorized}
Engine-->>User: {:error, :forbidden}
else Autorizado
Policy-->>Engine: :ok
rect rgb(240, 245, 255)
Note over Engine,Subject: Transacción atómica
Engine->>Subject: Aplicar efectos secundarios / validaciones de transición
Engine->>Engine: Actualizar current_state = :approved
end
Engine->>Bus: publish_transition(transition_payload)
Bus-->>User: (Asíncrono) Notificar a autor, custodios, Slack
Engine-->>User: {:ok, updated_instance}
end
Toda transición sigue exactamente el mismo cauce:
- Comprobación de topología: ¿Está permitido el evento solicitado desde el estado actual?
- Puerta de custodia: ¿Tiene el actor el mandato legítimo para disparar esta transición sobre este sujeto específico?
- Ejecución atómica: En una única transacción, ejecutar el gancho sobre el sujeto y actualizar el registro de la instancia del flujo de trabajo (con bloqueo optimista para prevenir condiciones de carrera).
- Difusión TWIMC: Publicar asíncronamente el evento de transición para notificar a quien deba saberlo.
Cómo incorporarlo a una base de código existente
No necesitas reconstruir tu aplicación para introducir esta maquinaria. La ruta de migración no es invasiva:
-
Añade dos tablas:
Necesitas
workflow_instances(para rastrear el estado, el nombre de la plantilla y los IDs polimórficos de los sujetos) y una tabla opcionalworkflow_logspara pistas de auditoría. Tus tablas de negocio existentes no necesitan ser rediseñadas. -
Construye el registro:
Crea un registro que asocie los identificadores de plantillas (por ejemplo,
"expense_report") con sus módulos de plantilla compilados. - Envuelve, no reescribas: Elige un proceso existente problemático, como devoluciones de pedidos o aprobación de facturas. Escribe una plantilla para él. Cuando se cree una factura, vincúlale una nueva instancia de flujo de trabajo.
-
Apóyate en el arnés:
Delega todo el avance de estados, la comprobación de permisos y las notificaciones a
WorkflowEngine.advance/4.
Una vez que la maquinaria está en su sitio, crear un nuevo flujo de trabajo deja de ser un calvario de una semana repleto de migraciones de esquemas artesanales y manejadores de eventos espagueti. Defines una plantilla, vinculas tu objeto y dejas que la maquinaria haga el trabajo pesado.
Fronteras nítidas, custodia clasificada y comunicación automatizada. Así es como conviertes requisitos de negocio caóticos en ingeniería predecible y placentera.