3 Задача

docs/API.md

@@ -912,6 +912,84 @@ API возвращает `409 Conflict`; соседние интервалы и
 выбранного действия возвращает `409` и откатывает остальные. Незаполненные занятия не
 меняются. Когда обработаны все оставшиеся занятия, отсутствие получает статус `RESOLVED`.
 
+### Пожелания преподавателей на семестр
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/teacher-preferences/meta` | Семестры и базовая сетка времени для календаря доступности |
+| `GET` | `/api/teacher-preferences?semesterId=&status=` | Доступные текущей роли пожелания с фильтрами по семестру и статусу |
+| `POST` | `/api/teacher-preferences` | Создать ограничение или мягкое пожелание |
+| `POST` | `/api/teacher-preferences/{id}/review` | Согласовать или отклонить ожидающее пожелание |
+| `DELETE` | `/api/teacher-preferences/{id}` | Отозвать ожидающее либо отменить действующее пожелание |
+
+Типы пожеланий: `HARD_UNAVAILABLE` — строгая недоступность по паре недели или целой дате,
+`SOFT_PREFERRED` — предпочтительный интервал, `SOFT_UNWANTED` — нежелательный интервал,
+`CONSECUTIVE` — пары подряд, `NO_GAPS` — расписание без окон. Интервальные пожелания
+используют `dayOfWeek` от 1 до 7 и `timeSlotId` базовой сетки; полная недоступность
+использует только `preferenceDate` внутри выбранного семестра.
+
+```json
+{
+  "semesterId": 4,
+  "preferenceType": "HARD_UNAVAILABLE",
+  "dayOfWeek": 5,
+  "timeSlotId": 3,
+  "comment": "Методический день"
+}
+```
+
+Преподаватель создаёт и видит только собственные пожелания; новая запись получает статус
+`PENDING`. `ADMIN` и `EDUCATION_OFFICE` работают со всеми преподавателями, а `DEPARTMENT` —
+только с преподавателями своей кафедры по истории назначений на период семестра. Запись,
+добавленная ответственным сотрудником, сразу получает статус `APPROVED`. При отклонении
+поле `comment` в запросе согласования обязательно:
+
+```json
+{
+  "approved": false,
+  "comment": "Уточните день полной недоступности"
+}
+```
+
+Согласованная строгая недоступность блокирует сохранение конфликтующего правила и разовой
+правки. Мягкие пожелания и требования компактности показываются в конструкторе правил как
+подсказки и не изменяют опубликованное расписание автоматически.
+
+### Заявки преподавателей на изменение занятия
+
+| Метод | URL | Назначение |
+|-------|-----|------------|
+| `GET` | `/api/teacher-change-requests?status=` | Доступный текущей роли журнал заявок и история решений |
+| `GET` | `/api/teacher-change-requests/candidates?baseRuleSlotId=&lessonDate=&targetDate=` | Предварительно проверенные даты, пары и аудитории |
+| `POST` | `/api/teacher-change-requests` | Отправить заявку по собственному занятию |
+| `POST` | `/api/teacher-change-requests/{id}/review` | Применить или отклонить заявку |
+| `DELETE` | `/api/teacher-change-requests/{id}` | Отозвать собственную ожидающую заявку |
+
+Преподаватель может выбрать только фактически существующее собственное занятие без уже
+созданного override. Поддерживаются `MOVE`, `CHANGE_CLASSROOM` и `CANCEL`; обоснование
+обязательно. Для `MOVE` передаются новая пара и, при необходимости, новая дата, для
+`CHANGE_CLASSROOM` — только новая аудитория. Кандидаты заранее проходят тот же валидатор
+ресурсных конфликтов, календаря, эффективной сетки времени, отсутствий и строгой
+недоступности, который используется при применении разовой правки.
+
+```json
+{
+  "baseRuleSlotId": 31,
+  "lessonDate": "2026-09-10",
+  "requestType": "MOVE",
+  "targetLessonDate": "2026-09-11",
+  "requestedTimeSlotId": 4,
+  "reason": "Участие в конференции"
+}
+```
+
+`ADMIN` и `EDUCATION_OFFICE` могут принять заявку; backend повторно валидирует её и
+транзакционно создаёт обычный `schedule_override`, записывает `appliedOverrideId` и событие
+`APPROVED` в историю. Кафедра видит заявки своих преподавателей, но не применяет изменения
+расписания. При отклонении комментарий обязателен. Статусы: `PENDING`, `APPROVED`,
+`REJECTED`, `CANCELLED`; по одному занятию одновременно допускается только одна ожидающая
+заявка.
+
 ## Загруженность
 
 | Метод | URL | Назначение |