Добавил запрос на создание препода от кафедры

2026-06-02 00:01:14 +03:00
parent 4b05d4287c
commit 4adce0b89c
23 changed files with 1370 additions and 51 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -147,6 +147,8 @@ Refresh-токен ротируется при каждом успешном о

 Список преподавателей привязанных к конкретной кафедре (роль `TEACHER`, код кафедры `departmentId`). Ответ использует ту же структуру `UserResponse`, что и `GET /api/users`.

+Выборка учитывает активные записи `teacher_department_assignments` на текущую дату и legacy-привязку `users.department_id`. Роль `DEPARTMENT` может запрашивать только свою кафедру.
+
 ### `POST /api/users`

 Создание пользователя.
@@ -165,7 +167,7 @@ Refresh-токен ротируется при каждом успешном о

 **Валидация:**
 - `username` — обязателен и уникален
- `password` — минимум 4 символа
+- `password` — минимум 8 символов
 - `role` — `ADMIN`, `EDUCATION_OFFICE`, `DEPARTMENT`, `SCHEDULE_VIEWER`, `TEACHER` или `STUDENT`
 - `fullName` — обязателен
 - `departmentId` — обязателен
@@ -196,7 +198,40 @@ Refresh-токен ротируется при каждом успешном о

 ### `GET /api/users/teachers/by-department/{departmentId}?date=2026-06-01`

-Список преподавателей кафедры на конкретную дату по таблице истории.
+Список преподавателей кафедры на конкретную дату по таблице истории и legacy-привязке `users.department_id`. Роль `DEPARTMENT` может запрашивать только свою кафедру.
+
+---
+
+## Заявки на создание преподавателей
+
+Администратор просматривает и обрабатывает заявки кафедр на создание новых преподавателей.
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/teacher-requests?status=PENDING` | Список заявок, опционально с фильтром статуса |
+| `POST` | `/api/teacher-requests/{id}/approve` | Одобрить заявку, скорректировать данные и создать преподавателя |
+| `POST` | `/api/teacher-requests/{id}/reject` | Отклонить заявку |
+
+**Тело одобрения:**
+```json
+{
+  "departmentId": 2,
+  "username": "teacher.new",
+  "password": "secure-pass",
+  "fullName": "Новый Преподаватель",
+  "jobTitle": "Доцент",
+  "reviewComment": "Данные проверены"
+}
+```
+
+Пароль задаёт только администратор при одобрении заявки. Сама заявка пароль не хранит.
+
+**Тело отклонения:**
+```json
+{
+  "reviewComment": "Нужно уточнить ФИО"
+}
+```

 ---

@@ -539,10 +574,33 @@ GET /api/workload/teachers?departmentId=1&startDate=2026-05-20&endDate=2026-06-0
 | `GET` | `/api/department/subjects/{subjectId}/comments` | Комментарии дисциплины |
 | `POST` | `/api/department/subjects/{subjectId}/comments` | Добавить комментарий |
 | `GET` | `/api/department/teachers` | Преподаватели кафедры |
+| `POST` | `/api/department/teachers/{teacherId}/assignments` | Добавить существующего преподавателя на кафедру |
+| `GET` | `/api/department/teacher-requests` | Заявки кафедры на создание преподавателей |
+| `POST` | `/api/department/teacher-requests` | Создать заявку на нового преподавателя |
 | `GET` | `/api/department/schedule` | Расписание кафедры |

 `GET /api/department/teachers` возвращает актуальных преподавателей кафедры по `teacher_department_assignments` и дополнительно учитывает старую привязку `users.department_id`, чтобы не терять преподавателей без записи в истории назначений.

+`POST /api/department/teachers/{teacherId}/assignments` создаёт дополнительную открытую связь преподавателя с кафедрой (`is_primary=false`). Для роли `DEPARTMENT` кафедра берётся из текущего пользователя, администратор может передать `departmentId`.
+
+```json
+{
+  "departmentId": 2,
+  "comment": "Совместительство"
+}
+```
+
+`POST /api/department/teacher-requests` принимает логин, ФИО, должность и комментарий. Повторная pending-заявка с тем же логином запрещена.
+
+```json
+{
+  "username": "teacher.new",
+  "fullName": "Новый Преподаватель",
+  "jobTitle": "Доцент",
+  "comment": "Нужен для дисциплин кафедры"
+}
+```
+
 ---

 ## Кафедры и специальности
--- a/docs/BUSINESS_LOGIC.md
+++ b/docs/BUSINESS_LOGIC.md
@@ -8,7 +8,7 @@
 |------|------|------------|
 | **Администратор** | `ADMIN` | Полный доступ: пользователи, справочники, тенанты, роли, архивирование и восстановление. |
 | **Учебный отдел** | `EDUCATION_OFFICE` | Редактирование расписания, точечные переносы/замены/отмены, временные слоты, аудитории, загруженность. |
-| **Кафедра** | `DEPARTMENT` | Дисциплины своей кафедры, загрузка дисциплин, привязки преподавателей, комментарии, расписание и нагрузка кафедры. |
+| **Кафедра** | `DEPARTMENT` | Дисциплины своей кафедры, загрузка дисциплин, привязки преподавателей, заявки на создание преподавателей, комментарии, расписание и нагрузка кафедры. |
 | **Просмотр расписаний** | `SCHEDULE_VIEWER` | Read-only просмотр расписаний по группам, преподавателям, аудиториям и кафедрам в режиме одной активной совмещённой таблицы чётной/нечётной недели. |
 | **Преподаватель** | `TEACHER` | Просмотр своего расписания. В перспективе — подача заявок на перенос. |
 | **Студент** | `STUDENT` | Только просмотр расписания (Read-only). |
@@ -27,7 +27,9 @@ Bearer-токен проверяется на backend. Frontend-скрытие

 - загрузка и комментарии дисциплин идут через `/api/department/*`;
 - общий `/api/subjects` доступен кафедре только на чтение;
- привязки `/api/teacher-subjects` разрешены только если преподаватель и дисциплина относятся к кафедре текущего пользователя.
+- привязки `/api/teacher-subjects` разрешены только если преподаватель и дисциплина относятся к кафедре текущего пользователя;
+- добавление существующего преподавателя через `/api/department/teachers/{teacherId}/assignments` создаёт связь только со своей кафедрой;
+- заявки `/api/department/teacher-requests` создаются и просматриваются кафедрой только в рамках своей кафедры, а создание пользователя выполняет администратор после проверки.

 ---

@@ -93,14 +95,19 @@ Bearer-токен проверяется на backend. Frontend-скрытие

 Методическая проверка активности учитывает период действия и `status`: архивная запись без `active_to` не считается активной, но запись с заполненным `active_to` остаётся активной для исторических дат до даты вывода из работы.

-### Перевод преподавателей между кафедрами
+### Кафедральные связи преподавателей

-Текущая кафедра преподавателя хранится в `users.department_id`, но история переводов фиксируется в `teacher_department_assignments`.
+Основная кафедра преподавателя хранится в `users.department_id` для совместимости, а актуальные и исторические связи фиксируются в `teacher_department_assignments`. Преподаватель может быть связан с несколькими кафедрами: одна связь остаётся основной, дополнительные связи создаются как неосновные.

 Правила:

 - у преподавателя должна быть одна открытая основная кафедра;
+- преподаватель может иметь несколько открытых неосновных кафедр;
+- одна открытая пара `teacher_id` + `department_id` запрещает дубли одной и той же связи;
 - при переводе старая запись закрывается датой `valid_to`, новая открывается с `valid_from`;
+- кафедра может добавить существующего активного преподавателя только на свою кафедру, без смены его основной кафедры;
+- кафедра может отправить заявку на создание нового преподавателя, но заявка не хранит пароль;
+- администратор при одобрении заявки может скорректировать кафедру, логин, ФИО и должность, задаёт пароль и создаёт пользователя с ролью `TEACHER`;
 - расписание и отчёты за прошлые периоды не теряют связь с прежней кафедрой.

 ---
--- a/docs/DATABASE.md
+++ b/docs/DATABASE.md
@@ -148,6 +148,21 @@ erDiagram
        TEXT comment
    }

+    teacher_creation_requests {
+        BIGSERIAL id PK
+        BIGINT department_id FK
+        VARCHAR username
+        VARCHAR full_name
+        VARCHAR job_title
+        TEXT comment
+        VARCHAR status
+        BIGINT requested_by FK
+        BIGINT reviewed_by FK
+        TIMESTAMP reviewed_at
+        TEXT review_comment
+        BIGINT created_teacher_id FK
+    }
+
    subject_comments {
        BIGSERIAL id PK
        BIGINT subject_id FK
@@ -306,6 +321,8 @@ erDiagram
    users ||--o{ auth_refresh_tokens : "user_id"
    users ||--o{ teacher_department_assignments : "teacher_id"
    departments ||--o{ teacher_department_assignments : "department_id"
+    departments ||--o{ teacher_creation_requests : "department_id"
+    users ||--o{ teacher_creation_requests : "requested_by/reviewed_by/created_teacher_id"
    users ||--o{ teacher_lesson_types : "user_id"
    users ||--o{ subject_comments : "author_id"
    subjects ||--o{ teacher_subjects : "subject_id"
@@ -528,7 +545,27 @@ erDiagram
 | `created_at` | TIMESTAMP | Дата создания записи |
 | `created_by` | BIGINT FK → users | Кто оформил перевод |

-Индекс `uq_teacher_department_open_primary` гарантирует не больше одной открытой основной кафедры у преподавателя.
+Индекс `uq_teacher_department_open_primary` гарантирует не больше одной открытой основной кафедры у преподавателя. Индекс `uq_teacher_department_open_pair` запрещает две открытые связи одного преподавателя с одной кафедрой, но позволяет преподавателю иметь несколько открытых неосновных кафедр.
+
+#### `teacher_creation_requests` — Заявки кафедр на создание преподавателей
+| Колонка | Тип | Описание |
+|---------|-----|----------|
+| `id` | BIGSERIAL PK | ID заявки |
+| `department_id` | BIGINT FK → departments | Кафедра, которая запрашивает преподавателя |
+| `username` | VARCHAR(50) | Предлагаемый логин |
+| `full_name` | VARCHAR(255) | ФИО преподавателя |
+| `job_title` | VARCHAR(255) | Должность |
+| `comment` | TEXT | Комментарий кафедры |
+| `status` | VARCHAR(20) | `PENDING`, `APPROVED` или `REJECTED` |
+| `requested_by` | BIGINT FK → users | Пользователь, создавший заявку |
+| `reviewed_by` | BIGINT FK → users | Администратор, рассмотревший заявку |
+| `reviewed_at` | TIMESTAMP | Дата рассмотрения |
+| `review_comment` | TEXT | Комментарий администратора |
+| `created_teacher_id` | BIGINT FK → users | Созданный преподаватель после одобрения |
+| `created_at` | TIMESTAMP | Дата создания заявки |
+| `updated_at` | TIMESTAMP | Дата последнего изменения |
+
+Заявка не хранит пароль. Пароль задаётся администратором только при одобрении, после чего создаётся пользователь с ролью `TEACHER` и основная запись в `teacher_department_assignments`. Частичный уникальный индекс `uq_teacher_creation_requests_pending_username` запрещает две открытые заявки с одним логином.

 #### `subject_comments` — Комментарии к дисциплинам
 | Колонка | Тип | Описание |
@@ -713,13 +750,13 @@ Seed создаёт `Базовая сетка` (`DEFAULT`) и `Субботня
 4. Flyway запускается **программно** при первом обращении к БД тенанта (`TenantConfigWatcher.initDatabaseForTenant()`)
 5. Настройка `baselineOnMigrate=true` — если в БД уже есть данные, Flyway начнёт с baseline

-> Текущая JWT-правка является осознанным исключением по прямой просьбе пользователя: `V1__init.sql` обновлён как новая базовая схема, а применение предполагает полный сброс tenant-БД без переноса старых Flyway checksum.
+> Текущая правка `V1__init.sql` является осознанным исключением по прямой просьбе пользователя: файл обновлён как новая базовая схема, а применение предполагает полный сброс tenant-БД без переноса старых Flyway checksum.

 ### Текущие миграции

 | Файл | Описание |
 |------|----------|
-| `V1__init.sql` | Инициализация: справочники, роли, refresh-сессии JWT, lifecycle-поля, история кафедр преподавателей, комментарии дисциплин, календарные учебные графики, динамическое расписание, версии/закрепления правил, точечные изменения расписания, тестовые правила, триггеры, комментарии |
+| `V1__init.sql` | Инициализация: справочники, роли, refresh-сессии JWT, lifecycle-поля, история кафедр преподавателей, заявки кафедр на создание преподавателей, комментарии дисциплин, календарные учебные графики, динамическое расписание, версии/закрепления правил, точечные изменения расписания, тестовые правила, триггеры, комментарии |

 ### Накатывание на существующих тенантов

--- a/docs/FRONTEND.md
+++ b/docs/FRONTEND.md
@@ -129,14 +129,14 @@ frontend/

 | Tab | Описание | API |
 |-----|----------|-----|
-| `users` | CRUD пользователей | `/api/users` |
+| `users` | CRUD пользователей и очередь заявок кафедр на создание преподавателей | `/api/users`, `/api/teacher-requests` |
 | `groups` | CRUD групп, подгруппы лабораторных и назначения графиков | `/api/groups`, `/api/subgroups` |
 | `edu-forms` | Формы обучения | `/api/education-forms` |
 | `profiles` | Создание, редактирование и удаление профилей обучения специальностей | `/api/specialties/{id}/profiles` |
 | `equipments` | Оборудование | `/api/equipments` |
 | `classrooms` | Аудитории | `/api/classrooms` |
 | `subjects` | Дисциплины | `/api/subjects` |
-| `department-workspace` | Кабинет кафедры: дисциплины, импорт, комментарии, преподаватели и нагрузка | `/api/department/*`, `/api/workload/teachers` |
+| `department-workspace` | Кабинет кафедры: дисциплины, импорт, комментарии, преподаватели, привязка преподавателей, заявки на новых преподавателей и нагрузка | `/api/department/*`, `/api/department/teacher-requests`, `/api/workload/teachers` |
 | `schedule-view` | Read-only просмотр расписаний: по одной выбранной дате строится двухнедельный диапазон, найденные расписания выбираются в переключателе, а на экране отображается одна активная совмещённая таблица чётной/нечётной недели | `/api/schedule/search` |
 | `schedule` | Конструктор правил динамического расписания с выезжающей визуальной матрицей групп по дням и времени | `/api/admin/schedule-rules`, `/api/admin/time-slots`, `/api/admin/calendar/years`, `/api/lesson-types`, `/api/subgroups` |
 | `academic-calendar` | Учебные годы, семестры, создание календарных графиков и Excel-подобный редактор дневной сетки | `/api/admin/calendar`, `/api/admin/academic-calendars`, `/api/admin/calendar/activity-types`, `/api/education-forms` |
@@ -147,7 +147,9 @@ frontend/
 ### Особенности админских вкладок

 - Вкладка `groups` загружает кафедры, специальности, профили, учебные годы и календарные графики. Список групп открывается через `/api/groups?includeArchived=true`, поэтому в таблице видны активные, будущие, завершившие обучение и архивные группы со статусом. Группа создаётся через `/api/groups` с `specialtyId` и `specialtyProfileId`, блок подгрупп использует `/api/subgroups` и `/api/groups/{id}/subgroups`, а блок назначений использует `/api/groups/{id}/calendar-assignments`. В селекты подгрупп и назначений попадают только группы с `active=true`.
+- Вкладка `users` показывает pending-заявки кафедр на создание преподавателей. Администратор может скорректировать кафедру, логин, ФИО и должность, задать пароль минимум 8 символов, затем одобрить заявку через `/api/teacher-requests/{id}/approve` или отклонить её через `/api/teacher-requests/{id}/reject`.
 - Вкладка `department-workspace` в блоке преподавателей объединяет данные `/api/department/teachers` и `/api/workload/teachers`: каждый преподаватель показывается одной карточкой с должностью и нагрузкой за выбранный период, преподаватели без занятий получают нулевую нагрузку, а преподаватели из расписания добавляются без дублей. Если дата начала периода выбрана позже даты окончания, поле окончания очищается, а расчёт нагрузки ждёт корректный период.
+- Вкладка `department-workspace` позволяет кафедре добавить существующего активного преподавателя на свою кафедру через `/api/department/teachers/{teacherId}/assignments`, отправить заявку на нового преподавателя через `/api/department/teacher-requests` и видеть статусы собственных заявок в таблице.
 - Вкладка `schedule-view` показывает найденные занятия в режиме одной активной таблицы. Пользователь выбирает, что смотреть: группу, преподавателя, аудиторию или кафедру; frontend запрашивает двухнедельный диапазон от понедельника выбранной даты и собирает найденные расписания в переключатель результатов. На странице не выводится стек таблиц: виден один выбранный результат, а остальные доступны через чипы и кнопки предыдущего/следующего расписания; чипы результатов переносятся и отделены от счётчика стабильным отступом. Для режима кафедры и роли `DEPARTMENT` расписание ограничивается кафедрой пользователя; преподавательские и студенческие отдельные страницы пока остаются самостоятельными. Таблица строится как строки пар и столбцы дней недели. Нечётная неделя отображается в верхней половине ячейки, чётная — в нижней, а одинаковые занятия в обе недели схлопываются в цельную ячейку. Бейдж диапазона недель скрывается для занятий на весь семестр, а для занятий до конца семестра показывает только неделю начала в формате `(с 5 нед.)`. На мобильной ширине вместо широкой недельной матрицы показывается один день активного расписания с переключателем дней.
 - Вкладка `auditorium-workload` стала общей вкладкой `Загруженность`: в поле «Что смотреть» выбираются аудитории, преподаватели или кафедры. Сводная матрица по выбранной дате использует одинаковую структуру: строки — выбранный тип сущности, столбцы — эффективные временные слоты дня из `/api/admin/time-slots/effective`, занятость собирается из динамического расписания `/api/schedule` по группам. Кафедральная матрица группирует занятия по кафедре преподавателя. Для аудиторий доступны фильтры корпуса, вместимости и оборудования. В поле «Отображение» можно выбрать конкретную аудиторию, преподавателя или кафедру; тогда сводная матрица заменяется одной таблицей по дням недели и времени для двухнедельного периода от выбранной даты. Таблица выбранной сущности растягивается до нижней части экрана. Ячейка делится вертикально только если верхняя и нижняя недели отличаются: нечётная неделя отображается сверху, чётная — снизу. Если состояние или занятие одинаковое, ячейка остаётся цельной. Чётность берётся из расписания, а для свободных дней рассчитывается по семестрам из `/api/admin/calendar/years`.
 - Вкладка `profiles` выделена под профили обучения: администратор выбирает специальность, создаёт профиль, редактирует описание и удаляет неиспользуемые профили.
@@ -208,6 +210,8 @@ export const api = {

 При `401` клиент один раз вызывает `POST /api/auth/refresh`, обновляет `localStorage.token` и повторяет исходный запрос. Если refresh неуспешен, auth state очищается и пользователь возвращается на страницу входа.

+После мутаций `api.js` инвалидирует кэш не только по точному URL, но и по связанным префиксам. Для заявок и кафедральных привязок очищаются `/api/users`, `/api/users/teachers`, `/api/teacher-requests`, `/api/department/teacher-requests` и `/api/department/teachers`, чтобы таблицы заявок и списки преподавателей обновлялись без ручного сброса страницы.
+
 ---

 ## Аутентификация (Frontend)