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

## Обзор

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

- **Продакшн:** [https://magistr.zuev.company](https://magistr.zuev.company)
- **Локальная разработка:** [http://localhost:80](http://localhost:80)

---

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

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

---

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

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

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

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

```bash
# 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` | Преподаватель |

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

```bash
# Просмотр логов
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-агентов
```

---

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

| Документ | Содержание |
|----------|-----------|
| [Архитектура](ARCHITECTURE.md) | Общая архитектура, мультитенантность, взаимодействие компонентов |
| [Бизнес-логика](BUSINESS_LOGIC.md) | Ролевая модель, правила расписания, управление ресурсами |
| [Календарный учебный график](ACADEMIC_CALENDAR.md) | Модель графиков по специальностям, профилям и группам |
| [База данных](DATABASE.md) | Схема БД, описание таблиц, Flyway миграции |
| [REST API](API.md) | Все эндпоинты с примерами запросов и ответов |
| [Инфраструктура](INFRASTRUCTURE.md) | Docker, Kubernetes, CI/CD, мониторинг |
| [Runbook безопасности](SECURITY_RUNBOOK.md) | Production-секреты, ротация и очистка истории |
| [Разработка](DEVELOPMENT.md) | Code Style, соглашения, инструкции для разработчиков |
| [Frontend](FRONTEND.md) | Архитектура фронтенда, модули, стили |
