add shel

docs/design/schedule.md

@@ -0,0 +1,147 @@
+# Расписание
+
+Договорённость на срез после штата, не текущий код.
+Штат и предметы: [`staffing.md`](staffing.md). Люди: [`people.md`](people.md).
+Типы и карта: [`defs.md`](defs.md). Экран: [`near-term.md`](near-term.md).
+
+Часы из учебного плана раскладываются по дням и кабинетам. Школа впервые начинает **жить по
+времени**: в 10:15 у 5Б математика в кабинете 204, и это видно на карте.
+
+## Зачем это раньше ходьбы
+
+Расписание закрывает дыру, которая тянется с первого среза: в панели локации пустуют «Персонажи»
+и «Сейчас». Заполнить их можно **без системы перемещения** — если урок стоит в расписании, мы
+знаем, кто в кабинете и чем занят. Ни поиска пути, ни шагов по коридору: таблица и часы.
+
+Люди по-прежнему не ходят. Они **находятся** там, где их застало расписание.
+
+## Каркас дня
+
+В `core`, дефом: первый урок в 8:30, до семи уроков, урок 45 минут, перемены по 10 с одной
+большой на 20. Одна смена.
+
+Длина недели — **в настройках**, а не в контенте: пять дней по умолчанию. Это школьное правило,
+а не свойство мира, и его меняют, чтобы посмотреть, что будет.
+
+Каникулы — дефами: осенние, зимние, весенние и лето, диапазонами дат внутри учебного года.
+В каникулы расписание не действует, школа стоит.
+
+## Учебный план
+
+Уже есть: `SubjectDef` знает, в каких параллелях преподаётся предмет и сколько часов в неделю.
+Расписание ничего не решает про количество — только про расстановку.
+
+## Кто его строит
+
+**Сервер, сам, детерминированно** — из учебного плана, назначений и карты. Игрок не раскладывает
+пасьянс на одиннадцать классов; он влияет тем, кого нанял и что назначил.
+
+Но игрок **может править** готовое: передвинуть урок, поменять кабинет.
+
+Отсюда правило, без которого правки будут пропадать: **исправленное игроком закрепляется.**
+Перестроение — а оно случается при каждом найме и назначении — сохраняет закреплённые уроки и
+пересобирает только остальное. Иначе первый же наём стёр бы всю ручную работу.
+
+Снять закрепление игрок может явно; тогда урок снова участвует в общей раскладке.
+
+## Правила раскладки
+
+Четыре запрета, нарушать которые нельзя:
+
+1. **Учитель не в двух местах.** Один человек — один урок в слоте.
+2. **Класс не в двух местах.** Один класс — один урок в слоте.
+3. **Кабинет не занят дважды.** Два класса в одной комнате одновременно невозможны.
+4. **Класс влезает в кабинет.** Учеников не больше, чем мест.
+
+Урок идёт **не обязательно в своём кабинете**. У предмета может быть требование к типу помещения:
+физкультура — в спортзале, информатика — в компьютерном классе. Без требования урок идёт в
+кабинете, закреплённом за классом.
+
+Это и делает карту нужной: один спортзал на одиннадцать классов — узкое место, которое видно в
+расписании, а не в отчёте.
+
+## Некому вести — урока нет
+
+Предмет без учителя не ставится вовсе. В расписании класса на этом месте пусто, а в разделе
+«Управление» предмет числится непокрытым.
+
+Так наём получает прямое последствие: нанял человека, назначил ему предмет — в расписании
+появились уроки. Это единственная обратная связь среза, и она должна быть мгновенной.
+
+То же самое, если часов больше, чем вытягивают нанятые: лишние часы просто не встают.
+
+## Что видит игрок
+
+**В дереве карты** — что происходит в комнате прямо сейчас, скобками рядом с названием:
+
+```
+Этаж 2
+  Кабинет 204 (Математика · 5Б)
+  Кабинет 205 (Физика · 9А)
+  Кабинет 206
+```
+
+Так классы не сливаются в одинаковые строчки: комната подписана тем, что в ней идёт. Пусто —
+значит свободна.
+
+**В панели локации** — «Сейчас» и «Персонажи» наконец не пустуют: урок, класс, учитель.
+
+**В «Управлении»** — расписание класса: сетка «день × урок» на одну параллель.
+
+**В карточке учителя** — его личное расписание: где он и когда. Это же карточка, что и в «Людях»,
+так что расписание видно всюду, где человек открывается.
+
+Общей сетки на всю школу нет: одиннадцать классов на шесть дней не читаются с экрана, а нужны
+они только тому, кто раскладывает вручную, — а раскладывает сервер.
+
+## Где это живёт
+
+Планировщик — **отдельная библиотека**, как `HSchool.People`: зависит от `HSchool.Content`, не
+знает ни Arch, ни ASP.NET, отдаёт простую таблицу. Причина та же, что и с генератором людей: то,
+что строится по детерминированным правилам, проверяется только тестами — «этот штат и эта карта
+дают вот такую раскладку», — а тест не должен поднимать хост.
+
+Расписание сохраняется вместе с составом: оно дешевле пересчитывается, чем восстанавливается, но
+ручные правки восстановить нельзя. Пишется по тем же правилам, что и ростер — при изменении, а не
+по таймеру.
+
+## Советы, которые стоит принять сразу
+
+- Не давать игроку раскладывать всё вручную. Автоматика с правками — это управление; пустая сетка
+  на 66 ячеек — это работа завуча.
+- Не пересобирать расписание на каждый тик. Оно меняется от найма и назначения, а не от времени.
+- Не хранить «кто где сейчас» отдельным состоянием. Это вычисляется из расписания и часов; вторая
+  копия немедленно разойдётся с первой.
+- Не ставить урок, который некому вести. Дыра в расписании честнее, чем урок без учителя.
+- Требование к типу помещения — у предмета, а не у комнаты. Комната не знает, что в ней физкультура.
+
+## Заведомо не сейчас
+
+- Перемещение по карте: люди находятся в комнате, но не идут в неё.
+- Оценки, посещаемость, домашние задания, успеваемость.
+- Замены заболевшего учителя.
+- Вторая смена, деление класса на подгруппы (языки, труд).
+- Четверти, триместры, экзамены.
+- Кружки, продлёнка, всё вне уроков.
+- Предпочтения учителей: «не ставьте мне первым уроком».
+
+## Зафиксировано этим разговором
+
+| Тема | Решение |
+| --- | --- |
+| Кто строит | Сервер, детерминированно, из плана и назначений |
+| Правки игрока | Можно; исправленное закрепляется и переживает перестроение |
+| Каркас дня | `core`: 8:30, до 7 уроков, 45 минут, перемены 10 и одна 20; одна смена |
+| Длина недели | В настройках, пять дней по умолчанию |
+| Каникулы | Дефами, диапазонами дат; в каникулы расписания нет |
+| Учебный план | Часы из `SubjectDef`, расписание их только расставляет |
+| Запреты | Учитель, класс и кабинет — не более одного урока в слоте; класс влезает в кабинет |
+| Место урока | Кабинет класса, если у предмета нет требования к типу помещения |
+| Нет учителя | Урок не ставится; предмет числится непокрытым |
+| Карта | В дереве рядом с комнатой — что и у кого там сейчас |
+| Панель локации | «Сейчас» и «Персонажи» заполняются из расписания |
+| Расписание класса | В разделе «Управление», сетка «день × урок» |
+| Расписание учителя | В его карточке, там же где навыки и семья |
+| Общая сетка школы | Не делаем: её читает только тот, кто раскладывает вручную |
+| Где живёт код | Отдельная библиотека рядом с `HSchool.People` |
+| Люди и место | Находятся по расписанию; ходьбы нет |

docs/design/staffing.md

@@ -0,0 +1,226 @@
+# Наём, предметы и бюджет
+
+Договорённость на следующий срез, не текущий код.
+Люди: [`people.md`](people.md). Типы и карта: [`defs.md`](defs.md).
+Экран игрока: [`near-term.md`](near-term.md). Проекты: [`projects.md`](projects.md).
+
+Первый срез, где игрок **что-то решает**. До сих пор школа собиралась сама: генератор закрывал
+все должности, игрок смотрел. Теперь школа открывается пустой — без единого учителя, — и её
+надо укомплектовать: нанять людей из пула соискателей, раздать им предметы и уложиться в
+выделенные деньги.
+
+Уроков по-прежнему нет. Предмет — это то, что учитель **числится** вести, а не то, что происходит
+в кабинете. Расписание, звонки и оценки — следующий разговор.
+
+## Что меняется в уже принятом
+
+Три решения прошлых срезов приходится поправить. Это не мелочь, поэтому названы отдельно.
+
+| Было | Стало | Почему |
+| --- | --- | --- |
+| Генератор закрывает все должности | Школа стартует без сотрудников | Иначе игроку нечего решать |
+| Кабинет — таблица именованных слотов | Кабинет — число мест | Никто не будет выбирать, какой стул у доски |
+| `PETeacher` — отдельная должность | Должность одна, физкультура — предмет | Иначе на каждый предмет заводится должность |
+
+## Мебель и вместимость
+
+Вместимость по-прежнему **физическая**: в классе не может сидеть больше учеников, чем стоит парт.
+Это не меняется — от неё зависит весь ростер.
+
+Меняется то, как эта мебель задаётся. У кабинета исчезает таблица именованных слотов — «доска»,
+«стол учителя», «стул учителя», «парты» — и остаётся одно число: сколько парт в кабинете.
+Выбирать между стулом и креслом у доски игрок не будет никогда, а таблица из четырёх строк на
+каждый из одиннадцати кабинетов делает редактор нечитаемым.
+
+Именованные слоты **остаются** там, где обстановка действительно разная: столовая, медкабинет,
+кабинет директора, библиотека. Там выбор осмыслен — сколько столов, какая кушетка.
+
+Правило простое: **слоты — там, где есть из чего выбирать; число — там, где важно только сколько.**
+
+## Предметы
+
+Новый вид def — `SubjectDef`. Не навык и не работа: навык — это то, что растёт у ребёнка, работа —
+то, чем занят человек в комнате, а предмет — то, что стоит в дипломе и в нагрузке.
+
+`SubjectDef` описывает:
+
+- **какие навыки развивает и насколько** — список пар «навык + доля»;
+- **в каких параллелях преподаётся**;
+- **сколько часов в неделю** в каждой из них — учебный план.
+
+Часы здесь не задел на расписание, а рабочая величина уже этого среза: из них считается нагрузка
+учителя, а из нагрузки — зарплата. Расписание ([`schedule.md`](schedule.md)) только расставит эти
+часы по дням; сколько их — решает учебный план.
+
+Так «начальные классы» получаются естественно: один предмет, который развивает всё понемногу и
+преподаётся с первой по четвёртую параллель. Дальше идут предметники: математика с пятой по
+одиннадцатую, развивает один навык, но сильно.
+
+```jsonc
+{
+  "defName": "PrimarySchool",
+  "grades": { "min": 1, "max": 4 },
+  "hoursPerWeek": 20,
+  "skills": [
+    { "skill": "Mathematics", "share": 0.3 },
+    { "skill": "RussianLanguage", "share": 0.3 },
+    { "skill": "Literature", "share": 0.2 },
+    { "skill": "Biology", "share": 0.2 },
+  ],
+}
+```
+
+Имена предметов и навыков **намеренно совпадают** там, где это одно и то же слово: `SubjectDef`
+`Mathematics` и `SkillDef` `Mathematics` — разные def'ы разных видов, но подпись у них одна, потому
+что локали ключуются по имени. Это то, что нужно: игрок не должен видеть «Математика (предмет)».
+
+Доли не обязаны давать в сумме единицу — это не проценты, а вес влияния. Ни на что в этом срезе
+они не влияют; они здесь потому, что предмет без ответа на вопрос «что он развивает» не проверишь,
+а дописывать поле позже — значит переписывать весь ванильный контент.
+
+## Учитель
+
+Должность одна — `Teacher`. Предмет не в должности, а в **назначении**: у нанятого учителя
+один предмет или несколько.
+
+Отсюда следует важное: **потребность в учителях больше не берётся из комнат.** Раньше кабинет
+открывал вакансию «учитель», спортзал — «физрук». Теперь кабинет не открывает ничего: он лишь
+место, где идёт урок. Школе нужны не «люди в комнатах», а **покрытие предметов по параллелям** —
+на каждый предмет, преподаваемый в существующих параллелях, нужен хотя бы один учитель.
+
+Нетренерские должности — директор, секретарь, медсестра, библиотекарь, повар — по-прежнему рождаются
+из комнат, как описано в [`defs.md`](defs.md). Их игрок тоже нанимает, но предметов им не назначают.
+
+## Соискатели
+
+Пул соискателей — **общий** список на школу, не «по трое на вакансию».
+
+Соискатель — **полноценный человек** со всеми слоями: тело, навыки, черты, семья. Иначе выбирать
+не из чего: весь смысл в том, чтобы сравнить «математика 78, усидчивый» с «математика 41,
+вспыльчивый».
+
+Соискателем **может оказаться родитель ученика** — и это не частный случай, а естественное
+следствие уже принятого: человек может быть в двух ролях сразу. Нанятый родитель становится
+работником, оставаясь родителем, и никакой второй сущности для него не заводится.
+
+Пул **обновляется раз в неделю и не целиком**. Часть людей уходит — нашли работу в другом месте, —
+часть остаётся искать дальше, приходят новые. Полная замена раз в неделю превращала бы выбор в
+лотерею: понравившийся кандидат исчезал бы, пока игрок думает.
+
+Не нанятый и не ушедший остаётся тем же человеком: с тем же именем, теми же навыками и тем же
+запросом по зарплате. Обновление детерминировано от сида школы и номера недели.
+
+## Деньги
+
+**Баланса нет.** Сверху выделяют фиксированную сумму на зарплаты в месяц — не на счёт, а как
+предел. Ничего не копится, сэкономленное не переносится.
+
+Значит и правило одно: **месячный фонд оплаты не может превысить выделенную сумму.** Выделили
+10 000, наняли одного за 3 000 и второго за 7 000 — всё, больше никого. Не «ушли в минус», не
+«долг», а просто нельзя.
+
+### Сколько просит человек
+
+Соискатель называет **цену часа**. Она складывается из двух вещей:
+
+- **навыки** — сильный предметник стоит дороже слабого;
+- **черты** — самоуверенный просит больше, зажатый меньше, при тех же навыках.
+
+Черта, влияющая на запрос, — это поле у `TraitDef`, а не список фамилий в коде. Мод, добавивший
+«скромный», сразу получает более дешёвого кандидата.
+
+### Сколько он в итоге стоит
+
+Месячная зарплата — **цена часа × недельная нагрузка**. Нагрузка не выдумывается: она следует из
+учебного плана. Назначили человеку математику — он забирает все часы математики во всех
+параллелях, где она преподаётся, и это может оказаться много.
+
+Отсюда два ограничения вместо одного:
+
+- **Деньги.** Фонд оплаты не может превысить выделенную сумму.
+- **Человек.** Никто не может вести больше `MaxWeeklyHours` часов в неделю. Если часов предмета
+  больше, чем вытянет один, нужен второй учитель того же предмета — часы делятся между ними.
+
+Поэтому «нанять посильнее» и «нагрузить одного вместо двоих» — два разных способа потратить один
+фонд, и в этом весь выбор среза. Дешёвый учитель, взявший три предмета, упрётся в часы; дорогой
+с одним предметом съест фонд.
+
+Цифры — шкала цены часа, влияние черт, предел часов — живут в настройках и в `core`, не в коде.
+
+## Старт в выходной
+
+Школа создаётся пустой, и первое, что делает игрок, — нанимает людей. Делать это под тикающие
+часы учебного дня незачем, поэтому дата по умолчанию переезжает с вторника **3 апреля 2012** на
+субботу **31 марта 2012**: у игрока есть выходные, чтобы собрать штат до того, как в понедельник
+придут дети.
+
+Учебный год при этом тот же, ростер не меняется.
+
+## Экран
+
+Не третья вкладка в панели и не модальное окно. Под часами появляется **два верхних раздела**:
+
+| Раздел | Что в нём |
+| --- | --- |
+| **Обзор** | Всё, что есть сейчас: карта / люди слева, просмотр выбранного справа |
+| **Управление** | Деньги, соискатели, штат и назначение предметов |
+
+Верхние разделы, а не вкладки внутри панели, потому что управление — это другой режим работы, а
+не ещё один список. Часы и дата остаются на месте в обоих: наём идёт по игровому времени, пул
+обновляется по неделям, и прятать календарь на время найма нельзя.
+
+Внутри «Управления» та же схема, что и в «Обзоре»: список слева, карточка справа. Карточка
+соискателя — та же карточка человека, что и в «Людях»; он и есть человек, просто пока не ваш.
+
+Сверху — одна строка про деньги: выделено, расписано, свободно. Ниже — непокрытые предметы,
+соискатели и нанятый штат.
+
+## Советы, которые стоит принять сразу
+
+- Не заводить должность на каждый предмет. Иначе `PositionDef` превращается в справочник
+  специальностей, а назначение предмета становится увольнением и повторным наймом.
+- Не делать баланс, пока сверху приходит фиксированная сумма. Баланс — это уже экономика:
+  накопления, долги, проценты. Здесь нужен предел, а предел — одно число.
+- Не обновлять пул целиком. Кандидат, исчезнувший, пока игрок его разглядывал, читается как баг.
+- Не выкидывать не нанятых людей в ростер школы. Соискатель — не сотрудник и не житель школы;
+  в ростер он попадает только при найме.
+- Проверять предел в момент действия, а не в конце месяца. «Нельзя нанять» игрок понимает,
+  «в конце месяца что-то случилось» — нет.
+
+## Заведомо не сейчас
+
+- Само расписание: когда именно идут эти часы. Следующий срез, [`schedule.md`](schedule.md).
+  Здесь предмет — нагрузка в часах, а не событие в кабинете.
+- Уроки, звонки, оценки, посещаемость.
+- Классное руководство: класс закреплён за кабинетом, но не за учителем.
+- Увольнение и уход по собственному желанию.
+- Переговоры о зарплате, повышения, стаж.
+- Любые траты, кроме зарплат: ремонт, закупки, коммуналка.
+- Накопление денег, долги, штрафы.
+- Требования к диплому: любой нанятый может вести любой предмет, вопрос только в его навыке.
+
+## Зафиксировано этим разговором
+
+| Тема | Решение |
+| --- | --- |
+| Старт школы | Без сотрудников вообще; игрок нанимает всех |
+| Стартовая дата | Суббота 31 марта 2012 — выходные на сборку штата |
+| Вместимость класса | По-прежнему физическая: не больше учеников, чем парт |
+| Кабинет | Одно число мест вместо таблицы именованных слотов |
+| Слоты | Остаются там, где обстановка разная: столовая, медкабинет, кабинет директора |
+| Должность учителя | Одна, `Teacher`; `PETeacher` упраздняется |
+| Предмет | Новый `SubjectDef`: какие навыки развивает и в каких параллелях |
+| Начальные классы | Предмет, развивающий всё понемногу, параллели 1–4 |
+| Назначение | У учителя один предмет или несколько |
+| Потребность в учителях | Покрытие предметов по параллелям, а не вакансии в комнатах |
+| Прочие должности | По-прежнему из комнат; игрок нанимает и их |
+| Соискатель | Полноценный человек; может быть родителем ученика |
+| Пул | Общий, обновляется раз в неделю частично, детерминированно |
+| Учебный план | Часы в неделю по параллелям — поле `SubjectDef`, а не задел |
+| Запрос по деньгам | Цена часа: от навыков и от черт (самоуверенный просит больше) |
+| Зарплата | Цена часа × недельная нагрузка из учебного плана |
+| Предел нагрузки | `MaxWeeklyHours` на человека; сверх — нужен второй учитель предмета |
+| Бюджет | Фиксированная сумма в месяц из настроек; баланса нет |
+| Предел | Фонд оплаты не может превысить выделенное; проверка в момент действия |
+| Экран | Два верхних раздела под часами: «Обзор» и «Управление» |
+| Внутри управления | Список слева, карточка человека справа — та же, что в «Людях» |