Bank Cards API — Тестовое приложение

Небольшая RESTful система управления банковскими картами. Реализовано для тестового задания на позицию Java Developer.
Проект покрывает основные бизнес-сценарии: регистрация и аутентификация пользователей (JWT), роли (ADMIN/USER), CRUD карт, поиск/пагинация, переводы между своими картами, шифрование номеров карт и маскирование при выводе.

---

Содержание

• Функционал
• Технологии
• Требования
• Быстрый старт (Docker)
• Запуск локально (Maven)
• Переменные окружения / конфигурация
• Документация API (OpenAPI / Swagger)
• Аутентификация и пример запросов (curl)
• Тесты
• Безопасность и замечания

---

Функционал

• Регистрация пользователей и логин (JWT).
• Роли: ROLE_ADMIN и ROLE_USER.
• CRUD операции с картами (ADMIN): создание, блокировка, активация, удаление, обновление срока действия.
• Просмотр собственных карт (USER) с фильтрацией по статусу и пагинацией.
• Запрос блокировки карты от владельца (USER).
• Переводы между своими картами (USER) с проверками:
  • принадлежат ли карты пользователю,
  • активный статус,
  • достаточно ли баланса,
  • нельзя переводить на ту же карту.
• Номера карт хранятся зашифрованными (AES), при выводе возвращается маска **** **** **** 1234.
• Migrations: Liquibase changelogs для создания таблиц.
• Swagger/OpenAPI документация.

---

Технологии

• Java 17
• Spring Boot 3.x
• Spring Security (JWT)
• Spring Data JPA (Hibernate)
• PostgreSQL
• Liquibase
• Docker / Docker Compose
• jjwt (JWT)
• springdoc-openapi (Swagger)
• Maven, JUnit5, Mockito

---

Требования

• Docker & Docker Compose (рекомендуется для dev)
• Java 17 (для локального запуска)
• Maven (для локальной сборки)

---

Быстрый старт (Docker)

В корне проекта есть docker-compose.yml, который поднимает Postgres и приложение.

1. Сборка и запуск:

   • docker-compose up --build

2. После запуска:

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

Docker Compose использует переменные внутри файла — при необходимости редактируйте docker-compose.yml и application.yml.

---

Запуск локально (Maven)

1. Поднять базу данных PostgreSQL (локально или через Docker).
2. Настроить параметры подключения в src/main/resources/application.yml или через переменные окружения.
3. Собрать и запустить:
   • ./mvnw clean package
   • java -jar target/bankcards-0.0.1-SNAPSHOT.jar (или mvn spring-boot:run)

Приложение применяет Liquibase миграции при старте (создание таблиц users, cards и индексов).

---

Переменные окружения / конфигурация

Основные параметры находятся в application.yml:

• spring.datasource.url — JDBC URL БД
• spring.datasource.username
• spring.datasource.password
• security.jwt.secret — секрет для подписи JWT (обязательно заменить в проде на безопасный)
• security.jwt.expiration — срок жизни токена (ms)
• security.jwt.issuer
• security.card-encryption.secret — секрет для AES шифрования номеров карт (минимум 16 байт). В проде хранить в секретном хранилище.

При запуске через Docker Compose используются переменные окружения, определённые в docker-compose.yml.

---

Документация API (OpenAPI / Swagger)

После запуска доступна документация:

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/api/docs (в зависимости от конфигурации)

В документации перечислены все конечные точки, модели запросов/ответов и возможные коды ответов.

---

Аутентификация и пример запросов (curl)

1. Регистрация пользователя (ROLE_USER)

   • POST /api/auth/register (query params)
   • Пример: curl -X POST "http://localhost:8080/api/auth/register?username=user1&password=secret"

2. Логин — получить JWT

   • POST /api/auth/login
   • Тело (JSON): { "username": "user1", "password": "secret" }
   • Пример: curl -X POST "http://localhost:8080/api/auth/login"
     -H "Content-Type: application/json"
     -d '{"username":"user1","password":"secret"}'
   • Ответ: { "token": "eyJhbGciOiJI..." }

3. Использование токена Authorization:

   • Header: Authorization: Bearer

4. Примеры важных эндпоинтов:

• Создать карту для пользователя (ADMIN) POST /api/cards/user/{userId} Body: CreateCardRequest JSON: { "cardNumber": "4111111111111111", "expiryDate": "2030-12-31", "initialBalance": 5000.00 }

• Получить свои карты GET /api/cards/my?status=ACTIVE&page=0&size=20

• Перевод между своими картами POST /api/transfers Body: { "fromCardId": 10, "toCardId": 20, "amount": 100.50 }

• Запросить блокировку карты (владелец) POST /api/cards/{cardId}/request-block

---

Тесты

Проект содержит юнит- и web-моки тесты (JUnit5, Spring Test, Mockito). Запуск:

• ./mvnw test

Тесты покрывают ключевые сценарии: регистрация/логин, работа с картами, переводы и утилиты (маскирование).

---

Безопасность и примечания

• Пароли хранятся закодированными (BCrypt).
• Номера карт шифруются AES (CardEncryptionService). В production секреты должны храниться в Vault/секретном менеджере.
• JWT содержит роль в claim; доступ к методам контролируется аннотациями @PreAuthorize.
• Валидируем входные DTO с помощью Jakarta Bean Validation; ошибки валидaции возвращаются в единообразном формате (GlobalExceptionHandler).
• В базе индекс на номер карты (шифрованный текст). В боевой системе стоит пересмотреть индексирование и конфиденциальность данных с точки зрения требований PCI DSS.

---