Настройка процесса генерации документации

2026-04-14 16:40:30 +03:00
parent acac19da71
commit 7f22a00696
140 changed files with 3581 additions and 1774 deletions
@@ -0,0 +1,185 @@
+# Системная аналитика
+
+## Общее описание
+
+Документ описывает изменения в автоматизированной системе. Пишется системными аналитиками для разработчиков и тестировщиков и проходит согласование с экспертами по архитектуре, безопасности и сопровождению.
+
+Документ может описывать как новый процесс, так и инкремент доработки существующей функциональности.
+
+## Требования к заголовкам
+
+- Заголовок должен отражать суть раздела.
+- Заголовок не должен содержать лишнюю информацию, которая относится к метаданным (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`.
+
+## Термины
+
+- Аудит: события, которые фиксируют действия пользователя и позволяют ответить на вопрос «кто, что, когда сделал».
+- Мониторинг: технические события/метрики для контроля стабильности и поиска сбоев.
+