magistr/SUPERVISOR_TASKS_IMPLEMENTATION_PLAN.md

Отчёт об изменениях по задачам научного руководителя

Дата: 2026-05-19

Краткий итог

Выполнен первый цельный релиз архитектурной основы:

• добавлены роли EDUCATION_OFFICE, DEPARTMENT и SCHEDULE_VIEWER;
• добавлена backend-проверка bearer-токена и ролей через AuthorizationInterceptor и @RequireRoles;
• добавлен жизненный цикл справочников: ACTIVE / ARCHIVED;
• физическое удаление ключевых сущностей заменено архивированием там, где это влияет на историю;
• добавлена история переводов преподавателей между кафедрами;
• добавлены точечные изменения расписания: перенос, отмена, замена;
• добавлен расширенный read-only поиск расписания по аудитории, преподавателю, кафедре, группе, дисциплине, типу занятия, паре и чётности;
• добавлены отчёты загруженности по преподавателям, аудиториям, кафедрам, парам и свободным аудиториям;
• просмотр расписаний переведён с плоского списка на совмещённые матричные таблицы чётной/нечётной недели с разрезом по группам, преподавателям или аудиториям;
• вкладка загруженности стала общей для аудиторий, преподавателей и кафедр;
• интерфейсы кафедры и учебного отдела переведены в общий стиль админ-панели через role-based вкладки;
• отдельная миграция V2 удалена, изменения схемы внесены в V1__init.sql;
• обновлена документация проекта.

Backend

Роли и авторизация

Поддерживаются роли:

• ADMIN;
• EDUCATION_OFFICE;
• DEPARTMENT;
• SCHEDULE_VIEWER;
• TEACHER;
• STUDENT.

Добавлены:

• AuthSessionService — in-memory UUID-сессии;
• AuthContext — текущий пользователь в ThreadLocal;
• AuthorizationInterceptor — проверка Authorization: Bearer ...;
• @RequireRoles — ограничение доступа на уровне контроллеров и методов;
• GET /api/auth/me — текущий пользователь по токену.

Redirect после входа:

• ADMIN -> /admin/;
• EDUCATION_OFFICE -> /admin/#schedule-view;
• DEPARTMENT -> /admin/#department-workspace;
• SCHEDULE_VIEWER -> /admin/#schedule-view;
• TEACHER -> /teacher/;
• STUDENT -> /student/.

Миграция БД

Отдельная миграция V2__roles_lifecycle_temporal_schedule.sql удалена по текущему решению проекта.

Все изменения схемы внесены в:

backend/src/main/resources/db/migration/V1__init.sql

V1__init.sql теперь сразу создаёт:

• lifecycle-поля к справочникам и пользователям;
• teacher_department_assignments;
• subject_comments;
• version-поля к schedule_rules;
• lock-поля к schedule_rule_slots;
• schedule_overrides;
• стартовых пользователей учебный_отдел, кафедра_иб и просмотр_расписаний.

Архивирование вместо удаления

Архивирование добавлено для пользователей, аудиторий, оборудования, кафедр, специальностей, групп, подгрупп, дисциплин и правил расписания.

Архивные аудитории, преподаватели, группы и дисциплины запрещены для новых назначений. Историческое расписание при этом не теряет ссылки.

История кафедр преподавателя

Добавлены endpoint:

• GET /api/users/{id}/department-history;
• POST /api/users/{id}/department-transfer;
• GET /api/users/teachers/by-department/{departmentId}?date=YYYY-MM-DD.

При переводе преподавателя старая запись закрывается, новая открывается с valid_from, а users.department_id обновляется как текущая кафедра.

Расписание и загруженность

Добавлены:

• GET /api/schedule/search;
• GET /api/workload/teachers;
• GET /api/workload/classrooms;
• GET /api/workload/departments;
• GET /api/workload/time-slots;
• GET /api/workload/free-classrooms;
• GET/POST/PUT/DELETE /api/edu-office/schedule/overrides.

GET /api/schedule теперь использует общий слой поиска, поэтому учитывает точечные изменения расписания.

Роль SCHEDULE_VIEWER имеет доступ только к read-only просмотру расписаний и справочникам-фильтрам.

Кабинет кафедры API

Добавлены:

• 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.

Для роли DEPARTMENT кафедра берётся из текущего пользователя. Для администратора можно выбрать кафедру в UI.

Frontend

Единая панель по ролям

Отдельные интерфейсы /department/ и /edu-office/ заменены на redirect в общую админ-панель:

• /department/ -> /admin/#department-workspace;
• /edu-office/ -> /admin/#schedule-view.

В frontend/admin/js/main.js добавлена фильтрация вкладок:

• ADMIN видит все вкладки;
• EDUCATION_OFFICE видит просмотр расписаний, конструктор расписания, календарный график, загруженность, аудитории и оборудование;
• DEPARTMENT видит кабинет кафедры и просмотр расписаний;
• SCHEDULE_VIEWER видит только просмотр расписаний.

Backend не опирается только на скрытие вкладок. AuthorizationInterceptor проверяет bearer-токен для /api/**, а @RequireRoles ограничивает операции на контроллерах и методах. Для кафедры дополнительно закрыты обходные пути:

• общий /api/subjects оставлен для записи только администратору, кафедра загружает дисциплины через scoped /api/department/subjects/import;
• /api/teacher-subjects для роли DEPARTMENT проверяет, что и преподаватель, и дисциплина относятся к кафедре текущего пользователя;
• SCHEDULE_VIEWER имеет только read-only доступ к расписаниям и справочникам-фильтрам.

После браузерной проверки исправлено визуальное скрытие недоступных вкладок: layout.css теперь принудительно скрывает .nav-item[hidden] и скрытые пункты меню настроек, поэтому роли больше не видят чужие вкладки в sidebar.

Просмотр расписаний

Добавлена вкладка:

frontend/admin/views/schedule-view.html
frontend/admin/js/views/schedule-view.js

Возможности:

• фильтры по одной дате в периоде, группе, преподавателю, аудитории, кафедре, дисциплине, типу занятия и чётности;
• двухнедельный диапазон для таблиц автоматически строится от понедельника выбранной недели;
• выбор разреза таблиц: автоматически, по группам, по преподавателям или по аудиториям;
• совмещённые матричные таблицы найденных занятий: строки — пары, столбцы — дни недели;
• нечётная неделя отображается в верхней половине ячейки, чётная — в нижней, одинаковые занятия в обе недели схлопываются в цельную ячейку;
• карточки занятий внутри ячеек с дисциплиной, группами, подгруппами, преподавателем, аудиторией, типом занятия, чётностью и ID слота.

Загруженность

Вкладка auditorium-workload оставлена техническим tab id, но в UI называется Загруженность.

Возможности:

• выбор типа загруженности: аудитории, преподаватели или кафедры;
• сводная матрица по выбранной дате: строки — выбранные сущности, столбцы — пары;
• кафедральная матрица группирует занятия по кафедре преподавателя;
• для аудиторий сохранены фильтры корпуса, вместимости и оборудования;
• выбор конкретной аудитории, преподавателя или кафедры заменяет обзор двухнедельной таблицей по дням недели и времени;
• чётная и нечётная недели показываются в одной ячейке: если состояние одинаковое, ячейка цельная, если отличается — делится вертикально.

Кабинет кафедры

Добавлена вкладка:

frontend/admin/views/department-workspace.html
frontend/admin/js/views/department-workspace.js

Возможности:

• просмотр дисциплин кафедры;
• загрузка дисциплин из списка код; название;
• просмотр и добавление комментариев к дисциплинам;
• просмотр преподавателей кафедры;
• просмотр нагрузки преподавателей кафедры за период.

Админка

Обновлено:

• создание пользователей теперь поддерживает роли DEPARTMENT, EDUCATION_OFFICE и SCHEDULE_VIEWER;
• удаление пользователей заменено на архивирование;
• вкладка аудиторий показывает архивные записи и умеет восстанавливать аудиторию;
• удаление аудитории заменено на вывод из эксплуатации;
• настройки временных слотов доступны ADMIN и EDUCATION_OFFICE.

Документация

Обновлены:

• AGENTS.md;
• docs/README.md;
• docs/API.md;
• docs/DATABASE.md;
• docs/BUSINESS_LOGIC.md;
• docs/FRONTEND.md;
• docs/ARCHITECTURE.md.

Проверки

Статически проверены новые и изменённые JS-файлы:

node --check frontend/admin/js/main.js
node --check frontend/admin/js/views/schedule-view.js
node --check frontend/admin/js/views/auditorium-workload.js
node --check frontend/admin/js/views/department-workspace.js
node --check frontend/admin/settings/js/main.js
node --check frontend/admin/js/api.js
node --check frontend/admin/js/views/users.js
node --check frontend/admin/js/views/classrooms.js
git diff --check

Backend-компиляция проверяется через Docker Maven:

docker run --rm -v /mnt/HDD/magistr/magistr/backend:/app -w /app maven:3.9-eclipse-temurin-17 mvn -q -DskipTests compile

Результат: компиляция прошла успешно.

Единая V1__init.sql проверена на пустой PostgreSQL 16 внутри Docker: SQL применился успешно.

Локальный mvn в окружении отсутствует, поэтому используется Docker.

Что осталось следующим этапом

Остались задачи, которые требуют отдельного цикла проработки:

• UI для просмотра истории переводов преподавателя в админке;
• UI для списка и редактирования уже созданных schedule_overrides;
• более строгая проверка конфликтов перед сохранением переносов;
• полноценный импорт XLSX/CSV для кафедры вместо текстовой загрузки;
• браузерный smoke-test и проверка ролевых вкладок после запуска localhost:80.