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

2026-04-14 16:40:30 +03:00
parent acac19da71
commit 7f22a00696
140 changed files with 3581 additions and 1774 deletions
@@ -0,0 +1,37 @@
+# Documentation Rules V3
+
+Этот каталог содержит правила генерации технической документации из системной аналитики.
+
+## Цель
+- синхронизировать требования к документации с требованиями к аналитике (`04. Analitycs artefacts - features.md`);
+- сохранить детальность техдокументации по сравнению с аналитикой;
+- убрать дублирование структуры и manifest-слоя между разными файлами;
+- собирать итоговый промпт из модулей: глобальные правила + template с manifest + блоки.
+
+## Структура
+- `documentation-rules.md` — верхнеуровневый регламент и порядок сборки.
+- `global/` — общие правила (заголовки, frontmatter, слой ответственности, мост аналитика->документация).
+- `common-elements/` — правила для общих блоков (`summary`, `details`, `use case`, `FR`, `NFR`, `UI`, `Contract`).
+- `templates/` — единственный источник истины для структуры итоговой страницы и manifest-метаданных типа документа.
+
+## Принцип сборки
+Для конкретного документа агент собирает единый набор правил из:
+1. `documentation-rules.md`
+2. `global/*.md`
+3. `templates/<doc_type>.template.md`
+4. `common-elements/*.md`, указанных в frontmatter template
+
+## Правило без дублирования
+- `templates/` отвечают за структуру документа, порядок разделов и manifest-метаданные типа.
+- `common-elements/` отвечают только за правила написания конкретного раздела.
+- отдельный слой `types/` не нужен, если для типа документа используется один основной template.
+
+## Формат template-manifest
+Manifest оформляется в YAML frontmatter самого template.
+
+Обязательные поля manifest:
+- `doc_type`
+- `required_common_elements`
+
+Рекомендуемые поля:
+- `special_rules`
@@ -0,0 +1,21 @@
+# API Contract Rules
+
+## Обязательные части
+- request parameters (`header/query/path`)
+- request body (если применимо)
+- response body
+- errors
+- auth
+- timeout
+- retry/idempotency (если применимо)
+
+## Табличный формат
+Для request/response таблицы должны содержать:
+- название
+- тип данных
+- обязательность
+- описание
+- пример
+
+Для response дополнительно:
+- заполнение (mapping/логика источника данных)
@@ -0,0 +1,17 @@
+# DB Columns Rules
+
+## Формат
+Структура таблицы оформляется таблицей.
+
+## Обязательные колонки
+- `Поле`
+- `Тип`
+- `Nullable`
+- `Описание`
+- `Источник заполнения`
+- `Использование`
+
+## Правила
+- перечислять все ключевые поля таблицы;
+- для служебных полей (`id`, `created_at`, `updated_at`, `deleted_at`) явно описывать назначение;
+- если тип или nullable не заданы в аналитике, допускается инженерное предположение с рабочим вариантом.
@@ -0,0 +1,16 @@
+# DB Constraints Rules
+
+## Что включать
+- primary key;
+- unique constraints;
+- foreign keys;
+- важные индексы;
+- бизнес-ограничения на уровне БД.
+
+## Формат
+- списком или таблицей;
+- для каждого индекса и ограничения писать, зачем оно нужно.
+
+## Правила
+- если индекс нужен для сценария чтения/пагинации, это должно быть явно сказано;
+- если точные названия индексов неизвестны, можно использовать осмысленные проектные названия.
@@ -0,0 +1,12 @@
+# DB Table Purpose Rules
+
+## Что описывать
+- назначение таблицы;
+- в каком сценарии она используется;
+- кто является владельцем данных;
+- является ли таблица источником истины или производным хранилищем.
+
+## Формат
+- 1-3 абзаца без воды;
+- явно указывать доменную сущность, которую хранит таблица;
+- если сделаны допущения по БД, фиксировать их отдельной фразой.
@@ -0,0 +1,11 @@
+# DB Usage Rules
+
+## Что описывать
+- какие API / logic block / batch job используют таблицу;
+- какие операции выполняются: read / insert / update / delete;
+- как таблица участвует в пользовательском сценарии.
+
+## Правила
+- ссылки на связанные документы давать по `doc_id` или path;
+- не дублировать полный use case, а показывать роль таблицы в сценарии;
+- если таблица используется для пагинации, фильтрации или сортировки, это нужно отметить явно.
@@ -0,0 +1,10 @@
+# Details Rules
+
+## Назначение
+Этот файл задает общие правила для секции `## Details`.
+
+## Правила
+- `Details` оформляется как `## Details`.
+- Внутри `Details` используются заголовки уровня `###` и ниже.
+- Структура `Details` определяется template типа документа.
+- В `Details` не нужно дублировать навигацию и связи, если они уже есть во frontmatter.
@@ -0,0 +1,31 @@
+# Functional Requirements Rules
+
+## Формат
+- `FR.<номер>. <Название>`
+- Нумерация инкрементальная внутри документа.
+
+## Правила
+- FR расширяют шаги сценария.
+- FR не копируют шаги сценария без добавления новой информации.
+- Для интеграционных шагов FR обязательны.
+- Если в сценарии есть вызов внешнего API / сервиса / БД, нужен отдельный FR на интеграцию.
+
+## FR для интеграционных шагов
+Для интеграционного FR обязательно раскрывать:
+- как формируется запрос;
+- откуда берется каждый значимый атрибут запроса;
+- какой downstream вызывается;
+- какой ответ считается успешным;
+- какие ответы и ситуации считаются бизнес-ошибкой;
+- какие ситуации считаются технической ошибкой;
+- как downstream-ответ маппится в контракт текущего слоя.
+
+## FR для шагов доступа к БД
+Если шаг читает или пишет БД, FR должен по возможности включать:
+- таблицу или набор таблиц;
+- логику фильтрации;
+- логику сортировки;
+- логику пагинации;
+- пример SQL или близкий к рабочему псевдо-SQL.
+
+Если СУБД и диалект не заданы, допускается сделать рабочее предположение и явно зафиксировать его.
@@ -0,0 +1,20 @@
+# Non-Functional Requirements Rules
+
+## Для api_method
+- Подразделы:
+  - `#### Аудит` (если применимо)
+  - `#### Мониторинг`
+
+## Мониторинг
+Оформлять таблицей:
+- `Метрика`
+- `Описание`
+- `Условие срабатывания`
+
+Запрещено:
+- использовать «точка измерения = метод» вместо условий срабатывания.
+
+Базовые суффиксы метрик:
+- `_SUCCESS`
+- `_FAIL`
+- `_BUSINESS_ERROR`
@@ -0,0 +1,15 @@
+# SQL Example Rules
+
+## Назначение
+Секция показывает пример рабочего SQL для основного сценария использования таблицы.
+
+## Правила
+- SQL должен быть близок к рабочему, а не абстрактным псевдокодом;
+- если диалект БД не указан, допускается выбрать наиболее вероятный вариант и явно зафиксировать допущение;
+- пример должен отражать реальный сценарий документа: чтение, вставка, обновление или агрегация;
+- для read-сценариев по возможности показывать фильтрацию, сортировку и пагинацию;
+- если есть join, нужно кратко пояснить, зачем он нужен.
+
+## Формат
+- fenced code block с указанием `sql`;
+- под кодом 1-3 поясняющих bullets о ключевых условиях, индексах и параметрах.
@@ -0,0 +1,10 @@
+# Summary Rules
+
+## Назначение
+Этот файл задает правила для секции `## Summary`.
+
+## Правила
+- `Summary` должен быть коротким слоем быстрого контекста.
+- `Summary` должен объяснять суть документа без длинных деталей.
+- Предпочтительный формат: краткий список ключевых фактов.
+- `Summary` не должен дублировать `Details`.
@@ -0,0 +1,16 @@
+# Tech Use Case Rules
+
+## Обязательные части
+- название
+- предусловия
+- триггер
+- основной сценарий
+- альтернативный сценарий
+- обработка ошибок
+- постусловие
+
+## Правила шага
+- Один шаг = одно предложение до 15-20 слов.
+- Формат шага: смысловое действие + техническая реализация (endpoint/топик/операция).
+- Длинные технические детали выносить в FR и ссылаться на FR из шага.
+- Для интеграционных шагов описание обработки ошибок обязательно.
@@ -0,0 +1,22 @@
+# UI Requirements Rules
+
+## Структура блока
+- `### Требования к UI`
+- Внутри обязательно отдельные формы:
+  - табличное представление
+  - пустой список (empty state)
+  - ошибка (error state)
+
+## Обязательные правила
+- Если есть интеграция, обязательно описывать показ ошибки.
+- Если есть список, обязательно описывать показ отсутствия данных.
+
+## Описание UI-элементов
+UI-элементы описываются строго в таблице.
+
+Обязательные колонки (где применимо):
+- `Код элемента`
+- `Название и описание`
+- `Данные`
+- `Поведение`
+- `Валидация`
@@ -0,0 +1,7 @@
+# User Analytics Rules
+
+События пользовательской аналитики оформлять таблицей:
+- `Название события`
+- `Описание`
+- `Точка вызова`
+- `Payload`
@@ -0,0 +1,45 @@
+# Documentation Rules V3
+
+## 1. Общий контракт
+- Документация строится на основе системной аналитики, но на более детальном уровне.
+- Заголовки отражают только суть раздела; метаданные в заголовках запрещены.
+- Метаданные указываются во frontmatter и/или отдельными строками в body.
+- Структура документа определяется только template соответствующего типа.
+- Правила написания конкретного раздела определяются только соответствующим `common-elements` файлом.
+- Manifest типа документа хранится во frontmatter соответствующего template.
+
+## 2. Источники требований
+При генерации документа учитывать:
+- `/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/_process/04. Analitycs artefacts - documentation.md`
+- `/Users/alex/Dev_projects_v2/ai driven app process/v2/agent/_process/04. Analitycs artefacts - features.md`
+- правила v2 из `src/app/core/agent/processes/v2/doc_rules_v2`
+
+## 3. Разрыв аналитика vs документация
+- Аналитика: концептуальная, укрупненная.
+- Документация: технически детальная.
+- Технический use case в документации не копирует аналитический 1-в-1, а детализирует его.
+- Функциональные требования расширяют сценарий и не дублируют шаги без новой информации.
+
+## 4. Заполнение пробелов
+Если атрибуты/детали отсутствуют в аналитике:
+1. восстановить из формулировок аналитики;
+2. уточнить по репозиторию (код, контракты, существующие документы);
+3. зафиксировать в документации явно.
+
+## 5. Сборка итогового промпта
+1. Загрузить global-правила.
+2. Загрузить template типа документа.
+3. Прочитать YAML frontmatter template как manifest.
+4. Загрузить общие блоки, указанные в manifest.
+5. Применить body template как единственный источник структуры.
+5. Проверить чек-лист совместимости с аналитикой (domain/sub_domain, роли слоев, интеграции, ошибки).
+
+## 6. Формат manifest типа документа
+Manifest типа документа хранится во frontmatter `templates/<doc_type>.template.md`.
+
+Минимальная схема:
+- `doc_type`
+- `required_common_elements`
+
+Дополнительно можно указывать:
+- `special_rules`
@@ -0,0 +1,10 @@
+# Analytics to Documentation Mapping
+
+## Принцип
+- Системная аналитика задает «что».
+- Документация детализирует «как».
+
+## Маппинг
+- Из раздела архитектуры аналитики переносить контейнеры, интеграции и цепочки вызовов.
+- Из раздела изменений аналитики строить отдельные технические страницы (`ui_page`, `api_method`, `logic_block`).
+- Если в аналитике упрощенный use case, в документации раскрывать полный технический сценарий по правилам `tech-use-case.md`.
@@ -0,0 +1,67 @@
+# Правила определения путей файлов
+
+Текущая happy-path реализация строит путь документа по фиксированному шаблону:
+
+`docs/<domain>/<platform>/<doc_type>/<doc_id>.md`
+
+Пример:
+
+`docs/orders/pprb/ui_page/orders.ui.list.md`
+
+## Источники атрибутов
+
+Для построения пути используются четыре основных атрибута:
+
+- `domain`
+- `application`
+- `platform`
+- `doc_type`
+- `id` как `doc_id`
+
+Если атрибуты явно указаны в подразделе `6.x`, нужно использовать их.
+Если атрибут не указан, он может быть взят из общих метаданных аналитики или определен fallback-логикой.
+
+## Нормализация сегментов
+
+Каждый сегмент пути нормализуется одинаково:
+
+- значение переводится в lowercase;
+- все символы, кроме `a-z`, `0-9`, `.`, `_`, `-`, заменяются на `-`;
+- ведущие и хвостовые `.` и `-` удаляются.
+
+Примеры нормализации:
+
+- `Payment Status` -> `payment-status`
+- `UFS Orders` -> `ufs-orders`
+- `crm.mobile` -> `crm.mobile`
+
+## Значения по умолчанию
+
+Если после нормализации сегмент пустой, используются fallback-значения:
+
+- корневая папка: `domain`, иначе `application`, иначе `common`
+- `platform` -> `web`
+- `doc_type` -> `misc`
+- `doc_id` -> `untitled`
+
+## Что важно в текущей версии
+
+- для корневой папки сначала используется `domain`;
+- если `domain` не задан, используется `application`;
+- `sub_domain` сейчас не участвует в построении пути;
+- операции `create`, `update`, `delete` работают с одним и тем же правилом вычисления пути;
+- специальных исключений для разных типов документов пока нет;
+- отдельные каталоги для `pprb`, `ufs`, `web` задаются только через значение `platform`.
+
+## Практическое правило для агента
+
+Если нужно предложить или определить путь новой страницы, агент должен:
+
+1. определить `application`;
+2. определить `domain`;
+3. определить `platform`;
+4. определить `doc_type`;
+5. определить стабильный `doc_id`;
+6. взять корневую папку как `domain`, а если он пустой, то `application`;
+7. нормализовать все сегменты;
+8. собрать путь по шаблону `docs/<root>/<platform>/<doc_type>/<doc_id>.md`.
@@ -0,0 +1,32 @@
+# Frontmatter Rules
+
+## Обязательные поля
+```yaml
+id: string
+title: string
+doc_type: string
+domain: string
+sub_domain: string
+related_docs: []
+status: string
+```
+
+## Рекомендуемые поля
+```yaml
+tags: []
+entities: []
+source_of_truth: string
+related_code: []
+system_analytics_refs: []
+```
+
+## Body-метаданные для секции изменений
+Под корнем секции изменений указывать:
+- `domain`
+- `sub_domain`
+
+Для каждого подраздела `X.Y` указывать строками:
+- `id`
+- `doc_type`
+- `application`
+- `platform`
@@ -0,0 +1,10 @@
+# Header Rules
+
+## Правила
+- Заголовок описывает только смысл раздела.
+- Не включать в заголовок: `id`, `doc_type`, `application`, `platform`, `domain`, `sub_domain`.
+- Метаданные указываются отдельными строками ниже заголовка или во frontmatter.
+
+## Пример
+- Правильно: `## 6.2 Метод UFS получения списка заказов`
+- Неправильно: `## 6.2 Блок api_method (id=..., platform=ufs)`
@@ -0,0 +1,10 @@
+# Layer Responsibility
+
+- `ui`: отображение, UX, запуск пользовательских сценариев.
+- `ufs`: авторизация/аутентификация, агрегация, маппинг, оркестрация вызовов.
+- `pprb`: API, БД, доменная логика backend.
+
+## Правила согласованности
+- Проверка ролевой модели пользователя обычно фиксируется на уровне `ufs`.
+- Если проверка роли вынесена в `ufs`, в `pprb`-сценарии не дублировать этот шаг.
+- Аудит для `pprb` может отсутствовать, если это явно принято для домена/фичи.
@@ -0,0 +1,34 @@
+---
+doc_type: api_method
+required_common_elements:
+  - common-elements/summary.md
+  - common-elements/details.md
+  - common-elements/tech-use-case.md
+  - common-elements/fr.md
+  - common-elements/nfr.md
+  - common-elements/api-contract.md
+special_rules:
+  - Технический use case детализируется по `common-elements/tech-use-case.md`.
+  - FR расширяют use case и не дублируют шаги сценария без новой информации.
+  - Для интеграционных шагов FR обязательны.
+---
+
+# <title>
+
+## Summary
+Правила оформления: `../common-elements/summary.md`
+
+## Details
+Правила оформления: `../common-elements/details.md`
+
+### Технический use case
+Правила оформления: `../common-elements/tech-use-case.md`
+
+### Функциональные требования
+Правила оформления: `../common-elements/fr.md`
+
+### Нефункциональные требования
+Правила оформления: `../common-elements/nfr.md`
+
+### Контракт
+Правила оформления: `../common-elements/api-contract.md`
@@ -0,0 +1,38 @@
+---
+doc_type: db_table
+required_common_elements:
+  - common-elements/summary.md
+  - common-elements/details.md
+  - common-elements/db-purpose.md
+  - common-elements/db-columns.md
+  - common-elements/db-constraints.md
+  - common-elements/db-usage.md
+  - common-elements/sql-example.md
+special_rules:
+  - Документ описывает одну физическую таблицу БД или materialized view.
+  - Нужно фиксировать назначение таблицы, поля, ограничения, индексы, связи и сценарии использования.
+  - Если точные детали БД не заданы, допустимо сделать рабочие инженерные допущения и явно записать их в документ.
+---
+
+# <title>
+
+## Summary
+Правила оформления: `../common-elements/summary.md`
+
+## Details
+Правила оформления: `../common-elements/details.md`
+
+### Назначение таблицы
+Правила оформления: `../common-elements/db-purpose.md`
+
+### Структура таблицы
+Правила оформления: `../common-elements/db-columns.md`
+
+### Ограничения и индексы
+Правила оформления: `../common-elements/db-constraints.md`
+
+### Использование в сценариях
+Правила оформления: `../common-elements/db-usage.md`
+
+### Пример SQL
+Правила оформления: `../common-elements/sql-example.md`
@@ -0,0 +1,28 @@
+---
+doc_type: logic_block
+required_common_elements:
+  - common-elements/summary.md
+  - common-elements/details.md
+  - common-elements/tech-use-case.md
+  - common-elements/fr.md
+  - common-elements/nfr.md
+special_rules:
+  - Logic block описывает переиспользуемую логику без дублирования UI/API деталей.
+---
+
+# <title>
+
+## Summary
+Правила оформления: `../common-elements/summary.md`
+
+## Details
+Правила оформления: `../common-elements/details.md`
+
+### Технический use case
+Правила оформления: `../common-elements/tech-use-case.md`
+
+### Функциональные требования
+Правила оформления: `../common-elements/fr.md`
+
+### Нефункциональные требования
+Правила оформления: `../common-elements/nfr.md`
@@ -0,0 +1,33 @@
+---
+doc_type: ui_page
+required_common_elements:
+  - common-elements/summary.md
+  - common-elements/details.md
+  - common-elements/tech-use-case.md
+  - common-elements/ui-requirements.md
+  - common-elements/fr.md
+  - common-elements/user-analytics.md
+special_rules:
+  - Для списочных страниц обязательно описывать табличное представление, empty state и error state.
+  - UI-элементы описываются в таблицах по правилам `common-elements/ui-requirements.md`.
+---
+
+# <title>
+
+## Summary
+Правила оформления: `../common-elements/summary.md`
+
+## Details
+Правила оформления: `../common-elements/details.md`
+
+### Технический use case
+Правила оформления: `../common-elements/tech-use-case.md`
+
+### Требования к UI
+Правила оформления: `../common-elements/ui-requirements.md`
+
+### Функциональные требования
+Правила оформления: `../common-elements/fr.md`
+
+### Нефункциональные требования
+Правила оформления: `../common-elements/user-analytics.md`