Руководство по документации¶

Полное руководство по написанию и структурированию документации.

Целевая аудитория¶

Вся документация в этом репозитории предназначена исключительно для внутренней команды провайдера.

Что это означает¶

Можно включать внутренние архитектурные решения и их обоснования
Можно описывать детали реализации и технический долг
Можно указывать на известные ограничения и планы по улучшению
Не нужно скрывать сложность или "упрощать для клиента"

Стиль написания¶

Технический, детальный
Предполагает знание контекста проекта
Включает "почему", а не только "что"

1. Архитектура проекта¶

source/
├── product/           # ЧТО делает система (бизнес-логика)
│   ├── integration/   # Интеграция с казино
│   ├── admin/         # Управление операторами
│   ├── instant/       # Instant-игры
│   ├── social/        # Социальные функции
│   └── math/          # Матемодели (таблицы выплат, алгоритмы)
│
└── methodology/       # Правила документирования

> **Note:** Technical documentation (API, DB Schema, Flows) resides in `game-api` repository.
│
└── methodology/       # Правила документирования

2. Принципы¶

Синхронизация¶

Уровень	Описывает	Где
product/	Бизнес-логика, правила игр, мат. модели	docs/content/
game-api	Контракты, алгоритмы, потоки, схемы БД	game-api/

Разрешение конфликтов:

Обнаружено расхождение → определить актуальное состояние
Синхронизировать оба уровня

Разделение слоёв¶

Вопрос	Слой
Что делает система? Зачем?	`product/`
Как это работает? Какие данные?	`game-api`

Абстракция¶

Технический слой использует абстрактные термины:

Вместо	Пишем
Redis	Кеш
Centrifugo	Сервис реального времени
PostgreSQL	База данных

3. Product-документация¶

Содержит:

Концепции и механики
User Stories с Acceptance Criteria
Бизнес-правила (BR-XX)
Состояния и переходы

НЕ содержит:

Таблицы коэффициентов (→ technical/math/)
JSON-схемы API (→ technical/api/)
Sequence diagrams (→ technical/flows/)
Таймауты и коды ошибок

4. Technical-документация¶

API (technical/api/)¶

JSON-схемы запросов/ответов
Коды ошибок
WebSocket-события

Flows (technical/flows/)¶

Sequence diagrams
Сценарии восстановления
Инварианты

Math (technical/math/)¶

Таблицы выплат
Формулы RTP
Алгоритм Provably Fair

Services (technical/services/)¶

Карта сервисов
Зоны ответственности

5. Delta-документирование¶

Каждый документ описывает только то, что он добавляет к зависимостям.

Структура документа¶

# Название

> **Слой:** Product | Technical

## Зависимости

| Концепция  | Источник    | Что берём        |
| ---------- | ----------- | ---------------- |
| [Название] | [ссылка](#) | [что используем] |

## Что добавляет этот документ

- Пункт 1
- Пункт 2
- **Не описывает:** [что не входит в scope]

---

[Основной контент]

Правила ссылок¶

technical/ → ссылается на product/ для бизнес-контекста
product/ → может ссылаться на technical/ для деталей
Не дублировать — ссылаться

6. Дедупликация¶

Когда выносить в общий компонент¶

Критерий	Примеры
Используется в 2+ играх	Статусы ставок
Используется везде	Provably Fair, чат
Логика идентична	История ставок

Когда НЕ выносить¶

Критерий	Примеры
Уникально для одной игры	Выбор чисел (Keno)
Семантика разная	"Результат" в Keno vs "Ранг карты" в Hilo

Правило динамических списков¶

Не перечислять элементы, которые могут измениться.

Плохо	Хорошо
"...игры (Keno, Hilo)..."	"...игры из каталога..."
"Валюты: USD, EUR, RUB"	"Валюты согласно конфигурации"

7. Терминология¶

Термин	Значение
Раунд	Один игровой цикл
Ставка	Денежная сумма игрока
Выигрыш	Зачисляемая сумма
Коэффициент	Множитель ставки
Оператор	Казино-клиент
Провайдер	Мы (поставщик игр)

Явный владелец:

Размытая формулировка	Уточнение
"сервер"	Game Backend / Wallet казино
"система"	Указать конкретного участника

8. Чек-лист ревью¶

Общие требования¶

Документ в правильном слое?
Нет дублирования?
Терминология консистентна?
Нет ссылок на задачи/коммиты/PR?

Product¶

Описывает "что", а не "как"?
Нет JSON-схем, таблиц коэффициентов?
Есть User Stories с Acceptance Criteria?

Technical¶

Абстрактные термины (кеш, не Redis)?
Есть ссылка на product/ для контекста?
Не дублирует бизнес-логику?