Настройка процесса генерации документации
This commit is contained in:
@@ -0,0 +1,21 @@
|
||||
# API Contract Rules
|
||||
|
||||
## Обязательные части
|
||||
- request parameters (`header/query/path`)
|
||||
- request body (если применимо)
|
||||
- response body
|
||||
- errors
|
||||
- auth
|
||||
- timeout
|
||||
- retry/idempotency (если применимо)
|
||||
|
||||
## Табличный формат
|
||||
Для request/response таблицы должны содержать:
|
||||
- название
|
||||
- тип данных
|
||||
- обязательность
|
||||
- описание
|
||||
- пример
|
||||
|
||||
Для response дополнительно:
|
||||
- заполнение (mapping/логика источника данных)
|
||||
@@ -0,0 +1,17 @@
|
||||
# DB Columns Rules
|
||||
|
||||
## Формат
|
||||
Структура таблицы оформляется таблицей.
|
||||
|
||||
## Обязательные колонки
|
||||
- `Поле`
|
||||
- `Тип`
|
||||
- `Nullable`
|
||||
- `Описание`
|
||||
- `Источник заполнения`
|
||||
- `Использование`
|
||||
|
||||
## Правила
|
||||
- перечислять все ключевые поля таблицы;
|
||||
- для служебных полей (`id`, `created_at`, `updated_at`, `deleted_at`) явно описывать назначение;
|
||||
- если тип или nullable не заданы в аналитике, допускается инженерное предположение с рабочим вариантом.
|
||||
@@ -0,0 +1,16 @@
|
||||
# DB Constraints Rules
|
||||
|
||||
## Что включать
|
||||
- primary key;
|
||||
- unique constraints;
|
||||
- foreign keys;
|
||||
- важные индексы;
|
||||
- бизнес-ограничения на уровне БД.
|
||||
|
||||
## Формат
|
||||
- списком или таблицей;
|
||||
- для каждого индекса и ограничения писать, зачем оно нужно.
|
||||
|
||||
## Правила
|
||||
- если индекс нужен для сценария чтения/пагинации, это должно быть явно сказано;
|
||||
- если точные названия индексов неизвестны, можно использовать осмысленные проектные названия.
|
||||
@@ -0,0 +1,12 @@
|
||||
# DB Table Purpose Rules
|
||||
|
||||
## Что описывать
|
||||
- назначение таблицы;
|
||||
- в каком сценарии она используется;
|
||||
- кто является владельцем данных;
|
||||
- является ли таблица источником истины или производным хранилищем.
|
||||
|
||||
## Формат
|
||||
- 1-3 абзаца без воды;
|
||||
- явно указывать доменную сущность, которую хранит таблица;
|
||||
- если сделаны допущения по БД, фиксировать их отдельной фразой.
|
||||
@@ -0,0 +1,11 @@
|
||||
# DB Usage Rules
|
||||
|
||||
## Что описывать
|
||||
- какие API / logic block / batch job используют таблицу;
|
||||
- какие операции выполняются: read / insert / update / delete;
|
||||
- как таблица участвует в пользовательском сценарии.
|
||||
|
||||
## Правила
|
||||
- ссылки на связанные документы давать по `doc_id` или path;
|
||||
- не дублировать полный use case, а показывать роль таблицы в сценарии;
|
||||
- если таблица используется для пагинации, фильтрации или сортировки, это нужно отметить явно.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Details Rules
|
||||
|
||||
## Назначение
|
||||
Этот файл задает общие правила для секции `## Details`.
|
||||
|
||||
## Правила
|
||||
- `Details` оформляется как `## Details`.
|
||||
- Внутри `Details` используются заголовки уровня `###` и ниже.
|
||||
- Структура `Details` определяется template типа документа.
|
||||
- В `Details` не нужно дублировать навигацию и связи, если они уже есть во frontmatter.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Functional Requirements Rules
|
||||
|
||||
## Формат
|
||||
- `FR.<номер>. <Название>`
|
||||
- Нумерация инкрементальная внутри документа.
|
||||
|
||||
## Правила
|
||||
- FR расширяют шаги сценария.
|
||||
- FR не копируют шаги сценария без добавления новой информации.
|
||||
- Для интеграционных шагов FR обязательны.
|
||||
- Если в сценарии есть вызов внешнего API / сервиса / БД, нужен отдельный FR на интеграцию.
|
||||
|
||||
## FR для интеграционных шагов
|
||||
Для интеграционного FR обязательно раскрывать:
|
||||
- как формируется запрос;
|
||||
- откуда берется каждый значимый атрибут запроса;
|
||||
- какой downstream вызывается;
|
||||
- какой ответ считается успешным;
|
||||
- какие ответы и ситуации считаются бизнес-ошибкой;
|
||||
- какие ситуации считаются технической ошибкой;
|
||||
- как downstream-ответ маппится в контракт текущего слоя.
|
||||
|
||||
## FR для шагов доступа к БД
|
||||
Если шаг читает или пишет БД, FR должен по возможности включать:
|
||||
- таблицу или набор таблиц;
|
||||
- логику фильтрации;
|
||||
- логику сортировки;
|
||||
- логику пагинации;
|
||||
- пример SQL или близкий к рабочему псевдо-SQL.
|
||||
|
||||
Если СУБД и диалект не заданы, допускается сделать рабочее предположение и явно зафиксировать его.
|
||||
@@ -0,0 +1,20 @@
|
||||
# Non-Functional Requirements Rules
|
||||
|
||||
## Для api_method
|
||||
- Подразделы:
|
||||
- `#### Аудит` (если применимо)
|
||||
- `#### Мониторинг`
|
||||
|
||||
## Мониторинг
|
||||
Оформлять таблицей:
|
||||
- `Метрика`
|
||||
- `Описание`
|
||||
- `Условие срабатывания`
|
||||
|
||||
Запрещено:
|
||||
- использовать «точка измерения = метод» вместо условий срабатывания.
|
||||
|
||||
Базовые суффиксы метрик:
|
||||
- `_SUCCESS`
|
||||
- `_FAIL`
|
||||
- `_BUSINESS_ERROR`
|
||||
@@ -0,0 +1,15 @@
|
||||
# SQL Example Rules
|
||||
|
||||
## Назначение
|
||||
Секция показывает пример рабочего SQL для основного сценария использования таблицы.
|
||||
|
||||
## Правила
|
||||
- SQL должен быть близок к рабочему, а не абстрактным псевдокодом;
|
||||
- если диалект БД не указан, допускается выбрать наиболее вероятный вариант и явно зафиксировать допущение;
|
||||
- пример должен отражать реальный сценарий документа: чтение, вставка, обновление или агрегация;
|
||||
- для read-сценариев по возможности показывать фильтрацию, сортировку и пагинацию;
|
||||
- если есть join, нужно кратко пояснить, зачем он нужен.
|
||||
|
||||
## Формат
|
||||
- fenced code block с указанием `sql`;
|
||||
- под кодом 1-3 поясняющих bullets о ключевых условиях, индексах и параметрах.
|
||||
@@ -0,0 +1,10 @@
|
||||
# Summary Rules
|
||||
|
||||
## Назначение
|
||||
Этот файл задает правила для секции `## Summary`.
|
||||
|
||||
## Правила
|
||||
- `Summary` должен быть коротким слоем быстрого контекста.
|
||||
- `Summary` должен объяснять суть документа без длинных деталей.
|
||||
- Предпочтительный формат: краткий список ключевых фактов.
|
||||
- `Summary` не должен дублировать `Details`.
|
||||
@@ -0,0 +1,16 @@
|
||||
# Tech Use Case Rules
|
||||
|
||||
## Обязательные части
|
||||
- название
|
||||
- предусловия
|
||||
- триггер
|
||||
- основной сценарий
|
||||
- альтернативный сценарий
|
||||
- обработка ошибок
|
||||
- постусловие
|
||||
|
||||
## Правила шага
|
||||
- Один шаг = одно предложение до 15-20 слов.
|
||||
- Формат шага: смысловое действие + техническая реализация (endpoint/топик/операция).
|
||||
- Длинные технические детали выносить в FR и ссылаться на FR из шага.
|
||||
- Для интеграционных шагов описание обработки ошибок обязательно.
|
||||
@@ -0,0 +1,22 @@
|
||||
# UI Requirements Rules
|
||||
|
||||
## Структура блока
|
||||
- `### Требования к UI`
|
||||
- Внутри обязательно отдельные формы:
|
||||
- табличное представление
|
||||
- пустой список (empty state)
|
||||
- ошибка (error state)
|
||||
|
||||
## Обязательные правила
|
||||
- Если есть интеграция, обязательно описывать показ ошибки.
|
||||
- Если есть список, обязательно описывать показ отсутствия данных.
|
||||
|
||||
## Описание UI-элементов
|
||||
UI-элементы описываются строго в таблице.
|
||||
|
||||
Обязательные колонки (где применимо):
|
||||
- `Код элемента`
|
||||
- `Название и описание`
|
||||
- `Данные`
|
||||
- `Поведение`
|
||||
- `Валидация`
|
||||
@@ -0,0 +1,7 @@
|
||||
# User Analytics Rules
|
||||
|
||||
События пользовательской аналитики оформлять таблицей:
|
||||
- `Название события`
|
||||
- `Описание`
|
||||
- `Точка вызова`
|
||||
- `Payload`
|
||||
Reference in New Issue
Block a user