131 lines
7.0 KiB
Markdown
131 lines
7.0 KiB
Markdown
# 📚 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) | Архитектура фронтенда, модули, стили |
|