Pathfinders - Электронный журнал клуба "Следопыт"

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

Pathfinders - это веб-приложение для управления клубом "Следопыт", которое позволяет директорам клуба управлять учениками, занятиями и выставлять оценки.

🚀 Технологический стек

• Backend: Java 17, Spring Boot 3.1.x
• Database: PostgreSQL 14+
• Build Tool: Maven
• Containerization: Docker, Docker Compose
• Frontend: HTML, CSS, JavaScript

📦 Требования

• Java 17 или выше
• Maven 3.6+
• Docker и Docker Compose
• PostgreSQL 14+ (при локальной разработке без Docker)

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

Вариант 1: Запуск с Docker Compose (рекомендуется)

1. Клонируйте репозиторий:

git clone https://github.com/kozionov/Pathfinders.git
cd Pathfinders

2. Запустите PostgreSQL:

docker-compose -f docker-compose-psgr.yml up -d

3. Соберите и запустите приложение:

docker-compose -f docker-compose-app.yml up --build

4. Откройте браузер и перейдите по адресу: http://localhost:9090

Вариант 2: Локальная разработка

1. Запустите PostgreSQL:

docker-compose -f docker-compose-psgr.yml up -d

2. Соберите проект:

mvn clean package

3. Запустите приложение:

java -jar target/pathfinders-*.jar

👤 Доступ по умолчанию

• URL: http://localhost:9090/
• Логин: dir
• Пароль: dir
• Роль: Директор клуба

🏗️ Архитектура проекта

Pathfinders/
├── src/
│   ├── main/
│   │   ├── java/ru/otus/hw/
│   │   │   ├── controller/     # REST контроллеры
│   │   │   ├── service/        # Бизнес-логика
│   │   │   ├── repository/     # Слой данных (JPA)
│   │   │   ├── model/          # Entities и DTO
│   │   │   ├── exception/      # Обработка ошибок
│   │   │   └── config/         # Конфигурация Spring
│   │   └── resources/
│   │       ├── application.yml # Настройки приложения
│   │       ├── static/         # Статические ресурсы
│   │       └── templates/      # HTML шаблоны
│   └── test/                   # Тесты
├── Dockerfile
├── docker-compose-app.yml
├── docker-compose-psgr.yml
└── pom.xml

📊 Основные функции

Управление клубом

• Создание и настройка клуба
• Управление информацией о клубе

Управление учениками

• Добавление новых учеников
• Редактирование информации об учениках
• Просмотр списка учеников

Управление занятиями

• Создание занятий
• Выставление оценок ученикам
• Просмотр истории занятий

🔧 Конфигурация

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

Вы можете настроить приложение через переменные окружения:

# База данных
SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/pathfinders
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=postgres

# Порт приложения
SERVER_PORT=8080

# Управление схемой БД (dev/test)
SPRING_JPA_HIBERNATE_DDL_AUTO=validate

# Детализация ошибок (dev)
SERVER_ERROR_INCLUDE_MESSAGE=always
SERVER_ERROR_INCLUDE_BINDING_ERRORS=always
SERVER_ERROR_INCLUDE_STACKTRACE=on_param

application.yml

Основные настройки находятся в src/main/resources/application.yml

🧩 Миграции базы данных (Liquibase)

По умолчанию миграции применяются автоматически при старте приложения.

Локальное применение миграций

1. Запустите PostgreSQL:

docker-compose -f docker-compose-psgr.yml up -d

2. Запустите приложение (миграции применятся автоматически):

mvn spring-boot:run

Где находятся миграции

• Основной changelog: src/main/resources/db/changelog/db.changelog-master.yml
• Структура БД: src/main/resources/db/changelog/1.0/
• Данные (seed): src/main/resources/db/changelog/data/

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

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

mvn test

Запуск с покрытием кода:

mvn test jacoco:report

Отчет будет доступен в target/site/jacoco/index.html

🐛 Известные проблемы и TODO

Требуется доработка:

• Валидация данных с форм - добавить Bean Validation для всех входных данных
• Обработка ошибок от сервера на клиенте - реализовать централизованную обработку ошибок
• Страница логина - создать полноценную страницу аутентификации
• Spring Security - внедрить полноценную систему безопасности
• API документация - добавить Swagger/OpenAPI
• Миграции БД - настроен Liquibase
• Unit тесты - увеличить покрытие кода тестами
• CI/CD - настроить GitHub Actions для автоматических сборок

🤝 Разработка

Стиль кода

• Используйте Google Java Style Guide
• Запускайте форматирование перед коммитом: mvn spotless:apply

Git workflow

1. Создайте feature-ветку от master
2. Внесите изменения
3. Создайте Pull Request
4. После review сделайте merge

Коммиты

Используйте Conventional Commits:

feat: добавление новой функциональности
fix: исправление ошибки
docs: изменение документации
test: добавление тестов
refactor: рефакторинг кода

📝 Лицензия

МIT License

👨‍💻 Автор

Sergey Kozionov - @kozionov

📞 Контакты

Если у вас есть вопросы или предложения, создайте Issue в репозитории.

---

⭐ Если проект оказался полезным, поставьте звезду на GitHub!