создал систему календарного учебного графика

docs/ACADEMIC_CALENDAR.md

@@ -0,0 +1,76 @@
+# Календарный учебный график
+
+## Назначение
+
+Календарный учебный график хранит правила учебного года в той же логике, что и исходные Excel-таблицы: для каждого курса и каждой даты указывается код активности. Динамическое расписание использует этот график как фильтр: обычные пары выводятся только в дни теоретического обучения.
+
+График нужен, чтобы разные образовательные программы могли иметь разные периоды теории, экзаменов, практики, каникул и нерабочих дней. Несколько групп могут использовать один и тот же график, если они учатся по одной календарной модели.
+
+## Связи данных
+
+Основная цепочка выглядит так:
+
+```text
+специальность -> профиль обучения -> календарный учебный график -> назначение группе
+```
+
+- `specialties` хранит код и название специальности, например `09.03.04`.
+- `specialty_profiles` хранит профили внутри специальности. У одной специальности может быть несколько профилей.
+- `academic_calendars` хранит график профиля, формы обучения и учебного года.
+- `academic_calendar_days` хранит дневную сетку графика по курсу и дате.
+- `student_groups` связана со специальностью и профилем обучения.
+- `student_group_calendar_assignments` назначает группе конкретный график на учебный год.
+
+Группа выбирает не код активности напрямую, а календарный график. Поэтому один график можно назначить нескольким группам.
+
+## Коды активностей
+
+| Код | Значение | Обычные пары |
+|-----|----------|--------------|
+| `Т` | Теоретическое обучение | Да |
+| `Э` | Экзаменационная сессия | Нет |
+| `К` | Каникулы | Нет |
+| `У` | Учебная практика | Нет |
+| `П` | Производственная практика | Нет |
+| `Пд` | Преддипломная практика | Нет |
+| `Н` | Научно-исследовательская работа | Нет |
+| `Г` | Государственная итоговая аттестация | Нет |
+| `Д` | Подготовка выпускной квалификационной работы | Нет |
+| `ПА` | Промежуточная аттестация | Нет |
+| `С` | Самостоятельная работа или специальный период | Нет |
+| `*` | Праздничный или нерабочий день | Нет |
+| `=` | День вне учебного года или пустая ячейка графика | Нет |
+
+Технически разрешение генерации задаётся полем `academic_calendar_activity_types.allow_schedule`. В seed-данных `true` установлен только для `Т`.
+
+## Правило генерации расписания
+
+`ScheduleGeneratorService` при запросе `GET /api/schedule` проверяет календарный график до вывода занятия:
+
+1. Определяется учебный год и семестр даты.
+2. Для группы находится назначение графика на этот учебный год.
+3. По году начала обучения группы вычисляется текущий курс.
+4. В `academic_calendar_days` ищется ячейка для курса и даты.
+5. Если код ячейки разрешает обычные пары, применяются правила `schedule_rules`.
+6. Если код не разрешает пары, день пропускается и академические часы не списываются.
+
+Если график группе не назначен, расписание группы возвращается пустым списком без ошибки. Это сделано намеренно: отсутствие календаря означает, что нет разрешённых дат для генерации.
+
+## Работа администратора
+
+1. В разделе кафедр и специальностей администратор создаёт специальность и её профили.
+2. В разделе групп администратор создаёт группу, выбирая специальность и профиль обучения.
+3. В разделе расписания администратор создаёт учебный год и семестры.
+4. Там же создаётся календарный учебный график: название, учебный год, специальность, профиль, форма обучения и количество курсов.
+5. Администратор открывает сетку графика, заполняет дни вручную или массово через диапазон дат.
+6. В разделе групп администратор назначает календарный график группе на нужный учебный год.
+
+После сохранения графика или назначения группы кэш динамического расписания сбрасывается. Следующий запрос `GET /api/schedule` сразу использует новые правила календаря.
+
+## Особенности модели
+
+- Старый отдельный механизм праздников не используется: праздник хранится кодом `*` в дневной сетке.
+- Дни вне учебного года или пустые периоды Excel хранятся кодом `=`.
+- График привязан к профилю обучения, а не только к коду специальности.
+- Название группы не является уникальным ключом; идентичные названия допустимы, если различаются другие параметры.
+- Excel-импорт в первой реализации не предусмотрен: редактор заполняет данные через сайт.