# 契约（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 类型（非必选）。