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

Also available in: ca en ru

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:

  1. La infección ad hoc : Añaden una columna artesanal workflow_status y un puñado de sentencias condicionales case a cada modelo existente. En tres sprints, cinco equipos independientes han implementado cinco formas incompatibles de mover registros, enviar correos electrónicos y verificar permisos.
  2. 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:

  1. Sujeto de destino: A qué tipo de objeto de dominio se vincula este flujo de trabajo.
  2. Estados y transiciones: La topología permitida del ciclo de vida.
  3. Reglas de custodia: Qué actores pueden disparar cada transición.
  4. Ganchos TWIMC: A quién se notifica cuando ocurre una transición.
  5. 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:

  1. Comprobación de topología: ¿Está permitido el evento solicitado desde el estado actual?
  2. Puerta de custodia: ¿Tiene el actor el mandato legítimo para disparar esta transición sobre este sujeto específico?
  3. 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).
  4. 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:

  1. 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 opcional workflow_logs para pistas de auditoría. Tus tablas de negocio existentes no necesitan ser rediseñadas.
  2. Construye el registro: Crea un registro que asocie los identificadores de plantillas (por ejemplo, "expense_report" ) con sus módulos de plantilla compilados.
  3. 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.
  4. 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.