https://github.com/kossahokia/bankcards
REST API for managing bank cards. Built with Java 21, Spring Boot, PostgreSQL, Liquibase, JWT, Docker, Swagger. Includes full authentication, roles, transfers & admin features.
https://github.com/kossahokia/bankcards
backend docker java jwt liquibase openapi postgresql rest-api springboot swagger
Last synced: 3 months ago
JSON representation
REST API for managing bank cards. Built with Java 21, Spring Boot, PostgreSQL, Liquibase, JWT, Docker, Swagger. Includes full authentication, roles, transfers & admin features.
- Host: GitHub
- URL: https://github.com/kossahokia/bankcards
- Owner: kossahokia
- Created: 2025-10-01T08:01:44.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-10-16T12:31:10.000Z (9 months ago)
- Last Synced: 2025-10-17T15:16:17.051Z (9 months ago)
- Topics: backend, docker, java, jwt, liquibase, openapi, postgresql, rest-api, springboot, swagger
- Language: Java
- Homepage:
- Size: 188 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 💳 BankCards REST API
Backend-приложение для управления банковскими картами.
Позволяет пользователям просматривать свои карты, делать переводы между ними,
а администраторам — управлять пользователями и картами.
Реализовано на **Spring Boot 3**, **Java 21**, **PostgreSQL**, **JWT Security**.
## 🚀 Запуск проекта
### 🔧 Требования
- Java 21+
- Docker & Docker Compose
- Maven 3.9+
### ▶️ Быстрый запуск через Docker Compose
```bash
git clone https://github.com/kossahokia/bankcards.git
cd bankcards
docker compose up --build
```
### 🌐 URL для работы с приложением
| Сервис | URL |
| ------------- | ------------------------------------------------------------------------------------------ |
| 🧠 API | [http://localhost:8080](http://localhost:8080) |
| 📘 Swagger UI | [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) |
| 🗄️ PgAdmin | [http://localhost:8081](http://localhost:8081) |
### 🧾 Данные для входа в PgAdmin:
- Email: kostya4j@gmail.com
- Пароль от pgAdmin: postgres
- Пароль от сервера BankCards DB: postgres
## 🧱 Архитектура проекта
```text
📁 src
├─📂 main
│ ├─📂 java/com/example/bankcards
│ │ ├─📁 config
│ │ ├─📁 controller
│ │ ├─📁 dto
│ │ │ └─📁 enums
│ │ ├─📁 entity
│ │ │ └─📁 enums
│ │ ├─📁 exception
│ │ │ └─📁 customexceptions
│ │ ├─📁 repository
│ │ ├─📁 security
│ │ ├─📁 service
│ │ └─📁 util
│ └─📂 resources
│ └─📂 db/migration
└─📂 test
├─📂 java/com/example/bankcards
│ ├─📁 controller
│ └─📁 service
└─📂 resources
```
## 🔐 Безопасность
- JWT (JSON Web Token) — аутентификация без сессий
- Spring Security 6 — разграничение доступа
- BCrypt — безопасное хранение паролей
- **CORS** — глобальная конфигурация через `WebConfig`
(глобальный `CorsConfigurationSource` + `http.cors()` в `SecurityConfig`)
### ⚖️ Роли:
- **ADMIN** — полное управление пользователями и картами
- **USER** — просмотр и переводы между своими картами
### 🧑💼 Администратор по умолчанию (из миграций Liquibase):
- username: admin
- password: admin123
## 💳 Основные функции API
### AuthController (/api/auth)
| Метод | Endpoint | Описание |
| ------ | ----------- | -------------------------------- |
| `POST` | `/login` | Аутентификация, получение JWT |
| `POST` | `/register` | Регистрация нового пользователя |
### AdminController (/api/admin) (только для ADMIN)
Пользователи:
| Метод | Endpoint | Описание |
| -------- | --------------------------------------- | --------------------------------------------------- |
| `POST` | `/users` | Создание пользователя |
| `GET` | `/users` | Просмотр пользователей (фильтрация + пагинация) |
| `GET` | `/users/{id}` | Получить пользователя по ID |
| `PATCH` | `/users/{id}/status?enabled=true` | Активировать / деактивировать |
| `PATCH` | `/users/{id}/role?roleName=USER` | Назначить роль |
| `PATCH` | `/users/{id}/role/remove?roleName=USER` | Удалить роль |
| `DELETE` | `/users/{id}` | Удалить пользователя |
| `GET` | `/users/{id}/cards` | Получить карты пользователя |
Карты:
| Метод | Endpoint | Описание |
| -------- | ----------------------------------- | ---------------------------------------- |
| `POST` | `/cards` | Создать новую карту |
| `GET` | `/cards` | Список всех карт (с фильтром по статусу) |
| `PATCH` | `/cards/{id}/status?status=BLOCKED` | Изменить статус карты |
| `DELETE` | `/cards/{id}` | Удалить карту |
### CardController (/api/cards)
| Метод | Endpoint | Описание |
| ------ | --------------------- | --------------------------------------- |
| `GET` | `/` | Просмотр своих карт (фильтр, пагинация) |
| `GET` | `/{id}/balance` | Баланс карты |
| `POST` | `/{id}/request-block` | Запрос на блокировку карты |
| `POST` | `/transfer` | Перевод между своими картами |
## 🧬 Модели данных
### User
| Поле | Тип | Описание |
| -------- | ----------| ---------------------- |
| id | Long | ID пользователя |
| username | String | Уникальный логин |
| password | String | Хэшированный пароль |
| fullName | String | Полное имя |
| enabled | boolean | Активен / заблокирован |
| roles | Set | Список ролей |
| cards | Set | Список карт |
### Card
| Поле | Тип | Описание |
| ------------ | -----------| -------------------------|
| id | Long | ID карты |
| cardNumber | String | Номер карты (зашифрован) |
| expiryDate | LocalDate | Срок действия |
| balance | BigDecimal | Баланс карты |
| status | CardStatus | Статус карты |
| owner | User | Владелец карты |
### Role
| Поле | Тип | Описание |
| ---- | ------ | -------------------------------- |
| id | Long | ID роли |
| name | String | Название роли (`USER`, `ADMIN`) |
## 🗝️ Шифрование и маскирование
- Номера карт шифруются (AES-128) и маскируются при выводе (`**** **** **** 1234`)
- Проверка срока действия выполняется в `CardExpiryUtil`
- Баланс хранится в `BigDecimal` с точностью 2 знака
## 🪛 Конфигурация
### `application.yml`
- Настройки PostgreSQL (через Docker)
- Liquibase changelogs
- JWT параметры (`secret`, `expiration`)
- Уровни логирования (`WARN`, `INFO`)
### `application-test.yml`
- Testcontainers (PostgreSQL 16)
- Liquibase отключён в интеграционных тестах (схема создаётся через JPA)
- Автоматическое создание схемы Hibernate
## 🧪 Тестирование
| Тип | Кол-во | Описание |
| -------------------- | -------- | --------------------------- |
| **Unit-тесты** | ~115 | Сервисы и контроллеры |
| **Integration-тест** | 1 | Smoke-тест с Testcontainers |
| **Фреймворки** | JUnit 5, Mockito, AssertJ, Spring Boot Test |
### Запуск тестов
```bash
mvn clean test
```
## 🗃️ Миграции БД (Liquibase)
- Все миграции описаны в YAML и подключены через `db.changelog-master.yaml`
- Используются **preConditions** для защиты от повторных запусков:
- Проверка наличия таблиц перед `createTable`
- Проверка наличия колонок перед `addColumn`
- Проверка записей перед `insert`
- Liquibase миграции полностью идемпотентны и безопасны для CI/CD
## 📖 JavaDoc
- Все **рабочие и тестовые классы** содержат JavaDoc-комментарии
- Генерация документации:
```bash
mvn javadoc:javadoc
```
- Результат: `target/site/apidocs/index.html`
- Документация покрывает сервисы, контроллеры, сущности, DTO и утилиты
## 🐳 Docker окружение
`docker-compose.yml` поднимает:
| Сервис | Версия | Порт |
| ------------- | ------ | ---- |
| PostgreSQL | 16 | 5432 |
| PgAdmin | 8 | 8081 |
| BankCards App | — | 8080 |
## 📚 Документация API
- Swagger UI: http://localhost:8080/swagger-ui/index.html
- OpenAPI спецификация: `bank_rest/openapi.yaml`
- Все эндпоинты снабжены аннотациями `@Operation`, `@ApiResponses`, `@Schema`
- Поддерживаются статусы ошибок: 400, 401, 403, 404, 422, 500
## 💻 Технологии
| Категория | Технология |
| --------- | -------------------------------- |
| Backend | Java 21, Spring Boot 3.3 |
| Security | Spring Security 6, JWT |
| DB | PostgreSQL 16, Liquibase |
| Docs | Swagger / OpenAPI 3, JavaDoc |
| Testing | JUnit 5, Mockito, Testcontainers |
| DevOps | Docker, Docker Compose |
| Utils | AES Encryption, Card Masking |
---
## 👨💻 Автор
✨ **Konstantin Sakhokiia — Java Backend Engineer**
📧 kostya4j@gmail.com
📧 kos.sahokia@yandex.ru
🐙 github.com/kossahokia
💬 Telegram: @kossahokia