Objectes, estats i custodis: com introduir fluxos de treball genèrics en un projecte existent

· 8 min read

architecture workflows fsm elixir programming design

Also available in: en es ru

L'impuls d'automatitzar processos de negoci rarament apareix el primer dia d'un projecte des de zero. El primer dia tens dues taules a la base de dades, un formulari de registre i la feliç il·lusió que la lògica de negoci sempre cabrà dins de tres funcions netes.

L'impuls arriba dos anys després.

Aleshores, ja tens comptes de clients, cicles de facturació, tiquets de suport, enviaments d'inventari i acords legals. També tens mitja dotzena de «processos» improvisats que viuen com a comentaris dins d'accions de controladors, processos en segon pla perduts comprovant indicadors booleans en bucles de cron i missatges enutjats a Slack demanant per què s'ha reemborsat una factura abans que ningú donés el vistiplau a la devolució.

La direcció té una petició senzilla: «Ens calen fluxos de treball» .

En aquesta cruïlla, els equips d'enginyeria acostumen a cometre un d'aquests dos errors catastròfics:

  1. La infecció ad hoc : Afegeixen una columna artesanal workflow_status i un grapat de sentències condicionals case a cada model existent. En tres esprints, cinc equips independents han implementat cinc maneres incompatibles de moure registres, enviar correus electrònics i verificar permisos.
  2. L'invasor pesant: Compren o despleguen un orquestrador BPMN corporatiu o un motor de microserveis que exigeix que cada objecte de domini se serialitzi en càrregues útils genèriques de JSON i es canalitzi a través d'un entorn d'execució extern i aliè.

Hi ha una tercera via: introduir una maquinària de fluxos de treball lleugera, genèrica i agnòstica directament al vostre projecte existent. Respecta els vostres models de domini actuals, imposa transicions d'estat estrictes, classifica l'accés mitjançant custòdia ( stewardship ), notifica les persones adequades sense codificar llistes de destinataris al codi i utilitza plantilles perquè afegir el vostre vintè flux de treball sigui tan agradable i predictible com afegir el primer.

Vet aquí el plànol de disseny.


Els quatre pilars de la maquinària agnòstica

Un motor de fluxos de treball genèric no necessita pas saber què és en realitat una factura, una petició de canvis ( pull request ) o el reemborsament d'un client. Només ha d'entendre quatre conceptes ortogonals:

flowchart LR
    Subject["Objecte(s) vinculat(s)\n(Realitat de domini)"] --- Engine["Maquinària de flux\n(Nucli agnòstic)"]
    Topology["Estats i transicions\n(Topologia discreta)"] --- Engine
    Stewardship["Custòdia (Stewardship)\n(Accés classificat)"] --- Engine
    TWIMC["Notificacions TWIMC\n(Difusió desacoblada)"] --- Engine

① Objectes vinculats: subjectar la corretja, no les dades

La pitjor errada arquitectònica és permetre que el motor de fluxos de treball devori o dupliqui el model de domini. Una Invoice (factura) pertany al vostre context de facturació. Un Contract (contracte) pertany al vostre context legal.

La instància del flux de treball simplement es vincula a l'objecte de domini mitjançant un identificador polimòrfic:

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

L'objecte de domini és el subjecte ( subject ). La instància del flux de treball és el governador ( governor ).

El flux de treball subjecta la corretja: sap on és el subjecte en el seu cicle de vida, però no li dicta pas el seu esquema de base de dades. Si un procés coordina múltiples objectes —posem per cas, una Order (comanda) i tres registres Shipment (enviament)—, el subjecte principal roman com a àncora, mentre que els identificadors de les entitats relacionades viatgen dins de la càrrega útil del context transitori del flux de treball.

② Estats intermedis: coordenades discretes

Un flux de treball no és un continu nebulós; és un graf finit. Entre el moment en què neix una petició i el moment en què conclou, ocupa exactament un estat discret en qualsevol segon donat.

Les transicions entre estats han de ser:

  • Explícites: Només es poden recórrer les arestes declarades al graf.
  • Atòmiques: El canvi d'estat i qualsevol mutació concomitant del subjecte tenen èxit o fracassen plegats dins d'una única transacció de base de dades.
  • Validades: El motor rebutja qualsevol esdeveniment que no coincideixi amb la coordenada actual.

③ Custòdia ( Stewardship ): autorització contextual

Els permisos de gra gruixut (com ara user.role == :admin ) s'ensorren tan bon punt entren en escena els fluxos de treball humans reals. Qui té permís per aprovar un informe de despeses? L'autor no pot aprovar el seu propi informe. El cap de departament pot aprovar fins a 5.000 $. El departament legal ha de donar el vistiplau si afecta el compliment normatiu internacional.

En diem Custòdia ( Stewardship ): accés classificat i regulat per la relació de l'actor amb el subjecte i la transició específica que s'intenta dur a terme.

Sota la custòdia, una acció no s'autoritza pas mitjançant un rol global estàtic, sinó avaluant tres variables:

  • L'Actor: Qui truca a la porta?
  • La Transició: Quina aresta vol creuar?
  • El Context del Subjecte: Quin és el mandat de l'actor respecte a aquest objecte específic en aquest estat específic?

Una transició declara la seva política de custòdia requerida: :author , :designated_reviewer , :finance_steward o :system_automation . Si l'actor no supera la comprovació de custòdia, la transició es rebutja a la porta abans que s'executi cap línia de codi de negoci.

④ Notificacions TWIMC: To Whom It May Concern (A qui correspongui)

En bases de codi degradades, la lògica de notificació està escampada per tota la capa d'aplicació:

# El camí cap al deliri:
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 nou requisit afegeix una altra línia d'efectes secundaris embullats. Si una notificació falla, es fa enrere la transacció? Ves a saber.

En una maquinària de fluxos de treball genèrica, les transicions emeten un esdeveniment estandarditzat:

%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 despatxador TWIMC dedicat captura aquest esdeveniment de manera asíncrona. Consulta les regles de notificació declarades per a aquella transició, resol la llista de destinataris dinàmicament (per exemple, l'autor del subjecte, els assignats actuals o un webhook extern) i despatxa les alertes.

La lògica de transició roman impol·luta i centrada exclusivament en la validació d'estats.


Plantilles de flux de treball: un escut contra el caos

Si a cada desenvolupador se li permet teixir canonades artesanals de màquines d'estats, el vostre sistema degenerarà ràpidament en una bardissa immantenible de patrons en conflicte.

L'antídot són les Plantilles de flux de treball : especificacions declaratives que defineixen el contracte sencer d'un procés en un únic indret.

Una plantilla especifica:

  1. Subjecte de destí: A quin tipus d'objecte de domini es vincula aquest flux de treball.
  2. Estats i transicions: La topologia permesa del cicle de vida.
  3. Regles de custòdia: Quins actors poden disparar cada transició.
  4. Ganxos TWIMC: A qui es notifica quan ocorre una transició.
  5. Accions amb efectes secundaris: Retorns de crida ( callbacks ) automàtics que s'executen un cop assolida una transició amb èxit.

Vet aquí com llueix una plantilla declarativa a la pràctica:

defmodule MyApp.Workflows.Templates.ExpenseReport do
  use MyApp.Workflow.Template,
    subject: MyApp.Expenses.Report,
    initial: :draft

  # Topologia d'estats
  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

Fixeu-vos en el que acaba de passar:

  • No ha calgut cap migració de base de dades per inventar un nou procés.
  • Els estats, les transicions, les regles de seguretat i les polítiques de comunicació es veuen d'un sol cop d'ull.
  • La lògica de negoci per liquidar pagaments o revisar està netament aïllada en mòduls independents d'acció i de polítiques.

El cicle d'execució

Quan un actor intenta fer avançar un procés, el motor genèric executa una seqüència 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 l'estat permet l'esdeveniment (:pending_review -> :approved)
    Engine->>Policy: check_stewardship(actor, transition, subject)
    alt No autoritzat
        Policy-->>Engine: {:error, :unauthorized}
        Engine-->>User: {:error, :forbidden}
    else Autoritzat
        Policy-->>Engine: :ok
        rect rgb(240, 245, 255)
            Note over Engine,Subject: Transacció atòmica
            Engine->>Subject: Aplicar efectes secundaris / validacions de transició
            Engine->>Engine: Actualitzar current_state = :approved
        end
        Engine->>Bus: publish_transition(transition_payload)
        Bus-->>User: (Asíncron) Notificar a l'autor, custodis, Slack
        Engine-->>User: {:ok, updated_instance}
    end

Tota transició segueix exactament el mateix conducte:

  1. Comprovació de topologia: Està permès l'esdeveniment sol·licitat des de l'estat actual?
  2. Porta de custòdia: Té l'actor el mandat legítim per disparar aquesta transició per a aquest subjecte específic?
  3. Execució atòmica: En una única transacció, executar el ganxo sobre el subjecte i actualitzar el registre de la instància del flux de treball (amb bloqueig optimista per evitar condicions de cursa).
  4. Difusió TWIMC: Publicar de manera asíncrona l'esdeveniment de transició per notificar a qui li calgui saber-ho.

Com incorporar-ho a una base de codi existent

No cal pas refer la vostra aplicació per introduir aquesta maquinària. El camí de migració no és invasiu:

  1. Afegiu dues taules: Calen workflow_instances (per rastrejar l'estat, el nom de la plantilla i els IDs polimòrfics dels subjectes) i una taula opcional workflow_logs per al registre d'auditoria. Les vostres taules de negoci existents no s'han de redissenyar.
  2. Construïu el registre: Creeu un registre que associï els identificadors de plantilles (com ara "expense_report" ) amb els seus mòduls de plantilla compilats.
  3. Embolcalleu, no reescriviu: Trieu un procés existent conflictiu, com ara devolucions de comandes o aprovacions de factures. Escriviu-ne una plantilla. Quan es creï una factura, vinculeu-hi una nova instància de flux de treball.
  4. Confieu en l'arnès: Delegueu tot l'avançament d'estats, la comprovació de permisos i les notificacions a WorkflowEngine.advance/4 .

Un cop la maquinària és al seu lloc, crear un nou flux de treball deixa de ser un calvari d'una setmana farcit de migracions d'esquema artesanals i gestors d'esdeveniments espagueti. Definiu una plantilla, hi vinculeu el vostre objecte i deixeu que la maquinària faci la feina feixuga.

Fronteres nítides, custòdia classificada i comunicació automatitzada. Així és com convertiu requisits de negoci caòtics en enginyeria predictible i plaent.