# 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
```