213 lines
12 KiB
Markdown
213 lines
12 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`
|
|
|
|
Дополнительные метаданные для случаев изменения существующей документации:
|
|
|
|
- `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`.
|
|
|
|
## Термины
|
|
|
|
- Аудит: события, которые фиксируют действия пользователя и позволяют ответить на вопрос «кто, что, когда сделал».
|
|
- Мониторинг: технические события/метрики для контроля стабильности и поиска сбоев.
|