Бэкенд диспетчерского стенда «Москоллектор»

Java-приложение принимает события датчиков, загружает справочники и данные смежных систем, хранит прогнозы и решения диспетчера в PostgreSQL и отдаёт REST API и SSE для интерфейса. Инференс модели работает отдельным процессом и обменивается с приложением данными через базу.

Локальный запуск

Нужны JDK 25, Docker и доступ к образам PostgreSQL 18 и Kafka для тестов. Версия Gradle берётся из Wrapper. Локальный compose.yaml поднимает PostgreSQL и имитатор ОДС при bootRun; Kafka по умолчанию ожидается на localhost:9092. Для проверки HTTP API без потока событий можно запустить:

./gradlew --no-daemon bootRun

При старте Liquibase применяет миграции. База по умолчанию — jdbc:postgresql://localhost:5432/goal, пользователь и пароль goal; эти значения предназначены только для локальной разработки. Для внешней базы задаются DB_URL, DB_USER и DB_PASSWORD. Профиль stand включает вход по локальным учётным записям с хэшами паролей из переменных окружения; без него вход через стендовые учётки недоступен.

./gradlew --no-daemon test bootJar

Тесты с аннотацией @IntegrationTest запускают PostgreSQL 18 и Kafka через Testcontainers и требуют работающего Docker. JAR создаётся в build/libs/. Контейнерный образ: docker build -t backend:local .; Dockerfile пропускает тесты, поэтому проверку выполняют отдельно.

API и документы

После запуска Java-приложения на его адресе доступны:

• /swagger-ui.html (либо /swagger-ui/index.html) — Swagger UI;
• /v3/api-docs — сгенерированная спецификация доступных контроллеров;
• /actuator/health — состояние приложения.

Swagger включён по умолчанию; SPRINGDOC_ENABLED=false отключает его. Проверка SwaggerTests подтверждает доступность UI и JSON без входа. Фронтовый Nginx стенда проксирует только /api/v1, поэтому путь Swagger на публичном домене интерфейса может быть недоступен: обращайтесь к адресу Java-приложения или используйте YAML-файл в репозитории.

Документ	Содержание
Описание решения	Архитектура, сборка, данные, ML, ограничения
PDF	Версия для передачи жюри
Контракт интерфейса	Проектный контракт REST/SSE
Виды прогнозов	Поля и фильтры для общего журнала инцидентов и оборудования
Контракт источников	Форматы входящих интеграций
Схема БД	Таблицы и связи
Загрузка данных	Подготовка и импорт журнала
Эксплуатация	Развёртывание, резервирование, откат
Тестирование	Окружение интеграционных тестов
Нагрузочный замер	Профиль и измеренные границы

YAML-файлы фиксируют согласуемые контракты и могут опережать код. /v3/api-docs отражает фактически запущенную версию Java API. При изменении контроллеров следует сверять оба представления.

Contributing

• main защищён: прямой push, force-push и удаление ветки запрещены всем, включая админов.
• Всё попадает в main через PR, merge только squash — один коммит на один PR.
• Merge невозможен без approve другого разработчика. Новый push сбрасывает approve, незакрытые review-треды блокируют merge.
• Заголовок PR — Conventional Commit: <type>(<scope>)!: описание, type из feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert. При squash он и становится коммитом в main, поэтому CI проверяет его и падает на невалидном. Сообщения коммитов внутри ветки тот же CI проверяет, но только предупреждением.
• Жёсткая граница размера PR — 1500 изменённых строк (добавлено + удалено), CI падает при превышении. Целевой размер — до 400. Не считаются gradle/wrapper/**, gradlew*, build/**, *.lock, package-lock.json. Не влезаешь — режь задачу на несколько PR.

Проверяют .github/workflows/pr-policy.yml и branch protection на main.

В одном пакете — не больше 7 смысловых единиц (файлов и подпакетов суммарно): больше — дели пакет на подпакеты.