ролевая моделю доступа + загруженность по кафедрам и преподавателям + просморт расписания

2026-05-19 23:10:56 +03:00
parent f010ffc467
commit 91729cff7d
93 changed files with 4264 additions and 699 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -46,6 +46,32 @@

 > После получения токена клиент должен передавать его в заголовке: `Authorization: Bearer <token>`

+Поддерживаемые роли: `ADMIN`, `EDUCATION_OFFICE`, `DEPARTMENT`, `SCHEDULE_VIEWER`, `TEACHER`, `STUDENT`.
+
+Redirect по ролям:
+
+| Роль | Redirect |
+|------|----------|
+| `ADMIN` | `/admin/` |
+| `EDUCATION_OFFICE` | `/admin/#schedule-view` |
+| `DEPARTMENT` | `/admin/#department-workspace` |
+| `SCHEDULE_VIEWER` | `/admin/#schedule-view` |
+| `TEACHER` | `/teacher/` |
+| `STUDENT` | `/student/` |
+
+### `GET /api/auth/me`
+
+Возвращает текущего пользователя по bearer-токену.
+
+```json
+{
+  "userId": 1,
+  "username": "admin",
+  "role": "ADMIN",
+  "departmentId": 1
+}
+```
+
 ---

 ## Пользователи
@@ -89,13 +115,50 @@
 **Валидация:**
 - `username` — обязателен и уникален
 - `password` — минимум 4 символа
- `role` — `ADMIN`, `TEACHER` или `STUDENT`
+- `role` — `ADMIN`, `EDUCATION_OFFICE`, `DEPARTMENT`, `SCHEDULE_VIEWER`, `TEACHER` или `STUDENT`
 - `fullName` — обязателен
 - `departmentId` — обязателен

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

-Удаление пользователя.
+Архивирование пользователя. Исторические связи и расписание остаются в БД, но пользователь больше не может войти.
+
+### `POST /api/users/{id}/restore`
+
+Восстановление архивного пользователя.
+
+### `GET /api/users/{id}/department-history`
+
+История переводов преподавателя между кафедрами.
+
+### `POST /api/users/{id}/department-transfer`
+
+Перевод преподавателя на другую кафедру без потери прошлых связей.
+
+```json
+{
+  "departmentId": 2,
+  "validFrom": "2026-06-01",
+  "comment": "Перевод на кафедру ВТ"
+}
+```
+
+### `GET /api/users/teachers/by-department/{departmentId}?date=2026-06-01`
+
+Список преподавателей кафедры на конкретную дату по таблице истории.
+
+---
+
+## Права ролей на API
+
+Скрытие вкладок во frontend не является защитой. Все `/api/**` запросы, кроме `POST /api/auth/login`, проходят через bearer-токен и `@RequireRoles`.
+
+Важные ограничения:
+
+- `DEPARTMENT` не может создавать аудитории, кафедры, специальности, группы, пользователей или правила расписания через API;
+- `DEPARTMENT` создаёт и комментирует дисциплины через `/api/department/*`, где кафедра берётся из текущего пользователя;
+- `/api/teacher-subjects` для `DEPARTMENT` разрешает связывать только преподавателей и дисциплины своей кафедры;
+- `SCHEDULE_VIEWER` имеет read-only доступ к просмотру расписаний, справочникам-фильтрам и загруженности.

 ---

@@ -334,6 +397,97 @@ CRUD доступен по:
 ]
 ```

+### `GET /api/schedule/search`
+
+Расширенный поиск расписания. В отличие от `GET /api/schedule`, принимает несколько фильтров одновременно.
+
+| Параметр | Описание |
+|----------|----------|
+| `startDate` / `endDate` | Обязательный период |
+| `groupId` | Учебная группа |
+| `teacherId` | Преподаватель |
+| `classroomId` | Аудитория |
+| `departmentId` | Кафедра |
+| `subjectId` | Дисциплина |
+| `lessonTypeId` | Тип занятия |
+| `timeSlotId` | Временной слот |
+| `parity` | `BOTH`, `ODD`, `EVEN` |
+
+Пример:
+
+```http
+GET /api/schedule/search?classroomId=1&startDate=2026-05-20&endDate=2026-05-27
+```
+
+Ответ совпадает со структурой `RenderedLessonDto` из `GET /api/schedule`.
+
+### Точечные изменения расписания учебного отдела
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/edu-office/schedule/overrides` | Список точечных изменений |
+| `POST` | `/api/edu-office/schedule/overrides` | Создать перенос, отмену или замену |
+| `PUT` | `/api/edu-office/schedule/overrides/{id}` | Обновить изменение |
+| `DELETE` | `/api/edu-office/schedule/overrides/{id}` | Удалить изменение |
+
+```json
+{
+  "baseRuleSlotId": 31,
+  "lessonDate": "2026-05-21",
+  "action": "REPLACE",
+  "newClassroomId": 2,
+  "newTeacherId": 5,
+  "comment": "Замена аудитории и преподавателя"
+}
+```
+
+`action=CANCEL` отменяет конкретную пару. `MOVE` и `REPLACE` могут менять аудиторию, преподавателя, формат и временной слот.
+
+## Загруженность
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/workload/teachers` | Загруженность преподавателей |
+| `GET` | `/api/workload/classrooms` | Загруженность аудиторий |
+| `GET` | `/api/workload/departments` | Загруженность кафедр |
+| `GET` | `/api/workload/time-slots` | Загруженность по парам |
+| `GET` | `/api/workload/free-classrooms` | Свободные аудитории на дату и пару |
+
+Общие параметры для отчётов: `startDate`, `endDate`, опционально `departmentId`.
+
+Пример:
+
+```http
+GET /api/workload/teachers?departmentId=1&startDate=2026-05-20&endDate=2026-06-01
+```
+
+Ответ:
+
+```json
+[
+  {
+    "id": 2,
+    "name": "Петров Препод Петрович",
+    "departmentId": 1,
+    "departmentName": "Кафедра ИБ",
+    "lessonCount": 8,
+    "academicHours": 16,
+    "occupiedSlotCount": 8
+  }
+]
+```
+
+## Кабинет кафедры
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/department/subjects` | Дисциплины текущей кафедры |
+| `POST` | `/api/department/subjects/import` | Загрузка списка дисциплин |
+| `GET` | `/api/department/subjects/{subjectId}/comments` | Комментарии дисциплины |
+| `POST` | `/api/department/subjects/{subjectId}/comments` | Добавить комментарий |
+| `GET` | `/api/department/teachers` | Преподаватели кафедры |
+| `GET` | `/api/department/schedule` | Расписание кафедры |
+
 ---

 ## Кафедры и специальности
@@ -557,7 +711,11 @@ CRUD доступен по:

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

-Удаление аудитории.
+Архивирование аудитории. Архивная аудитория остаётся в историческом расписании, но не выбирается в новых назначениях.
+
+### `POST /api/classrooms/{id}/restore`
+
+Восстановление архивной аудитории.

 ---