# Системная аналитика ## Общее описание Документ описывает изменения в автоматизированной системе. Пишется системными аналитиками для разработчиков и тестировщиков и проходит согласование с экспертами по архитектуре, безопасности и сопровождению. Документ может описывать как новый процесс, так и инкремент доработки существующей функциональности. ## Требования к заголовкам - Заголовок должен отражать суть раздела. - Заголовок не должен содержать лишнюю информацию, которая относится к метаданным (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` Дополнительные метаданные для случаев изменения существующей документации: - `action` - `target_doc_id` - `target_path` #### 6.x для `ui_page` Обязательная структура: - `### Технический use case (тезисно)` - `### Требования к UI` - `### Функциональные требования` - `### Нефункциональные требования` Требования к разделу `### Требования к UI`: - Внутри нужно отдельно описывать каждую UI-форму. - Если есть интеграция, обязательно описать, как показывается ошибка. - Если показываем список, обязательно описать, как показывается отсутствие данных. Рекомендуемая детализация UI-форм: - табличное представление, - пустой список (empty state), - ошибка (error state). Правила описания UI-полей: - Поля описывать списком (не таблицей). - Общие правила (например, read-only, поведение при пустом значении) выносить в общий блок, не дублировать для каждого поля. Отдельно нужно различать два сценария описания: 1. Если описывается новая UI-страница или новая самостоятельная UI-форма, раздел оформляется полноценно по шаблону `ui_page`. - Нужно дать достаточный контекст для разработки и тестирования. - Нужно подробно описывать структуру формы, состояния отображения, поведение полей, ошибки, empty state и пользовательские действия. 2. Если описывается доработка уже существующей страницы или существующей UI-формы, не нужно повторно копировать полное описание из действующей документации. - Нужно учитывать уже существующее описание страницы в документации и аналитике. - В аналитике нужно явно указать, что именно меняется в существующем сценарии: что добавляется, редактируется или удаляется. - Нужно указывать точку изменения: в какой существующей странице, форме, блоке или сценарии вносится изменение. - Нужно ссылаться на существующий документ или раздел, где базовое поведение уже описано. - Нужно описывать только delta изменений, достаточную для реализации доработки и актуализации документации. - Полное описание существующей страницы в таком разделе не дублируется. - Для такой доработки в metadata нужно явно указывать `action: update`. - Если изменение должно попасть в уже существующий markdown-документ, нужно явно указывать `target_doc_id` и/или `target_path`. - `target_doc_id` должен совпадать с `id` существующего документа, который требуется обновить. - Если `target_doc_id`/`target_path` не указаны, агент может ошибочно интерпретировать раздел как создание нового документа. Нефункциональные требования для `ui_page`: - пользовательская аналитика оформляется таблицей с колонками: - `Название события` - `Описание` - `Точка вызова` - `Payload` #### 6.x для `api_method` Обязательная структура: - `### Технический use case (тезисно)` - `### Функциональные требования` - `### Нефункциональные требования` - `### Контракт метода` Правило для функциональных требований: - Если дополнительных требований нет (дублируют сценарий), писать: `Не выявлены`. Нефункциональные требования: - Разделять на подразделы: - `#### Аудит` (если применимо) - `#### Мониторинг` Для `Мониторинг` использовать таблицу с колонками: - `Метрика` - `Описание` - `Условие срабатывания` Важно: - В мониторинге описывать условия срабатывания, а не «точку измерения = метод». - Базово закладывать 3 метрики: - `_SUCCESS` - `_FAIL` - `_BUSINESS_ERROR` Контракт метода: - Для запроса: таблица параметров (`header/query/path`) с колонками: название, тип параметра, тип данных, обязательность, описание, пример. - Для тела JSON (если есть): структура отдельной таблицей. - Для ответа JSON: таблица с колонками: название, тип данных, обязательность, описание, заполнение, пример. #### 6.x для `logic_block` Обязательная структура: - `### Технический use case (тезисно)` - `### Функциональные требования` - `### Нефункциональные требования` `logic_block` удобно использовать для фиксации точечных изменений существующего сценария, если раздел не описывает новую самостоятельную страницу или новую самостоятельную форму, а только уточняет delta к уже существующей документации. Если точечное изменение должно изменить существующий документ другого типа, `logic_block` для этого использовать нельзя. В этом случае metadata раздела должна указывать тип и идентификатор целевого существующего документа, который требуется обновить. ## Дополнительные правила по слоям - Проверка ролевой модели пользователя обычно выполняется на уровне `ufs`. - Для `pprb` аудит может не фиксироваться, если это правило принято для конкретной фичи/домена. - Если проверка ролей вынесена в `ufs`, не дублировать этот шаг в сценарии `pprb`. ## Термины - Аудит: события, которые фиксируют действия пользователя и позволяют ответить на вопрос «кто, что, когда сделал». - Мониторинг: технические события/метрики для контроля стабильности и поиска сбоев.