101 lines
3.7 KiB
Markdown
101 lines
3.7 KiB
Markdown
|
# APLP Backend — Setup
|
||
|
|
|
||
|
|
| | |
|
||
|
|
| --- | --- |
|
||
|
|
| **Status** | Implemented (Phase 0 — Foundation) |
|
||
|
|
| **Stack** | Java 21 (LTS) · Maven · Spring Boot 3.5 · PostgreSQL · Flyway · H2 (test) |
|
||
|
|
|
||
|
|
## 1. Prerequisites
|
||
|
|
|
||
|
|
- JDK 21+ (build chạy được trên JDK 25; target release 21)
|
||
|
|
- Maven (hoặc dùng `./mvnw`)
|
||
|
|
- Docker (database local)
|
||
|
|
|
||
|
|
## 2. Cấu trúc dự án
|
||
|
|
|
||
|
|
```text
|
||
|
|
aplp.backend.spring/
|
||
|
|
├── GOAL.md
|
||
|
|
├── APLP-Project-Phases.md
|
||
|
|
├── README.md
|
||
|
|
├── docs/
|
||
|
|
├── pom.xml
|
||
|
|
├── mvnw
|
||
|
|
├── Dockerfile
|
||
|
|
├── docker-compose.yml # PostgreSQL local (port 5432)
|
||
|
|
└── src/
|
||
|
|
├── main/java/com/aplp/backend/
|
||
|
|
│ ├── AplpBackendApplication.java
|
||
|
|
│ ├── common/ # infra: api (errors), security (JWT), web (requestId), config
|
||
|
|
│ ├── identity/ # api / application / domain / persistence
|
||
|
|
│ └── learner/ # api / application / domain / persistence
|
||
|
|
├── main/resources/
|
||
|
|
│ ├── application.yml # base config
|
||
|
|
│ ├── application-dev.yml # Postgres local
|
||
|
|
│ ├── application-prod.yml # Postgres via env vars
|
||
|
|
│ └── db/migration/ # Flyway migrations
|
||
|
|
└── test/...
|
||
|
|
```
|
||
|
|
|
||
|
|
## 3. Chạy local (dev)
|
||
|
|
|
||
|
|
```bash
|
||
|
|
# 1. Start database
|
||
|
|
docker compose up -d db
|
||
|
|
|
||
|
|
# 2. Chạy app (dev profile, port 8080)
|
||
|
|
./mvnw spring-boot:run
|
||
|
|
|
||
|
|
# 3. Kiểm tra
|
||
|
|
curl http://localhost:8080/actuator/health
|
||
|
|
# => {"status":"UP","groups":["liveness","readiness"]}
|
||
|
|
```
|
||
|
|
|
||
|
|
Flyway tự migrate schema khi app khởi động (`ddl-auto: validate` để kiểm tra entity khớp schema).
|
||
|
|
|
||
|
|
## 4. Verification
|
||
|
|
|
||
|
|
```bash
|
||
|
|
./mvnw test # integration test với H2 (PostgreSQL mode)
|
||
|
|
./mvnw package # build jar
|
||
|
|
```
|
||
|
|
|
||
|
|
## 5. Endpoints (Phase 0)
|
||
|
|
|
||
|
|
| Method | Path | Auth | Mô tả |
|
||
|
|
| --- | --- | --- | --- |
|
||
|
|
| POST | `/api/v1/auth/register` | Public | Đăng ký + cấp token |
|
||
|
|
| POST | `/api/v1/auth/login` | Public | Đăng nhập |
|
||
|
|
| POST | `/api/v1/auth/refresh` | Public | Refresh access token (rotate refresh token) |
|
||
|
|
| POST | `/api/v1/auth/logout` | Bearer | Thu hồi refresh token |
|
||
|
|
| GET | `/api/v1/learners/me` | Bearer | Xem learner profile (UC-0.2) |
|
||
|
|
| PATCH | `/api/v1/learners/me` | Bearer | Cập nhật display name |
|
||
|
|
| GET | `/actuator/health` | Public | Health/liveness/readiness |
|
||
|
|
|
||
|
|
## 6. Environment Variables
|
||
|
|
|
||
|
|
| Var | Mô tả | Default (dev) |
|
||
|
|
| --- | --- |--------------------------------------------|
|
||
|
|
| `DB_URL` | JDBC url | `jdbc:postgresql://localhost:5432/aplp` |
|
||
|
|
| `DB_USERNAME` | db user | `postgres` |
|
||
|
|
| `DB_PASSWORD` | db password | `Pa55w0rd` |
|
||
|
|
| `DB_PORT` | host port map | `5432` |
|
||
|
|
| `JWT_SECRET` | Base64 secret (HS256, ≥ 32 bytes) | dev-only default — **phải set khi deploy** |
|
||
|
|
| `JWT_ACCESS_TTL` | Access token TTL | `15m` |
|
||
|
|
| `JWT_REFRESH_TTL` | Refresh token TTL | `30d` |
|
||
|
|
| `CORS_ALLOWED_ORIGINS` | Allowed origins | `http://localhost:5173` |
|
||
|
|
| `SERVER_PORT` | App port | `8080` |
|
||
|
|
|
||
|
|
> Dev default secret chỉ dùng cho local. **Không commit secret thật**; set `JWT_SECRET` trong môi trường không phải dev.
|
||
|
|
|
||
|
|
## 7. Test Database
|
||
|
|
|
||
|
|
Integration test dùng H2 in-memory (PostgreSQL mode) tại `src/test/resources/application-test.yml`. Migration viết portable (chạy được trên cả Postgres và H2).
|
||
|
|
|
||
|
|
## 8. Docker
|
||
|
|
|
||
|
|
```bash
|
||
|
|
docker build -t aplp-backend .
|
||
|
|
docker run -p 8080:8080 -e JWT_SECRET=... -e DB_URL=... aplp-backend
|
||
|
|
```
|