Модуль 1.1. Системная аналитика с нуля: инструменты и программы
Confluence/Jira/YouTrack, Miro/FigJam, UML/BPMN/DMN, Postman, Swagger/OpenAPI, SQL для системного аналитика, базовые диаграммы. Практика: настроить проектный рабочий стол.
Ваша задача — не просто «знать инструменты», а собрать из них рабочую систему: хранилище артефактов, прозрачно связанное с задачами, контрактами API, диаграммами и тестами. В конце модуля у вас будет настроенный проектный рабочий стол: пространство в Confluence/Notion, проект в Jira/YouTrack, библиотека диаграмм в Miro/FigJam, репозиторий /docs с OpenAPI/диаграммами, настроенный Postman и набор SQL-заготовок для проверок.
Принципы среды (как сотруднику — к исполнению)
-
Единый источник правды (SSOT).
- Каноничные спецификации (OpenAPI/AsyncAPI, JSON-Schema, BDD, диаграммы в PlantUML/Mermaid) — в Git.
- Wiki (Confluence/Notion) — витрина: страницы с контекстом и ссылками на канон, индекс артефактов.
- Трекер (Jira/YouTrack) — план и статус, обязательно хранит ссылки на спецификации.
- Версионирование и трассируемость. SemVer для документов; RTM связывает требование → задача → тест → мониторинг.
- Автоматизируем всё, что повторяется. Линтеры для OpenAPI, проверки битых ссылок, pre-commit hooks, Postman/Newman для регресса, экспорт диаграмм из исходников.
Confluence/Notion: структура, макросы, шаблоны
Рекомендуемая структура пространства
/ Product X / 0. Onboarding (глоссарий, ссылки, принципы) / 1. Vision & BRD / 2. System Requirements (SRS, NFR, RTM) / 3. Processes & Rules (BPMN/DMN) / 4. Interfaces (OpenAPI/Events, Error model, Versioning) / 5. Data (ER, словарь, DQ) / 6. Testing (AC/BDD, UAT) / 7. Observability (SLI/SLO, алерты, логи) / 8. ADR (решения) / 9. Change Log (версии, релизные срезы PDF)
Блок «Meta» вверху каждой страницы
-
Owner, Version (semver), Status (Draft/Review/Approved/Deprecated), Last Review, Links (Jira/Git/Miro).
В Confluence используйте Page Properties + Page Properties Report для индекса.
Анти-спам правило
- В Wiki — только читабельные тексты/решения и врезки с артефактами; исходники диаграмм/контрактов — в Git.
- Любая картинка диаграммы должна ссылаться на исходник (PlantUML/Mermaid/drawio) и на раздел SRS.
Чек-лист Confluence
- Структура каталогов создана.
- Шаблоны страниц (Vision/BRD/SRS/ADR) добавлены.
- Индекс документов (Page Properties Report) выведен на главную.
- На страницах «Interfaces» и «Data» — таблицы «Артефакт → Версия → Git-путь».
Jira/YouTrack: типы задач, поля, DoR/DoD (для SA)
Типы задач
- Epic/Feature/Story/Task, Spike (исследование → выход: ADR), Change Request, Bug (req-defect).
Обязательные поля для трассируемости
- SpecLink (URL на SRS/ADR), ContractVersion (напр., OpenAPI 2.4.0),
- DataImpact (сущности/справочники/CDC), NFR Tags (latency, security, obs…),
- TestRef (BDD/наборы), Dependencies (внешние API/команды).
DoR/DoD для карточек с участием SA
DoR (вход в разработку): SRS-раздел + диаграммы, OpenAPI/AsyncAPI с ошибками/пагинацией/лимитами, измеримые NFR, AC/BDD, тестовые данные, RTM-связь.
DoD (выход): реализовано по AC; обновлены SRS/OpenAPI/ER (bump версий, changelog); настроены логи/метрики/трейсы/алерты; контрактные тесты и совместимость (N-1) пройдены.
Miro/FigJam: библиотека диаграмм и правила
- Используйте единый набор шейпов (BPMN/DMN/UML/C4). Цветов — не более 3–4; ошибки/исключения — отдельным цветом.
- На каждой диаграмме: заголовок, владелец, версия, дата.
- Экспортируйте SVG/PNG + исходник в Git /docs/diagrams.
- Тэги карточек: bpmn, dmn, sequence, c4, er.
Базовые диаграммы (минимальный набор)
- BPMN — основной сценарий + альтернативы + ошибки.
- DMN — таблицы решений для правил/валидаций (hit policies).
- UML Sequence — 2–3 критичных взаимодействия.
- C4 Level 1–2 — контекст и контейнеры.
- ER — сущности, атрибуты, ключи и кардинальности.
Пример UML sequence (Mermaid) для оплаты:
sequenceDiagram participant Client participant Checkout participant PSP as PaymentProvider Client->>Checkout: POST /payments (Idempotency-Key) Checkout->>PSP: Authorize() PSP-->>Checkout: Authorized Checkout-->>Client: 201 Created (paymentId) PSP-->>Checkout: Webhook Captured Checkout-->>Client: Status update via SSE
Swagger/OpenAPI: контракты, версии, ошибки
Структура и правила
- Один файл openapi.yml на сервис или моно-репо /api/<service>/openapi.yml.
- SemVer: MAJOR.MINOR.PATCH. Ломающие изменения — только в MAJOR.
- Ошибки: единая модель (коды/типы/детали), идемпотентность и correlation-id обязательны для финансовых/критичных операций.
- Пагинация: стандартные параметры limit/offset или cursor.
- Security: схемы OAuth2/JWT/MTLS.
Пример (фрагмент) OpenAPI 3.0:
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 or invalid state)
content:
application/json:
schema: { $ref: '#/components/schemas/Error' }
components:
schemas:
Error:
type: object
required: [code, message]
properties:
code: { type: string, example: PAYMENT_CONFLICT }
message: { type: string }
details: { type: object, additionalProperties: true }
Инструменты
- Swagger UI/ReDoc для рендера.
- Линтеры: spectral, openapi-diff (контроль совместимости).
- Моки: prism/stoplight (быстрый стенд для фронта/QA).
- Контрактные тесты: Dredd, Schemathesis.
Postman: среды, коллекции, регресс
Среды (environments)
-
local, dev, staging, prod.
Переменные: base_url, auth_token, tenant, correlation_id, idempotency_key.
Pre-request / Tests (сниппеты)
Pre-request (генерация заголовков):
pm.environment.set("correlation_id", crypto.randomUUID());
pm.environment.set("idempotency_key", crypto.randomUUID());
pm.request.headers.add({ key: "X-Correlation-Id", value: pm.environment.get("correlation_id") });
pm.request.headers.add({ key: "Idempotency-Key", value: pm.environment.get("idempotency_key") });
Test (проверки):
pm.test("Status is 201", () => pm.response.code === 201);
pm.test("Has correlation id", () => pm.response.headers.has("X-Correlation-Id"));
pm.test("p95 latency budget", () => pm.response.responseTime < 3000);
Newman в CI
- Экспорт коллекций/сред → запуск в CI на каждом PR контракта: newman run payments.postman_collection.json -e dev.postman_environment.json.
SQL для системного аналитика: проверки и сверки
Минимум, который нужен
- SELECT … FROM … WHERE … JOIN …
- Агрегации/оконные (COUNT/SUM, ROW_NUMBER, LAG/LEAD)
- Проверки качества данных (DQ), сверки «источник → витрина», поиск дублей, пропусков.
Заготовки
Проверка идемпотентности (дубли ключей):
SELECT idempotency_key, COUNT(*) cnt FROM payments GROUP BY idempotency_key HAVING COUNT(*) > 1;
Сверка сумм заказа и платежей:
SELECT o.order_id,
SUM(i.qty * i.price) AS order_amount,
SUM(p.amount) AS paid_amount
FROM orders o
JOIN order_items i ON i.order_id = o.order_id
LEFT JOIN payments p ON p.order_id = o.order_id AND p.status = 'CAPTURED'
GROUP BY o.order_id
HAVING SUM(p.amount) <> SUM(i.qty * i.price);
Мониторинг «тихих» ошибок (латентные провалы):
SELECT date_trunc('hour', created_at) AS ts,
AVG(CASE WHEN status='SUCCESS' THEN latency_ms END) AS avg_ok_latency,
SUM(CASE WHEN status<>'SUCCESS' THEN 1 END) AS errors
FROM api_logs
WHERE created_at >= now() - interval '24 hours'
GROUP BY 1
ORDER BY 1;
Базовые нотации: UML/BPMN/DMN (что именно рисовать)
- BPMN: старт/финиш, пользовательские/сервисные задачи, события ошибок, шлюзы (XOR/AND), пулы/потоки.
- DMN: hit policy (U, F, C, A), входы/выходы с типами, примеры строк, отрицательные кейсы.
- UML Sequence: акторы/сервисы, сообщения (sync/async), ответы/ошибки, жизненные линии.
- C4 L1–L2: контекст и контейнеры, внешние системы/пользователи, протоколы.
- ER: сущности, типы данных, PK/FK, кардинальности (1:1, 1:N, M:N), неизменяемые домены.
Правило ценности: любая диаграмма существует не «ради красоты», а чтобы снизить один из рисков: неясность сценариев, неучтённые исключения, конфликт правил, недосказанность интеграции.
Практические мини-кейсы
Кейс A: «Регистрация и логин»
- BPMN: регистрация с подтверждением email/SMS, альтернативы (повторный код, истёкший токен).
- DMN: правила сложности пароля, лимиты попыток.
- OpenAPI: POST /users (идемпотентность?), POST /auth/login, POST /auth/verify.
- Postman: коллекция auth, pre-request генерация X-Correlation-Id.
- SQL: проверка уникальности email/телефона, метрики ошибок логина.
- NFR: p95 регистрации < 2с, рассылка кода < 10с, 99.9% доступности.
Кейс B: «Возврат платежа»
- DMN: правила допустимости возврата (сроки, статусы, суммы).
- OpenAPI: POST /refunds (идемпотентный), GET /refunds/{id}.
- События: RefundRequested/Completed/Failed.
- Observability: метрики refund_error_rate, трассировки, аудит-логи.
- SQL: сверка сумм возвратов с платежами, ловушка двойного списания.
Риски и как их гасить
-
Разрыв Wiki и Git.
— Симптом: в Confluence одно, в репозитории — другое.
— Лечение: «канон» в Git, в Wiki — рендеры/ссылки; линтеры/CI проверяют версии. -
PNG-архитектура (без исходников).
— Симптом: только картинки, править нельзя.
— Лечение: храните исходники (PlantUML/Mermaid/drawio); PR запрещает бинарники без исходника. -
Контракты без ошибок/лимитов/идемпотентности.
— Симптом: дубли/таймауты/нестабильность.
— Лечение: шаблон ошибок, ключи идемпотентности, correlation-id, лимиты/таймауты в SRS/OpenAPI. -
Неформализованные NFR.
— Симптом: «медленно/падает».
— Лечение: p95/throughput/error-rate + SLI/алерты; DoR без NFR — «не готово». -
Тестовые данные отсутствуют.
— Симптом: «только в проде воспроизводится».
— Лечение: каталог тест-данных, генераторы фикстур, маскирование PII.
Вопрос–Ответ
Q1: Можно ли вести SRS целиком в Confluence?
A: Нет. Храните каноничные спецификации (OpenAPI/ER/диаграммы/BDD) в Git. В Confluence — контекст и ссылки/рендеры.
Q2: Чем Swagger UI отличается от ReDoc?
A: Оба рендерят OpenAPI. Swagger UI удобен для «пощупать», ReDoc — для читабельной документации. Держите оба, источник один — openapi.yml.
Q3: Нужен ли Postman, если есть автотесты?
A: Нужен для быстрых проверок/демо/исследований, а также для Newman-регресса по коллекции, пока автотесты не покрыли всё.
Q4: Минимальный SQL для SA?
A: Чтение/джойны/агрегации, оконные функции для сверок и DQ. Без этого сложно валидировать данные и находить причины дефектов.
Q5: Сколько диаграмм делать?
A: Ровно столько, сколько снижает риск. Минимум: BPMN для ключевого потока, Sequence для 1–2 критичных интеграций, ER, C4 L1–L2.
Q6: Можно ли генерировать OpenAPI из кода и не писать руками?
A: Можно, но SA всё равно владеет контрактом: структуру/ошибки/пагинацию/безопасность вы задаёте и ревьюите.
Практика: настроить проектный рабочий стол (за 1–2 дня)
Шаг 1. Confluence/Notion
- Создайте пространство по структуре (см. §2.1).
- Загрузите шаблоны Vision/BRD/SRS/ADR; добавьте блок «Meta» и индекс документов.
Шаг 2. Git-репозиторий /docs
/docs /srs/srs-core.md /api/openapi.yml /events/order-changed.avsc /diagrams/c4-context.mmd /diagrams/checkout.bpmn.drawio /data/er.mmd /bdd/auth.feature /nfr/nfr-catalog.md CHANGELOG.md
- Включите pre-commit: spectral (OpenAPI), линтер Markdown, проверку ссылок.
Шаг 3. Jira/YouTrack
- Добавьте поля: SpecLink, ContractVersion, DataImpact, NFR, TestRef, Dependencies.
- Создайте типы Integration, Non-Functional, Data Contract.
- Заведите DoR/DoD чек-листы.
Шаг 4. Miro/FigJam
- Создайте борд Product X — Models, библиотеку шейпов BPMN/DMN/UML/C4, цветовую схему.
- Экспортируйте первый BPMN «Регистрация» и sequence «Оплата» в Git.
Шаг 5. Postman
- Создайте коллекцию Product X API; среды dev/staging; pre-request для X-Correlation-Id и Idempotency-Key.
- Импортируйте openapi.yml → авто-эндпоинты; сохраните запросы.
Шаг 6. SQL
- Подготовьте sql/checks.sql с 3–5 проверками (дубли идемпотентности, сверка сумм, латентные ошибки).
Критерии готовности практики
- В Wiki есть структура, шаблоны и индекс.
- В Git — openapi.yml, ER/диаграммы, SRS, CHANGELOG, linters.
- В Jira — поля и шаблон Story; DoR/DoD подключены.
- В Miro — минимум 2 диаграммы, ссылки на SRS.
- В Postman — коллекция + среды + автоген заголовков.
- SQL-заготовки лежат в /docs/sql.
Короткая шпаргалка (распечатайте)
- Канон в Git, витрина в Confluence, план в Jira.
- Любая диаграмма ↔ имеет исходник и ссылку на SRS.
- OpenAPI: ошибки/лимиты/идемпотентность/версионирование обязательно.
- Postman: окружения, pre-request, Newman в CI.
- SQL: сверки и DQ — ваша страховка от «тихих» ошибок.
- DoR/DoD: без NFR/observability и тест-данных — «не готово».
