Zuev/magistr
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Add comprehensive project documentation covering architecture, development, and APIs, and update AGENTS.md.

Browse Source
This commit is contained in:
Zuev
2026-03-22 02:49:13 +03:00
committed by alekan
parent 9e7b35aa0b
commit ec7e615557
10 changed files with 1829 additions and 145 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
AGENTS.md
View File

@@ -28,174 +28,59 @@ magistr/
│ ├── admin/ # Интерфейс администратора
│ ├── teacher/ # Интерфейс преподавателя
│ └── student/ # Интерфейс студента
├── docs/ # 📖 Документация проекта
├── compose.yaml # Docker Compose конфигурация
└── .env # Переменные окружения
```
**Внешние зависимости (родительская директория)**
На уровень выше расположен `../caddy-proxy/`. Это реверс-прокси, обрабатывающий трафик для `magistr.zuev.company`. Если возникают проблемы с доменом или внешним доступом, проверяйте `Caddyfile` там.
так же на уровень выше расположен конфиг kubernetes `../k8s/`, все файлы сборки на проде расположены там.
На уровень выше расположен конфиг kubernetes `../k8s/`, все файлы сборки на проде расположены там.
---
## Команды сборки и запуска
### Docker Compose (основной способ)
Сборка и запуск всех сервисов (backend, frontend, PostgreSQL) выполняется через Docker Compose.
## Быстрый справочник команд
```bash
# Сборка и запуск всех сервисов
# Сборка и запуск
docker compose up -d --build
# Остановка всех сервисов
docker compose down
# Полный сброс БД
docker compose down -v && docker compose up -d
# Просмотр логов всех сервисов
docker compose logs -f
# Просмотр логов конкретного сервиса
# Логи конкретного сервиса
docker compose logs -f backend
# Пересоздать контейнер базы данных (полный сброс данных и повтор миграций Flyway)
docker compose down -v
docker compose up -d db
```
### Frontend
Статические файлы обслуживаются через Apache (httpd:alpine). Изменения в файлах frontend требуют пересборки контейнера.
Подробнее — см. [`docs/README.md`](docs/README.md) и [`docs/INFRASTRUCTURE.md`](docs/INFRASTRUCTURE.md).
---
## Соглашения о коде (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)**:
- Предложение подходящей замены преподавателя на этот слот.
- Предложение переноса занятия на другое время или в другую аудиторию.
---
## Языковые требования
### Flyway миграции
- **ЗАПРЕЩЕНО** изменять существующие файлы миграций (например, `V1__init.sql`). Это сломает контрольные суммы Flyway.
- Новые миграции: `V{N}__{описание}.sql` в `backend/src/main/resources/db/migration/`
- Подробнее — см. [`docs/DATABASE.md`](docs/DATABASE.md)
### Языковые требования
- **Все ответы и комментарии на русском языке**
- Сообщения об ошибках и логи на русском
- Пользовательский интерфейс на русском
---
## Существующие правила проекта
## Подробная документация
См. `.agent/rules/main.md` и `.agent/rules/database_schema.md` для полного контекста о функциональных требованиях и схеме БД.
Полная документация проекта находится в папке `docs/`:
| Документ | Содержание |
|----------|-----------|
| [`docs/README.md`](docs/README.md) | Обзор проекта, стек технологий, быстрый старт |
| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Архитектура системы, мультитенантность, аутентификация |
| [`docs/BUSINESS_LOGIC.md`](docs/BUSINESS_LOGIC.md) | Бизнес-логика, ролевая модель, правила расписания |
| [`docs/DATABASE.md`](docs/DATABASE.md) | Схема БД (ER-диаграмма), описание всех таблиц, Flyway |
| [`docs/API.md`](docs/API.md) | REST API эндпоинты с примерами запросов и ответов |
| [`docs/INFRASTRUCTURE.md`](docs/INFRASTRUCTURE.md) | Docker, Kubernetes, CI/CD, мониторинг (SigNoz) |
| [`docs/DEVELOPMENT.md`](docs/DEVELOPMENT.md) | Code Style, соглашения, пошаговое создание нового эндпоинта |
| [`docs/FRONTEND.md`](docs/FRONTEND.md) | Frontend архитектура, SPA-маршрутизация, CSS, адаптивность |