# Системная аналитика

## Общее описание

Документ описывает изменения в автоматизированной системе. Пишется системными аналитиками для разработчиков и тестировщиков и проходит согласование с экспертами по архитектуре, безопасности и сопровождению.

Документ может описывать как новый процесс, так и инкремент доработки существующей функциональности.

## Требования к заголовкам

- Заголовок должен отражать суть раздела.
- Заголовок не должен содержать лишнюю информацию, которая относится к метаданным (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`.

## Термины

- Аудит: события, которые фиксируют действия пользователя и позволяют ответить на вопрос «кто, что, когда сделал».
- Мониторинг: технические события/метрики для контроля стабильности и поиска сбоев.

