← Все статьи

Диаграмма состояний заказа: переходы, события и запрещённые действия

· 8 мин чтения

Как построить корректную диаграмму состояний для заказа в PlantUML: определить состояния, события, переходы и запрещённые действия. Разбор учебного примера с обработкой исключений, гонки условий и проверкой инвариантов.

Когда менеджер поддержки пытается отменить уже доставленный заказ, а система позволяет это сделать, возникает конфликт данных. Когда склад получает задание на сборку товара, который пользователь только что вернул, логистика ломается. Эти проблемы редко связаны с багом в одном методе; чаще они указывают на отсутствие явной модели жизненного цикла сущности. State machine (машина состояний) — формальный способ зафиксировать, в каких статусах может находиться объект, какие события вызывают смену статуса и какие действия категорически запрещены в каждом состоянии. Без такой модели поведение системы становится непредсказуемым, особенно при параллельных запросах или сбоях сети.

Анатомия модели состояний

Любая state machine состоит из четырёх базовых элементов: состояний (states), событий (events/triggers), переходов (transitions) и действий (actions). Состояние — это устойчивая конфигурация объекта, в которой он ожидает наступления события. Переход определяет, какое событие из какого исходного состояния приводит к целевому состоянию. Действие — побочный эффект, выполняемый при переходе (например, отправка уведомления или изменение записи в базе данных).

Состояние описывает наблюдаемое положение заказа, а действие или событие вызывает переход. Оплата может быть длительным асинхронным процессом; при необходимости модель включает ожидание и неопределённый исход. Paid означает подтверждённую оплату, а Processing — начатое исполнение. Это промежуточные состояния, а не терминальные: из них есть дальнейшие переходы.

Выбор гранулярности состояний

Главная сложность при проектировании — определение правильной глубины детализации. Слишком грубая модель («Активен», «Завершен») скрывает критические промежуточные шаги. Слишком детальная модель (отдельные состояния для каждого клика пользователя) делает диаграмму непригодной для чтения и поддержки.

Практическое правило: состояние должно представлять собой точку принятия решения или стабилизированный результат. Если между двумя точками нет возможности отмены, изменения или внешнего воздействия, они могут быть объединены. В случае заказа естественными точками являются: создание, оплата, передача в исполнение, завершение исполнения, возврат средств. Чем точнее выбраны эти граничные точки, тем проще будет поддерживать логику в коде и объяснять ее бизнес-пользователям.

Учебный пример: жизненный цикл интернет-заказа

Рассмотрим типовой сценарий e-commerce. Заказ проходит следующие стадии: пользователь оформляет заказ, платит, склад собирает товар, курьер доставляет, клиент подтверждает получение. Также возможны ветвления: отмена пользователем, отказ от оплаты, возврат товара.

Ниже приведён код диаграммы в PlantUML. Обратите внимание на использование -> для прямых переходов и <<guard>> для условий. Мы явно указываем, что переход возможен только при выполнении предиката.

@startuml
title Жизненный цикл заказа (учебный пример)

[*] --> Created : create()
Created -> Paid : pay_success()
Created -> Cancelled : cancel_by_user()
Created -> Expired : timeout_24h()

Paid -> Processing : start_fulfillment()
Paid -> RefundPending : refund_request()
Processing -> Shipped : dispatch_parcel()
Processing -> Failed : fulfillment_error()
Shipped -> Delivered : confirm_receipt()
Shipped -> ReturnRequested : return_initiated()
Delivered -> ReturnRequested : return_initiated()
Delivered -> [*] : return_period_expired()
ReturnRequested -> Returned : return_received()
Returned -> RefundPending : request_refund()
RefundPending -> Refunded : refund_confirmed()
RefundPending -> RefundFailed : refund_rejected()
RefundFailed -> RefundPending : retry_refund()
Refunded -> [*]
Cancelled -> [*]
Expired -> [*]
Failed -> RefundPending : request_auto_refund()
@enduml

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

Таблица переходов и инварианты

Диаграмма хорошо подходит для визуального восприятия, но для реализации в коде удобнее использовать таблицу переходов. Таблица явно указывает, какие события разрешены в каждом состоянии и какие инварианты должны быть выполнены перед переходом. Ниже представлена фрагмент таблицы для нашего учебного примера.

Текущее состояние Событие Целевое состояние Инвариант (предусловие) Действие (побочный эффект)
Created pay_success Paid payment_id is not null set paid_at = now()
Created cancel_by_user Cancelled no items reserved in warehouse release stock reservation
Paid start_fulfillment Processing stock available >= order_qty lock inventory units
Processing dispatch_parcel Shipped packing_list generated send tracking number to client
Shipped confirm_receipt Delivered delivery_date <= expected_max close financial transaction

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

Запрещённые действия и инварианты

То, чего нельзя сделать, часто важнее того, что можно. В state machine запрещённые действия определяются отсутствием перехода. Если из состояния Delivered нет стрелки к Paid, значит, такой обратный переход не входит в выбранный договор.

Но запрет в диаграмме — это только логическое ограничение. Реальная защита обеспечивается инвариантами — условиями, которые должны быть истинными в любой момент времени. Примеры инвариантов для заказа:

  • Подтверждённая оплата требует paid_at для Paid, Processing, Shipped, Delivered и достигнутых после оплаты ветвей возврата. Для Created, Cancelled и Expired оно не требуется. Состояния не сравниваются как линейное «или позже»: нужные ветви перечисляются явно.
  • Поле tracking_number должно быть не пустым, если состояние равно Shipped.
  • Сумма возврата не может превышать сумму оплаченного заказа.

Инварианты проверяются перед каждым переходом. Если условие нарушено, переход блокируется с ошибкой. Это отличает robust state machine от простого перечня статусов.

Обработка гонок и идемпотентность

В распределённых системах события могут приходить в неправильном порядке или дублироваться. Например, уведомление об успехе оплаты может прийти дважды, или уведомление о доставке может прийти раньше, чем о сборке. State machine должна быть устойчива к таким ситуациям.

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

Для реализации этого механизма в коде используется проверка текущего статуса перед применением операции. Если запрошенный переход не определён в таблице переходов для текущего статуса, операция отклоняется. Это предотвращает ситуацию, когда поздняя доставка «перекрывает» раннюю отмену.

Сохранение истории переходов

Само состояние — это снапшот. Но для аудита, отладки и восстановления часто нужна полная история. Рекомендуется вести журнал событий (event sourcing) или таблицу переходов, где каждая строка содержит: ID заказа, предыдущее состояние, новое состояние, событие, timestamp, actor (кто инициировал).

Такая история позволяет ответить на вопросы: «Когда именно заказ был оплачен?», «Кто отменил заказ?», «Были ли попытки несанкционированных переходов?». Без этой истории диагностика проблем сводится к чтению логов приложений, что значительно сложнее и ненадёжнее.

Типичные ошибки проектирования

При создании моделей состояний аналитики часто допускают следующие ошибки:

  • Состояния-действия. Использование глаголов в названиях состояний («Оплата», «Доставка»). Это стирает границу между процессом и результатом.
  • Неявные переходы. Допущение, что некоторые переходы происходят автоматически, без указания триггера. Все переходы должны иметь явное событие.
  • Циклические петли без выхода. Создание замкнутых циклов, из которых невозможно выйти, кроме как через ошибку. Всегда нужны пути завершения или отмены.
  • Игнорирование таймеров. Многие состояния имеют временну́ю составляющую (например, «ожидание оплаты 24 часа»). Таймеры должны быть явными событиями (timeout), а не неявными свойствами.
  • Смешение уровней абстракции. Одновременное описание технических статусов базы данных и бизнес-статусов для клиента. Лучше разделить: внутренняя state machine сервиса и внешний контракт API.

Проверка полноты модели

Как убедиться, что диаграмма полна? Проведите анализ покрытия: для каждого состояния перечислите все возможные входящие и исходящие события. Проверьте, что для каждого события существует хотя бы один допустимый переход из любого возможного состояния (или явный отказ). Используйте матрицу переходов (state transition table), где строки — состояния, столбцы — события, ячейки — целевые состояния или «-» (запрещено).

Также проведите сценарный тест: возьмите набор типововых сценариев (успешный заказ, отмена, возврат, сбой оплаты) и проследите путь по диаграмме. Если в каком-то сценарии путь обрывается или требует невозможного перехода, модель неполна.

Инструменты и хранение

PlantUML — удобный формат для описания таких диаграмм, так как он компактен, поддерживается version control и легко рендерится в Markdown. Диаграмму рекомендуется хранить в репозитории рядом с кодом сервиса, который использует эту модель. Изменения в диаграмме должны проходить тот же ревью-процесс, что и изменения в коде.

Для сложных систем с множеством взаимодействующих state machines (например, заказ, платеж, доставка) полезно создавать отдельные диаграммы для каждого компонента и общую диаграмму взаимодействия (sequence diagram), показывающую, как события передаются между машинами.

Итог

State machine для заказа — это не просто картинка со стрелками. Это формальная спецификация допустимых операций, которая защищает данные от несогласованных изменений. Правильно построенная модель с явными событиями, инвариантами и историей переходов снижает количество дефектов, связанных с управлением статусами, и упрощает поддержку системы. Начните с определения стабильных состояний, затем добавьте события и переходы, и наконец — защитные механизмы против гонок и дублей.

Вы можете создать такую диаграмму в редакторе PlantUML и включить её в вашу документацию. Более широкий контекст применения UML в работе аналитика описан в статье «UML для аналитиков».