# Концепция документации (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-слои

Это позволяет:
- точно искать
- объяснять
- строить навигацию
- генерировать и обновлять документацию