# OpenWC Documentation

Этот каталог — единая точка входа в разработку OpenWC: клиента World of Warcraft 3.3.5a и набора инструментов авторинга внутри Godot Editor.

Исполняемая последовательность текущих целей находится в [`../targets/README.md`](../targets/README.md). Все агенты обязаны следовать корневому [`../AGENTS.md`](../AGENTS.md).

Полная инженерная карта проекта находится в [`../targets/DEVELOPMENT_ROADMAP.md`](../targets/DEVELOPMENT_ROADMAP.md); она раскрывает renderer, protocol, gameplay, UI/Lua/audio, Editor tooling, server emulators и quality/release workstreams.

## Статус документов

Документы описывают целевую архитектуру. Реализованное состояние рендера зафиксировано отдельно в [`../RENDER.md`](../RENDER.md). Если описание целевого решения расходится с кодом, это считается известным архитектурным долгом, а не разрешением обходить границы слоёв.

Нормативные слова `ДОЛЖЕН`, `НЕ ДОЛЖЕН`, `СЛЕДУЕТ` и `МОЖЕТ` задают обязательность решения. Существенные отклонения оформляются Architecture Decision Record (ADR).

## Карта документов

| Документ | Назначение |
|---|---|
| [ARCHITECTURE.md](ARCHITECTURE.md) | Границы модулей, направления зависимостей, runtime и editor |
| [CLIENT_FEATURES.md](CLIENT_FEATURES.md) | Полная карта функций клиента WoW 3.3.5a |
| [GODOT_EDITOR.md](GODOT_EDITOR.md) | Архитектура инструментов внутри Godot Editor |
| [CONTENT_AND_SERVER_DATA.md](CONTENT_AND_SERVER_DATA.md) | Content Project, данные клиента, БД TrinityCore/AzerothCore, сборка и публикация |
| [GAME_DESIGN.md](GAME_DESIGN.md) | Принципы геймдизайна, квестов, локаций, подземелий и баланса |
| [TESTING.md](TESTING.md) | Стратегия тестирования runtime, протокола, рендера и authoring pipeline |
| [ROADMAP.md](ROADMAP.md) | Последовательность вертикальных срезов и критерии готовности |
| [REFERENCES.md](REFERENCES.md) | Использованные локальные reference-проекты и правила работы с ними |
| [TOOLING_CATALOG.md](TOOLING_CATALOG.md) | Реестр готовых библиотек, редакторов, test oracles и кандидатов на интеграцию |
| [GODOT_BEST_PRACTICES.md](GODOT_BEST_PRACTICES.md) | Нормативные правила scenes, data, jobs, rendering, EditorPlugin, profiling и tests |
| [TEAM_WORKFLOW.md](TEAM_WORKFLOW.md) | Ветки/worktree, task claims, ownership, handoff, integration и conflict protocol |
| [DOCUMENTATION_STANDARD.md](DOCUMENTATION_STANDARD.md) | Обязательные API docs, module specs, data-flow/state/sequence diagrams и documentation gate |
| [modules/README.md](modules/README.md) | Реестр фактических модулей и шаблон их спецификаций |
| [CODING_STANDARD.md](CODING_STANDARD.md) | Явные длинные имена, KISS, простота функций/data flow и правила оправданной сложности |

## Обязательный workflow изменения функции

1. Найти функцию в матрице [CLIENT_FEATURES.md](CLIENT_FEATURES.md).
2. Определить владельца данных и границу модуля по [ARCHITECTURE.md](ARCHITECTURE.md).
3. Для контента описать канонические данные и server adapter по [CONTENT_AND_SERVER_DATA.md](CONTENT_AND_SERVER_DATA.md).
4. Для игровых изменений сформулировать player goal, feedback и failure states по [GAME_DESIGN.md](GAME_DESIGN.md).
5. До реализации определить тесты и observability по [TESTING.md](TESTING.md).
6. Выполнить работу вертикальным срезом и обновить статус feature matrix.

## Definition of Done для документации

Изменение считается документированным, если указаны:

- владелец состояния;
- публичные команды, события или read models;
- формат сохранения и версия схемы, если есть данные;
- серверная авторитетность и поведение при рассинхронизации;
- пользовательский сценарий и обработка ошибок;
- автоматические и ручные проверки;
- migration/rollback для изменяемого формата или БД.
