начало работы построения динамического расписания и документация

2026-04-29 15:42:05 +03:00
parent 813e81be70
commit 8f71b9b2b5
43 changed files with 3894 additions and 457 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -25,7 +25,9 @@
  "message": "OK",
  "token": "550e8400-e29b-41d4-a716-446655440000",
  "role": "ADMIN",
-  "redirect": "/admin/"
+  "redirect": "/admin/",
+  "departmentId": 1,
+  "userId": 1
 }
 ```

@@ -36,7 +38,9 @@
  "message": "Неверное имя пользователя или пароль",
  "token": null,
  "role": null,
-  "redirect": null
+  "redirect": null,
+  "departmentId": null,
+  "userId": null
 }
 ```

@@ -95,7 +99,145 @@

 ---

-## Расписание (Lessons)
+## Динамическое расписание
+
+Новая модель расписания строится из правил (`schedule_rules`) и слотов (`schedule_rule_slots`). Фактические занятия рендерятся на диапазон дат.
+
+### `GET /api/schedule`
+
+Получение расписания группы или преподавателя за период.
+
+**Параметры:**
+
+| Параметр | Обязателен | Описание |
+|----------|------------|----------|
+| `groupId` | Да, если нет `teacherId` | ID учебной группы |
+| `teacherId` | Да, если нет `groupId` | ID преподавателя |
+| `startDate` | Да | Начало периода в формате `YYYY-MM-DD` |
+| `endDate` | Да | Конец периода в формате `YYYY-MM-DD` |
+
+Передаётся ровно один параметр: `groupId` или `teacherId`. Максимальный диапазон — 120 дней.
+
+**Пример:**
+```http
+GET /api/schedule?groupId=1&startDate=2026-04-27&endDate=2026-05-03
+```
+
+**Ответ:**
+```json
+[
+  {
+    "scheduleRuleId": 10,
+    "scheduleRuleSlotId": 31,
+    "date": "2026-04-27",
+    "dayOfWeek": 1,
+    "dayName": "Понедельник",
+    "weekNumber": 13,
+    "parity": "ODD",
+    "timeSlotId": 3,
+    "timeSlotOrder": 3,
+    "startTime": "11:40:00",
+    "endTime": "13:10:00",
+    "subjectId": 1,
+    "subjectName": "Высшая математика",
+    "teacherId": 2,
+    "teacherName": "Петров Препод Петрович",
+    "classroomId": 1,
+    "classroomName": "101 Ленинская",
+    "lessonTypeId": 1,
+    "lessonTypeName": "Лекция",
+    "lessonFormat": "Очно",
+    "subgroupId": null,
+    "groupIds": [1],
+    "groupNames": ["ИВТ-21-1"],
+    "activityType": "THEORY",
+    "totalAcademicHours": 72,
+    "consumedAcademicHoursBeforeLesson": 24,
+    "remainingAcademicHoursAfterLesson": 46
+  }
+]
+```
+
+### `GET /api/admin/time-slots`
+
+Список временных слотов занятий. CRUD доступен по:
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/admin/time-slots` | Список слотов |
+| `POST` | `/api/admin/time-slots` | Создать слот |
+| `PUT` | `/api/admin/time-slots/{id}` | Обновить слот |
+| `DELETE` | `/api/admin/time-slots/{id}` | Удалить слот |
+
+**Тело создания/обновления:**
+```json
+{
+  "orderNumber": 1,
+  "startTime": "08:00:00",
+  "endTime": "09:30:00",
+  "durationMinutes": 90
+}
+```
+
+### Календарный график администратора
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/admin/calendar/years` | Учебные годы с семестрами |
+| `POST` | `/api/admin/calendar/years` | Создать учебный год |
+| `PUT` | `/api/admin/calendar/years/{id}` | Обновить учебный год |
+| `DELETE` | `/api/admin/calendar/years/{id}` | Удалить учебный год |
+| `GET` | `/api/admin/calendar/years/{academicYearId}/semesters` | Семестры учебного года |
+| `POST` | `/api/admin/calendar/years/{academicYearId}/semesters` | Создать семестр |
+| `PUT` | `/api/admin/calendar/semesters/{id}` | Обновить семестр |
+| `GET` | `/api/admin/calendar/holidays?academicYearId=1` | Праздники учебного года |
+| `POST` | `/api/admin/calendar/holidays` | Создать праздник |
+| `PUT` | `/api/admin/calendar/holidays/{id}` | Обновить праздник |
+| `DELETE` | `/api/admin/calendar/holidays/{id}` | Удалить праздник |
+| `GET` | `/api/admin/calendar/matrix?semesterId=1&courseNumber=1&specialtyId=2` | Матрица учебного графика |
+| `PUT` | `/api/admin/calendar/matrix` | Массовое сохранение матрицы |
+
+### `POST /api/admin/schedule-rules`
+
+Создание правила динамического расписания.
+
+```json
+{
+  "subjectId": 1,
+  "semesterId": 1,
+  "activeFromDate": "2026-02-01",
+  "totalAcademicHours": 72,
+  "groupIds": [1, 2],
+  "slots": [
+    {
+      "dayOfWeek": 1,
+      "parity": "BOTH",
+      "timeSlotId": 3,
+      "subgroupId": null,
+      "teacherId": 2,
+      "classroomId": 1,
+      "lessonTypeId": 1,
+      "lessonFormat": "Очно"
+    }
+  ]
+}
+```
+
+CRUD доступен по:
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/admin/schedule-rules` | Список правил, фильтры `semesterId`, `groupId` |
+| `GET` | `/api/admin/schedule-rules/{id}` | Одно правило |
+| `POST` | `/api/admin/schedule-rules` | Создать правило |
+| `PUT` | `/api/admin/schedule-rules/{id}` | Обновить правило |
+| `DELETE` | `/api/admin/schedule-rules/{id}` | Удалить правило |
+
+---
+
+## Расписание (Lessons, deprecated)
+
+Старые эндпоинты ещё физически есть в коде до удаления старых контроллеров и таблиц. Новый просмотр расписания использует `GET /api/schedule`, а новые seed-данные создаются сразу в динамической модели.

 ### `GET /api/users/lessons`