# API 接口规格文档

> **事实纪律**:只填写来自当前项目、上游契约或用户确认的事实。未知项写“待确认”并说明责任与下一步；合法不适用项写 `N/A（原因）`。不得伪造通过结果、字段、消费方或样例值。

> **产物定位**:涉及外部或跨模块 API 对接时产出(按需)。把接口契约先于实现定清楚，避免消费方等待或双方各自猜测。
> **核心纪律**:契约先行;每个 endpoint 有验收场景 + 验证证据。
> **反退化纪律**:每个 endpoint 必须完整重复其全部必填结构块,禁止退化——
> - 禁止「前详后废」(前几个 endpoint 完整、后面的退化成一行文字)
> - 禁止用一行文字 `**xxx**:…` 代替表格,或省略标 `[Always]` 的必填块(基本信息/响应体字段/错误与副作用/验收场景)
> - 章节标题必须用 `###`,禁止降级为 `**粗体**`
> - 禁止「同上格式」「见上文」「…」等模糊偷懒占位
> - **显式 schema 引用**(唯一合法引用形态):多个 endpoint 复用同一 schema 时,「请求体字段/响应体字段」表可写一行 `| 同 DD-Axx schema | | | | | | | |`(同结构、同字段集)。限一层(被引块不得也是引用);被引 endpoint 必须有完整字段表;引用与逐字段展开二选一,不得混用制造歧义
> 任一 endpoint 缺任一必填块 = 未完成,须补齐后再推进。
> **完成判定**:见文末,每个 endpoint 须满足。

OpenAPI 权威路径：填写 project map 解析后的真实路径；默认候选为 `docs/api/openapi.yaml`。

## 资源 CRUD 策略 [有资源型接口时必填]

> 每个资源必须显式声明行为策略；未声明会失败，不会默认补 DELETE。
> - `full`:确有创建、查询、修改和删除语义
> - `state_machine`:通过明确状态流转改变资源，不提供物理删除
> - `append_only`:允许创建和查询，不允许修改或删除既有记录
> - `read_only`:只查询，不创建、修改或删除
> - `derived`:派生资源——集合与 `/{id}` 只读，创建/流转经主资源事务（如合同明细随合同 POST 创建）或 `/{id}/` 子操作路径（如 `/{id}/submit`、`/{id}/transition`）承载

| 资源路径 | CRUD 类型 | 说明 |
|----------|-----------|------|

## Endpoint: `METHOD {真实接口路径}`

> **接口编号**: `DD-A*`(替换为当前项目中的真实唯一编号,供切片计划/代码审查引用)
> **关联需求**: `REQ-*`(替换为当前需求文档中的真实编号;多个用 `/` 分隔)

### 基本信息 [Always — 每个 endpoint 必填]

| endpoint_id | 用途 | 调用端 | 权限 | 幂等 | 限流 | 副作用 |
|-------------|------|--------|------|------|------|--------|

### 请求 Header 字段 [有认证/自定义 Header 时必填]

| 字段路径 | 类型 | 必填 | 格式/约束 | 数据映射 | 说明 | 真实样例或来源 |
|----------|------|------|-----------|----------|------|------|

### 请求 Path / Query 字段 [有路径/查询参数时必填]

| 字段路径 | 类型 | 必填 | 默认值 | 格式/约束 | 说明 | 真实样例或来源 |
|----------|------|------|--------|-----------|------|------|

### 请求体字段 [有请求体时必填]

| 字段路径 | 类型 | 必填 | 可空 | 枚举/格式/校验 | 数据映射 | 说明 | 真实样例或来源 |
|----------|------|------|------|----------------|----------|------|------|

### 响应体字段 [Always — 每个 endpoint 必须有表格或 `N/A（无响应体，例如 204）`]

> 只写成功(2xx)响应体字段。4xx/5xx 错误体（如 code/message 包络）不写入本表——错误响应在下方「错误与副作用」按业务码登记，两侧分开比对。

| 字段路径 | 类型 | 必有 | 可空 | 枚举/格式 | 数据来源 | 说明 | 真实样例或来源 |
|----------|------|------|------|-----------|----------|------|------|

### 错误与副作用 [Always — 每个 endpoint 必填]

| 业务码 | HTTP 状态 | 触发条件 | 用户提示 | 可重试 | 状态/数据副作用 |
|--------|-----------|----------|----------|--------|-----------------|

### 验收场景 [Always — 每个 endpoint 必填]

| 场景 | 输入 | 预期响应 | 数据/状态变化 | 验证方式与证据要求 |
|------|------|----------|---------------|----------------------|

### 枚举值定义 [有枚举字段时必填]

| 枚举名 | 值 | 含义 |
|--------|------|------|

### 页面交互映射 [前端直接调用的接口必填]

| 页面操作 | 触发接口 | 加载状态 | 成功行为 | 失败行为 |
|---------|---------|---------|---------|---------|

## 接口消费方总览

> 声明每个 API 给谁消费(决定 API 风格 REST/RPC/webhook + 必要性;无消费方 = 产出黑洞)。**纯后端 API 尤其须声明**(无 UI 时 API「为什么需要」弱)。

| API(DD-A*) | 消费方类型 | 消费方说明 |
|-------------|-----------|-----------|
| | 前端页面 / 外部系统 / 定时任务 / 其他服务 | |

> 消费方类型:前端页面(UI 直接调用,须有页面交互映射)/ 外部系统(第三方集成,须契约稳定+版本)/ 定时任务(批处理,须幂等)/ 其他服务(内部 RPC)。

## 接口规范检查

- [ ] 接口版本号和演进策略来自当前项目约定
- [ ] 写接口明确幂等、去重或不可安全重试的真实语义
- [ ] 错误码体系完整(业务码 + HTTP 状态码双映射;**一码一义一 HTTP**——同业务码跨 endpoint 不得映射不同 HTTP/语义)
- [ ] 分页参数有上限(防恶意大翻页)
- [ ] 限流适用时有阈值与来源；不适用时写明原因
- [ ] 批量操作有经当前项目确认的数量上限

## 完成判定(每个 endpoint 须满足)

- [ ] endpoint_id 使用当前文档的唯一 `DD-A*` 编号，并在 OpenAPI 对应 operation 标 `x-soloforge-endpoint-id: DD-A*`（供 companion_consistency 字段级一致性校验：openapi schema 字段 vs md 字段表字段）
- [ ] 所有数据映射精确到当前存储或外部系统的真实来源；关系型存储写到表字段，文档/键值/对象/事件存储使用其原生可定位路径，派生字段说明计算规则
- [ ] 类型与格式使用当前 OpenAPI 版本支持的表达，并与人读文档一致；没有把 format 或 enum 误写成独立基础类型
- [ ] 每种可观察失败都有稳定 HTTP/业务语义；无业务码的标准协议错误说明理由
- [ ] 每个验收场景有可执行验证方式和证据要求；尚未执行时没有伪造结果
- [ ] 枚举值定义覆盖所有枚举字段
- [ ] 涉及前端调用的接口有页面交互映射
- [ ] 每个 endpoint 都含全部必填表格块(基本信息/响应体字段/错误与副作用/验收场景),无一行文字替代、无偷懒占位
- [ ] OpenAPI 顶级 `tags:` 完整声明所有用到的 tag，每个 tag 带 description（枚举覆盖的子能力）
- [ ] 每个 endpoint operation 有 `tags`，引用的 tag 均在顶级声明；tag 与该 endpoint 业务域（及 `x-soloforge-endpoint-id` 归属）一致