agent/_process/04. Analitycs artefacts - features.md

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

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

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

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

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

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

Контракт метода:

• Для запроса: таблица параметров (header/query/path) с колонками: название, тип параметра, тип данных, обязательность, описание, пример.
• Для тела JSON (если есть): структура отдельной таблицей.
• Для ответа JSON: таблица с колонками: название, тип данных, обязательность, описание, заполнение, пример.

6.x для logic_block

Обязательная структура:

• ### Технический use case (тезисно)
• ### Функциональные требования
• ### Нефункциональные требования

logic_block удобно использовать для фиксации точечных изменений существующего сценария, если раздел не описывает новую самостоятельную страницу или новую самостоятельную форму, а только уточняет delta к уже существующей документации.

Если точечное изменение должно изменить существующий документ другого типа, logic_block для этого использовать нельзя. В этом случае metadata раздела должна указывать тип и идентификатор целевого существующего документа, который требуется обновить.

Дополнительные правила по слоям

• Проверка ролевой модели пользователя обычно выполняется на уровне ufs.
• Для pprb аудит может не фиксироваться, если это правило принято для конкретной фичи/домена.
• Если проверка ролей вынесена в ufs, не дублировать этот шаг в сценарии pprb.

Термины

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