magistr/AGENTS.md

AGENTS.md - Руководство для агентных помощников

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

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

• Backend: Java 17, Spring Boot 3.2.5 (Мультитенантная архитектура: отдельная БД для каждого клиента)
• Frontend: Vanilla JavaScript + HTML/CSS (без фреймворков)
• Database: PostgreSQL (множество БД, управляются через Flyway)
• Локальный URL: localhost:80
• Продакшн URL: https://magistr.zuev.company

---

Структура директорий

magistr/
├── backend/           # Java Spring Boot приложение
│   └── src/main/java/com/magistr/app/
│       ├── controller/   # REST контроллеры
│       ├── model/       # JPA сущности
│       ├── dto/         # Data Transfer Objects
│       ├── repository/  # Spring Data JPA репозитории
│       ├── config/      # Конфигурация приложения
│       ├── utils/       # Утилиты
│   └── src/main/resources/db/migration/ # Flyway SQL миграции (версионирование схемы БД)
├── frontend/          # Статические файлы
│   ├── admin/         # Интерфейс администратора
│   ├── teacher/       # Интерфейс преподавателя
│   └── student/       # Интерфейс студента
├── compose.yaml       # Docker Compose конфигурация
└── .env               # Переменные окружения

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

На уровень выше расположен ../caddy-proxy/. Это реверс-прокси, обрабатывающий трафик для magistr.zuev.company. Если возникают проблемы с доменом или внешним доступом, проверяйте Caddyfile там.

так же на уровень выше расположен конфиг kubernetes ../k8s/, все файлы сборки на проде расположены там.

---

Команды сборки и запуска

Docker Compose (основной способ)

Сборка и запуск всех сервисов (backend, frontend, PostgreSQL) выполняется через Docker Compose.

# Сборка и запуск всех сервисов
docker compose up -d --build

# Остановка всех сервисов
docker compose down

# Просмотр логов всех сервисов
docker compose logs -f

# Просмотр логов конкретного сервиса
docker compose logs -f backend

# Пересоздать контейнер базы данных (полный сброс данных и повтор миграций Flyway)
docker compose down -v
docker compose up -d db

Frontend

Статические файлы обслуживаются через Apache (httpd:alpine). Изменения в файлах frontend требуют пересборки контейнера.

---

Соглашения о коде (Code Style)

Java (Backend)

Именование:

• Классы: PascalCase (например, LessonsController, LessonResponse)
• Методы и переменные: camelCase
• Константы: UPPER_SNAKE_CASE
• Пакеты: lowercase (например, com.magistr.app.controller)

Импорты:

• Группировка: static imports, затем external packages, затем internal
• Используйте wildcard imports для пакетов того же модуля: import com.magistr.app.model.*;
• Порядок: java., javax., external., internal.

Форматирование:

• Отступы: 4 пробела (стандарт Java)
• Фигурные скобки: K&R style (открывающая на той же строке)
• Длина строки: до 120 символов
• Всегда используйте фигурные скобки для if/for/while

Типы и аннотации:

• Используйте явные типы вместо var для возвращаемых значений публичных методов
• Аннотации JPA: @Entity, @Table, @Id, @GeneratedValue, @Column
• Используйте @JsonInclude(JsonInclude.Include.NON_NULL) для DTO
• Для логгирования используйте SLF4J: LoggerFactory.getLogger(ClassName.class)

Обработка ошибок:

• Возвращайте ResponseEntity<?> с соответствующим HTTP статусом
• Логируйте ошибки с полным стектрейсом: logger.error("msg: {}", e.getMessage(), e)
• Для валидации используйте отдельные классы-валидаторы (см. DayAndWeekValidator)

Архитектура контроллеров:

• Используйте constructor injection для зависимостей
• Все endpoints имеют префикс /api/
• Возвращайте понятные сообщения об ошибках на русском языке

Frontend (JavaScript)

Именование:

• Файлы: kebab-case (например, main.js, schedule-view.js)
• Функции и переменные: camelCase
• Константы: UPPER_SNAKE_CASE

Модули:

• Используйте ES6 modules с import/export
• Всегда указывайте расширение при импорте: import { x } from './api.js';

Форматирование:

• Отступы: 4 пробела
• Используйте template literals вместо конкатенации строк
• Предпочитайте const переменные, используйте let только при необходимости переприсваивания

Лучшие практики:

• Используйте async/await для асинхронных операций
• Всегда обрабатывайте ошибки в блоках catch
• Используйте деструктуризацию объектов
• Кешируйте DOM-элементы в переменные

---

Работа с базой данных и мультитенантностью

Мультитенантность:

• Приложение поддерживает множество клиентов (университетов). Каждый клиент имеет свою изолированную базу данных PostgreSQL.
• Маршрутизация к нужной БД происходит динамически на основе поддомена (TenantInterceptor -> TenantContext -> TenantRoutingDataSource).
• Список клиентов хранится в Kubernetes ConfigMap (tenants-config), который монтируется в под бэкенда как /config/tenants.json.
• Локально список берётся из файла backend/tenants.json.
• При добавлении нового клиента в интерфейсе DatabaseController через K8s API обновляет ConfigMap. Все реплики бэкенда заметят изменения и в фоне инициализируют новый пул соединений (TenantConfigWatcher).

Миграции схемы (Flyway):

• Автогенерация Hibernate ОТКЛЮЧЕНА (ddl-auto=none). Структура баз данных управляется строго через Flyway.
• Все изменения схемы БД вносятся путем создания новых файлов в backend/src/main/resources/db/migration/ (название строго V2__add_new_table.sql и т.д.).
• ЗАПРЕЩЕНО изменять существующие файлы миграций (например, V1__init.sql), которые уже закоммичены. Это сломает контрольные суммы Flyway.
• Flyway запускается программно при первом обращении к базе тенанта. Чтобы запустить Flyway для уже существующих тенантов (накатить V2), необходимо перезапустить бэкенд: kubectl rollout restart deployment backend -n magistr.
• Для локального сброса базы до изначального состояния: docker compose down -v && docker compose up -d.

Сущности и связи:

• Foreign keys с ON DELETE CASCADE для поддержания целостности
• Используйте расширение pgcrypto для хеширования паролей (bcrypt)

---

Функциональные требования к системе (Бизнес-логика)

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

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

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

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

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

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

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

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

---

Языковые требования

• Все ответы и комментарии на русском языке
• Сообщения об ошибках и логи на русском
• Пользовательский интерфейс на русском

---

Существующие правила проекта

См. .agent/rules/main.md и .agent/rules/database_schema.md для полного контекста о функциональных требованиях и схеме БД.