Модуль 9.2. Визуальное моделирование
Темы: UML (компоненты, последовательности, состояния), C4, BPMN/DMN. Артефакты: пакет диаграмм. Практика: диаграмма последовательности для API-сценария.
Диаграммы — это быстрый общий язык между бизнесом, разработкой, QA, DevOps и безопасностью. Хорошее визуальное моделирование:
- уменьшает неоднозначность SRS, ускоряет ревью и разработку;
- делает требования проверяемыми (связь с AC/BDD/OpenAPI/RTM);
- помогает планировать интеграции и обнаруживать риски раньше.
В этом модуле вы получите стандарты, примеры и шаблоны кода (PlantUML/Mermaid) для C4, UML, BPMN и DMN — с практикой на реальном кейсе «Оплата/Возврат».
Как выбирать нотацию (как сотруднику — к исполнению)
|
Задача |
Диаграмма |
Ключ к пользе |
|---|---|---|
|
Показать «кто с кем и зачем» |
C4 L1 (Context) |
1 экран, 5–7 элементов, краткие обязанности |
|
Показать контейнеры/сервисы и интеграции |
C4 L2 (Container) |
протоколы, драйверы, персистенс, границы |
|
Показать внутренние компоненты сервиса |
C4 L3 (Component) или UML Component |
слои, адаптеры, ключевые классы |
|
Пошаговое взаимодействие в API/интеграции |
UML Sequence |
lifeline’ы, alt/opt, коды ответов, idempotency |
|
Жизненный цикл сущности/агрегата |
UML State |
состояния, события, охранные условия, таймауты |
|
Бизнес-процесс с людьми/системами |
BPMN 2.0 |
пулы/потоки, таймеры, ошибки, компенсации |
|
Явные правила/тарифы/лимиты |
DMN Decision Table |
входы/выходы, hit policy, тестируемость |
Правило: одна диаграмма — одна идея (1–2 экрана max). Лишние детали — в другие виды.
Конвенции и «санитарные нормы» диаграмм
- Единая тёмная/светлая тема, минимум цветов (семафор ошибок/успеха — опционально).
- Именование: сущности и события — в доменном UL (модуль 4.2).
- Легенда и версионирование: в правом нижнем углу — версия, дата, владелец.
- Ссылки: в подписи элементов — линк на SRS/контракты/OpenAPI/AC/BDD.
- Экспорт: svg (для Confluence/Git), исходники (.puml, .bpmn, .dmn, .md) — в репозитории.
- Линк на RTM: номер требования/фичи в заголовке диаграммы.
- Definition of Done диаграмм: читаемость на ноутбуке 13″, нет «обоев», есть легенда/границы/версии.
C4: контекст и контейнеры
C4 Level 1 — Context (пример, PlantUML)
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml
LAYOUT_LEFT_RIGHT()
title C4 L1: Контекст — Платежи (v1.0)
Person(customer, "Покупатель", "Оплачивает заказ")
System_Boundary(b, "Наш продукт") {
System(pay, "Платежный сервис", "Создание/возвраты платежей")
System(web, "Витрина", "UI чекаута")
}
System_Ext(psp, "PSP", "Авторизация/капчур")
System_Ext(anti, "Антифрод", "Оценка риска")
Rel(customer, web, "Оформляет заказ")
Rel(web, pay, "POST /payments", "HTTPS/JSON")
Rel(pay, psp, "Authorize/Capture", "HTTPS")
Rel(pay, anti, "Score", "gRPC")
@enduml
C4 Level 2 — Container
Покажите базы/кэши/очереди/шины, протоколы, версии API, внешние зависимости. Для каждого контейнера — ответственность и технологические ограничения (если это требования).
UML: компоненты, последовательности, состояния
UML Component — структура сервиса (PlantUML)
@startuml
title UML Component: Платежный сервис (v1.0)
package "Payments Service" {
[API Controller] --> [Application Service]
[Application Service] --> [Domain Model]
[Application Service] --> [PSP Client]
[Application Service] --> [Outbox Publisher]
[Domain Model] --> [Repo (Postgres)]
[Cache (Redis)] ..> [Application Service] : optional
}
@enduml
Где полезно: объяснить, почему ретраи/идемпотентность живут в Application Service, и где именно outbox.
UML Sequence — «POST /payments» (Mermaid)
sequenceDiagram
autonumber
participant C as Client App
participant API as Payments API
participant S as Service (App)
participant DB as DB
participant PSP as PSP
participant BUS as Event Bus
Note over C,API: Idempotency-Key=K1, CorrelationId=corr-123
C->>API: POST /v1/payments {orderId, amount, currency}
API->>S: validate(request)
alt дубликат по Idempotency-Key
S->>DB: SELECT payment WHERE idem_key=K1
DB-->>S: found P1
S-->>API: 200 {paymentId:P1}
else новый платёж
S->>DB: INSERT payment(status=AUTHORIZING, idem_key=K1)
S->>PSP: authorize(amount,currency)
alt PSP ответ < 2.5s
PSP-->>S: OK authId=A1
S->>DB: UPDATE payment(status=AUTHORIZED, authId=A1)
S->>BUS: publish payment.authorized.v1
S-->>API: 201 {paymentId:P2}
else PSP timeout
S->>DB: enqueue task (authorize later)
S-->>API: 202 Accepted
end
end
Фишки: alt/else для веток, заметки о заголовках (Idempotency-Key, CorrelationId), точки измерения p95.
UML State — жизненный цикл Payment (PlantUML)
@startuml title State: Payment (v1.0) [*] --> NEW NEW --> AUTHORIZING : CreatePayment AUTHORIZING --> AUTHORIZED : PSPAuthorized AUTHORIZING --> FAILED : PSPDeclined / reason AUTHORIZING --> PENDING : Timeout(2.5s) / EnqueueTask PENDING --> AUTHORIZED : AsyncPSPAuthorized AUTHORIZED --> CAPTURED : Capture AUTHORIZED --> REFUNDED : Refund(amount<=captured) AUTHORIZED --> FAILED : Expired(7d) FAILED --> [*] CAPTURED --> [*] REFUNDED --> [*] @enduml
Зачем: согласовать инварианты (например, refundable?=status in {AUTHORIZED, CAPTURED}) и таймауты.
BPMN/DMN: процессы и правила
BPMN — возврат платежа (текстовое описание)
- Пулы: «Операторы саппорта», «Платежный сервис», «PSP».
- События: старт (создать возврат), таймер «SLA 2 мин», ошибка «PSPDeclined», компенсация «CancelRefund».
- Гейтвеи: проверка роли/лимитов (задача скрипта), проверка суммы.
- Завершение: успешный Refunded или ошибка с записью в аудит.
Используйте BPMN там, где есть люди + системы + SLA, а не только сервис-к-сервису.
DMN — правила возврата (таблица решений)
Hit policy: U (unique) или F (first).
Входы: role, limit, amount, capturedAmount.
Выход: decision (APPROVE/DECLINE) + reason.
|
role |
amount ≤ limit |
amount ≤ captured |
decision |
reason |
|---|---|---|---|---|
|
Support |
true |
true |
APPROVE |
— |
|
Support |
false |
— |
DECLINE |
LIMIT |
|
Analyst |
— |
— |
DECLINE |
ROLE |
Рекомендация: храните DMN как код (.dmn/CSV), версионируйте и покрывайте BDD тестами.
Как связать диаграммы с требованиями и кодом
- В каждой диаграмме — ссылки на: SRS §, OpenAPI/AsyncAPI, .feature (BDD), RTM ID.
- Sequence → контракт-тесты (тот же happy/alt path).
- State → инварианты/ограничения в ER/доменной модели.
- BPMN → UAT-сценарии и чек-листы SLA.
- DMN → таблицы тест-данных и автопроверки в CI.
Пакет диаграмм (артефакт) — структура и чек-лист
Структура репозитория:
docs/ c4/context_l1.puml c4/containers_l2.puml uml/components_payments.puml uml/sequence_create_payment.mmd uml/state_payment.puml bpmn/refund_process.bpmn dmn/refund_rules.dmn README.md # легенды, версии, ссылки
Чек-лист качества:
- Назначение и уровень (L1/L2, Sequence/State) понятны из заголовка.
- < 12 элементов на диаграмме; нет «обоев».
- Все подписи на UL, без внутреннего жаргона.
- Есть версия/дата/владелец, ссылка на SRS/контракты.
- Проверены связи с AC/BDD/RTM.
- Экспортирован SVG, исходники в Git.
Типовые анти-паттерны и как их избегать
|
Анти-паттерн |
Симптом |
Что делать |
|---|---|---|
|
«Обо всем на одном листе» |
Диаграмма не читается |
Разделить по целям/уровням; C4→UML→Sequence |
|
Надписи «UI нажимает кнопку…» в архитектуре |
Смешение уровней |
В архитектуре — поведение сервисов, UI — отдельно |
|
Sequence без ошибок/таймаутов |
«Счастливая тропа» |
alt/opt для 4xx/5xx/timeout/idempotency |
|
State без таймаутов/компенсаций |
Висящие состояния |
Добавить переходы по SLA/ошибкам |
|
BPMN как «рисунок», не исполнимая логика |
Не тестируется |
Свяжите с AC/UAT, добавьте таймеры/ошибки |
|
DMN в голове у человека |
Расхождения |
DMN как файл, версионировать, тестировать |
|
Нет версий/легенд |
Непонятно, что актуально |
Версия/дата/владелец в каждой диаграмме |
Практика: диаграмма последовательности для API-сценария (60–90 мин)
Задание: нарисовать UML Sequence для кейса «POST /v1/refunds» (частичный возврат).
Требования (фрагмент):
- amount ≤ capturedAmount, причина обязательна;
- роль Support c лимитом 100 (ABAC);
- при недоступности PSP — 202 Accepted и задача в очередь;
- аудит-лог на каждый исход.
Шаги:
- Определите lifeline’ы: Client, Refunds API, Service, DB, PSP, Event Bus, Audit.
- Обозначьте заголовки: Authorization, CorrelationId.
- Нарисуйте ветки: успех, превышение суммы, нет прав, timeout/202.
- Добавьте публикацию refund.completed.v1 и запись в аудит.
- Сопоставьте шаги с AC и RTM (комментариями).
- Экспортируйте в SVG, сохраните .mmd в docs/uml/sequence_create_refund.mmd.
Критерии зачёта:
- Есть alt/else, таймаут/202, аудит, событие.
- Подписи на UL, коды ответов отражены.
- Есть ссылки на SRS/OpenAPI/AC.
Вопрос–Ответ
В: Когда хватит C4, а когда нужен UML?
О: C4 отвечает «кто с кем и по каким протоколам». Как только нужны порядок действий/коды/ветки — переходите к Sequence. Для жизненных циклов — State.
В: Нужен ли BPMN, если нет людей в процессе?
О: Необязательно. Для чисто системных сценариев хватит Sequence+State. BPMN — когда есть человеческие роли, SLA, эскалации.
В: Чем DMN лучше «if-else» в документации?
О: DMN — исполнимая/тестируемая таблица правил с hit policy и версионированием. Её можно валидировать и гонять контракт-тестами.
В: Как поддерживать диаграммы актуальными?
О: Docs-as-Code: хранить исходники в Git, править через PR, ставить гейт DoD «обновлены диаграммы/ссылки». Добавляйте диаграммы в ревью-чек-лист.
В: Нужно ли показывать коды ошибок на Sequence?
О: Да — ключевые 2–3 ветки (422/401/202/5xx) с краткими кодами. Это облегчает тест-дизайн и контракт-тесты.
В: Как не «утонуть» в картинках?
О: Каждая диаграмма — цель/вопрос. Если диаграмма не добавляет нового смысла к SRS — не рисуйте или упростите.
Шпаргалка
- Начинаем с C4 L1–L2, далее UML Component → Sequence → State по необходимости.
- Диаграмма = одна идея; UL-язык; версия/легенда/владелец обязательны.
- Sequence всегда с ответами/ошибками/таймерами/идемпотентностью.
- State с таймаутами и конечными состояниями.
- BPMN — когда есть люди/SLA; DMN — когда есть явные правила.
- Все диаграммы — в Git, связаны ссылками с SRS/AC/BDD/OpenAPI/RTM.
