From d69eab1c122fa1a921614438769faa7c64d923d6 Mon Sep 17 00:00:00 2001 From: Zuev Date: Tue, 17 Mar 2026 01:30:48 +0300 Subject: [PATCH] chore: Update Gitea workflow actions to newer versions, add AGENTS.md, and modify gitignore. --- .gitea/workflows/docker-build.yaml | 16 +-- .gitignore | 1 - AGENTS.md | 201 +++++++++++++++++++++++++++++ 3 files changed, 209 insertions(+), 9 deletions(-) create mode 100755 AGENTS.md diff --git a/.gitea/workflows/docker-build.yaml b/.gitea/workflows/docker-build.yaml index b23c642..cef8511 100755 --- a/.gitea/workflows/docker-build.yaml +++ b/.gitea/workflows/docker-build.yaml @@ -17,10 +17,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v6 - name: Log in to the Container registry - uses: docker/login-action@v3 + uses: docker/login-action@v4 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} @@ -28,12 +28,12 @@ jobs: - name: Extract metadata (tags, labels) for Docker id: meta - uses: docker/metadata-action@v5 + uses: docker/metadata-action@v6 with: images: ${{ env.REGISTRY }}/${{ env.BACKEND_IMAGE }} - name: Build and push Docker image - uses: docker/build-push-action@v6 + uses: docker/build-push-action@v7 with: context: ./backend push: true @@ -45,10 +45,10 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repository - uses: actions/checkout@v4 + uses: actions/checkout@v6 - name: Log in to the Container registry - uses: docker/login-action@v3 + uses: docker/login-action@v4 with: registry: ${{ env.REGISTRY }} username: ${{ github.actor }} @@ -56,12 +56,12 @@ jobs: - name: Extract metadata (tags, labels) for Docker id: meta - uses: docker/metadata-action@v5 + uses: docker/metadata-action@v6 with: images: ${{ env.REGISTRY }}/${{ env.FRONTEND_IMAGE }} - name: Build and push Docker image - uses: docker/build-push-action@v6 + uses: docker/build-push-action@v7 with: context: ./frontend push: true diff --git a/.gitignore b/.gitignore index 6b4c2cd..b362f1c 100755 --- a/.gitignore +++ b/.gitignore @@ -11,5 +11,4 @@ frontend/dist/ .idea/ .vscode/ *.DS_Store -AGENTS.md GEMINI.md \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100755 index 0000000..1e900b4 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,201 @@ +# 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/ # Интерфейс студента +├── compose.yaml # Docker Compose конфигурация +└── .env # Переменные окружения +``` + +**Внешние зависимости (родительская директория)** + +На уровень выше расположен `../caddy-proxy/`. Это реверс-прокси, обрабатывающий трафик для `magistr.zuev.company`. Если возникают проблемы с доменом или внешним доступом, проверяйте `Caddyfile` там. + +так же на уровень выше расположен конфиг kubernetes `../k8s/`, все файлы сборки на проде расположены там. + +--- + +## Команды сборки и запуска + +### Docker Compose (основной способ) + +Сборка и запуск всех сервисов (backend, frontend, PostgreSQL) выполняется через Docker Compose. + +```bash +# Сборка и запуск всех сервисов +docker compose up -d --build + +# Остановка всех сервисов +docker compose down + +# Просмотр логов всех сервисов +docker compose logs -f + +# Просмотр логов конкретного сервиса +docker compose logs -f backend + +# Пересоздать контейнер базы данных (полный сброс данных и повтор миграций Flyway) +docker compose down -v +docker compose up -d db +``` + +### Frontend + +Статические файлы обслуживаются через Apache (httpd:alpine). Изменения в файлах frontend требуют пересборки контейнера. + +--- + +## Соглашения о коде (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)**: + - Предложение подходящей замены преподавателя на этот слот. + - Предложение переноса занятия на другое время или в другую аудиторию. + +--- + +## Языковые требования + +- **Все ответы и комментарии на русском языке** +- Сообщения об ошибках и логи на русском +- Пользовательский интерфейс на русском + +--- + +## Существующие правила проекта + +См. `.agent/rules/main.md` и `.agent/rules/database_schema.md` для полного контекста о функциональных требованиях и схеме БД.