Use Case спецификация: универсальный шаблон

Универсальный шаблон спецификации сервиса: 16 разделов, три уровня детализации (Tier A/B/C). Подходит для legacy, UCP и DDD-сервисов.

Спецификация сервиса — контракт между бизнесом и разработкой. Заполняется совместно бизнес-аналитиком, архитектором и разработчиками; после заполнения содержит всё необходимое для реализации: от бизнес-терминов до критериев приёмки и НФТ.

Перед заполнением — соберите данные через Event Storming. Это workshop на 4-8 часов, который параллельно с командой и бизнесом выявляет события, акторы, бизнес-правила, агрегаты и границы контекстов. Каждый артефакт workshop ложится в конкретный раздел этой спеки. → Event Storming: workshop, который собирает данные для DDD-спеки

Это универсальный шаблон, не привязанный к конкретному стилю архитектуры. Он одинаково подходит legacy-системе со слоёной архитектурой, сервису на Use Case Pattern (Levels 1–2) и полноценному DDD/Hexagonal-сервису (Levels 3–4). Конкретная глубина каждого раздела зависит от Tier (см. ниже).

Сквозных примеров нет — только структура. Заполненные примеры по сервисам маркетплейса — в разделе Кейс.

Гайды по ролям

Роль	Гайд	Что внутри
Бизнес-аналитик	гайд BA	Как заполнять каждый раздел простым языком
Архитектор	гайд архитектора	Границы контекстов, агрегаты, Outbox, Saga, интеграции, НФТ
Разработчик	гайд разработчика	Java/Spring: пакеты, модель, state machine, commands, events, API
QA	гайд тестировщика	Матрицы переходов, BR-тесты, авторизация, E2E, Saga, нагрузка
DevOps	гайд DevOps	PostgreSQL, Kafka, K8s, мониторинг, алерты, масштабирование
Security	гайд security	IDOR, PII, rate limiting, TLS, аудит, OWASP Top 10
Дизайнер	гайд дизайнера	Экраны, статусы в UI, ошибки, валидация, дизайн-система
Сопровождение	гайд сопровождения	Инциденты, зависшие Saga, SQL-диагностика, эскалация
AI-агент	гайд AI-агента	Генерация кода/тестов, ревью, актуализация спецификации

Уровни спеки (Tier A / B / C)

Глубина спеки зависит от архитектурного стиля сервиса. Не каждый сервис — DDD; для legacy-кода полная DDD-спека избыточна. Поэтому шаблон делится на три уровня — Tier:

Tier	Архитектура	Привязка к UCP-уровням
A. Legacy / слоёная	Controller → Service → Repository, без библиотеки `usecase-pattern`	—
B. UseCase Pattern	подключена `usecase-pattern`, есть `UseCase` + `UseCaseHandler` (с CQRS-маркерами или без)	UCP Level 1–2
C. DDD / Hexagonal	+ агрегаты, доменные события, ports/adapters	UCP Level 3–4

Каждый раздел шаблона помечен минимальным Tier-ом, на котором он становится обязательным:

🟦 A — обязательно для всех систем, включая legacy.
🟩 B — добавляется на Tier B (UCP L1–L2). На Tier A раздел упрощён или отсутствует.
🟪 C — добавляется на Tier C (UCP L3–L4). Раньше — упрощён или не нужен.

Раздел	Tier A	Tier B	Tier C
1. Bounded Context	⭕ как «модуль»	✅	✅
2. Ubiquitous Language	✅	✅	✅
3. Domain Model	только ER + таблицы	+ UseCase-модели	+ агрегаты, VO, события
4. Жизненный цикл	если есть статусы	✅	✅
5. Роли и права	✅	✅	✅
6. Бизнес-правила	✅	✅	✅
7. Commands	список операций	UseCase-команды	+ предусловия / события
8. Domain Events	❌	⭕ если есть Kafka	✅
9. Queries / Read Model	список read-операций	+ Read Model на L2	✅
10. Use Cases	сценарии	+ ссылки на UseCase	✅
11. UI	✅	✅	✅
12. Saga	❌	⭕ редко	✅
13. Каталог ошибок	✅	✅	✅
14. Интеграции	базовые контракты	+ UseCase как порты	+ Context Mapping типы
15. Критерии приёмки	✅	✅	✅
16. НФТ	✅	✅	✅

✅ обязательно · ⭕ упрощённо / опционально · ❌ не пишется

В заголовке вашей спеки явно укажите Tier: «Order Service — DDD-спецификация (Tier C)». Это сразу задаёт читателю ожидания от глубины разделов.

Содержание

Bounded Context 🟦
Ubiquitous Language 🟦
Domain Model 🟦
Жизненный цикл и состояния 🟦
Роли и права доступа 🟦
Бизнес-правила и инварианты 🟦
Commands 🟦
Domain Events 🟩
Queries / Read Model 🟦
Use Cases 🟦
UI-спецификация 🟦
Saga / Process Manager 🟪
Каталог ошибок 🟦
Интеграции (Context Mapping) 🟦
Критерии приёмки 🟦
Нефункциональные требования 🟦

1. Bounded Context

🟦 Tier A+ · на A называется «модуль» / «компонент», понятие Bounded Context не нужно.

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

Что должно быть:

Название контекста и его краткая миссия в одной фразе.
Внутри контекста: бизнес-возможности, агрегаты, владелец данных.
Снаружи: соседние контексты, с которыми он общается, и роль (upstream / downstream / shared kernel).
Стейкхолдеры и владелец (product owner, ответственная команда).
Диаграмма C1 — System Context (Mermaid или draw.io): пользователи, внешние системы, сам контекст одной коробкой.

Формат:

Текст 5–15 строк + одна C1-диаграмма.
Никаких таблиц и кода — это самый верхний уровень.

2. Ubiquitous Language

🟦 Tier A+ · обязательно для всех уровней, без него невозможно говорить ни с бизнесом, ни в коде.

Назначение. Зафиксировать словарь домена: каждый термин — одно значение, без синонимов и омонимов. Один и тот же термин в коде, БД, UI, разговоре.

Что должно быть:

Глоссарий в виде таблицы: термин (рус) — термин (en, как в коде) — определение — пример употребления.
Запрещённые синонимы: пары «не путать» (например, «заявка ≠ заказ ≠ корзина»).
Решения по неоднозначным словам: что такое «клиент», «пользователь», «покупатель» именно в этом контексте.

Формат:

Русский термин	В коде	Определение	Пример

3–7 столбцов, без длинных описаний — каждое определение в 1–2 строках.

3. Domain Model

🟦 Tier A+ · содержание сильно меняется по уровню:

Tier A — только ER-схема и список таблиц.
Tier B — + модели UseCase-входов / выходов (JsonBean, Pojo, View).
Tier C — + агрегаты, value objects, доменные события, C3-диаграмма.

Назначение. Описать структуру предметной области: агрегаты, сущности, value objects и связи между ними.

Что должно быть:

3.1 Агрегаты

Список корней агрегатов и их инвариантов (что не должно нарушаться никогда).
Размер агрегата — количество сущностей внутри. Big aggregate ≠ масштабируемо.
Граница транзакции = граница агрегата.

3.2 Сущности

Сущности, входящие в агрегат, и их жизненный цикл внутри корня.
Внешние ссылки — только по ID соседнего агрегата.

3.3 Value Objects

Список VO с инвариантами, которые они защищают (Money, Email, Quantity).
Никаких ID, immutable.

3.4 Схема БД

ER-диаграмма или DDL-наброски на уровне таблиц + ключей. Без рантайм-индексов.
Связь «таблица ↔ агрегат» (одна таблица может покрывать целый агрегат, могут быть и подтаблицы).

3.5 Диаграмма C3 — Domain Model

Mermaid или PlantUML: классы агрегатов, сущности, VO, связи, кардинальности.

Формат:

1 C3-диаграмма + список агрегатов + DDL/ER. Без бизнес-правил (они в §6).

4. Жизненный цикл и состояния

🟦 Tier A+ · если сущность имеет статусы / state machine. Иначе раздел пропускается.

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

Что должно быть:

Перечисление состояний (enum в коде).
Матрица переходов: «из какого в какое можно», «при какой команде».
State diagram (Mermaid stateDiagram-v2).
Терминальные состояния и условия отката.
Time-based переходы (например, автоматический cancel через N часов).

Формат:

Из	Команда	В	Условие

диаграмма состояний.

5. Роли и права доступа

🟦 Tier A+ · обязательно для любого сервиса с пользователями; формат не меняется по Tier.

Назначение. Кто что может делать с командами и запросами этого контекста.

Что должно быть:

Список ролей (Customer, Seller, Admin, Support и т.п.).
Матрица прав: команда / запрос → разрешённые роли.
Условия владения (ABAC): «покупатель видит только свои заказы», «продавец — заказы по своим товарам».
Маркировка PII в data-моделях (для §16 NFR / Security).

Формат:

Команда / Query	Customer	Seller	Admin	ABAC-условие

6. Бизнес-правила и инварианты

🟦 Tier A+ · обязательно. На Tier C добавляется столбец «инвариант агрегата».

Назначение. Перечислить ВСЕ правила, которые домен обязан соблюдать. Их код должен валидировать; QA — тестировать.

Что должно быть:

Каждое правило — отдельной строкой с уникальным кодом (BR-001, BR-002).
Тип: инвариант (всегда истинно), предусловие (для команды), постусловие.
Связь: какой агрегат / команда / событие правило затрагивает.
Сообщение об ошибке (для §13 каталог ошибок).

Формат:

Код	Правило	Тип	Затрагивает	Ошибка
BR-001	…	инвариант	Order	ORDER_INVALID_STATE

7. Commands

🟦 Tier A+ · содержание меняется:

Tier A — список операций (метод сервиса / endpoint), без явной CQRS-модели.
Tier B — каждая операция = UseCase или UseCaseCommand (на L2). Указывается useCaseType и handler.
Tier C — + предусловия, постусловия, публикуемые события, изменения состояния агрегата.

Назначение. Список всех операций, изменяющих состояние контекста.

Что должно быть для каждой команды:

Имя в инфинитиве: CreateOrder, ConfirmPayment.
Цель в одной фразе.
Входные данные: поля + типы + валидации.
Предусловия: какие BR должны быть выполнены до.
Эффекты: какие поля агрегата меняются, какие события публикуются.
Кто может вызвать (роли из §5).
Идемпотентность: ключ или явное «не идемпотентна».
Ошибки (коды из §13).

Формат:

Список команд + 1 короткая карточка на команду (5–10 строк). Без полного OpenAPI здесь — он в §10 / API.

8. Domain Events

🟩 Tier B+ · на Tier A раздел пропускается (legacy редко публикует доменные события). На Tier B — только если сервис реально публикует/потребляет события (например, Kafka).

Назначение. Список всех событий, которые контекст публикует и/или потребляет.

Что должно быть для каждого события:

Имя в прошедшем времени: OrderPaid, ItemReserved.
Когда возникает: триггерная команда + условие.
Payload: поля события (только идентификаторы и значения, без ссылок на агрегаты).
Внутреннее vs внешнее: остаётся в bounded context или публикуется в Kafka.
Подписчики: какие контексты слушают (для §14 интеграций).
Версионирование схемы (если событие — внешний контракт).

Формат:

Карточка на событие + сводная таблица «событие → топик → подписчики».

9. Queries / Read Model

🟦 Tier A+ · содержание зависит от уровня:

Tier A — список read-операций (GET endpoint-ов).
Tier B (L2) — + UseCaseQuery и Read Model (View / отдельная таблица) — раздел значимо расширяется.
Tier C — + источник Read Model (проекция из событий, реплика, кэш) и согласованность.

Назначение. Список запросов на чтение и структура read-моделей (отдельно от write-side).

Что должно быть:

Список запросов с входными параметрами и формой ответа.
Read Model: какие представления (*View, materialized view, отдельные таблицы) собирают данные для чтения.
Источник данных read-модели: проекция из событий, отдельный кэш, реплика.
Согласованность: eventual / strong, типичный лаг.
API-контракт (OpenAPI-набросок) — если запрос наружу.

Формат:

Список запросов + ссылка на OpenAPI / контракт. Read Model — отдельная подсекция со схемой.

10. Use Cases

🟦 Tier A+ · на Tier A — обычные user-сценарии. На Tier B — добавляются ссылки на конкретные UseCase-ы. На Tier C — + участвующие агрегаты, события, саги.

Назначение. Сквозные сценарии: как команды и запросы складываются в бизнес-операции конечного пользователя.

Что должно быть для каждого use case:

Актор и цель.
Триггер: что запускает сценарий.
Основной поток — пронумерованные шаги.
Альтернативные потоки и обработка ошибок.
Ссылки на команды (§7), запросы (§9), события (§8) и саги (§12), которые задействованы.

Формат:

Карточка на use case (10–25 строк) + sequence-диаграмма для нетривиальных.

11. UI-спецификация

🟦 Tier A+ · если у сервиса есть UI / front-end. Формат от уровня не зависит.

Назначение. Список экранов, на которых проявляются команды и состояния.

Что должно быть:

Реестр экранов: имя, ссылка на макет, какие команды/запросы вызывает.
Связь UI ↔ состояния из §4: какие состояния как отображаются (бейджи, цвета).
Сообщения об ошибках (тексты для каждого кода из §13).
Дизайн-система: ссылка на компоненты, токены.

Формат:

Таблица экранов + ссылки на Figma / wireframes. Сами макеты в этой статье не лежат.

12. Saga / Process Manager

🟪 Tier C+ · на Tier A раздел пропускается. На Tier B — только если в сервисе действительно есть длинные межагрегатные процессы (редко).

Назначение. Описать длительные межагрегатные / межсервисные процессы.

Что должно быть для каждой саги:

Имя саги и её цель.
Шаги: команда → ожидаемое событие → следующая команда.
Компенсации для каждого шага: «если не получилось — откатить так».
Таймауты: сколько ждём каждое событие, что делаем при истечении.
Хранилище состояния саги (своя таблица, snapshot, event-sourced).
Sequence-диаграмма (Mermaid).

Формат:

Карточка + диаграмма. Реализация (Spring + Outbox) — в гайде разработчика, не здесь.

13. Каталог ошибок

🟦 Tier A+ · обязательно. Формат не зависит от Tier.

Назначение. Единый список доменных ошибок, на которые ссылаются команды (§7), запросы (§9), UI (§11).

Что должно быть:

Код	HTTP	Сообщение (RU)	Сообщение (EN)	Когда возникает
ORDER_NOT_FOUND	404	Заказ не найден	Order not found	…

Коды — UPPER_SNAKE_CASE, согласованы с RFC 9457 ProblemDetails (см. REST API style guide).

14. Интеграции (Context Mapping)

🟦 Tier A+ · содержание расширяется:

Tier A — базовые контракты (REST / SOAP / БД).
Tier B — + интеграции через UseCase (порт = интерфейс UseCase, реализуемый внешним адаптером).
Tier C — + явные типы Context Mapping: ACL, Open Host Service, Conformist, Customer/Supplier, Shared Kernel.

Назначение. Зафиксировать, как этот контекст общается с соседями.

Что должно быть для каждой пары контекстов:

Тип связи: Conformist, ACL, Open Host Service, Published Language, Shared Kernel, Customer/Supplier.
Канал: REST, gRPC, Kafka, файлы.
Контракт: OpenAPI / схема события (ссылка).
Гарантии: at-least-once / exactly-once / at-most-once; идемпотентность; порядок.
Ответственный за миграцию контракта (upstream).
Диаграмма C2 уровня всей системы — общая, в case или strategic, не в каждом BC отдельно.

Формат:

Таблица «контекст A → контекст B» + ссылки на контракты.

15. Критерии приёмки

🟦 Tier A+ · обязательно. Формат не зависит от Tier.

Назначение. Условия, по которым фича считается готовой.

Что должно быть:

Acceptance criteria на каждый use case (Given/When/Then или нумерованный список).
Покрытие тестами: какие BR-правила (§6) каким уровнем теста (unit/integration/e2e) проверяются.
Вход в прод: feature flag, канареечный rollout, дашборды.

Формат:

Чек-лист на use case. Не путать с отдельным гайдом QA — там методология тестов, здесь — конкретные критерии.

16. Нефункциональные требования

🟦 Tier A+ · обязательно для всех. Формат не зависит от Tier.

Назначение. Зафиксировать ограничения вне функциональных сценариев.

Что должно быть:

Производительность: целевой p95/p99 latency, RPS, размер агрегата.
Доступность: SLA / SLO (например, 99.9 %).
Согласованность: где допустим eventual, где обязательна strong.
Безопасность: PII, аудит, retention, шифрование (см. гайд security).
Наблюдаемость: ключевые метрики, логи, трейсы; алерты при их пропадании.
Капасити: storage и трафик на 1 / 6 / 12 месяцев.
Compliance: 152-ФЗ, GDPR, PCI DSS — если применимо.

Формат:

Таблица «требование → значение → как измеряется → как алёртить».

Дальше

Гайды по ролям — как заполнять каждый раздел в зависимости от твоей роли (см. таблицу выше).
Реальные примеры заполнения шаблона на сервисах маркетплейса — в кейсе (по DDD-спецификации на каждый микросервис).
Тактические паттерны DDD — как §3 (Domain Model) переводится в код.
REST API Style Guide — как §7 (Commands) и §9 (Queries) превращаются в OpenAPI.
Распределённые паттерны — как §12 (Saga) реализуется с Outbox.

← Предыдущая

Уровень 4: Hexagonal