PTKnowBackend

PTKnowBackend - серверная часть платформы дополнительного образования PTKnow. Сервис предоставляет HTTP API для работы с пользователями, профилями, курсами, уроками и файлами

🧭 Назначение проекта

Сервер отвечает за:

• регистрацию, вход, обновление сессии и выход из системы
• выпуск и проверку JWT-токенов
• работу с профилями пользователей
• создание и ведение курсов
• создание и ведение уроков
• хранение markdown-содержимого уроков
• запись пользователей на курсы
• разграничение прав доступа
• загрузку, выдачу и удаление файлов
• административное управление пользователями
• публикацию OpenAPI-описания и Swagger UI

👥 Роли пользователей

• GUEST — пользователь вошёл в систему, но ещё не подтверждён колледжем
• STUDENT — подтверждённый студент
• TEACHER — преподаватель
• ADMIN — администратор платформы

✅ Что уже реализовано

• аутентификация на основе JWT с access- и refresh-токенов
• защита refresh-токенов через хранение хэша
• ролевая модель и проверки владения ресурсами
• работа с профилями пользователей
• полный набор операций для курсов
• полный набор операций для уроков
• запись на курсы
• файловые вложения для профилей, курсов и уроков
• локальное файловое хранилище и поддержка S3-совместимого хранилища
• миграции Flyway
• обработка ошибок на уровне API
• ограничение частоты запросов для критичных точек входа
• кэширование безопасных запросов на чтение
• OpenAPI-описание и Swagger UI
• автоматическая проверка сборки, тестов и миграций

🧱 Технологии

• Java 25
• Spring Boot 4
• Spring Security
• Spring Data JPA и Hibernate
• PostgreSQL
• Flyway
• MapStruct
• JUnit 5 и Mockito
• Docker

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

• политика доступа и безопасности: SECURITY.md
• OpenAPI в формате JSON: /v3/api-docs
• OpenAPI в формате YAML: /v3/api-docs.yaml
• Swagger UI: /swagger-ui.html

⚙️ Требования для локального запуска

Для локального запуска без контейнеров нужны:

• Java 25
• PostgreSQL

🔐 Переменные окружения

Файл .env.example используется как шаблон значений для локального запуска.

Основные переменные:

• PTKNOW_PORT
• PTKNOW_DATASOURCE_ADDRESS
• PTKNOW_DATASOURCE_NAME
• PTKNOW_DATASOURCE_USERNAME
• PTKNOW_DATASOURCE_PASSWORD
• JWT_ISSUER
• SECRET_JWT_KEY
• JWT_REFRESH_COOKIE_SECURE
• JWT_REFRESH_COOKIE_SAME_SITE
• APP_FILE_UPLOAD_DIR
• APP_FILE_STORAGE_TYPE

Spring Boot читает переменные окружения Файл .env сам по себе автоматически не считывается. Его значения применяются только в тех сценариях, где этот файл предварительно загружается во внешние переменные окружения, например через Docker Compose или через конфигурацию запуска среды разработки либо командной оболочки

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

1. Поднять PostgreSQL.
2. Подготовить переменные окружения по шаблону .env.example.
3. Запустить приложение:

./gradlew bootRun

Вместо этого можно запустить PTKnowApplication из среды разработки

🐳 Сборка контейнера

В этом репозитории хранится только образ серверной части:

docker build -t ptknow-server .

Полный сценарий развёртывания через Compose вынесен в отдельный репозиторий: PTKnowDeployment.

🧪 Проверка проекта

Запуск тестов:

./gradlew test

🗃️ Миграции базы данных

Flyway применяется автоматически при запуске приложения JPA работает в режиме ddl-auto=validate

Это означает:

• структура базы данных должна создаваться миграциями
• Hibernate только проверяет соответствие сущностей и схемы