исправил ошибки и проблемы безопасности

2026-05-27 20:29:50 +03:00
parent c7cb5125f4
commit e9575cf2ce
36 changed files with 897 additions and 376 deletions
--- a/docs/API.md
+++ b/docs/API.md
@@ -2,6 +2,20 @@

 Все эндпоинты имеют префикс `/api/`. Ответы возвращаются в формате JSON.

+Необработанные ошибки проходят через единый `GlobalExceptionHandler`. Для `400`, `404` и `500` используется общий JSON-формат:
+
+```json
+{
+  "timestamp": "2026-05-27T19:47:54",
+  "status": 400,
+  "error": "Некорректный запрос",
+  "message": "Некорректные параметры запроса",
+  "path": "/api/schedule"
+}
+```
+
+Контроллеры, у которых исторически есть собственная обработка ошибок, могут возвращать более короткий объект с полем `message`.
+
 ---

 ## Аутентификация
@@ -105,6 +119,8 @@ Refresh-токен ротируется при каждом успешном о
 }
 ```

+`departmentId` присутствует в ответе всегда, но может быть `null` для пользователей без привязки к кафедре.
+
 ---

 ## Пользователи
@@ -116,18 +132,20 @@ Refresh-токен ротируется при каждом успешном о
 **Ответ:**
 ```json
 [
-  { "id": 1, "username": "admin", "role": "ADMIN", "fullName": "Иванов Админ Иванович", "jobTitle": "Доцент", "departmentName": "Кафедра ИБ" },
-  { "id": 2, "username": "Тестовый преподаватель", "role": "TEACHER", "fullName": "Петров Препод Петрович", "jobTitle": "Профессор", "departmentName": "Кафедра ВТ" }
+  { "id": 1, "username": "admin", "role": "ADMIN", "fullName": "Иванов Админ Иванович", "jobTitle": "Доцент", "departmentName": "Кафедра ИБ", "departmentId": 1, "status": "ACTIVE" },
+  { "id": 2, "username": "teacher1", "role": "TEACHER", "fullName": "Петров Препод Петрович", "jobTitle": "Профессор", "departmentName": "Кафедра ВТ", "departmentId": 2, "status": "ACTIVE" }
 ]
 ```

+`UserResponse` единый для списков пользователей, списков преподавателей и ответов создания/восстановления. Поля `departmentName`, `departmentId` и `status` не выводятся только если равны `null`.
+
 ### `GET /api/users/teachers`

 Список только преподавателей (роль `TEACHER`).

 ### `GET /api/users/teachers/{departmentId}`

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

 ### `POST /api/users`

@@ -446,6 +464,8 @@ CRUD доступен по:
 | `timeSlotId` | Временной слот |
 | `parity` | `BOTH`, `ODD`, `EVEN` |

+Если указан только `teacherId` без `groupId` и `departmentId`, поиск строит расписание преподавателя напрямую и не обходит все группы. Широкий поиск без `groupId` и `departmentId` разрешён только до 50 активных групп; при большем количестве групп API вернёт `400` с просьбой уточнить группу или кафедру.
+
 Пример:

 ```http
@@ -939,7 +959,7 @@ GET /api/workload/teachers?departmentId=1&startDate=2026-05-20&endDate=2026-06-0
 | Код | Описание |
 |-----|----------|
 | `200` | Успех |
-| `400` | Ошибка валидации (с `message` в теле) |
+| `400` | Ошибка валидации или некорректные параметры запроса |
 | `401` | Неверные учётные данные |
 | `404` | Ресурс / тенант не найден |
 | `500` | Внутренняя ошибка сервера |
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -32,7 +32,7 @@ graph TD
 - **Порт:** 8080 (внутренний)
 - **ORM:** Hibernate (JPA), `ddl-auto=none`
 - **Миграции:** Flyway (программный запуск при подключении тенанта)
- **Аутентификация:** bcrypt (через `BCryptPasswordEncoder`), in-memory UUID-сессии, bearer-токены и backend-проверка ролей
+- **Аутентификация:** bcrypt (через `BCryptPasswordEncoder`), access JWT, ротируемые refresh-токены и backend-проверка ролей

 ### PostgreSQL
 - **Версия:** `postgres:alpine3.23`
@@ -80,6 +80,7 @@ sequenceDiagram
 | `TenantContext` | `ThreadLocal`-хранилище имени текущего тенанта |
 | `TenantRoutingDataSource` | Наследует `AbstractRoutingDataSource`, маршрутизирует запросы к нужной БД |
 | `TenantDataSourceConfig` | Загружает конфигурацию тенантов из JSON-файла, создаёт HikariCP пулы |
+| `TenantWebMvcConfig` | Регистрирует `TenantInterceptor` и `AuthorizationInterceptor` в MVC-слое |
 | `TenantConfigWatcher` | Периодически (каждые 30 сек) перечитывает `tenants.json`, синхронизирует тенантов |
 | `ConfigMapUpdater` | Обновляет Kubernetes ConfigMap при добавлении/удалении тенанта через API |
 | `TenantConfig` | POJO с параметрами тенанта: `name`, `domain`, `url`, `username`, `password` |
@@ -99,7 +100,7 @@ sequenceDiagram
 ### Конфигурация тенантов

 Список тенантов хранится в JSON-файле:
- **Локально:** `backend/tenants.json`
+- **Локально:** `backend/tenants.json` (не коммитится; шаблон — `backend/tenants.example.json`)
 - **Продакшн:** Kubernetes ConfigMap `tenants-config`, монтируется в `/config/tenants.json`

 Формат:
@@ -121,12 +122,16 @@ sequenceDiagram
 2. **Синхронизация подов:** `TenantConfigWatcher` каждые 30 сек проверяет `tenants.json` → добавляет новые / удаляет отсутствующие тенанты
 3. **Удаление:** `DELETE /api/database/tenants/{domain}` → закрывает пул → обновляет ConfigMap

+`TenantConfigWatcher` сравнивает содержимое `tenants.json` по SHA-256, а не по `String.hashCode()`, чтобы изменение ConfigMap не пропускалось из-за 32-битной коллизии.
+
 ### Fallback при отсутствии тенантов

 Если при запуске нет ни одного настроенного тенанта:
 1. Проверяется наличие `spring.datasource.url` → создаётся тенант `default`
 2. Если datasource тоже нет → создаётся H2 in-memory заглушка для инициализации Spring JPA

+`TenantContext` хранит имя текущего тенанта в `ThreadLocal` и очищается интерцептором после завершения запроса. Виртуальные потоки в приложении не включены; если их включать в будущем, нужно отдельно проверить перенос и очистку tenant/auth context на асинхронных участках.
+
 ---

 ## Аутентификация
--- a/docs/BUSINESS_LOGIC.md
+++ b/docs/BUSINESS_LOGIC.md
@@ -90,6 +90,8 @@ Bearer-токен проверяется на backend. Frontend-скрытие

 Архивирование уже применяется к пользователям, аудиториям, оборудованию, кафедрам, специальностям, группам, подгруппам, дисциплинам и профилям обучения. Исторические отчёты используют записи, действовавшие на дату занятия.

+Методическая проверка активности учитывает и период действия, и `status`: запись со статусом `ARCHIVED` не считается активной даже без заполненного `active_to`.
+
 ### Перевод преподавателей между кафедрами

 Текущая кафедра преподавателя хранится в `users.department_id`, но история переводов фиксируется в `teacher_department_assignments`.
@@ -136,6 +138,12 @@ Bearer-токен проверяется на backend. Frontend-скрытие
 10. Останавливает вывод слотов конкретного типа, когда достигнут его лимит часов.
 11. Применяет точечные изменения из `schedule_overrides` в расширенном поиске и отчётах.

+Расход часов считается в пределах одного построения расписания: при первом использовании семестра генератор одним последовательным проходом прогревает проведённые часы от начала семестра до начала запрошенного диапазона, затем ведёт локальный прогресс по правилу, типу занятия, группе и подгруппе. Обратного пересчёта прошлых дат для каждого слота нет. Singleton-кэш в сервисе не используется, поэтому данные расписания не накапливаются в heap между запросами и не устаревают после изменений правил, календаря или подгрупп.
+
+В генерацию попадают только активные на дату правила, дисциплины, группы, преподаватели и аудитории. Для будущих дат аудитория с `is_available=false` не выводится в расписании, но прошлые занятия остаются доступными для просмотра.
+
+Расширенный поиск расписания ограничивает широкие запросы: если не указаны `groupId` и `departmentId`, сервис не будет обходить больше 50 активных групп и вернёт ошибку валидации. Запросы по одному `teacherId` без группы или кафедры строятся через генерацию расписания преподавателя, чтобы не выполнять полный перебор групп.
+
 Лабораторные работы могут делиться на подгруппы через `schedule_rule_slot_subgroups`. Если подгруппы выбраны, занятие выводится только для родительских групп этих подгрупп, а лимит лабораторных часов списывается отдельно по каждой подгруппе. Если лабораторная проводится у нескольких групп одновременно, один слот может содержать разные подгруппы разных групп. Лекции и практики не делятся на подгруппы.

 Обычные пары генерируются только на коде `Т` (`allow_schedule = true`). Экзамены, каникулы, практики, нерабочие дни, праздники `*` и дни вне учебного года `=` считаются пропуском: занятие не переносится и не списывает академические часы. Если у группы нет назначения графика на учебный год, `GET /api/schedule` возвращает пустой список для этой группы без ошибки.
@@ -167,6 +175,7 @@ Bearer-токен проверяется на backend. Frontend-скрытие
 - **Подгруппы:** `subgroupIds` разрешены только для лабораторных слотов, должны относиться к группам правила, и в одном слоте можно выбрать не больше одной подгруппы каждой группы.
 - **Формат:** `lessonFormat` обязателен и хранится в слоте правила.
 - **Жизненный цикл:** архивные преподаватели, аудитории, группы и дисциплины не принимаются в новых правилах.
+- **Правило расписания:** `status=ARCHIVED` или дата вне `valid_from` / `valid_to` исключают правило из генерации.
 - **Доступность аудитории:** `is_available=false` запрещает новые назначения, но не удаляет историю.

 ### Точечные изменения расписания
--- a/docs/DATABASE.md
+++ b/docs/DATABASE.md
@@ -644,6 +644,8 @@ Seed создаёт `Базовая сетка` (`DEFAULT`) и `Субботня
 | `version_group_id` | BIGINT | Группа версий одного правила |
 | `change_reason` | TEXT | Причина изменения |

+`ScheduleRule` использует собственные поля жизненного цикла `status`, `valid_from` и `valid_to`: архивированное правило или правило вне периода действия не участвует в генерации расписания. В отличие от справочников на `LifecycleEntity`, таблица не содержит `active_from`/`active_to`, поэтому состояние правила проверяется по `valid_*`.
+
 #### `schedule_rule_groups` — Группы правила
 | Колонка | Тип | Описание |
 |---------|-----|----------|
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -254,11 +254,13 @@ com.magistr.app/
 │       ├── TenantContext.java         # ThreadLocal текущего тенанта
 │       ├── TenantInterceptor.java     # Определение тенанта из Host
 │       ├── TenantRoutingDataSource.java  # Маршрутизация к БД
-│       ├── TenantDataSourceConfig.java   # Spring-конфигурация
+│       ├── TenantDataSourceConfig.java   # Конфигурация DataSource/JPA
+│       ├── TenantWebMvcConfig.java       # Регистрация MVC-интерцепторов
 │       ├── TenantConfigWatcher.java      # Периодическая синхронизация
 │       └── ConfigMapUpdater.java         # Обновление K8s ConfigMap
 ├── controller/                # REST-контроллеры
 │   ├── AuthController.java
+│   ├── GlobalExceptionHandler.java
 │   ├── ScheduleController.java
 │   ├── ClassroomController.java
 │   ├── DatabaseController.java
--- a/docs/INFRASTRUCTURE.md
+++ b/docs/INFRASTRUCTURE.md
@@ -25,18 +25,21 @@ docker network create proxy

 ```env
 POSTGRES_USER=myuser
-POSTGRES_PASSWORD=supersecretpassword
+POSTGRES_PASSWORD=replace-with-local-password
+POSTGRES_DB=app_db
 JWT_SECRET=replace-with-random-jwt-secret-minimum-32-bytes
 JWT_ACCESS_TOKEN_TTL=15m
 JWT_REFRESH_TOKEN_TTL=7d
 ```

-`JWT_SECRET` должен быть случайным секретом длиной минимум 32 байта. В продакшене он задаётся через Kubernetes Secret `app-secret`.
+`POSTGRES_PASSWORD` обязателен для `docker compose up`: пароль не хранится в `compose.yaml`. `JWT_SECRET` должен быть случайным секретом длиной минимум 32 байта. В продакшене секреты задаются через Kubernetes Secret, а не через коммитимые файлы.
+
+Локальный `backend/tenants.json` тоже не коммитится. Для ручного запуска backend вне Docker можно взять `backend/tenants.example.json`, создать рядом `tenants.json` и подставить локальный пароль.

 ### Dockerfile (Backend)

 Backend собирается через multi-stage сборку Maven:
-1. Этап сборки: `maven:3-eclipse-temurin-17-alpine` → `mvn package`
+1. Этап сборки: `maven:3.9-eclipse-temurin-17` → `mvn package`
 2. Этап запуска: `eclipse-temurin:17-jre-alpine` → `java -jar app.jar`

 ### Dockerfile (Frontend)