Шаблон детальной спецификации

Когда использовать

Для детальных доменных подспек в domains/name/features/feature.md: auth.md, oauth-server.md, lessons.md, billing.md, answers-checking.md, results.md, payroll.md и подобных.

Для обзорных документов используется overview.md.

Frontmatter

---
title: <русский заголовок>
sidebar_label: <короткий>
sidebar_position: <число>
status: active | draft | deprecated
version: v<major>.<minor>
updated: 2026-04-30
owners:
  - <команда>
canonical: true | false
---

Статусы и версии

Поле	Правило
status: active	документ является текущим рабочим контрактом; допускается v0.x, если контракт принят как временный для разработки
status: draft	документ не является обязательным контрактом для разработки без дополнительного review
status: deprecated	документ сохранён только для истории или миграции
version: v0.x	черновая или временная версия структуры
version: v1.0+	стабильный контракт; breaking changes требуют увеличения major

status важнее version: active v0.x означает принятый временный контракт, а draft v1.x — ещё не утверждённый документ.

Структура

# Название

## Зачем нужно

Что делает функция и какую проблему решает.

## Кто использует

| Роль | Что делает |
|---|---|

## Сценарии

Основные пользовательские, преподавательские, административные и системные сценарии.

## Данные

- сущности и поля;
- связи;
- статусы и lifecycle (или ссылка на `state-machines.md`);
- правила хранения и retention.

## Правила

Инварианты, ограничения, бизнес-правила, что запрещено.

## API

- эндпоинты, методы, права;
- DTO request/response (или ссылка на `api-contracts.md`);
- ошибки;
- идемпотентность;
- пагинация и фильтры.

## Серверная часть

- сервисы и модули;
- транзакции;
- очереди и фоновые задачи;
- интеграции с другими доменами (через `integrations/`).

## Интерфейс

- экраны и состояния;
- формы, таблицы, модалки;
- empty states;
- права видимости.

## Интеграции

- что получает, что отдаёт;
- источники истины;
- события (ссылки на `events.md` и `integrations/`).

## Безопасность

- права доступа;
- PII;
- аудит;
- rate limits;
- опасные действия.

## Нестандартные случаи

Пограничные сценарии, ошибки, конфликты, ручные корректировки.

## Готовность

Проверяемые критерии, по которым видно, что функция реализована.

Правила

• Не оставлять пустые разделы — убирать.
• Не дублировать одно правило в нескольких разделах.
• Где есть таблицы, API или UI-состояния — описывать конкретно, а не общими словами.
• Если документ можно передать разработчику без устных пояснений, он достаточно подробен.
• Если после чтения остаётся вопрос «а как это должно работать?», в документе не хватает сценария, правила или нестандартного случая.