архитектура и цели для агентов

2026-07-10 10:28:37 +04:00
parent f561e52aa9
commit 93bfe114c0
46 changed files with 2826 additions and 55 deletions
@@ -0,0 +1,126 @@
+# Контент, клиентские данные и серверная БД
+
+## Источник истины
+
+Пользовательские изменения хранятся в Content Project. Original client data и server DB являются импортируемыми upstream-источниками; generated cache, SQL и packages являются build artifacts.
+
+```text
+upstream snapshot + user content + build profile → validated artifacts
+```
+
+## Структура Content Project
+
+```text
+content/projects/<project>/
+  project.json
+  manifests/
+  maps/
+  placements/
+  creatures/
+  gameobjects/
+  quests/
+  dialogues/
+  loot/
+  encounters/
+  dungeons/
+  localization/
+  scripts/
+  client_assets/
+  tests/
+```
+
+Файлы должны быть детерминированными, Git-friendly, с явными `schema_version`, stable symbolic ID и минимальным шумом форматирования. Generated IDs хранятся в allocation manifest, чтобы две сборки давали одинаковый результат.
+
+## Идентификаторы и ссылки
+
+- Authoring использует symbolic ID вида `quest.my_pack.bandit_problem`.
+- Server numeric entry выделяется allocator-ом по профилю окружения.
+- WoW GUID не используется как content ID.
+- Ссылки типизированы и проверяются до сборки.
+- Удаление сущности с входящими ссылками требует явного cascade/replacement решения.
+
+## Координаты
+
+Определяются отдельные типы `CanonicalWowPosition`, `GodotWorldPosition`, `AdtTileCoordinate`, `AdtChunkCoordinate`, `LocalTilePosition`, orientation и transport-relative position.
+
+Только `CoordinateMapper` выполняет преобразования. Axis swap, origin, handedness, rotation units и scale фиксируются тестовыми golden points. Ручные преобразования в renderer, SQL exporter или gizmo запрещены.
+
+## Server snapshot
+
+Read-only import создаёт versioned snapshot с provenance:
+
+- core family и commit/revision;
+- world/auth/characters schema version;
+- время получения;
+- набор импортированных таблиц;
+- checksum и applied filters.
+
+Snapshot нужен для поиска, ссылок, offline validation и diff. Credentials и персональные данные в snapshot не включаются.
+
+## Каноническая модель и adapters
+
+Редактор работает с `QuestDefinition`, `CreatureTemplate`, `CreatureSpawn`, `GameObjectDefinition`, `LootTable`, `Dialogue`, `Condition`, `EncounterDefinition`. Адаптеры `TrinityCore335` и `AzerothCore335` отвечают за конкретные таблицы, flags, SmartAI/script conventions и capabilities.
+
+Нельзя считать близкие схемы идентичными. Перед записью adapter проверяет fingerprint схемы. Unsupported property выдаёт ошибку или documented degradation, но не игнорируется молча.
+
+## Change set
+
+Build генерирует immutable change set:
+
+- metadata и target profile;
+- preconditions;
+- ordered operations;
+- SQL preview;
+- affected entities/tables;
+- validation report;
+- rollback или описание необратимости;
+- checksum.
+
+Apply сначала выполняет dry-run на disposable/dev DB. Повторное применение должно быть idempotent либо безопасно отклоняться precondition-ом.
+
+## Клиентские данные
+
+Custom locations и mechanics могут требовать согласованных изменений:
+
+- ADT/WDT/WDL, M2/WMO/BLP;
+- DBC overlays;
+- minimap/world map assets;
+- loading screens, audio и localization;
+- server maps, collision, pathfinding/mmaps/vmaps;
+- DB records и scripts.
+
+`ContentBundleManifest` связывает client и server artifacts общей версией. Клиент не входит в мир при несовместимой обязательной версии пакета без понятной диагностики.
+
+## Overlay и модификации
+
+Оригинальные извлечённые файлы не изменяются in-place. Пользовательские пакеты образуют ordered overlay:
+
+```text
+base → core compatibility → project dependencies → user project → local dev override
+```
+
+Конфликт разрешается декларативным priority/dependency rule и показывается в build report. Для коллекций предпочтительны semantic merge operations, а не копирование целой upstream-таблицы.
+
+## Сборка и публикация
+
+Pipeline: `inspect → import → validate → compile → bake → diff → package → verify → publish`.
+
+Каждый шаг:
+
+- детерминирован при одинаковых входах;
+- кешируется по content hash;
+- пишет structured diagnostics;
+- не публикует частичный результат;
+- доступен из Godot Editor и headless CI.
+
+## Миграции форматов
+
+Каждая схема имеет monotonically increasing version. Loader либо мигрирует старую версию с backup, либо открывает read-only. Migration имеет fixture `before → after`, проверку idempotence и documented loss policy.
+
+## Локализация
+
+Текст хранится по locale, отдельно от логики. Validator проверяет placeholders, plural/gender conventions, длины UI, отсутствующие переводы и orphan keys. Fallback locale задаётся профилем и явно отображается в preview.
+
+## Пользовательские scripts
+
+Script assets имеют declared hooks, API version, permissions и deterministic validation. Генерация C++ skeleton для core допустима, но его сборка и deployment являются отдельным артефактом. Editor не обещает выразить любую серверную механику только через визуальный граф.