feat: add guide

2026-08-22 08:29:30 +07:00
parent 3d22e0dfc0
commit 1715e366c6
5 changed files with 447 additions and 0 deletions
@@ -0,0 +1,100 @@
+# 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
+```