324 lines
12 KiB
Markdown
324 lines
12 KiB
Markdown
# Концепция документации (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-слои
|
|
|
|
Это позволяет:
|
|
- точно искать
|
|
- объяснять
|
|
- строить навигацию
|
|
- генерировать и обновлять документацию
|