Объекты, состояния и смотрители: внедрение обобщенного механизма воркфлоу в существующий проект

· 6 min read

architecture workflows fsm elixir programming design

Also available in: ca en es

Желание автоматизировать бизнес-процессы редко посещает разработчиков в первый день проекта с чистого листа. В первый день у вас есть две таблицы в базе данных, форма регистрации и благодушная иллюзия, будто бизнес-логика всегда будет аккуратно укладываться в три чистые функции.

Это желание настигает вас два года спустя.

К этому моменту у вас появляются клиентские аккаунты, биллинговые циклы, тикеты службы поддержки, складские отправления и юридические соглашения. А ещё — полдюжины самопальных «процессов», оформленных в виде комментариев внутри действий контроллера, неприкаянные фоновые воркеры, проверяющие булевы флаги в кроне, и гневные сообщения в Slack с вопросом, почему возврат средств по инвойсу был отправлен до того, как кто-либо подписал акт возврата.

У руководства простая просьба: «Нам нужны воркфлоу» .

На этой развилке инженерные команды обычно совершают одну из двух катастрофических ошибок:

  1. Кустарная инфекция: В каждую существующую модель втыкается доморощенная колонка workflow_status и горсть условных операторов case . Через три спринта пять независимых команд изобретают пять несовместимых способов перемещать записи, слать имейлы и проверять права доступа.
  2. Тяжеловесный захватчик: Покупается или разворачивается монструозный enterprise-оркестратор BPMN или микросервисный движок, требующий сериализации каждого доменного объекта в generic-JSON и прогона через чужеродный внешний рантайм.

Существует третий путь: внедрение легковесного, обобщенного и агностического механизма воркфлоу непосредственно в ваш существующий проект. Он уважает ваши текущие доменные модели, форсирует строгие переходы между состояниями, классифицирует доступ через стюардшип (смотрительство), уведомляет нужных участников без хардкода списков адресатов и использует шаблоны, благодаря чему добавление двадцатого по счёту воркфлоу оказывается столь же приятным и предсказуемым, как и создание самого первого.

Вот его архитектурный чертёж.


Четыре столпа агностического механизма

Обобщенному движку воркфлоу совершенно ни к чему знать, чем на самом деле является инвойс, пулл-реквест или возврат средств клиенту. Ему требуется понимать лишь четыре ортогональные концепции:

flowchart LR
    Subject["Привязанный объект(ы)\n(Доменная реальность)"] --- Engine["Механизм воркфлоу\n(Агностическое ядро)"]
    Topology["Состояния и переходы\n(Дискретная топология)"] --- Engine
    Stewardship["Смотрительство / Стюардшип\n(Классифицированный доступ)"] --- Engine
    TWIMC["Уведомления TWIMC\n(Слабосвязанное вещание)"] --- Engine

① Привязанные объекты: держать поводок, а не данные

Главный архитектурный провал — позволить движку воркфлоу поглотить или дублировать доменную модель. Модель Invoice (инвойс) принадлежит контексту биллинга. Модель Contract (договор) принадлежит юридическому контексту.

Экземпляр воркфлоу просто привязывается к доменному объекту через полиморфный дескриптор:

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

Доменный объект выступает субъектом ( subject ). Экземпляр воркфлоу выступает управляющим ( governor ).

Воркфлоу держит поводок: он знает, где находится субъект в своём жизненном цикле, но не навязывает ему схему базы данных. Если процесс координирует несколько объектов — например, заказ Order и три связанные записи доставки Shipment — главный субъект остаётся якорем, а идентификаторы связанных сущностей передаются внутри транзитного context -пейлоада воркфлоу.

② Промежуточные состояния: дискретные координаты

Воркфлоу — это не туманный континуум, а конечный граф. Между моментом зарождения запроса и моментом его завершения он в любую секунду занимает ровно одну дискретную координату.

Переходы между состояниями обязаны быть:

  • Явными: Движение возможно только по декларированным рёбрам графа.
  • Атомарными: Смена состояния и любые сопутствующие мутации субъекта фиксируются либо откатываются строго вместе в рамках единой транзакции БД.
  • Валидируемыми: Движок отвергает любое событие, не соответствующее текущей координате.

③ Смотрительство ( Stewardship ): контекстная авторизация

Грубые роли (вроде user.role == :admin ) рассыпаются в прах, как только начинаются реальные человеческие процессы. Кому дозволено утвердить отчет о расходах? Автор не имеет права утверждать свой собственный отчет. Руководитель отдела может утверждать суммы до $5,000. Юридический отдел обязан поставить визу, если затронут международный комплаенс.

Мы называем это Стюардшипом (смотрительством, Stewardship ): доступ классифицируется и регулируется отношением актора к субъекту и конкретному совершаемому переходу.

При стюардшипе действие авторизуется не статической глобальной ролью, а оценкой трех переменных:

  • Актор: Кто стучится в дверь?
  • Переход: Какое ребро графа он пытается пересечь?
  • Контекст субъекта: Каковы полномочия актора относительно данного конкретного объекта в данном конкретном состоянии?

Переход декларирует требуемую политику смотрительства: :author , :designated_reviewer , :finance_steward или :system_automation . Если актор не проходит проверку стюардшипа, переход пресекается на пороге до выполнения какого-либо бизнес-кода.

④ Уведомления TWIMC: To Whom It May Concern («Тем, кого это касается»)

В запущенных кодовых базах логика уведомлений размазана ровным слоем по всему прикладному уровню:

# Дорога в ад:
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

Каждое новое требование добавляет очередную строчку спагетти с сайд-эффектами. Если одно из уведомлений падает с ошибкой, откатывается ли транзакция? Никто не знает.

В обобщенном механизме переходы генерируют стандартизированное событие:

%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]
}

Выделенный диспетчер TWIMC перехватывает это событие асинхронно. Он извлекает правила оповещения, задекларированные для данного перехода, динамически вычисляет список адресатов (например, автора субъекта, текущих ответственных или внешний вебхук) и рассылает уведомления.

Сама логика перехода остаётся кристально чистой и сосредоточенной исключительно на валидации состояний.


Шаблоны воркфлоу: защита от хаоса

Если каждому разработчику позволено вручную говядить трубы конечных автоматов, система стремительно превратится в непроходимые дебри конфликтующих решений.

Противоядие — Шаблоны воркфлоу (Workflow Templates) : декларативные спецификации, определяющие весь контракт процесса в одном месте.

Шаблон задаёт:

  1. Целевой субъект: К какому типу доменных объектов привязывается воркфлоу.
  2. Состояния и переходы: Допустимую топологию жизненного цикла.
  3. Правила стюардшипа: Какие акторы правомочны инициировать каждый переход.
  4. Хуки TWIMC: Кого уведомлять при совершении перехода.
  5. Действия с побочными эффектами: Автоматические коллбэки, выполняемые при успешном переходе.

Вот как выглядит декларативный шаблон на практике:

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

  # Топология состояний
  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

Обратите внимание на то, что произошло:

  • Для добавления нового процесса не потребовалось никаких миграций БД.
  • Состояния, переходы, правила безопасности и политики оповещения видны как на ладони.
  • Бизнес-логика выплат или ревью аккуратно изолирована в независимых модулях действий и политик.

Цикл выполнения

Когда актор пытается продвинуть процесс вперёд, обобщенный движок выполняет строгую последовательность шагов:

sequenceDiagram
    autonumber
    actor User as Актор
    participant Engine as Workflow Engine
    participant Policy as Политика стюардшипа
    participant Subject as Привязанный объект (DB)
    participant Bus as TWIMC Bus

    User->>Engine: advance(instance_id, :approve, actor, params)
    Engine->>Engine: Проверка: допускает ли состояние событие (:pending_review -> :approved)
    Engine->>Policy: check_stewardship(actor, transition, subject)
    alt Доступ запрещён
        Policy-->>Engine: {:error, :unauthorized}
        Engine-->>User: {:error, :forbidden}
    else Авторизован
        Policy-->>Engine: :ok
        rect rgb(240, 245, 255)
            Note over Engine,Subject: Атомарная транзакция
            Engine->>Subject: Применить сайд-эффекты перехода / валидации
            Engine->>Engine: Обновить current_state = :approved
        end
        Engine->>Bus: publish_transition(transition_payload)
        Bus-->>User: (Async) Уведомить автора, стюардов, Slack
        Engine-->>User: {:ok, updated_instance}
    end

Каждый переход проходит через один и тот же конвейер:

  1. Проверка топологии: Допустимо ли запрашиваемое событие из текущего состояния?
  2. Барьер стюардшипа: Обладает ли актор легитимным мандатом на запуск этого перехода для данного конкретного субъекта?
  3. Атомарное выполнение: В рамках единой транзакции выполнить хук субъекта и обновить запись инстанса воркфлоу (с оптимистической блокировкой для исключения гонок).
  4. Вещание TWIMC: Асинхронно опубликовать событие перехода, чтобы оповестить всех заинтересованных лиц.

Внедрение в существующую кодовую базу

Вам не нужно переписывать всё приложение заново, чтобы внедрить этот механизм. Путь миграции абсолютно неинвазивен:

  1. Добавьте две таблицы: Потребуется workflow_instances (для отслеживания состояния, имени шаблона и полиморфных идентификаторов субъекта) и опциональная таблица workflow_logs для журнала аудита. Существующие бизнес-таблицы трогать не придётся.
  2. Создайте реестр: Заведите реестр, сопоставляющий строковые идентификаторы шаблонов (например, "expense_report" ) со скомпилированными модулями шаблонов.
  3. Оборачивайте, а не переписывайте: Выберите один наболевший бизнес-процесс — скажем, возврат заказов или согласование счетов. Напишите для него шаблон. При создании счета привязывайте к нему новый экземпляр воркфлоу.
  4. Положитесь на каркас: Делегируйте продвижение по состояниям, проверку полномочий и уведомления вызову WorkflowEngine.advance/4 .

Когда каркас готов, создание очередного воркфлоу перестаёт быть недельной пыткой с изобретением ad-hoc миграций и спагетти из обработчиков событий. Вы объявляете шаблон, привязываете объект — и позволяете механизму взять рутину на себя.

Чёткие границы, классифицированный стюардшип и автоматизированные коммуникации. Именно так хаотичные требования бизнеса превращаются в предсказуемый и приносящий удовольствие инженерный процесс.