Сервис интерактивных карт зданий

Backend-часть интерактивных карт, предоставляющая REST API для навигации, построения маршрутов, аутентификации и администрирования данных карты.

Содержание

• Описание проекта
• Технологии
• Структура и архитектура
• Установка и запуск
• Лицензия

Описание проекта

Сервис обеспечивает хранение и обработку пространственных данных университета. Система позволяет ориентироваться в зданиях, строить оптимальные маршруты между кабинетами, объектами и этажами. Включает административный модуль с авторизацией для настройки инфраструктуры (добавление новых зданий, этажей, помещений, лестниц и узлов графа маршрутизации).

Технологии

• Язык разработки: Java 21
• Фреймворк: Spring Boot 3.4.4
• База данных: PostgreSQL
• ORM: Hibernate 6 / Spring Data JPA (+ Hypersistence Utils 3.9.2)
• Маппинг: MapStruct 1.6.3
• Безопасность: Spring Security, JWT (JJWT 0.11.5), Rate Limiting
• API Документация: Swagger (Springdoc OpenAPI 2.8.6)
• Сборка: Gradle 8.13

Структура и архитектура

Проект разбит на логические модули внутри пакета org.mininuniver.interactiveMap:

1. Модуль auth (Авторизация и безопасность)

Обеспечивает stateless аутентификацию на основе JWT.

• controller: Эндпоинты для логина и получения/обновления токенов (AuthController).
• security: Фильтры (JwtFilter, LoginRateLimitFilter) и утилиты валидации токенов (JwtUtil).
• dto: Модели запросов/ответов (LoginRequest, AuthResponse и т.д.).

2. Модуль map (Бизнес-логика карты)

Ядро системы, описывающее все топологические данные карты.

• model (Сущности БД):
  • Building (Здание) — корневая инфраструктурная сущность.
  • Floor (Этаж) — содержит объекты, лестницы и привязан к зданию.
  • Room (Аудитория), Stairs (Лестница) — конкретные объекты на этаже.
  • GraphNode — узлы графа для расчёта кратчайших путей (Wayfinding).
  • MapObject / DefaultObject — базовые классы/интерфейсы.
• dto: Транспортные объекты для сериализации (например, BuildingDTO, FloorShortDTO, PointDTO).
• mapper: Компоненты для маппинга сущностей в DTO (BuildingMapper, RoomMapper, StairsMapper и др.).
• controller:
  • MapController — публичное API для получения данных клиентом.
  • AdminController — защищенные эндпоинты для управления картой.
• service / repository: Слои логики и работы с БД для каждой сущности.

3. Базовые компоненты (config, common, seed)

• config: Настройки SecurityConfig (CORS/CSRF, доступы), SwaggerConfig, WebConfig.
• common.exception: Глобальная обработка ошибок (GlobalExceptionHandler) для возврата стандартизированных ответов (ApiError).
• seed: Класс DataSeeder для автоматического наполнения базы начальными данными при запуске.

Установка и запуск

Требования

• JDK 21
• PostgreSQL
• Сборщик Gradle 8.13 (или обертка gradlew)

Настройка

1. Создайте базу данных в PostgreSQL (например, minin_map).
2. Задайте настройки в файле src/main/resources/application.properties (адрес БД, логин, пароль, секреты JWT). Либо поднимите PostgreSQL с помощью Docker Сompose, используя предоставленный docker-compose.yml.

Сборка и запуск

Выполните команды:

./gradlew clean build
./gradlew bootRun

Документация API

После запуска приложения интерактивная документация (Swagger UI) доступна по пути: http://localhost:8080/swagger-ui/index.html

Лицензия

Распространяется под лицензией GNU Affero General Public License v3.0 или более поздней версии. Подробности см. в файле LICENSE.