📚 Magistr — Система управления университетским расписанием

Обзор

Magistr — веб-приложение для управления расписанием занятий университета. Система поддерживает мультитенантную архитектуру (каждый университет = отдельная база данных), ролевую модель доступа (Администратор, Преподаватель, Студент), календарные учебные графики и полное управление аудиторным фондом, группами, дисциплинами и преподавательским составом.

• Продакшн: https://magistr.zuev.company
• Локальная разработка: http://localhost:80

---

Стек технологий

Компонент	Технология
Backend	Java 17, Spring Boot 3.5.16
Frontend	React 19 + переходные Vanilla JavaScript ES-модули + HTML/CSS
База данных	PostgreSQL (через Flyway миграции)
Контейнеризация	Docker, Docker Compose
Продакшн	Kubernetes, Caddy (реверс-прокси)
Мониторинг	SigNoz, OpenTelemetry
CI/CD	Gitea Actions

---

Быстрый старт

Предварительные требования

• Docker и Docker Compose
• Git
• запущенный Caddy из ../сaddy-proxy/

Локальный запуск

# 1. Клонировать репозиторий
git clone <repo-url> magistr && cd magistr

# 2. Подготовить локальные переменные
cp .env.example .env
# Укажите в .env POSTGRES_PASSWORD и случайный JWT_SECRET.
# JWT_SECRET можно сгенерировать командой: openssl rand -base64 48

# 3. Один раз создать общую proxy-сеть и запустить Caddy
docker network inspect proxy >/dev/null 2>&1 || docker network create proxy
docker compose -f ../сaddy-proxy/compose.yaml up -d

# 4. Запустить все сервисы Magistr
docker compose up -d --build

Compose создаёт внутреннюю сеть и именованный том PostgreSQL, а backend/frontend подключает к общей внешней сети proxy. Они не публикуют порты на хосте: Caddy принимает запросы на https://localhost (http://localhost перенаправляется на HTTPS), /api отправляет в backend, остальные пути — во frontend. PostgreSQL остаётся только во внутренней сети.

Caddy использует локальный корневой сертификат. В CachyOS/Arch его можно добавить в системное хранилище командами из STARTUP_GUIDE.md; без этого браузер покажет предупреждение.

Учётные данные по умолчанию:

Логин	Пароль	Роль
admin	admin	Администратор
Тестовый преподаватель	1234567890	Преподаватель

Эти и остальные прежние демонстрационные записи загружаются миграцией V2__test_data.sql. Она также создаёт 200 дополнительных групп, 150 синтетических преподавателей и связанные дисциплины, аудитории, календари и правила расписания. Пароли массовых преподавателей генерируются случайно и не предназначены для входа.

Полезные команды

# Просмотр логов
docker compose logs -f backend

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

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

---

Структура проекта

magistr/
├── backend/                    # Java Spring Boot backend
│   └── src/main/
│       ├── java/com/magistr/app/
│       │   ├── controller/     # REST-контроллеры (10 шт.)
│       │   ├── model/          # JPA-сущности
│       │   ├── dto/            # Data Transfer Objects
│       │   ├── repository/     # Spring Data JPA репозитории
│       │   ├── config/         # Конфигурация приложения
│       │   │   └── tenant/     # Мультитенантность
│       │   └── utils/          # Валидаторы
│       └── resources/
│           ├── application.properties
│           └── db/migration/   # Flyway SQL миграции
├── frontend/                   # Статический фронтенд
│   ├── index.html              # Страница авторизации
│   ├── admin/                  # Админ-панель (деканат)
│   │   ├── js/views/           # Модули представлений
│   │   └── css/                # Стили
│   ├── department/             # Redirect в кабинет кафедры внутри admin SPA
│   ├── edu-office/             # Redirect в кабинет учебного отдела внутри admin SPA
│   ├── teacher/                # Интерфейс преподавателя
│   └── student/                # Интерфейс студента
├── docs/                       # 📖 Документация (вы здесь)
├── compose.yaml                # Docker Compose конфигурация
├── .env                        # Переменные окружения
└── AGENTS.md                   # Руководство для AI-агентов

---

📖 Навигация по документации

Документ	Содержание
Архитектура	Общая архитектура, мультитенантность, взаимодействие компонентов
Бизнес-логика	Ролевая модель, правила расписания, управление ресурсами
Идеи развития	Продуктовые предложения, приоритеты и возможный roadmap проекта
Календарный учебный график	Модель графиков по специальностям, профилям и группам
База данных	Схема БД, описание таблиц, Flyway миграции
REST API	Все эндпоинты с примерами запросов и ответов
Инфраструктура	Docker, Kubernetes, CI/CD, мониторинг
Runbook безопасности	Production-секреты, ротация и очистка истории
Разработка	Code Style, соглашения, инструкции для разработчиков
Frontend	Архитектура фронтенда, модули, стили