Модуль 1.3. Документация системного аналитика и артефакты
Видение (Vision), SRS, BPMN, диаграммы последовательности (Sequence/UML), ER-модель, API-контракт (OpenAPI), NFR. Практика: пакет артефактов к одной фиче.
Ваша цель как SA — превратить «хотелку» в набор согласованных, версионируемых и проверяемых артефактов, по которым команда разрабатывает, тестирует, выкатывает и мониторит фичу. В этом модуле делаем полный разбор каждого артефакта: что в него входит, как он связан с остальными, как версионируется и какие риски закрывает.
Принципы «живой» документации (как сотруднику — к исполнению)
- Единый источник правды: канон (OpenAPI/диаграммы/BDD/схемы данных) — в Git; Wiki — витрина и навигация.
- Версионирование SemVer: MAJOR.MINOR.PATCH у SRS/контрактов/событий/ER. Любой breaking change — bump MAJOR.
- Трассируемость: каждый артефакт помечен Artifact-ID и ссылается на REQ-ID, Jira-ID, тесты и метрики.
- Проверяемость: требования формулируются через AC/BDD и NFR со измеримыми SLO.
- Docs-as-code: PR/ревью, линтеры, changelog, релизные теги.
Vision (Видение): кратко, зачем делаем
Назначение: ответить «зачем фича», «какая ценность» и «как поймём, что получилось».
Структура (1–2 страницы):
- Контекст/проблема: кто пользователь, где болит.
- Цели/метрики: бизнес-KPI и технические SLO (например, «p95 оплаты < 3с»).
- Область и границы: что входит/исключено, регуляторика, каналы.
- Релизные срезы/MVP и риски.
Типичные ошибки: обещания без метрик; нет ограничений; смешение Vision и SRS.
Пример (фрагмент):
Цель: увеличить конверсию успешных оплат на 2 п.п. в чекауте.
SLO: p95 POST /payments < 3000 мс; error-rate < 0.5% по неделям.
SRS (System Requirements Specification): как именно это будет работать
Назначение: инженерная спецификация — сценарии, данные, интеграции, NFR, критерии приемки.
Рекомендуемая структура SRS:
- Область и термины (ссылка на глоссарий).
- Сценарии и варианты (Use Cases, BPMN, Sequence).
- Данные (ER, домены, справочники, миграции).
- Интеграции (REST/GraphQL/gRPC, события, очереди).
- Ошибки/валидаторы/идемпотентность/ограничения.
- Нефункциональные требования (производительность, надёжность, безопасность, наблюдаемость, совместимость, локализация).
- AC/BDD (критерии приемки).
- Трассируемость (ссылка на RTM).
- Версионирование/изменения (changelog, ADR).
Специфика:
- Каждая функция — с AC/BDD.
- Любой интеграционный вызов — с ошибками, лимитами, таймаутами, идемпотентностью и X-Correlation-Id.
- NFR — измеримые и привязаны к сценариям.
BPMN: как зафиксировать процесс, исключения и роли
Когда нужен: есть несколько акторов/шлюзов/исключений, требуется согласовать «кто что делает и когда падаем».
Минимум на диаграмме:
- Пулы/потоки, старт/конец, задачи (user/service), события ошибок, шлюзы XOR/AND, сообщения между пулами.
- Версия/владелец/дата/ссылка на SRS.
Правила качества:
- У каждого шлюза — семантический критерий («Сумма > лимита?»).
- Ошибки всегда промоделированы событийными элементами.
- Никаких «заглушек: здесь магия» — либо фиксим, либо явно помечаем Assumption.
Что часто ломают: «линейка без альтернатив» (нет ошибок/таймаутов/повторов), смешение процессов и UI-потоков.
Диаграммы последовательности (UML Sequence): кто и как общается
Когда нужен: согласовать взаимодействия сервисов/внешних систем, показать порядок, таймауты и ретраи.
Пример (Mermaid) — «Создание платежа с PSP-колбэком»:
sequenceDiagram
autonumber
participant Client
participant Checkout
participant PSP as PSP
Client->>Checkout: POST /payments (Idempotency-Key, X-Correlation-Id)
activate Checkout
Checkout->>PSP: Authorize(request) [timeout=10s]
alt success
PSP-->>Checkout: 200 Authorized
Checkout-->>Client: 201 Created (paymentId)
PSP-->>Checkout: Webhook /payments/callback (Captured)
Checkout-->>Checkout: Update status=CAPTURED (idempotent)
else timeout/error
PSP-->>Checkout: 504/5xx or no response
Checkout-->>Client: 202 Accepted (status=PENDING)
Checkout-->>Checkout: Schedule retry (max=3, exp)
end
deactivate Checkout
Правила качества: всегда указываем таймауты/ретраи/идемпотентность, отмечаем ошибки и альтернативы.
ER-модель: сущности, ключи, домены
Цель: прояснить, какие данные и в каких связях нужны, где «истина», какие ограничения.
Требования к ER:
- PK/FK, кардинальности (1:N, M:N через стыковочную), домены и обязательность (nullable/not null), инварианты (уникальность, диапазоны).
- Версионирование справочников и адресов (например, valid_from/valid_to).
Пример (Mermaid ER):
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains
ORDER ||--o| PAYMENT : has
PAYMENT ||--o{ REFUND : creates
CUSTOMER {
uuid customer_id PK
string email
string phone
}
ORDER {
uuid order_id PK
uuid customer_id FK
string status
timestamp created_at
}
ORDER_ITEM {
uuid order_item_id PK
uuid order_id FK
int qty
decimal price
}
PAYMENT {
uuid payment_id PK
uuid order_id FK
string status
string idempotency_key
decimal amount
}
REFUND {
uuid refund_id PK
uuid payment_id FK
decimal amount
string status
timestamp created_at
}
Антипаттерны: ER без типов/ключей; отсутствие доменов/справочников; «скрытые» поля, всплывающие в проде.
API-контракт (OpenAPI): договор с разработкой/QA/внешним миром
Цель: согласованный и проверяемый контракт интерфейса.
Минимум в контракте:
- Имена и пути, схемы запрос/ответ, ошибки (коды/типы/детали), пагинация/фильтры, лимиты/таймауты и заголовки (X-Correlation-Id, Idempotency-Key), безопасность (OAuth2/JWT/MTLS).
- Версионирование SemVer; политика совместимости и депрекейта.
Пример (фрагмент OpenAPI 3.0.3):
openapi: 3.0.3
info:
title: Payments API
version: 2.4.0
paths:
/payments:
post:
summary: Create payment (idempotent)
parameters:
- in: header
name: Idempotency-Key
required: true
schema: { type: string }
- in: header
name: X-Correlation-Id
required: true
schema: { type: string, format: uuid }
requestBody:
required: true
content:
application/json:
schema: { $ref: '#/components/schemas/CreatePaymentRequest' }
responses:
"201":
description: Created
headers:
X-Correlation-Id: { schema: { type: string, format: uuid } }
content:
application/json:
schema: { $ref: '#/components/schemas/Payment' }
"409":
description: Conflict (duplicate / invalid state)
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
components:
schemas:
CreatePaymentRequest:
type: object
required: [orderId, amount, currency]
properties:
orderId: { type: string, format: uuid }
amount: { type: number, format: decimal }
currency: { type: string, minLength: 3, maxLength: 3 }
Payment:
type: object
required: [paymentId, status, amount]
properties:
paymentId: { type: string, format: uuid }
status: { type: string, enum: [PENDING, AUTHORIZED, CAPTURED, FAILED] }
amount: { type: number, format: decimal }
Error:
type: object
required: [code, message]
properties:
code: { type: string, example: PAYMENT_CONFLICT }
message: { type: string }
details: { type: object, additionalProperties: true }
Антипаттерны: «сгенерим из кода и ладно», отсутствие ошибок/лимитов/идемпотентности, breaking-change без MAJOR.
NFR (нефункциональные требования): измеримые и привязанные к сценариям
Зачем: без них «быстро/надёжно» превращается в «медленно/падает».
Категории и примеры SLO/AC:
- Производительность: p95 latency POST /payments < 3s, RPS ≥ 50.
- Надёжность/Доступность: 99.9% monthly, RTO ≤ 30m, RPO ≤ 5m.
- Безопасность: маскирование PII в логах, ролевой доступ к логам, OAuth2/JWT.
- Наблюдаемость: логи (уровни/маски), метрики (latency, error-rate, throughput), трассировки (trace/correlation-id), алерты (порог/время реакции).
- Совместимость: поддержка N и N-1 версии контрактов X месяцев.
Формат записи (шаблон):
NFR-PERF-001: p95 POST /payments < 3 000 ms (на 95% запросов в неделе), измерение: Prometheus metric payments_latency_ms_p95.
NFR-REL-002: Availability 99.9%/month; RTO 30 min; RPO 5 min; кейсы деградации: отключение 3DS, снижение таймаутов.
NFR-SEC-003: Маскирование PAN/PII в логах (xxx…xxxx), доступ roles: ops.read/sec.read; аудит всех чтений логов.
NFR-OBS-004: Метрики payments_latency_p95, payments_error_rate; алерты: error_rate >0.5% 5 мин — page on-call.
Связность артефактов: как это склеивается
- Vision → SRS §1 «Цели» (копия метрик) → RTM.
- BPMN/Sequence → ссылки в SRS §2; из диаграмм — якорь на SRS.
- ER → SRS §3; поля и домены отражены в OpenAPI/событиях.
- OpenAPI → SRS §4/5; версии прописаны в заголовке SRS, changelog синхронен.
- NFR → SRS §6 + Observability-раздел; SLI/алерты прописаны и привязаны к RTM.
Definition of Spec Done (DoD для документации):
- Есть Vision + SRS с заполненными разделами.
- BPMN/Sequence/ER — минимальный набор с версиями и владельцами.
- OpenAPI — полные схемы + ошибки/лимиты/идемпотентность/безопасность; версия совпадает с SRS.
- NFR — измеримые, привязаны к сценариям; есть SLI/алерты.
- RTM покрывает ≥ 90% требований; changelog заполнен; все артефакты лежат в Git, на Wiki — витрина.
Практические примеры: «Пакет артефактов к фиче — Возврат платежа»
Состав пакета (минимум):
- vision/vision-refund.md — цель, KPI, SLO.
- srs/srs-refund.md — разделы 1–9.
- diagrams/bpmn/refund.bpmn.drawio — основной процесс + ошибки.
- diagrams/sequence/refund-seq.mmd — взаимодействия PSP/сервисов.
- data/er.mmd — сущности Payment/Refund/Order.
- api/openapi.yml — POST /refunds, GET /refunds/{id}, ошибки/идемпотентность.
- nfr/nfr-refund.md — p95<2с, error-rate<0.5%, RTO/RPO, алерты.
- tests/refund.feature — BDD на позитив/негатив/таймаут/повтор.
- rtm/rtm.csv — 10–15 связей Goal→FR/NFR→Model/Contract→Jira→Test→Metric.
Фрагмент BDD:
Feature: Refund payment
Scenario: Idempotent refund
Given payment CAPTURED with amount 1000
And Idempotency-Key "abc-123"
When POST /refunds { paymentId, amount: 1000 }
Then response code is 201
And refund.status is "PENDING"
When POST /refunds { paymentId, amount: 1000 } with same Idempotency-Key
Then response code is 200
And refundId is the same
Риски и анти-паттерны (и как их гасить)
- Док-долг: «спеки отстают от кода». → Docs-as-code, PR-чеклист: без bump версий/CHANGELOG — нельзя мёржить.
- PNG-архитектура: нет исходников диаграмм. → Храним Mermaid/PlantUML/drawio рядом.
- SRS без NFR: «медленно/падает» в проде. → Шаблон NFR обязателен, DoR без NFR — не проходит.
- OpenAPI без ошибок/идемпотентности: дубли и «залипшие» транзакции. → Применяйте единый error-модель, Idempotency-Key, X-Correlation-Id.
- ER без доменов/справочников: рассинхрон данных. → Домены/валидаторы/версионирование справочников.
- Нет RTM: никто не понимает, что реализовано/протестировано. → RTM как «вход в релиз».
Вопрос–Ответ (частые)
Q1: Нужна ли всегда BPMN, если есть Sequence?
A: Да, если есть человеческий процесс с ролями/исключениями. Sequence — про «кто с кем говорит», BPMN — про «кто и что делает и где ломается».
Q2: Можно ли генерить OpenAPI из кода?
A: Можно, но владелец контракта — SA: вы задаёте структуру/ошибки/лимиты/идемпотентность/безопасность и следите за совместимостью.
Q3: Как понять, что NFR «правильные»?
A: Они измеримы, привязаны к сценариям, есть SLI/алерты, и команда согласна, как мерить и что делать при нарушении (деградации/откаты).
Q4: Где держать диаграммы — в Wiki или Git?
A: Исходники — в Git; в Wiki — рендер и ссылка на канон.
Q5: Что важнее — текст или диаграммы?
A: Согласованность. Текст фиксирует исключения/ограничения, диаграммы снижают риск недопонимания. Версионируйте и то, и другое.
Практика: «Пакет артефактов к фиче» (4–8 часов)
Задача: собрать минимально жизнеспособный набор артефактов для одной фичи (на выбор: «Возврат платежа», «Смена адреса доставки», «Сброс пароля»).
Шаги:
- Vision (1 стр.) — цель/метрики/SLO/границы.
- SRS (до 8 стр.) — сценарии, правила, данные, интеграции, NFR, AC/BDD, трассируемость/версии.
- BPMN — основной поток + 2 альтернативы + 1 ошибка.
- Sequence — критичное взаимодействие (таймаут/ретраи/идемпотентность).
- ER — ≥ 5 сущностей, PK/FK, домены.
- OpenAPI — 2–3 endpoint (создание/получение/список), ошибки/пагинация/лимиты/безопасность/Idempotency-Key.
- NFR — 4–6 требований (perf, rel, sec, obs, compat).
- RTM — 10+ связей Goal→FR/NFR→Model/Contract→Jira→Test→Metric.
- Версии/Changelog — semver и список изменений.
Критерии зачёта:
- Полнота пакета; AC/BDD покрывают ключевые ветви; NFR измеримы; OpenAPI и ER согласованы; RTM ≥ 90%; все артефакты связаны и версионированы.
Структура репозитория (рекомендация):
/docs /vision/vision-<feature>.md /srs/srs-<feature>.md /diagrams/bpmn/<feature>.drawio /diagrams/sequence/<feature>.mmd /data/er-<domain>.mmd /api/openapi.yml /nfr/nfr-<feature>.md /tests/<feature>.feature /rtm/rtm.csv CHANGELOG.md
Шпаргалка на каждый день
- Канон в Git, витрина в Wiki, план в Jira.
- У любого артефакта есть владелец/версия/ссылка на требования/задачи/тесты.
- OpenAPI всегда с ошибками/лимитами/идемпотентностью/безопасностью.
- NFR измеримы и привязаны к сценариям + SLI/алерты.
- Диаграммы с исходниками, версии синхронны с SRS.
- RTM закрывает путь от цели до метрики — иначе фича «не готова».
