mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 10:00: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
28 lines
1019 B
Markdown
28 lines
1019 B
Markdown
# 契约（Contracts）
|
||
|
||
## OpenAPI — 交付平台 API
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| [`openapi/delivery-platform-api.json`](openapi/delivery-platform-api.json) | **`delivery-platform-api` 的单一事实来源（SSOT）**；与运行时 `/v3/api-docs` 对齐。 |
|
||
|
||
### 更新快照（维护者）
|
||
|
||
在仓库根目录或 `services/delivery-platform-api` 下执行（需 JDK 17）：
|
||
|
||
```bash
|
||
export JAVA_HOME=… # JDK 17+
|
||
cd services/delivery-platform-api
|
||
UPDATE_OPENAPI=1 mvn -q test -Dtest=OpenApiContractSnapshotTest
|
||
```
|
||
|
||
提交前请 **审阅 diff**：破坏性变更需 bump 版本说明、同步前端与集成方。
|
||
|
||
### CI 校验
|
||
|
||
默认 `mvn verify` 会运行 `OpenApiContractSnapshotTest`：**运行时生成的 OpenAPI 与快照须一致**。若仅改实现未改契约却导致文档变化，应更新快照并写在 PR 说明中。
|
||
|
||
### 与前端
|
||
|
||
`web/delivery-platform-ui` 的 axios 路径应与 OpenAPI `paths` 一致；可选后续接入 OpenAPI Generator 生成 TS 类型（非必选）。
|