Объекты, состояния и смотрители: внедрение обобщенного механизма воркфлоу в существующий проект
· 6 min read
architecture workflows fsm elixir programming design
Желание автоматизировать бизнес-процессы редко посещает разработчиков в первый день проекта с чистого листа. В первый день у вас есть две таблицы в базе данных, форма регистрации и благодушная иллюзия, будто бизнес-логика всегда будет аккуратно укладываться в три чистые функции.
Это желание настигает вас два года спустя.
К этому моменту у вас появляются клиентские аккаунты, биллинговые циклы, тикеты службы поддержки, складские отправления и юридические соглашения. А ещё — полдюжины самопальных «процессов», оформленных в виде комментариев внутри действий контроллера, неприкаянные фоновые воркеры, проверяющие булевы флаги в кроне, и гневные сообщения в Slack с вопросом, почему возврат средств по инвойсу был отправлен до того, как кто-либо подписал акт возврата.
У руководства простая просьба: «Нам нужны воркфлоу» .
На этой развилке инженерные команды обычно совершают одну из двух катастрофических ошибок:
-
Кустарная инфекция:
В каждую существующую модель втыкается доморощенная колонка
workflow_statusи горсть условных операторовcase. Через три спринта пять независимых команд изобретают пять несовместимых способов перемещать записи, слать имейлы и проверять права доступа. - Тяжеловесный захватчик: Покупается или разворачивается монструозный 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) : декларативные спецификации, определяющие весь контракт процесса в одном месте.
Шаблон задаёт:
- Целевой субъект: К какому типу доменных объектов привязывается воркфлоу.
- Состояния и переходы: Допустимую топологию жизненного цикла.
- Правила стюардшипа: Какие акторы правомочны инициировать каждый переход.
- Хуки TWIMC: Кого уведомлять при совершении перехода.
- Действия с побочными эффектами: Автоматические коллбэки, выполняемые при успешном переходе.
Вот как выглядит декларативный шаблон на практике:
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
Каждый переход проходит через один и тот же конвейер:
- Проверка топологии: Допустимо ли запрашиваемое событие из текущего состояния?
- Барьер стюардшипа: Обладает ли актор легитимным мандатом на запуск этого перехода для данного конкретного субъекта?
- Атомарное выполнение: В рамках единой транзакции выполнить хук субъекта и обновить запись инстанса воркфлоу (с оптимистической блокировкой для исключения гонок).
- Вещание TWIMC: Асинхронно опубликовать событие перехода, чтобы оповестить всех заинтересованных лиц.
Внедрение в существующую кодовую базу
Вам не нужно переписывать всё приложение заново, чтобы внедрить этот механизм. Путь миграции абсолютно неинвазивен:
-
Добавьте две таблицы:
Потребуется
workflow_instances(для отслеживания состояния, имени шаблона и полиморфных идентификаторов субъекта) и опциональная таблицаworkflow_logsдля журнала аудита. Существующие бизнес-таблицы трогать не придётся. -
Создайте реестр:
Заведите реестр, сопоставляющий строковые идентификаторы шаблонов (например,
"expense_report") со скомпилированными модулями шаблонов. - Оборачивайте, а не переписывайте: Выберите один наболевший бизнес-процесс — скажем, возврат заказов или согласование счетов. Напишите для него шаблон. При создании счета привязывайте к нему новый экземпляр воркфлоу.
-
Положитесь на каркас:
Делегируйте продвижение по состояниям, проверку полномочий и уведомления вызову
WorkflowEngine.advance/4.
Когда каркас готов, создание очередного воркфлоу перестаёт быть недельной пыткой с изобретением ad-hoc миграций и спагетти из обработчиков событий. Вы объявляете шаблон, привязываете объект — и позволяете механизму взять рутину на себя.
Чёткие границы, классифицированный стюардшип и автоматизированные коммуникации. Именно так хаотичные требования бизнеса превращаются в предсказуемый и приносящий удовольствие инженерный процесс.