Sequence-диаграмма для общего сценария

Когда нужна sequence-диаграмма

Sequence-диаграмма - это один из UML-артефактов, который полезен не сам по себе, а как способ сделать порядок взаимодействий общим для команды.

Sequence-диаграмма полезна, когда команде нужно договориться не просто о том, какие части системы существуют, а о том, в каком порядке они взаимодействуют.

Она помогает, если в задаче есть:

• несколько ролей, сервисов или внешних сторон;
• важный порядок шагов;
• синхронный запрос, очередь, webhook или ручной переход;
• спор о том, кто начинает сценарий;
• неясность, где появляется статус или ошибка;
• риск, что разные участники понимают один сценарий по-разному.

Главная польза диаграммы не в том, чтобы красиво нарисовать стрелки. Польза в том, чтобы команда увидела один общий сценарий и перестала обсуждать разные версии процесса в голове.

Что sequence-диаграмма должна ответить

Хорошая диаграмма отвечает минимум на пять вопросов:

1. Кто участвует в сценарии?
2. Кто начинает взаимодействие?
3. Какие сообщения или действия идут по порядку?
4. Где система ждет ответ, а где продолжает работу асинхронно?
5. Что происходит при ошибке, таймауте, повторе или ручной проверке?

Если диаграмма не помогает ответить на эти вопросы, она может быть аккуратной, но бесполезной.

Перед диаграммой нужна рабочая карта

Не стоит начинать сразу с нотации. Сначала полезно коротко описать систему:

• цель сценария;
• границу задачи;
• участников;
• данные;
• состояния;
• рискованные исключения.

Без этого sequence-диаграмма быстро превращается в набор стрелок без смысла. Команда видит порядок вызовов, но не понимает, какую работу пользователя или процесса этот порядок должен защитить.

Минимальный предварительный блок:

## Сценарий

Зачем он нужен:
Кто получает результат:
Что запускает сценарий:
Что считается успешным завершением:
Что точно не входит:

## Участники

Роль или пользователь:
Наша система:
Внешняя система:
Ручной участник:

## Риски

Где возможна ошибка:
Где нужен повтор:
Где нужна ручная проверка:
Где нельзя терять данные:

После этого диаграмма будет уточнять порядок, а не подменять анализ.

Как перейти от диаграммы к готовности задачи

Sequence-диаграмма полезна не только как схема. Она должна дать сырье для проверки готовности задачи:

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

1. Назвать участников

Участник на диаграмме - это не только сервис.

Им может быть:

• пользователь;
• оператор;
• frontend;
• backend;
• внешний API;
• очередь;
• cron или worker;
• сервис уведомлений;
• ручной процесс;
• поддержка или администратор.

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

Слабый вариант:

Пользователь -> Система -> API

Более полезный вариант:

Клиент -> Форма заявки -> Backend -> Внешняя проверка -> Оператор

Во втором варианте видно, что сценарий не заканчивается API-вызовом. В нем есть пользовательский старт, backend-решение, внешняя зависимость и возможная ручная проверка.

2. Показывать сообщения как действия, а не как технический шум

Стрелка должна объяснять, что передается или запускается.

Не очень полезно:

Backend -> API: request
API -> Backend: response

Лучше:

Backend -> Внешняя проверка: отправляет обезличенные данные заявки
Внешняя проверка -> Backend: возвращает статус проверки и код причины

Так команда сразу видит данные, результат и место, где понадобится обработка статуса.

Если в сообщении нельзя коротко назвать смысл, возможно, команда еще не договорилась о действии.

3. Отделить happy path от исключений

Happy path нужен, но он редко раскрывает главные риски.

После основного сценария стоит добавить минимум три вопроса:

• что будет при ошибке внешней системы;
• что будет при повторном действии пользователя или сервиса;
• что будет, если ответ пришел, но его нельзя автоматически принять.

Удобный формат:

sequenceDiagram
  actor Client as Клиент
  participant App as Наша система
  participant Check as Внешняя проверка
  participant Operator as Оператор

  Client->>App: Отправляет заявку
  App->>Check: Запрашивает проверку данных
  Check-->>App: Возвращает статус проверки

  alt Проверка успешна
    App-->>Client: Показывает следующий шаг
  else Нужна ручная проверка
    App->>Operator: Создает задачу на разбор
    Operator-->>App: Фиксирует решение
    App-->>Client: Показывает результат
  else Внешняя система недоступна
    App-->>Client: Показывает статус ожидания
    App->>App: Планирует повторную проверку
  end

Даже если команда не использует Mermaid, такая текстовая диаграмма помогает договориться о ветках.

Примеры рабочих sequence-диаграмм

Ниже не “правильные картинки для документации”, а стартовые заготовки. Их смысл в том, чтобы быстро увидеть участников, порядок, ожидание ответа и место, где сценарий может сломаться.

Асинхронная обработка через очередь

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

sequenceDiagram
  actor User as Пользователь
  participant Web as Интерфейс
  participant Api as Backend
  participant Queue as Очередь
  participant Worker as Worker
  participant Store as Хранилище

  User->>Web: Загружает файл
  Web->>Api: Отправляет файл и параметры обработки
  Api->>Store: Сохраняет файл и задачу
  Api->>Queue: Публикует задачу обработки
  Api-->>Web: Возвращает статус "принято в обработку"

  Queue->>Worker: Передает задачу
  Worker->>Store: Читает файл и параметры
  Worker->>Worker: Обрабатывает файл
  Worker->>Store: Сохраняет результат и статус

  Web->>Api: Запрашивает текущий статус
  Api-->>Web: Возвращает результат или прогресс

Что проверить по диаграмме:

• где пользователь получает быстрый ответ;
• где сохраняется исходный файл;
• что будет, если worker упал после чтения задачи;
• как пользователь узнает, что обработка завершилась.

Webhook от внешней системы

Подходит, когда наша система не управляет моментом ответа: платеж, внешняя проверка, доставка статуса от партнера, callback после ручной операции.

sequenceDiagram
  participant App as Наша система
  participant External as Внешняя система
  participant Webhook as Webhook endpoint
  participant Jobs as Фоновая обработка
  participant Support as Поддержка

  App->>External: Создает внешнюю операцию
  External-->>App: Возвращает внешний идентификатор
  App->>App: Сохраняет операцию в статусе "ожидает callback"

  External->>Webhook: Отправляет callback со статусом
  Webhook->>Webhook: Проверяет подпись и идемпотентность

  alt Callback корректный
    Webhook->>Jobs: Передает событие на обработку
    Jobs->>App: Обновляет статус операции
  else Подпись не прошла проверку
    Webhook-->>External: Возвращает ошибку приема
    Webhook->>Support: Фиксирует событие для разбора
  else Дубль callback
    Webhook-->>External: Подтверждает прием без повторной обработки
  end

Что проверить по диаграмме:

• кто является источником истины по внешнему статусу;
• где проверяется подпись;
• как обрабатывается повторный callback;
• где появляется след для поддержки.

Ручная проверка после автоматического отказа

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

sequenceDiagram
  actor Client as Клиент
  participant App as Наша система
  participant Risk as Сервис риска
  participant Operator as Оператор
  participant Notify as Уведомления

  Client->>App: Отправляет заявку
  App->>Risk: Запрашивает оценку риска
  Risk-->>App: Возвращает высокий риск
  App->>Operator: Создает задачу ручной проверки
  App-->>Client: Показывает статус "заявка на проверке"

  Operator->>App: Принимает решение

  alt Заявка подтверждена
    App->>Notify: Отправляет уведомление об одобрении
    App-->>Client: Открывает следующий шаг
  else Заявка отклонена
    App->>Notify: Отправляет отказ с безопасной формулировкой
    App-->>Client: Показывает финальный статус
  end

Что проверить по диаграмме:

• кто владеет решением после автоматического риска;
• что видит клиент во время ожидания;
• какие причины можно показывать пользователю;
• где QA должен проверить обе ручные ветки.

4. Не прятать ответственность в слове “система”

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

Если в сценарии важно, кто отвечает за действие, лучше разделить участников:

• пользовательский интерфейс;
• backend;
• внешний сервис;
• очередь;
• worker;
• оператор;
• поддержка.

Это не значит, что нужно раскрывать всю архитектуру. Достаточно показать те границы, где может потеряться ответственность.

Например, если пользователь видит “проверка в процессе”, а оператор должен понять причину задержки, диаграмма должна показать не только запрос во внешний сервис, но и место диагностики.

5. Подписать состояния и данные

Sequence-диаграмма показывает порядок, но часто рядом нужны короткие пометки:

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

Не нужно превращать диаграмму в спецификацию всего. Но если состояние или данные влияют на поведение, они должны быть видимы.

6. Проверить диаграмму с командой

Готовая диаграмма должна пройти короткую проверку:

• разработчик понимает, какой порядок реализовывать;
• аналитик видит сценарии и исключения;
• QA понимает, какие ветки проверять;
• продукт или владелец результата понимает пользовательский смысл;
• поддержка или эксплуатация видит, где диагностировать проблему;
• тимлид видит риск, владельцев и точки эскалации.

Если диаграмму понимает только автор, это не рабочий артефакт, а личная заметка.

Когда sequence-диаграмма не нужна

Не надо рисовать sequence-диаграмму только потому, что “так выглядит системный анализ”.

Возможно, лучше подойдет другой артефакт:

• если непонятна цель и граница - сначала рабочая карта системы;
• если важны состояния объекта - state diagram или таблица переходов;
• если важны роли и ручной процесс - процессная схема;
• если важны границы систем - контекстная схема;
• если важен выбор решения - decision record;
• если важна приемка - критерии acceptance.

Диаграмма должна отвечать на рабочий вопрос. Если вопроса нет, артефакт станет украшением.

Короткий чеклист

Перед тем как считать sequence-диаграмму готовой, проверьте:

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

Короткий итог

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

Если после диаграммы команда одинаково понимает сценарий, ошибки, данные и владельцев действий, артефакт сработал. Если остались только красивые стрелки, смысл все еще потерян.