diploma-server/docs/architecture.md

Архитектура и структура сервиса

Документ описывает как организован сервер дипломного проекта: какие слои присутствуют, как они взаимодействуют и где искать ключевые модули.

Общий обзор

Сервис написан на Kotlin с использованием Ktor и разворачивается как Netty-приложение (Application.kt). Приложение поднимает инфраструктурные плагины (HTTP, сериализация, безопасность) и регистрирует доменные маршруты. Все функции сгруппированы в повторяющийся паттерн Controller → Service → Repository → Entity, что делает поддержку CRUD-операций симметричной во всех доменных областях.

Высокоуровневый поток запросов:

1. HTTP-вызов попадает в Routing.kt, где маршруты разделены на публичную и админскую зоны (/api/v1/...).
2. Контроллер модуля занимается десериализацией запроса, базовой валидацией и формированием ответа.
3. Сервис инкапсулирует бизнес-правила: публикация материалов, фильтрация, проверка прав, подготовка DTO.
4. Репозиторий обращается к PostgreSQL через Ktorm, используя HikariCP-пул соединений.
5. Исключения (ValidationException, NotFoundException) перехватывает StatusPages, что обеспечивает единый контракт ошибок.

Графическая схема слоев расположена в docs/crud-model.svg.

Структура каталогов

src/main/kotlin
├── app                # Bootstrap: Application, Routing, Security, HTTP, Database
├── shared             # Переиспользуемые DTO, пагинация, ошибки
└── modules            # Доменные модули (admin, news, service, serviceCategory, lead)
src/main/resources
├── application.yaml   # Конфигурация Ktor
└── openapi            # Спецификации API
src/test/kotlin        # Зеркало production-пакетов для тестов
docs/
├── crud-model.svg     # Диаграмма последовательности CRUD
└── architecture.md    # Текущий документ

Инфраструктурный слой (app/*)

• Application.module – точка входа, выстраивает последовательность configureDatabase → configureHTTP → configureSerialization → configureSecurity → configureRouting.
• Database.kt – инициализация пула HikariCP (настройки берутся из .env), регистрация Database в Application.attributes.
• Http.kt – подключает плагины Ktor (CORS, Compression, CachingHeaders, StatusPages, Swagger UI). Здесь же централизованно обрабатываются исключения.
• Serialization.kt – ContentNegotiation с kotlinx.serialization.
• Security.kt – загрузка параметров JWT из окружения, настройка схемы admin-auth, валидация JWTPrincipal.
• Routing.kt – собирает зависимости модулей, подключает публичные маршруты и оборачивает админские роуты в authenticate("admin-auth").

Доменные модули (modules/*)

Каждый модуль состоит из четырех файлов:

• Controller.kt – набор Ktor-маршрутов для публичной и/или админской зоны.
• Service.kt – бизнес-логика. Например, NewsService отвечает за публикацию, пагинацию и преобразование сущностей в DTO, а ServiceService поддерживает фильтры по статусу, категории и ценовому диапазону.
• Repository.kt – слой доступа к данным на Ktorm: построение SQL, пагинация, CRUD-операции, трансформации в Entity.
• Entity.kt / DTO – описания таблиц, модели для сериализации и транспортировки данных.

Admin

Отвечает за регистрацию, авторизацию и управление администраторами. Использует BcryptPasswordHasher для хранения паролей и TokenService для выпуска JWT. Публичная часть (/admin/login) возвращает токен; защищенная (/admin/*) требует admin-auth.

News

Два набора маршрутов: публичные (/news, /news/{slug}) и админские (/admin/news). Сервис применяет правила публикации и формирует страницы (Page<T>). Репозиторий обрабатывает SQL для списков и выборок по slug.

Services и Service Categories

ServiceController поддерживает сложные фильтры (категория, диапазон цен, статус). ServiceService связывает услуги с категориями, обеспечивая получение вложенных DTO. ServiceCategory* модули обслуживают справочник категорий и проверяют уникальность slug.

Leads

publicLeadRoutes принимает заявки с сайта (POST /leads), adminLeadRoutes предоставляет CRUD для операторов. Сервис выполняет базовую валидацию и поиск по строке q.

Общие компоненты (shared/*)

• shared.pagination.Page – универсальный ответ для списков.
• shared.errors.ValidationException/NotFoundException – типы, которые перехватываются StatusPages и автоматически конвертируются в HTTP-ответ.

Работа с БД

• База – PostgreSQL, подключение через Ktorm + HikariCP (jdbc:postgresql://...).
• Пулы – настраиваются через переменные окружения (DB_HOST, DB_POOL_MAX и т.д.).
• Репозитории – реализованы вручную на SQL Builder, что дает контроль над запросами и связями между таблицами (services ↔ service_categories, news, leads, admins).

Безопасность

• Единственная схемa аутентификации – JWT admin-auth.
• Конфигурация (JWT_SECRET, JWT_ISSUER, JWT_AUDIENCE, JWT_EXPIRES_MIN) читается из .env или переменных окружения.
• Public маршруты доступны без токена, все admin*Routes подключены внутри authenticate.

Сборка и эксплуатация

• Основные команды Gradle:
  • ./gradlew run – локальный сервер.
  • ./gradlew test – прогон тестов (обязателен перед пушем).
  • ./gradlew buildFatJar – сборка standalone JAR.
  • ./gradlew buildImage / runDocker – сборка и запуск docker-образа.
• Конфигурация HTTP-порта, логирования и OpenAPI лежит в src/main/resources/application.yaml и resources/openapi.
• Для обновления документации добавляйте артефакты в docs/ (например, текущую архитектурную схему и диаграмму CRUD).

Тестирование

Тесты зеркалируют production-пакеты (src/test/kotlin/...). При добавлении новой функциональности рекомендуется:

1. Класть тесты в соответствующий пакет модуля (например, modules/news/NewsServiceTest.kt).
2. Проверять ветки успеха, валидации и авторизации.
3. Запускать ./gradlew test перед коммитом, чтобы убедиться в корректной работе всего набора.