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

2026-04-14 16:40:30 +03:00
parent 02eaab6bce
commit 88987abaa6
180 changed files with 9397 additions and 33226 deletions
@@ -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` может отсутствовать, если это явно принято для домена/фичи.