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/         # Интерфейс администратора
│   │   └── settings/  # Страница настроек (отдельный SPA)
│   ├── teacher/       # Интерфейс преподавателя
│   └── student/       # Интерфейс студента
├── docs/              # 📖 Документация проекта
├── compose.yaml       # Docker Compose конфигурация
└── .env               # Переменные окружения

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

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

Быстрый справочник команд

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

# Полный сброс БД
docker compose down -v && docker compose up -d

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

Подробнее — см. docs/README.md и docs/INFRASTRUCTURE.md.

Критические правила для агентов

Flyway миграции

ЗАПРЕЩЕНО изменять существующие файлы миграций (например, V1__init.sql). Это сломает контрольные суммы Flyway.
Новые миграции: V{N}__{описание}.sql в backend/src/main/resources/db/migration/
Подробнее — см. docs/DATABASE.md

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

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

Подробная документация

Полная документация проекта находится в папке docs/:

Документ	Содержание
`docs/README.md`	Обзор проекта, стек технологий, быстрый старт
`docs/ARCHITECTURE.md`	Архитектура системы, мультитенантность, аутентификация
`docs/BUSINESS_LOGIC.md`	Бизнес-логика, ролевая модель, правила расписания
`docs/DATABASE.md`	Схема БД (ER-диаграмма), описание всех таблиц, Flyway
`docs/API.md`	REST API эндпоинты с примерами запросов и ответов
`docs/INFRASTRUCTURE.md`	Docker, Kubernetes, CI/CD, мониторинг (SigNoz)
`docs/DEVELOPMENT.md`	Code Style, соглашения, пошаговое создание нового эндпоинта
`docs/FRONTEND.md`	Frontend архитектура, SPA-маршрутизация, CSS, адаптивность
`docs/LOGGING.md`	Логирование: SLF4J + Logback, MDC, OpenTelemetry → SigNoz
`docs/UI_COMPONENTS.md`	Использование дизайн-системы (кастомные селекты, чекбоксы и др.)

4.9 KiB Executable File Raw Blame History Unescape Escape