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,45 @@
+# Фаза 27. Версия сейва и взгляд внутрь
+
+## Зависимости
+
+- [Фаза 2](02-school-worker.md) — сейв и дев-поверхность уже есть
+
+## Зачем
+
+Две дыры в обслуживании. Первая: `Format` в сейве штампуется при записи и копируется при чтении,
+но никогда не сравнивается — файл из будущей версии загрузится молча и будет понят неправильно, а
+места для миграции просто нет. Вторая: посмотреть внутрь живой школы нечем. Всё ревью замеры
+делались временными тестами, потому что другого способа узнать, кто где и с какими нуждами, не
+существует.
+
+## Задачи
+
+- [ ] Загрузка читает `Format`: новее своего — школу не стартовать, файл не трогать, в лог. Как с
+      пропавшей папкой мода
+- [ ] Формат старее своего — явный шов для апгрейда: сегодня пустой, но названный и с комментарием
+- [ ] `GET /api/dev/schools/{id}/dump` — ростер, присутствие, расписание и нужды одним JSON. За тем
+      же переключателем, что и `reload-schools`, и никогда в проде по умолчанию
+- [ ] Дамп читает опубликованные снимки и мейлбокс, а не лезет в `World` мимо работника
+- [ ] Раздел «Things that will bite you» в `AGENTS.md` пополняется тем, что нашло ревью: сид школы
+      был её id; тесты хоста делят один сервер и одну папку сейвов, поэтому начинают с очистки;
+      на паузе кадры присутствия не приходят вовсе
+- [ ] Классы тестов вокруг Arch перестают идти параллельно: `HSchool.Simulation.Tests` получает
+      запрет параллельности, потому что нативная память Arch этого не любит
+- [ ] `docs/protocol.md` описывает дамп в разделе дев-ручек
+
+## Тесты, без которых фаза не закрыта
+
+- [ ] Сейв с `format` больше текущего оставляет школу незапущенной и файл нетронутым
+- [ ] Сейв текущего формата грузится как раньше
+- [ ] Дамп отдаёт людей, их узлы и текущее расписание для живой школы
+- [ ] Дамп неизвестной школы — `404`
+
+## Критерий готовности
+
+- Подсунуть сейв из будущего — сервер стартует, эта школа не поднимается, в логе понятно почему
+- Снять дамп с идущей школы и увидеть, кто где стоит
+- `dotnet test` проходит; полный прогон решения стабилен
+
+## Стоп
+
+Не писать миграции, которых пока не нужно. Не открывать дев-ручки без переключателя.