docs: Add comprehensive project documentation covering architecture, development, and APIs, and update AGENTS.md.

2026-03-22 02:49:13 +03:00
parent 9e7b35aa0b
commit ec7e615557
10 changed files with 1829 additions and 145 deletions
--- a/docs/BUSINESS_LOGIC.md
+++ b/docs/BUSINESS_LOGIC.md
@@ -0,0 +1,149 @@
+# 📋 Бизнес-логика
+
+## Ролевая модель
+
+Система поддерживает три роли пользователей:
+
+| Роль | Enum | Возможности |
+|------|------|------------|
+| **Администратор** (Деканат) | `ADMIN` | Полный доступ: CRUD пользователей, групп, аудиторий, дисциплин, расписания. Управление тенантами (БД). |
+| **Преподаватель** | `TEACHER` | Просмотр своего расписания. В перспективе — подача заявок на перенос. |
+| **Студент** | `STUDENT` | Только просмотр расписания (Read-only). |
+
+После авторизации пользователь перенаправляется на свой интерфейс:
+- `ADMIN` → `/admin/`
+- `TEACHER` → `/teacher/`
+- `STUDENT` → `/student/`
+
+---
+
+## Управление ресурсами
+
+### Кафедры (Departments)
+
+Организационные единицы университета. К кафедре привязываются пользователи, группы и дисциплины.
+
+- Имеют уникальный числовой `code`
+- Предзаполнены: «Кафедра ИБ», «Кафедра ВТ», «Кафедра КТ»
+
+### Специальности (Specialties)
+
+Учебные направления с кодом по ФГОС.
+
+- Примеры: «Информационная безопасность» (10.03.01), «Программная инженерия» (09.03.04)
+
+### Формы обучения (Education Forms)
+
+Уровни/формы обучения для привязки к группам.
+
+- Предзаполнены: Бакалавриат, Магистратура, Специалитет
+- Нельзя удалить форму обучения, если к ней привязаны группы
+
+### Учебные группы (Student Groups)
+
+- **Поля:** Название (уникальное), численность, форма обучения, кафедра, курс (1–6)
+- **Подгруппы:** Возможно деление группы на подгруппы (таблица `subgroups`)
+
+### Аудитории (Classrooms)
+
+- **Поля:** Название (уникальное), вместимость (> 0), корпус, этаж, доступность
+- **Оборудование:** К каждой аудитории привязывается список оборудования (Many-to-Many) с указанием количества
+- **Статус:** Флаг `is_available` для блокирования назначения пар
+
+### Оборудование (Equipments)
+
+Каталог оборудования для привязки к аудиториям.
+
+- Предзаполнены: Проектор, ПК, Лаборатория, Интерактивная доска, Документ-камера, Аудиосистема
+- Уникальность по названию
+
+### Дисциплины (Subjects)
+
+- **Поля:** Название (уникальное), код, кафедра, описание
+- Привязка преподавателей через `teacher_subjects` (Many-to-Many)
+
+---
+
+## Логика расписания
+
+### Сущность «Занятие» (Lesson)
+
+Каждая запись в расписании содержит:
+
+| Поле | Описание | Пример |
+|------|----------|--------|
+| `teacher_id` | Преподаватель | 2 |
+| `group_id` | Учебная группа | 1 |
+| `subject_id` | Дисциплина | 3 |
+| `lesson_format` | Формат проведения | `Очно`, `Онлайн` |
+| `type_lesson` | Тип занятия | `Лекция`, `Практическая работа`, `Лабораторная работа` |
+| `classroom_id` | Аудитория | 1 |
+| `day` | День недели | `Понедельник` ... `Суббота` |
+| `week` | Чётность недели | `Верхняя`, `Нижняя`, `Обе` |
+| `time` | Временной слот | `8:00 - 9:30` |
+
+### Временны́е слоты
+
+Система использует 7 фиксированных слотов по 90 минут:
+
+| № | Время |
+|---|-------|
+| 1 | 08:00 – 09:30 |
+| 2 | 09:40 – 11:10 |
+| 3 | 11:40 – 13:10 |
+| 4 | 13:30 – 15:00 |
+| 5 | 15:00 – 16:30 |
+| 6 | 16:40 – 18:10 |
+| 7 | 18:30 – 20:00 |
+
+### Валидация при создании/обновлении
+
+- **Дни:** только `Понедельник` – `Суббота` (`DayAndWeekValidator`)
+- **Недели:** только `Верхняя`, `Нижняя`, `Обе`
+- **Формат:** только `Очно`, `Онлайн` (`TypeAndFormatLessonValidator`)
+- **Тип:** только `Лекция`, `Практическая работа`, `Лабораторная работа`
+- Все ID (преподаватель, группа, дисциплина, аудитория) обязательны и не могут быть 0
+
+### Данные к составлению расписания (Schedule Data)
+
+Таблица `schedule_data` хранит **плановую нагрузку** для составления расписания:
+
+| Поле | Описание |
+|------|----------|
+| `department_id` | Кафедра |
+| `semester` | Номер семестра |
+| `group_id` | Учебная группа |
+| `subjects_id` | Дисциплина |
+| `lesson_type_id` | Тип занятия |
+| `number_of_hours` | Количество часов |
+| `is_division` | Деление на подгруппы |
+| `teacher_id` | Преподаватель |
+| `semester_type` | Тип семестра (Весенний / Осенний) |
+| `period` | Учебный год (напр. `2024/2025`) |
+
+---
+
+## Привязка преподаватель ↔ дисциплина
+
+Связь Many-to-Many через таблицу `teacher_subjects`:
+- Указывается, какие дисциплины может вести конкретный преподаватель
+- Дополнительные поля: `qualification_level`, `experience_years`
+
+Дополнительная связь через `teacher_lesson_types`:
+- Определяет, какие **типы занятий** (лекция, практика, лаба) может вести преподаватель по конкретной дисциплине
+
+---
+
+## Бизнес-правила (планируемые)
+
+> **Примечание:** Следующие правила описаны в требованиях, но пока не полностью реализованы в коде.
+
+### Проверка конфликтов
+- **Критический конфликт:** Преподаватель не может одновременно находиться в двух разных аудиториях
+- **Исключение:** Преподаватель может вести несколько пар одновременно (потоковая лекция), если все группы в одной аудитории
+- **Вместимость:** Суммарная численность всех групп в слоте не должна превышать вместимость аудитории
+
+### Управление инцидентами
+- Регистрация отсутствия преподавателя (болезнь, командировка) с указанием периода
+- Автоматическая подсветка конфликтующих пар (Red Zone)
+- Resolution Wizard: предложение замены преподавателя или переноса занятия