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

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

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

---

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

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

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

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

Подробнее — см. [`docs/README.md`](docs/README.md) и [`docs/INFRASTRUCTURE.md`](docs/INFRASTRUCTURE.md).

---

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

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