lixi
bd20adc700
- Flyway V1 baseline：identity 全部 5 表 + media.assets + platform 最小硬依赖（set_updated_at/regions），无 fixture 凭据；dev 种子独立为 afterMigrate 回调且默认不执行 - patbond-user 迁移到 PostgreSQL：UUIDv7 主键、JdbcClient 仓储、bcrypt 密码、唯一性依赖 DB 约束翻译为 409、E.164 手机号校验对齐 ck_users_phone - 统一异常契约：common 新增 ErrorCode/BusinessException，两服务 GlobalExceptionHandler；auth 经 ApiErrorDecoder 原码透传下游错误，修复状态码折叠（审计 M1） - 门禁：JAVA_HOME=jdk17 ./mvnw clean test，37 个测试 0 失败（含 Testcontainers postgres:16 集成测试），BUILD SUCCESS Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
111 lines
3.7 KiB
Markdown
111 lines
3.7 KiB
Markdown
# Patbond API
|
|
|
|
Patbond API is a Spring Boot multi-module backend.
|
|
|
|
## Modules
|
|
|
|
- `patbond-common`: stable cross-module contracts (response wrapper, shared DTOs). No web/messaging dependencies.
|
|
- `patbond-user`: user service for user creation, profile lookup, and password verification.
|
|
- `patbond-auth`: authentication service for registration and login. Calls `patbond-user` over HTTP via OpenFeign with a configured static URL (no service discovery in the MVP, see ADR-002).
|
|
|
|
## Technology Stack
|
|
|
|
- Java 17 (build baseline; use JDK 17 for release builds)
|
|
- Spring Boot 3.5.16
|
|
- Spring Cloud 2025.0.3 (OpenFeign only)
|
|
- PostgreSQL 16 + Flyway (patbond-user owns the `identity`/`media` schemas)
|
|
- Maven (use the committed Maven Wrapper `./mvnw`)
|
|
|
|
## Build and Test
|
|
|
|
```bash
|
|
./mvnw clean test
|
|
```
|
|
|
|
Integration tests start a disposable `postgres:16` via Testcontainers, so a
|
|
running Docker daemon is required (no local PostgreSQL installation or
|
|
credentials are needed).
|
|
|
|
If your default JDK is not 17, point `JAVA_HOME` at a JDK 17 installation first, e.g.:
|
|
|
|
```bash
|
|
JAVA_HOME=/usr/lib/jvm/java-17-openjdk ./mvnw clean test
|
|
```
|
|
|
|
## Run
|
|
|
|
Running `patbond-user` requires a reachable PostgreSQL 16 database; Flyway
|
|
applies the versioned migrations in
|
|
`patbond-user/src/main/resources/db/migration` automatically on startup.
|
|
Development seed data (`db/dev`, regions reference rows) is opt-in via a dev
|
|
profile — see `application.yml.sample`.
|
|
|
|
Each service ships a committed `application.yml.sample`; the real `application.yml`
|
|
is git-ignored. First copy the samples (defaults work locally, overrides via
|
|
environment variables):
|
|
|
|
```bash
|
|
cp patbond-user/src/main/resources/application.yml.sample \
|
|
patbond-user/src/main/resources/application.yml
|
|
cp patbond-auth/src/main/resources/application.yml.sample \
|
|
patbond-auth/src/main/resources/application.yml
|
|
```
|
|
|
|
Install the shared module once, then run each service in its own terminal:
|
|
|
|
```bash
|
|
./mvnw -pl patbond-common install
|
|
./mvnw -pl patbond-user spring-boot:run
|
|
./mvnw -pl patbond-auth spring-boot:run
|
|
```
|
|
|
|
Tests do not require this copy step — `patbond-auth/src/test/resources/application.yml`
|
|
keeps `./mvnw clean test` self-contained on a clean checkout.
|
|
|
|
Smoke check:
|
|
|
|
```bash
|
|
curl -X POST http://127.0.0.1:8081/auth/register \
|
|
-H 'Content-Type: application/json' \
|
|
-d '{"username":"demo_user","password":"secret123"}'
|
|
```
|
|
|
|
### Configuration
|
|
|
|
| Environment variable | Default | Used by |
|
|
| --- | --- | --- |
|
|
| `PATBOND_USER_PORT` | `8082` | patbond-user |
|
|
| `PATBOND_AUTH_PORT` | `8081` | patbond-auth |
|
|
| `PATBOND_USER_SERVICE_URL` | `http://127.0.0.1:8082` | patbond-auth (Feign target for patbond-user) |
|
|
| `PATBOND_DB_URL` | `jdbc:postgresql://127.0.0.1:5432/patbond` | patbond-user |
|
|
| `PATBOND_DB_USER` | `patbond` | patbond-user |
|
|
| `PATBOND_DB_PASSWORD` | `patbond` | patbond-user |
|
|
|
|
Machine-specific values live in the git-ignored `application.yml` (copied from the
|
|
committed `.sample`); never commit secrets to the samples.
|
|
|
|
## Services
|
|
|
|
### Auth Service
|
|
|
|
- Application name: `patbond-auth`
|
|
- Default port: `8081`
|
|
- Register: `POST /auth/register`
|
|
- Login: `POST /auth/login`
|
|
|
|
### User Service
|
|
|
|
- Application name: `patbond-user`
|
|
- Default port: `8082`
|
|
- Create user: `POST /internal/users`
|
|
- Verify password: `POST /internal/users/verify-password`
|
|
- Get user by id: `GET /internal/users/{id}`
|
|
- Get user by username: `GET /internal/users/by-username/{username}`
|
|
|
|
> Note: user data is persisted in PostgreSQL (`identity.users` /
|
|
> `identity.user_credentials`, bcrypt password hashes, UUIDv7 ids generated in
|
|
> the application). Errors follow the `{code, message, data}` envelope with
|
|
> stable business codes and matching HTTP statuses. Verifiable JWT tokens,
|
|
> refresh sessions, and `/internal` access control are planned in iteration 1
|
|
> follow-up tasks.
|