mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 18:10:30 +08:00
huangping
3f577b34d5
Deliver dual Spring Boot services (platform API + webhook ingress), JWT auth, Flyway with isolated history tables, customer/project/dictionary endpoints, OpenAPI snapshot under contracts/, RUNBOOK, and CI that runs on services/web/contracts paths plus enforcer + dependency tree ban on craftlabs-auth-bitanswer. Made-with: Cursor
52 lines
2.6 KiB
Markdown
52 lines
2.6 KiB
Markdown
# 平台后端服务（I1 骨架）
|
||
|
||
与 **`java/craftlabs-auth-*` SDK 分构建线**，坐标 `cn.craftlabs.platform`，**不依赖** `craftlabs-auth-bitanswer`。
|
||
|
||
- **部署与运维**：[RUNBOOK.md](RUNBOOK.md)
|
||
- **OpenAPI 契约（SSOT）**：[../contracts/README.md](../contracts/README.md)
|
||
- **误依赖门禁**：`maven-enforcer-plugin`（`validate`）+ CI `dependency:tree` 扫描 `craftlabs-auth-bitanswer`
|
||
|
||
| 模块 | 端口 | 说明 |
|
||
|------|------|------|
|
||
| `license-webhook-ingress` | 8081 | `POST /webhook/bitanswer/callback`，头 `x-bitanswer-token`（可选 `CRAFTLABS_WEBHOOK_EXPECTED_TOKEN`）；**Flyway** 建表 `webhook_callback_receipt`，**Idempotency-Key** 落库幂等 |
|
||
| `delivery-platform-api` | 8080 | **M1**：`GET|POST /api/v1/customers`、`GET|PUT|DELETE /api/v1/customers/{id}`（DELETE 软删 → `INACTIVE`）；`GET|POST /api/v1/projects`、`GET|PUT|DELETE /api/v1/projects/{id}`（DELETE 物理删）；`GET /api/v1/dictionaries/{type}`；另 `POST /api/v1/auth/login`、`GET /api/v1/ping`、JWT `Authorization: Bearer`、**OpenAPI** `/swagger-ui.html`；**Flyway** 表 `flyway_platform_api` |
|
||
|
||
生产须设置 **`PLATFORM_JWT_SECRET`**（≥32 字符）。
|
||
|
||
## I2 / M1（客户与项目）
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| `/api/v1/customers` | 客户分页 CRUD（删除为软删 `INACTIVE`） |
|
||
| `/api/v1/projects` | 项目分页 CRUD（删除为物理删除） |
|
||
| `/api/v1/dictionaries/{type}` | 字典项，如 `PROJECT_PHASE` |
|
||
|
||
Flyway 历史表：`delivery-platform-api` → **`flyway_platform_api`**；`license-webhook-ingress` → **`flyway_webhook`**。
|
||
|
||
## 构建 Fat JAR
|
||
|
||
```bash
|
||
mvn -f services/pom.xml -pl license-webhook-ingress -am clean package
|
||
mvn -f services/pom.xml -pl delivery-platform-api -am clean package
|
||
```
|
||
|
||
产物：`*/target/*.jar`（spring-boot-maven-plugin repackage）。
|
||
|
||
## Spring Boot 版本
|
||
|
||
父 POM 当前为 **3.4.5**（易解析）；产品目标 **4.0.\*** 时升级 `services/pom.xml` 中 `spring-boot.version` 并全量回归。
|
||
|
||
## 数据层（架构约定）
|
||
|
||
| 项 | 说明 |
|
||
|----|------|
|
||
| **数据库** | **PostgreSQL 15** |
|
||
| **ORM** | **MyBatis-Plus**（`mybatis-plus-spring-boot3-starter`，版本见父 POM `mybatis-plus.version`） |
|
||
|
||
本地起库：`docker compose -f services/docker-compose.yml up -d`，默认库名 `craftlabs_platform`、用户/密码 `craftlabs`/`craftlabs`，与 `delivery-platform-api` 的 `application.yml` 默认值一致。
|
||
Maven 单测使用 **H2（PostgreSQL 兼容模式）**，不强制本机安装 PostgreSQL。
|
||
|
||
## 环境变量（数据源，可选）
|
||
|
||
覆盖默认 JDBC 时使用：`SPRING_DATASOURCE_URL`、`SPRING_DATASOURCE_USERNAME`、`SPRING_DATASOURCE_PASSWORD`。
|