Add foundational phase documentation for mod development

2026-08-19 23:35:30 +03:00
parent 5eabc90d53
commit c27d43f66a
9 changed files with 495 additions and 0 deletions
@@ -0,0 +1,48 @@
+# Фаза 22. Удостоверение пака
+
+## Зависимости
+
+- [Фаза 4](04-create-editor.md) — моды и каталог уже ездят в create
+
+## Зачем
+
+Мод перестаёт быть именем папки. У него появляется название, версия и список паков, без которых он
+не работает, — а у сервера появляется право отказать во внятной форме вместо сломанного каталога.
+
+## Задачи
+
+- [ ] `pack.jsonc` в папке пака: `version` строкой, `requires` списком id. Файла нет — пак
+      по-прежнему валиден: id вместо названия, версия пустая, зависимостей нет
+- [ ] Название пака — ключ по его id в его же `localizations/<lang>.jsonc`; второго способа
+      называть вещи не заводить
+- [ ] `GET /api/mods` принимает `?lang=ru|en` и отдаёт `label`, `version` и `requires` рядом с
+      `id` и `required`
+- [ ] У `core` такой же `pack.jsonc` и такое же название в локалях
+- [ ] Создание школы проверяет, что каждая зависимость выбрана; нет — `400` с кодом и id того,
+      кого не хватает
+- [ ] Порядок загрузки выстраивает сервер: устойчивая топологическая сортировка поверх порядка
+      игрока, `core` всегда первый. Цикл зависимостей — отказ
+- [ ] Разрешённый порядок виден: пишется в лог при старте школы и возвращается в ответе создания
+- [ ] Сейв хранит **разрешённый** порядок паков, чтобы школа поднималась тем же каталогом
+- [ ] Загрузчик пишет предупреждение, когда у конкретного def нет подписи в локали пака
+- [ ] `docs/protocol.md` и [`../design/foundation.md`](../design/foundation.md) правятся тем же
+      коммитом, что и обработчики
+
+## Тесты, без которых фаза не закрыта
+
+- [ ] Пак без `pack.jsonc` виден в списке, id стоит вместо названия
+- [ ] Название приходит на языке запроса, у `core` тоже
+- [ ] Пак с невыбранной зависимостью не создаёт школу; в ответе видно, кого не хватает
+- [ ] Зависимость, выбранная после зависимого, всё равно грузится раньше
+- [ ] Цикл зависимостей — отказ, а не зависание
+- [ ] Def без подписи даёт предупреждение, но не роняет каталог
+
+## Критерий готовности
+
+- В диалоге создания моды подписаны по-человечески, `core` заблокирован как раньше
+- Школа с модом поднимается после перезапуска тем же набором и в том же порядке
+- `dotnet test` и клиентские `npm test` / `run build` проходят
+
+## Стоп
+
+Не грузить DLL. Не давать менять набор модов у живой школы. Не делать UI перестановки паков.