ййй
This commit is contained in:
@@ -0,0 +1,323 @@
|
||||
# Концепция документации (Strong MVP, без связи с кодом)
|
||||
|
||||
## 1. Область применения
|
||||
Документ описывает систему работы с документацией как самостоятельный слой.
|
||||
|
||||
Включает:
|
||||
- текущее состояние (as-is)
|
||||
- целевые сценарии использования
|
||||
- целевую модель документации
|
||||
- расширенный frontmatter
|
||||
- базовую структуру документа `frontmatter + Summary + Details`
|
||||
- RAG-слои (без связи с кодом)
|
||||
|
||||
---
|
||||
|
||||
# 2. Текущее состояние (As-Is)
|
||||
|
||||
## 2.1 Источник истины
|
||||
- Документация хранится в Confluence
|
||||
- Основная модель — иерархия страниц
|
||||
- Навигация через дерево страниц
|
||||
|
||||
## 2.2 Структура и связи
|
||||
- Документы не атомарны
|
||||
- Одна страница содержит несколько тем
|
||||
- Используются перекрестные ссылки между страницами
|
||||
|
||||
## 2.3 Ограничения
|
||||
- Нет типизации документов
|
||||
- Нет структурированного metadata-слоя
|
||||
- Связи не формализованы
|
||||
|
||||
---
|
||||
|
||||
# 3. Целевые сценарии использования
|
||||
|
||||
## 3.1 Поиск документации
|
||||
|
||||
Пользователь формулирует запрос, например: "как работает создание заказа".
|
||||
|
||||
Система должна:
|
||||
- найти релевантные документы
|
||||
- отобрать наиболее точные фрагменты
|
||||
- учитывать тип документа, модуль и сущности
|
||||
|
||||
Результат:
|
||||
- короткий список релевантных документов
|
||||
- возможность перейти в детали
|
||||
|
||||
## 3.2 Объяснение (Explain)
|
||||
|
||||
Пользователь хочет понять:
|
||||
- как работает компонент
|
||||
- что делает API
|
||||
- как устроен процесс
|
||||
|
||||
Система должна:
|
||||
- взять summary документа
|
||||
- дополнить его деталями из Details
|
||||
- дать краткое и точное объяснение без лишнего текста
|
||||
|
||||
## 3.3 Поиск по сущности (Entity Lookup)
|
||||
|
||||
Пользователь ищет:
|
||||
- где используется сущность
|
||||
- какие документы с ней связаны
|
||||
|
||||
Система должна:
|
||||
- найти все документы, где упоминается сущность
|
||||
- показать связи между ними
|
||||
|
||||
## 3.4 Навигация по документации
|
||||
|
||||
Пользователь начинает с одного документа и хочет:
|
||||
- понять контекст
|
||||
- перейти к связанным частям
|
||||
|
||||
Система должна:
|
||||
- использовать parent/children
|
||||
- использовать links
|
||||
- строить осмысленный путь по документации
|
||||
|
||||
## 3.5 Генерация документации
|
||||
|
||||
Система создает новый документ:
|
||||
- по шаблону
|
||||
- с корректным frontmatter
|
||||
- с заполненными разделами `Summary` и `Details`
|
||||
|
||||
Результат:
|
||||
- документ сразу пригоден для использования
|
||||
- соответствует структуре системы
|
||||
|
||||
## 3.6 Актуализация документации
|
||||
|
||||
При изменениях документа:
|
||||
- система должна обновить только нужные части
|
||||
- сохранить структуру
|
||||
- обновить frontmatter и Details
|
||||
|
||||
Результат:
|
||||
- документ остается консистентным
|
||||
- не происходит деградации структуры
|
||||
|
||||
## 3.7 Связывание документации
|
||||
|
||||
При создании или обновлении:
|
||||
- система добавляет связи между документами
|
||||
- формирует граф знаний
|
||||
|
||||
Результат:
|
||||
- документы не изолированы
|
||||
- появляется навигация и reasoning
|
||||
|
||||
---
|
||||
|
||||
# 4. Frontmatter (расширенный контракт)
|
||||
|
||||
```yaml
|
||||
id: api.create_order
|
||||
type: api_method
|
||||
name: create_order
|
||||
title: Create order API
|
||||
|
||||
module: orders
|
||||
layer: application
|
||||
|
||||
status: draft
|
||||
updated_at: 2026-03-20
|
||||
|
||||
tags:
|
||||
- orders
|
||||
- api
|
||||
|
||||
entities:
|
||||
- Order
|
||||
- Cart
|
||||
|
||||
parent: orders_api
|
||||
children: []
|
||||
|
||||
links:
|
||||
- type: related_api
|
||||
target: api.get_order
|
||||
```
|
||||
|
||||
## Назначение ключевых полей
|
||||
|
||||
- `id` — стабильный идентификатор документа
|
||||
- `type` — тип документа
|
||||
- `title` — человекочитаемое имя
|
||||
- `module` — модуль или bounded context
|
||||
- `layer` — слой системы
|
||||
- `status` — состояние документа
|
||||
- `updated_at` — дата последнего обновления
|
||||
- `tags` — фильтрация и поиск
|
||||
- `entities` — база для entity lookup
|
||||
- `parent` / `children` — иерархия
|
||||
- `links` — граф связей
|
||||
|
||||
Все сведения о связях, сущностях и навигации должны храниться во frontmatter.
|
||||
В теле документа отдельные разделы для связей, сущностей и навигации не создаются.
|
||||
|
||||
---
|
||||
|
||||
# 5. Структура документа (целевая)
|
||||
|
||||
Каждый документ состоит из двух смысловых слоев:
|
||||
- frontmatter
|
||||
- контент
|
||||
|
||||
Контент документа всегда состоит из двух обязательных разделов:
|
||||
- `# Summary`
|
||||
- `# Details`
|
||||
|
||||
## 5.1 Общие правила структуры
|
||||
|
||||
- `Summary` и `Details` всегда имеют заголовок уровня `#`
|
||||
- других заголовков первого уровня в документе быть не должно
|
||||
- `Summary` остается кратким и пригодным для explain
|
||||
- `Details` заменяет прежние разделы `Context` и `Основное описание`
|
||||
- внутренняя структура `Details` зависит от типа документа
|
||||
|
||||
## 5.2 Summary
|
||||
|
||||
Краткое описание на 3-6 строк.
|
||||
Используется для explain, краткого ответа и быстрого понимания сути документа.
|
||||
|
||||
## 5.3 Details
|
||||
|
||||
Раздел содержит полное содержательное описание документа.
|
||||
Состав подразделов определяется типом документа.
|
||||
|
||||
---
|
||||
|
||||
# 6. Типовая структура Details для API
|
||||
|
||||
Для документов типа `api_method` раздел `# Details` должен содержать следующие подразделы:
|
||||
|
||||
- `## Описание`
|
||||
- `## Сценарий`
|
||||
- `## Функциональные требования`
|
||||
- `## Нефункциональные требования`
|
||||
- `## Контракт`
|
||||
|
||||
## 6.1 Описание
|
||||
|
||||
Короткое описание сути метода:
|
||||
- какую работу он выполняет
|
||||
- для чего предназначен
|
||||
|
||||
## 6.2 Сценарий
|
||||
|
||||
Сценарий описывается в формате технического use case и включает:
|
||||
- название
|
||||
- предусловия
|
||||
- триггер
|
||||
- основной сценарий
|
||||
- альтернативный сценарий
|
||||
- обработку ошибок
|
||||
- постусловие
|
||||
|
||||
Правила для сценария:
|
||||
- сценарий должен быть лаконичным
|
||||
- сценарий должен быть читаемым человеком
|
||||
- в сценарии фиксируется суть шага, а не полная техническая реализация
|
||||
- если условие можно выразить одним предложением, его допустимо оставить в сценарии
|
||||
- если шаг требует детального описания формирования запроса, обработки ответа или внутренней логики, детали выносятся в функциональные требования
|
||||
|
||||
## 6.3 Функциональные требования
|
||||
|
||||
Функциональные требования описываются как последовательность требований внутри одного документа.
|
||||
|
||||
Формат:
|
||||
- `FR-1`
|
||||
- `FR-2`
|
||||
- `FR-3`
|
||||
|
||||
Правила:
|
||||
- идентификаторы локальны для документа
|
||||
- на них нельзя ссылаться извне как на сквозные идентификаторы
|
||||
- каждое требование описывает отдельный обязательный аспект реализации
|
||||
|
||||
## 6.4 Нефункциональные требования
|
||||
|
||||
Нефункциональные требования описываются аналогично функциональным.
|
||||
|
||||
Формат:
|
||||
- `NFR-1`
|
||||
- `NFR-2`
|
||||
- `NFR-3`
|
||||
|
||||
Детальный формат записи может быть уточнен правилами конкретного проекта.
|
||||
|
||||
## 6.5 Контракт
|
||||
|
||||
Контракт должен быть пригоден для последующей сборки OpenAPI-спецификации.
|
||||
|
||||
Контракт описывает:
|
||||
- входные параметры метода API
|
||||
- выходные параметры
|
||||
- структуру сообщения, как правило JSON
|
||||
- обязательность полей
|
||||
- типы полей
|
||||
- ограничения на размер и формат
|
||||
- назначение полей
|
||||
- правила заполнения полей
|
||||
- примеры данных
|
||||
|
||||
---
|
||||
|
||||
# 7. Базовая структура Details для остальных типов документов
|
||||
|
||||
Для всех типов документов, кроме `api_method`, на текущем этапе обязателен минимум:
|
||||
- `# Summary`
|
||||
- `# Details`
|
||||
|
||||
Дополнительные рекомендации по внутренней структуре `Details` для `logic_block`, `architecture_overview`, `domain_entity` и других типов будут заданы отдельно.
|
||||
|
||||
---
|
||||
|
||||
# 8. RAG слои (только документация)
|
||||
|
||||
## D0 — Чанки документов
|
||||
Полный текст + разбиение.
|
||||
|
||||
## D1 — Каталог документов
|
||||
- `id`
|
||||
- `type`
|
||||
- `title`
|
||||
- `module`
|
||||
- `tags`
|
||||
|
||||
## D2 — Индекс фактов
|
||||
Факты, извлеченные из документов.
|
||||
|
||||
## D3 — Каталог сущностей
|
||||
- сущности
|
||||
- документы, где они используются
|
||||
|
||||
## D4 — Индекс сценариев (Workflow)
|
||||
- последовательности действий
|
||||
- пользовательские сценарии
|
||||
|
||||
## D5 — Граф связей
|
||||
- связи между документами
|
||||
|
||||
---
|
||||
|
||||
# 9. Итог
|
||||
|
||||
Система документации:
|
||||
- атомарные документы
|
||||
- строгий frontmatter
|
||||
- единая структура `Summary + Details`
|
||||
- типовые правила для API-документов
|
||||
- разделенные RAG-слои
|
||||
|
||||
Это позволяет:
|
||||
- точно искать
|
||||
- объяснять
|
||||
- строить навигацию
|
||||
- генерировать и обновлять документацию
|
||||
Reference in New Issue
Block a user