Update design documentation to clarify the structure and relationships of game elements. Enhance the definitions of TerritoryDef, BuildingDef, and FloorDef, and introduce new concepts like Patch for modifying definitions. Revise the near-term design to outline the UI structure and interactions, ensuring a clear framework for future development phases.

2026-08-18 13:41:35 +03:00
parent d96b420133
commit bc9a33e67f
9 changed files with 337 additions and 105 deletions
@@ -2,38 +2,27 @@

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

- [Фаза 0](00-drop-pixi.md) — не обязательно технически, но логично закрыть первой
+- [Фаза 0](00-drop-pixi.md) — логично закрыть первой

 ## Зачем

-Сейчас внутри школы только часы и кнопки скорости. Дальше туда поедут списки, а не холст.
-Нужен каркас панелей, чтобы следующий срез (локации, события) садился в готовые места, а не
-ломал вёрстку часов.
-
-Пока нет ответа, **что** лежит в дереве и в ленте, фаза рисует пустые панели с подписями и
-сохраняет часы/паузу/скорость. Это не игра, это экран, в который игра въедет.
-
-## Советы по укладке (не задачи, пока не закрыт дизайн)
-
- Выбор узла дерева на этом шаге можно держать **на клиенте**: сервер ещё не шлёт карту.
-  Когда появится симуляция локаций, решить отдельно, фильтр это или `OpenLocation`.
- Не слать дерево 20 раз в секунду. Часы уже едут по сокету; списки и события — когда меняются
-  (отдельные кадры или редкий снимок). Иначе меню-карточки повторятся внутри школы.
- Строки UI — через `t(...)`, как остальной клиент.
+Сейчас внутри школы только часы. Нужны места под дерево, события и локацию — с теми секциями,
+которые уже закрыты в срезе, даже если списки пустые.

 ## Задачи

- [ ] На экране школы три области: дерево карты, общие события, выбранная локация — плюс текущие часы и управление временем
- [ ] Пока нет данных с сервера, панели показывают пустое состояние (не ломаются)
- [ ] Переключение языка обновляет подписи панелей
+- [ ] Три области: дерево карты, общие события, выбранная локация — плюс часы и скорость
+- [ ] События: заголовок и пустое состояние, без выдуманных записей
+- [ ] Локация: секции имя, предметы, персонажи, действия на месте, должности — пустые, не ломаются
+- [ ] Клик по дереву переключает панель локации на клиенте (пока узлы-заглушки или пустое дерево)
+- [ ] Переключение языка обновляет подписи панелей и пустых состояний (`t(...)`)

 ## Критерий готовности

- Можно открыть школу и увидеть каркас менеджера рядом с работающими часами
- Нет регрессии паузы и скоростей
- Клиентские тесты и `npm --prefix src/HSchool.Client run build` проходят
+- Школу можно открыть, часы и пауза работают как раньше
+- Видны пустые панели среза
+- `npm --prefix src/HSchool.Client test` и `run build` проходят

 ## Стоп

-Не наполнять панели выдуманными учениками и комнатами. Наполнение идёт из defs и карты
-([`../design/defs.md`](../design/defs.md)), когда закроются открытые вопросы там.
+Не наполнять персонажами и событиями. Данные — с фазы 4.
@@ -0,0 +1,32 @@
+# Фаза 2. Работник школы и диск
+
+## Зависимости
+
+Нет по коду клиента. Ломает текущий общий `GameLoopService`.
+
+## Зачем
+
+Основа среза: каждая школа — свой поток, свой Arch `World`, свой файл. Пока ещё можно обойтись
+часами без карты — сейв расширится в фазе 3, формат закладывать расширяемым.
+
+## Задачи
+
+- [ ] Супервизор держит ящики `id →` очередь; не трогает `World`
+- [ ] У школы выделенный поток (`LongRunning`), свой таймер фиксированного шага, свой `World`
+- [ ] Команды create/delete/open/close/running/speed идут в ящик, не в общий цикл
+- [ ] Меню читает опубликованные снимки, как сейчас, без блокировки работника
+- [ ] Кадры часов по-прежнему из работника в outbox соединения
+- [ ] Сейв на диск: имя, id, часы, running, speedIndex; запись при create/delete, shutdown, редкий снимок часов (не 20 Гц)
+- [ ] Старт процесса поднимает школы с диска
+- [ ] Обновить инвариант в `AGENTS.md`: трогает школу только её работник
+- [ ] Тесты AppHost: create → рестарт хоста (или явный reload) → школа на месте с тем же временем с разумной погрешностью снимка
+
+## Критерий готовности
+
+- `dotnet test` проходит
+- Две школы тикают независимо (пауза одной не останавливает часы другой — уже так по симуляции; поток не должен это ломать)
+- После перезапуска сервера список школ не пустой, если их создали
+
+## Стоп
+
+Не грузить defs в этой фазе. Не писать файл каждый тик.
@@ -0,0 +1,34 @@
+# Фаза 3. Каталог def и карта
+
+## Зависимости
+
+- [Фаза 2](02-school-worker.md) — каталог и раскладка живут у работника школы
+
+## Зачем
+
+Типы в JSONC, инстанс карты в школе, валидация связности. Без этого нечему редактировать в create.
+
+## Задачи
+
+- [ ] Проект `HSchool.Content` (+ тесты): JSONC, defs, локали, граф карты, валидация. Не Arch, не ASP.NET
+- [ ] Загрузчик пачки документов (сервер потом подставит папки `mods/`)
+- [ ] `core` всегда первый; дальше моды по списку; повтор `defName` / ключа локали — последний победил, warning в лог
+- [ ] Резолв ссылок `ThingDef.actions`, слотов RoomDef после чтения всего набора
+- [ ] Карта-инстанс: двор (TerritoryDef) всегда есть; здания (BuildingDef), этажи (FloorDef + id), помещения, двусторонние рёбра
+- [ ] Валидация: неизвестный def, ребро в никуда, несвязный граф, изолированный узел
+- [ ] Пустая комната допустима; должности для панели — из def узла, если они там есть
+- [ ] Каталог замораживается на работнике при create/load; сейв хранит id модов и раскладку, не развёрнутый каталог
+- [ ] Нет папки мода из сейва — школу не стартовать, файл не удалять, в лог
+- [ ] Обновить ориентир в `AGENTS.md` (куда класть defs)
+- [ ] Наследование: `parent`, `abstract`, замена полей, запрет цикла и чужого вида, abstract нельзя на карту
+- [ ] Патчи из `patches/`: add / replace / remove по JSON Pointer; неизвестный op или нет target — ошибка каталога
+- [ ] Тесты Content: фикстуры JSONC, last-wins, parent/abstract, патч add в actions, связность, пустая комната, одна комната без двора — отказ
+
+## Критерий готовности
+
+- `dotnet test` покрывает загрузчик и валидацию без хоста (`HSchool.Content.Tests`)
+- Ванильная раскладка `mods/core/maps/default.jsonc` проходит валидацию
+
+## Стоп
+
+Не UI редактора. Не исполнение ActionDef. Не xpath и не новые op сверх add/replace/remove.
@@ -0,0 +1,34 @@
+# Фаза 4. Моды и редактор в create
+
+## Зависимости
+
+- [Фаза 1](01-manager-shell.md)
+- [Фаза 3](03-defs-map.md)
+
+## Зачем
+
+Игрок выбирает моды, правит или стирает дефолтную карту, создаёт школу. Внутри школы дерево и
+панель локации читают снимок, не заглушки.
+
+## Задачи
+
+- [ ] `GET` списка модов: `core` как обязательный, остальные папки `mods/`
+- [ ] `GET` каталога с `?lang=ru|en` (типы + локали) для `core` + выбранных id
+- [ ] Hello несёт тот же locale; снимок карты при OpenSchool на этом языке
+- [ ] `POST /api/schools` принимает доп. моды и раскладку; сервер всегда подставляет `core` первым и валидирует
+- [ ] В диалоге создания: чекбоксы модов (`core` нельзя снять), редактор дерева/связей/слотов или сброс к дефолту
+- [ ] При `OpenSchool` — один снимок карты (дерево + локации: имя, предметы, пустые персонажи и действия на месте, должности). Не на каждый клик, не 20 Гц
+- [ ] Клиент фильтрует выбранный узел; часы как сейчас
+- [ ] Протокол/HTTP описать в `docs/protocol.md` в том же коммите, что кодек
+- [ ] Тесты API: create с картой, отказ на дырявый граф, открытие отдаёт снимок
+
+## Критерий готовности
+
+- Создать школу с ванильной картой и с упрощённой своей
+- Открыть: дерево кликается, локация показывает имя/предметы/должности, персонажи и действия на месте пустые, события пустые
+- Перезапуск сервера поднимает эту школу с той же раскладкой
+- `dotnet test` и клиентский `npm test` / `build` проходят
+
+## Стоп
+
+Не приказы «сесть». Не лента событий. Не `OpenLocation` на сервер.
@@ -1,15 +1,18 @@
-# Фазы ближайшего горизонта
+# Фазы первого среза

 Индекс. Статус: ⬜ не начата, 🔄 в работе, ✅ готова.

-Дизайн игрока: [`../design/near-term.md`](../design/near-term.md).
-Defs и карта: [`../design/defs.md`](../design/defs.md).
-Потоки: [`../design/runtime.md`](../design/runtime.md).
+Дизайн закрыт: [`../design/near-term.md`](../design/near-term.md),
+[`../design/defs.md`](../design/defs.md),
+[`../design/runtime.md`](../design/runtime.md),
+[`../design/projects.md`](../design/projects.md).
+
+Новых игровых фич в эти фазы не добавлять. 1 и 2 можно вести параллельно (клиент / сервер).

 | Фаза | Статус | Зачем |
 | --- | --- | --- |
-| [0. Убрать PixiJS](00-drop-pixi.md) | ⬜ | Зависимость была под сцену, которой не будет |
-| [1. Оболочка менеджера](01-manager-shell.md) | ⬜ | Каркас экрана школы под дерево / события / локацию |
-| Работник на школу (поток + свой World) | — | Ломает текущий общий цикл; делать до тяжёлой симуляции |
-| Каталог def + ванильная карта | — | Загрузчик JSONC, локали мода, связность карты |
-| Моды и редактор при создании | — | Список `mods/`, выбор, раскладка в POST create |
+| [0. Убрать PixiJS](00-drop-pixi.md) | ⬜ | Сцена не планируется |
+| [1. Оболочка менеджера](01-manager-shell.md) | ⬜ | Панели с секциями среза, пока без данных |
+| [2. Работник школы и диск](02-school-worker.md) | ⬜ | Поток + World + сейв — основа |
+| [3. Каталог def и карта](03-defs-map.md) | ⬜ | JSONC, core, валидация раскладки |
+| [4. Моды и редактор в create](04-create-editor.md) | ⬜ | Выбор модов, карта в POST, снимок при открытии |