186 lines
8.2 KiB
Markdown
186 lines
8.2 KiB
Markdown
# Системная аналитика
|
|
|
|
## Общее описание
|
|
|
|
Документ описывает изменения в автоматизированной системе. Пишется системными аналитиками для разработчиков и тестировщиков и проходит согласование с экспертами по архитектуре, безопасности и сопровождению.
|
|
|
|
Документ может описывать как новый процесс, так и инкремент доработки существующей функциональности.
|
|
|
|
## Требования к заголовкам
|
|
|
|
- Заголовок должен отражать суть раздела.
|
|
- Заголовок не должен содержать лишнюю информацию, которая относится к метаданным (id, doc_type, platform, application и т.д.).
|
|
- Метаданные указываются отдельными строками в теле раздела.
|
|
|
|
## Состав документа
|
|
|
|
Каждый раздел верхнего уровня оформляется заголовком уровня `#`.
|
|
|
|
### 1. Цели
|
|
|
|
- Коротко описать, какую проблему и для кого решаем.
|
|
- 1-2 предложения.
|
|
- Не дублировать критерии приемки.
|
|
|
|
### 2. Процесс AS IS и TO BE
|
|
|
|
- Фокус на пользовательских и бизнес-изменениях.
|
|
- Не указывать технические детали (платформы, API, внутренние интеграции).
|
|
|
|
### 3. Ограничения
|
|
|
|
- Ограничения и допущения в техническом и бизнесовом плане.
|
|
|
|
### 4. Критерии приемки
|
|
|
|
- Описывать с точки зрения пользователя.
|
|
- Не добавлять технические детали (платформы, API, внутренние компоненты).
|
|
|
|
### 5. Архитектура
|
|
|
|
Нужно указать:
|
|
|
|
- схему контейнеров,
|
|
- таблицу интеграций,
|
|
- сквозные интеграционные сценарии.
|
|
|
|
Слои:
|
|
|
|
- `ui` - web-приложение, клиент.
|
|
- `ufs` - BFF: аутентификация/авторизация, агрегация и маппинг данных.
|
|
- `pprb` - backend: API, БД, логика жизненного цикла сущностей.
|
|
|
|
#### Диаграмма
|
|
|
|
Mermaid-диаграмма должна содержать:
|
|
|
|
- основные контейнеры,
|
|
- названия приложений и платформ,
|
|
- интеграции между приложениями,
|
|
- названия вызываемых endpoint или топиков.
|
|
|
|
#### Таблица интеграций
|
|
|
|
Обязательные колонки:
|
|
|
|
- Код
|
|
- Название endpoint/топика
|
|
- Источник данных
|
|
- Потребитель данных
|
|
- Инициатор вызова
|
|
- Передаваемые данные
|
|
|
|
#### Сквозной интеграционный сценарий
|
|
|
|
- Нумерованный список вызовов вида: «Компонент 1 вызывает endpoint в Компонент 2».
|
|
- Только интеграционная цепочка, без детального разбора логики.
|
|
|
|
### 6. Описание изменений
|
|
|
|
Раздел состоит из подразделов уровня `##` (например, `6.1`, `6.2`, `6.3`).
|
|
|
|
Под корнем раздела `# 6` указываются общие метаданные:
|
|
|
|
- `domain`
|
|
- `sub_domain`
|
|
|
|
Для каждого раздела `6.x` обязательно указывать метаданные строками сразу после заголовка:
|
|
|
|
- `id`
|
|
- `doc_type`
|
|
- `application`
|
|
- `platform`
|
|
|
|
#### 6.x для `ui_page`
|
|
|
|
Обязательная структура:
|
|
|
|
- `### Технический use case (тезисно)`
|
|
- `### Требования к UI`
|
|
- `### Функциональные требования`
|
|
- `### Нефункциональные требования`
|
|
|
|
Требования к разделу `### Требования к UI`:
|
|
|
|
- Внутри нужно отдельно описывать каждую UI-форму.
|
|
- Если есть интеграция, обязательно описать, как показывается ошибка.
|
|
- Если показываем список, обязательно описать, как показывается отсутствие данных.
|
|
|
|
Рекомендуемая детализация UI-форм:
|
|
|
|
- табличное представление,
|
|
- пустой список (empty state),
|
|
- ошибка (error state).
|
|
|
|
Правила описания UI-полей:
|
|
|
|
- Поля описывать списком (не таблицей).
|
|
- Общие правила (например, read-only, поведение при пустом значении) выносить в общий блок, не дублировать для каждого поля.
|
|
|
|
Нефункциональные требования для `ui_page`:
|
|
|
|
- пользовательская аналитика оформляется таблицей с колонками:
|
|
- `Название события`
|
|
- `Описание`
|
|
- `Точка вызова`
|
|
- `Payload`
|
|
|
|
#### 6.x для `api_method`
|
|
|
|
Обязательная структура:
|
|
|
|
- `### Технический use case (тезисно)`
|
|
- `### Функциональные требования`
|
|
- `### Нефункциональные требования`
|
|
- `### Контракт метода`
|
|
|
|
Правило для функциональных требований:
|
|
|
|
- Если дополнительных требований нет (дублируют сценарий), писать: `Не выявлены`.
|
|
|
|
Нефункциональные требования:
|
|
|
|
- Разделять на подразделы:
|
|
- `#### Аудит` (если применимо)
|
|
- `#### Мониторинг`
|
|
|
|
Для `Мониторинг` использовать таблицу с колонками:
|
|
|
|
- `Метрика`
|
|
- `Описание`
|
|
- `Условие срабатывания`
|
|
|
|
Важно:
|
|
|
|
- В мониторинге описывать условия срабатывания, а не «точку измерения = метод».
|
|
- Базово закладывать 3 метрики:
|
|
- `<METRIC_NAME>_SUCCESS`
|
|
- `<METRIC_NAME>_FAIL`
|
|
- `<METRIC_NAME>_BUSINESS_ERROR`
|
|
|
|
Контракт метода:
|
|
|
|
- Для запроса: таблица параметров (`header/query/path`) с колонками: название, тип параметра, тип данных, обязательность, описание, пример.
|
|
- Для тела JSON (если есть): структура отдельной таблицей.
|
|
- Для ответа JSON: таблица с колонками: название, тип данных, обязательность, описание, заполнение, пример.
|
|
|
|
#### 6.x для `logic_block`
|
|
|
|
Обязательная структура:
|
|
|
|
- `### Технический use case (тезисно)`
|
|
- `### Функциональные требования`
|
|
- `### Нефункциональные требования`
|
|
|
|
## Дополнительные правила по слоям
|
|
|
|
- Проверка ролевой модели пользователя обычно выполняется на уровне `ufs`.
|
|
- Для `pprb` аудит может не фиксироваться, если это правило принято для конкретной фичи/домена.
|
|
- Если проверка ролей вынесена в `ufs`, не дублировать этот шаг в сценарии `pprb`.
|
|
|
|
## Термины
|
|
|
|
- Аудит: события, которые фиксируют действия пользователя и позволяют ответить на вопрос «кто, что, когда сделал».
|
|
- Мониторинг: технические события/метрики для контроля стабильности и поиска сбоев.
|
|
|