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

2026-04-30 23:40:49 +03:00
parent 96e9d8155f
commit 89c822a073
56 changed files with 3356 additions and 1644 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -101,7 +101,7 @@

 ## Динамическое расписание

-Новая модель расписания строится из правил (`schedule_rules`) и слотов (`schedule_rule_slots`). Фактические занятия рендерятся на диапазон дат.
+Новая модель расписания строится из правил (`schedule_rules`) и слотов (`schedule_rule_slots`). Фактические занятия рендерятся на диапазон дат только для дней, где календарный учебный график группы имеет код, разрешающий обычные пары.

 ### `GET /api/schedule`

@@ -116,7 +116,7 @@
 | `startDate` | Да | Начало периода в формате `YYYY-MM-DD` |
 | `endDate` | Да | Конец периода в формате `YYYY-MM-DD` |

-Передаётся ровно один параметр: `groupId` или `teacherId`. Максимальный диапазон — 120 дней.
+Передаётся ровно один параметр: `groupId` или `teacherId`. Максимальный диапазон — 120 дней. Если у группы нет назначения календарного графика на учебный год даты, расписание для неё возвращается пустым списком.

 **Пример:**
 ```http
@@ -150,7 +150,7 @@ GET /api/schedule?groupId=1&startDate=2026-04-27&endDate=2026-05-03
    "subgroupId": null,
    "groupIds": [1],
    "groupNames": ["ИВТ-21-1"],
-    "activityType": "THEORY",
+    "activityType": "Т",
    "totalAcademicHours": 72,
    "consumedAcademicHoursBeforeLesson": 24,
    "remainingAcademicHoursAfterLesson": 46
@@ -179,7 +179,7 @@ GET /api/schedule?groupId=1&startDate=2026-04-27&endDate=2026-05-03
 }
 ```

-### Календарный график администратора
+### Учебные годы, семестры и коды календарного графика

 | Метод | URL | Назначение |
 |-------|-----|------------|
@@ -190,12 +190,59 @@ GET /api/schedule?groupId=1&startDate=2026-04-27&endDate=2026-05-03
 | `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` | Массовое сохранение матрицы |
+| `GET` | `/api/admin/calendar/activity-types` | Справочник кодов активностей графика |
+| `POST` | `/api/admin/calendar/activity-types` | Создать код активности |
+| `PUT` | `/api/admin/calendar/activity-types/{id}` | Обновить код активности |
+| `DELETE` | `/api/admin/calendar/activity-types/{id}` | Удалить код активности |
+
+**Тело создания/обновления кода активности:**
+```json
+{
+  "code": "Т",
+  "name": "Теоретическое обучение",
+  "allowSchedule": true,
+  "colorCode": "#22c55e",
+  "displayOrder": 10,
+  "description": "Обычные пары разрешены"
+}
+```
+
+### Календарные учебные графики
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/admin/academic-calendars` | Список графиков, фильтры `academicYearId`, `specialtyId`, `profileId` |
+| `GET` | `/api/admin/academic-calendars/study-forms` | Формы обучения графика |
+| `GET` | `/api/admin/academic-calendars/{id}` | Один график |
+| `POST` | `/api/admin/academic-calendars` | Создать график |
+| `PUT` | `/api/admin/academic-calendars/{id}` | Обновить график |
+| `DELETE` | `/api/admin/academic-calendars/{id}` | Удалить график |
+| `GET` | `/api/admin/academic-calendars/{id}/grid` | Дневная сетка графика |
+| `PUT` | `/api/admin/academic-calendars/{id}/grid` | Полное сохранение дневной сетки |
+
+**Тело создания/обновления графика:**
+```json
+{
+  "title": "09.03.04 очная форма 2025-2026",
+  "academicYearId": 1,
+  "specialtyId": 2,
+  "specialtyProfileId": 3,
+  "studyFormId": 1,
+  "courseCount": 4
+}
+```
+
+**Ячейка сетки графика:**
+```json
+{
+  "calendarId": 1,
+  "courseNumber": 1,
+  "date": "2025-09-01",
+  "weekNumber": 1,
+  "dayOfWeek": 1,
+  "activityTypeId": 1
+}
+```

 ### `POST /api/admin/schedule-rules`

@@ -274,6 +321,10 @@ CRUD доступен по:
 | `POST` | `/api/specialties` | Создать специальность |
 | `PUT` | `/api/specialties/{id}` | Обновить специальность |
 | `DELETE` | `/api/specialties/{id}` | Удалить специальность |
+| `GET` | `/api/specialties/{id}/profiles` | Профили выбранной специальности |
+| `POST` | `/api/specialties/{id}/profiles` | Создать профиль |
+| `PUT` | `/api/specialties/{id}/profiles/{profileId}` | Обновить профиль |
+| `DELETE` | `/api/specialties/{id}/profiles/{profileId}` | Удалить профиль |

 **Тело создания/обновления:**
 ```json
@@ -283,6 +334,16 @@ CRUD доступен по:
 }
 ```

+При создании специальности автоматически создаётся профиль `Без профиля`.
+
+**Тело создания/обновления профиля:**
+```json
+{
+  "name": "Безопасность автоматизированных систем",
+  "description": "Необязательное описание"
+}
+```
+
 ---

 ## Группы
@@ -301,7 +362,14 @@ CRUD доступен по:
    "educationFormId": 1,
    "educationFormName": "Бакалавриат",
    "departmentId": 1,
+    "yearStartStudy": 2023,
    "course": 3,
+    "semester": 6,
+    "specialtyId": 1,
+    "specialtyCode": "09.03.04",
+    "specialtyName": "Программная инженерия",
+    "specialtyProfileId": 2,
+    "specialtyProfileName": "Без профиля",
    "specialityCode": 1
  }
 ]
@@ -322,16 +390,53 @@ CRUD доступен по:
  "educationFormId": 1,
  "departmentId": 1,
  "yearStartStudy": 2026,
-  "specialityCode": 1
+  "specialtyId": 1,
+  "specialtyProfileId": 2
 }
 ```

-`specialityCode` исторически содержит ID записи из `/api/specialties`; текущий курс вычисляется из `yearStartStudy`.
+`specialtyId` и `specialtyProfileId` обязательны. Поле `specialityCode` сохранено как legacy-alias для старых клиентов и исторически содержит ID записи из `/api/specialties`. Текущий курс вычисляется из `yearStartStudy`.
+
+Название группы не является уникальным полем: допускается несколько групп с одинаковым `name`.
+
+### `PUT /api/groups/{id}`
+
+Редактирование группы.
+
+```json
+{
+  "name": "ИВТ-11",
+  "groupSize": 24,
+  "educationFormId": 1,
+  "departmentId": 1,
+  "yearStartStudy": 2026,
+  "specialtyId": 1,
+  "specialtyProfileId": 2
+}
+```

 ### `DELETE /api/groups/{id}`

 Удаление группы.

+### Календарные графики группы
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/groups/{id}/calendar-assignments` | Список назначений графиков группе |
+| `PUT` | `/api/groups/{id}/calendar-assignments` | Создать или заменить назначение на учебный год |
+| `DELETE` | `/api/groups/{id}/calendar-assignments/{assignmentId}` | Удалить назначение |
+
+**Тело назначения графика:**
+```json
+{
+  "academicYearId": 1,
+  "calendarId": 5
+}
+```
+
+Назначаемый график должен относиться к тому же учебному году, специальности и профилю, что и группа.
+
 ---

 ## Аудитории