magistr/.agent/rules/main.md

trigger

trigger
always_on

Контекст проекта: Система расписания университета

Обзор проекта

Этот проект представляет собой веб-сайт системы управления университетским расписанием.

• Роль: Образовательная платформа для управления расписанием.
• Язык: Смешанный (Java Backend + Web Frontend).
• Публичный URL: https://magistr.zuev.company

Структура директорий и обязанности

Проект следует определенной структуре папок. Вы должны придерживаться этих путей:

• backend/: Содержит исходный код бэкенд-приложения на Java.

  • При работе с API или серверной логикой фокусируйтесь здесь.

• frontend/: Содержит исходный код фронтенда. Обратите внимание на строгое разделение ролей:

  • frontend/admin/: Код, специфичный для интерфейса Администратора.
  • frontend/teacher/: Код, специфичный для интерфейса Преподавателя.
  • frontend/student/: Код, специфичный для интерфейса Студента.
  • Ограничение: Не смешивайте логику между этими папками, если только не создаете общую утилиту.

• db/: Конфигурация и данные базы данных.

  • db/init/init.sql: SQL-скрипт, отвечающий за создание и инициализацию схемы базы данных (таблицы, начальные данные).

• Корневые файлы:

  • compose.yaml: Конфигурация Docker Compose. Этот файл определяет сервисы (бэкенд, БД, фронтенд-серверы) и то, как они работают вместе.
  • .env: Переменные окружения. Содержит конфиденциальные настройки (пароли БД, порты, ключи API).

Внешние зависимости (родительская директория)

Некоторые компоненты инфраструктуры расположены за пределами корня проекта:

• ../caddy-proxy/: Находится на один уровень выше относительно корня проекта.
  • Роль: Реверс-прокси, обрабатывающий трафик для magistr.zuev.company.
  • Caddyfile: Конфигурация для маршрутизации и SSL.
  • compose.yaml: Отдельный файл Docker Compose специально для службы прокси.

Рекомендации по рабочему процессу

1. Изменения в базе данных: Если вам нужно изменить схему базы данных, вы должны обновить db/init/init.sql, чтобы изменения сохранялись при пересборке контейнера.
2. Конфигурация: Если вы добавляете новые параметры конфигурации, добавьте их в .env и сошлитесь на них в compose.yaml или коде приложения.
3. Маршрутизация/Прокси: Если возникают проблемы с доменом или внешним доступом, проверьте конфигурацию в ../caddy-proxy/Caddyfile.

Языковые предпочтения

• Всегда отвечайте на русском: Это строгое требование пользователя. Все объяснения, комментарии и взаимодействия должны быть на русском языке, если только не будет специально запрошено иное.

Функциональные требования к системе

1. Ролевая модель

• Администратор (Деканат): Полный доступ, настройка топологии университета, управление аудиторным фондом, подтверждение переносов, регистрация инцидентов.
• Преподаватель: Просмотр своего расписания, подача заявок на перенос, отметка о своём отсутствии.
• Студент: Только просмотр расписания (Read-only).

2. Управление ресурсами и топология

• Управление аудиториями:
  • Указание вместимости.
  • Указание тэгов оборудования (Проектор, ПК, Лаборатория).
  • Установка статуса "Не доступно" (блокирует назначение пар в этот период).
• Управление группами:
  • Управление списком студентов (и возможность деления на подгруппы).
• Управление дисциплинами:
  • Создание предметов и привязка их к преподавателям (какие дисциплины имеет право вести конкретный преподаватель).

3. Логика расписания

• Проверка конфликтов:
  • Критический конфликт: Преподаватель не может находиться в двух разных аудиториях одновременно.
  • Уточнение по преподавателям: Преподаватель может иметь несколько пар одновременно (для разных групп), только если они проходят в одной и той же аудитории (потоковая лекция).
• Потоковые занятия:
  • Возможность назначить одну лекцию сразу нескольким группам (технически — несколько записей в БД или одна запись со списком групп).
  • Проверка вместимости: вместимость аудитории должна покрывать суммарную численность всех групп, находящихся в этой аудитории в данный слот.

4. Управление инцидентами (Инклюзия отсутствия)

• Отсутствие (Sickness/Business Trip): Регистрация отсутствия преподавателя (с указанием причины и периода дат).
• Обнаружение коллизий: Автоматическая подсветка конфликтующих пар в расписании (Red Zone).
• Система разрешения конфликтов (Resolution Wizard):
  • Предложение подходящей замены преподавателя на этот слот.
  • Предложение переноса занятия на другое время или в другую аудиторию.

Технологический стек (Tech Stack)

• Backend: Java 17, Spring Boot 3.2.5 (Starter Web, Data JPA), кастомная токен-авторизация (используется BCrypt, без полной автоконфигурации Spring Security).
• Database: PostgreSQL.
• Frontend: Vanilla JavaScript + HTML/CSS (без тяжеловесных фреймворков).

Специфика времени и сетка расписания (Time Management)

• Гибкие временные слоты: По умолчанию слоты по 1.5 часа:
  1. 08:00 - 09:30
  2. 09:40 - 11:10
  3. 11:40 - 13:10
  4. 13:20 - 14:50
  5. 15:00 - 16:30
  6. 16:50 - 18:20
  7. 18:30 - 20:00
• Кастомное время: Система должна позволять устанавливать кастомное время начала и конца пары.
• Тип расписания: Календарное расписание, строящееся по принципу чётной / нечётной недели.

Основные сущности базы данных (Data Entities)

• Users: Хранение пользователей и их ролей (Администратор, Преподаватель, Студент) для управления доступом.
• Groups: Группы студентов, их привязка к формам обучения. (Могут делиться на подгруппы для лабораторных и практик).
• Classrooms: Аудиторный фонд (название, вместимость, статус доступности, тэги оборудования).
• Subjects: Предметы/Дисциплины (Высшая математика, Физика, Базы данных и т.д.).
• Teacher_Subjects: Связующая таблица (Many-to-Many), определяющая, какие дисциплины ведет конкретный преподаватель.
• Lesson_Types: Типы занятий для валидации (Лекция, Практика, Лабораторная работа).
• Lessons / Schedules: Сами занятия (пары). Каждая запись связывает преподавателя, аудиторию, группу (или подгруппу), предмет (subject_id), тип занятия (lesson_type) и конкретное время.