zuozh11 To API
将当前可用的需求材料整理成接口规划契约 API清单.md。只整理需求材料、用户确认和当前适用 RULE 中已有的规则，不把经验、惯例、模板占位或代码现状补写成新规则。按模板成稿；对象图深度、接口数量、内部入口和停用入口以本次需求为准，没有的章节整节省略。
流程
1. 加载项目上下文
按项目知识协议使用相关 CONTEXT 与适用 RULE；已有知识足够时复用，知识不可用时说明缺口并继续。
2. 汇总需求来源
使用用户指定的需求来源；没有指定时，从当前对话和仓库中识别与接口规划直接相关的材料。来源可以是 PRD、其他需求文档、截图或当前对话。
根据需求目标确定本次规划的系统或服务范围；需求不涉及接口时停止并说明。
3. 收口接口形状
读取需求材料，对照规划范围内现有公开路由和内部调用，标成改造、新增、内部或停用：
- 改造 / 新增：本期前端或其他外部调用方要打的业务路由
- 内部：改变业务状态，但不对前端新增路由
- 停用：现有公开路由本期下线
根据实际调用需要和项目约定选择路由、HTTP 方法与对象边界，优先复用语义一致的现有能力。业务操作和资源访问需求决定路由边界。
现有入口语义与需求不一致时说明差异，再确定改造或新增；只有需求或用户确认要求下线时才列为停用。平台已有且本期无需改造的能力记录为复用项。
已确认由现有返回数据支撑的页面内操作不增设路由；在场景调用中写清哪些 ID 来自已有响应，以及后续如何使用。
常规接口设计依据已确认需求和项目惯用法自行完成。缺失的业务取舍会改变对象边界、覆盖语义、失败结果或交付范围时定向提问；关键取舍相互依赖时围绕这些问题调用 ask-me。代码用于查证现状，不能据此新增需求规则。
完成标准： 每个拟写接口都有状态、调用方、主标识和对象图边界；每个前端场景都有接口顺序和跨接口 ID；未决的接口形状决策已关闭。
4. 拟稿并写入
用户指定输出路径时直接使用；已有对应需求目录时写入该目录的 API清单.md。否则写入 docs/scratch/<下一个两位序号>-<中文需求名称>/API清单.md。覆盖已有同名文件，无需询问是否发布。
按写法填入模板。公开接口按实际调用顺序编号，全部写在 接口规划 下；每个接口只选查询或命令一种小节集。
完成标准： 文件已写入目标位置；接口总表覆盖全部拟交付的公开、内部和停用入口；每个公开接口出现在至少一个场景；每条跨接口 ID 能在标识表中找到「谁产生 / 后续谁用」；写法每条均已落实。
写法
- 契约层：写路由、业务对象、状态变化和跨接口 ID。代码只用来查证。分页外壳、鉴权参数、快照全字段和页面显隐不进正文。
- 结构对形状：扁平且有规则的字段用两列表；嵌套用对象图，节点右侧标标识；列表响应按定位 / 展示 / 跳转分行，详情响应换对象图。请求只剩一个 ID 时写一句话。已确认的服务端判断写入「执行条件」。结构装不下的绑定规则紧跟其后，一句一条。
- 短语入格：总表、标识表、场景表每格一个短语。场景顺序用
→。 - 副作用写全：同一操作必须连续完成的多件事用有序列表，标题改为「成功副作用，同一业务操作内完成」。失败写触发条件、整批还是单条、留下什么，以及面向办理人的业务文案。成功是否返回业务对象必须写明。
- 不做打误读：只列读者会以为本接口会做、实际不会做的事；已经写进请求、执行条件或副作用的不再单列，没有误读则整节省略。
- 标识一处定义：对外资源与聚合边界写在资源与标识。标识表只收跨接口流转或易混的 ID。接口正文引用 ID，不重复定义。
模板
# <功能名称> API 清单
## 文档用途
本文是接口规划契约，只回答三件事：
1. 本次对外暴露哪些接口、停用哪些接口、哪些能力根本不进 Controller。
2. 每个接口的调用方、标识、对象图边界、副作用和失败语义。
3. 接口之间传递哪些 ID，以及一次用户动作会打到哪些接口。
本文不是 Swagger / OpenAPI，不枚举快照字段、分页外壳和平台通用参数。字段级契约留给实现后的 API 文档；页面显隐、二次确认和节点裁剪留给前端与联调说明。
需求来源：<链接本次使用的需求材料；没有文档时简述需求来自当前对话>。本清单规划 <系统或服务范围>；<其他系统或角色> 是调用方。
## 资源与标识
<对外资源是什么。聚合是详情内部结构时，写明不按表拆 Controller。>
```text
<资源> <主标识>
├── <子资源> <id>
```
| 标识 | 含义 | 谁产生 | 后续谁用 |
| --- | --- | --- | --- |
| `<id>` | | | |
## 接口总表
| 状态 | 接口 | 调用方 | 用途 |
| --- | --- | --- | --- |
| 改造 / 新增 / 内部 / 停用 | `<METHOD> /...` 或内部能力名 | | |
平台通用能力继续复用，不写入本清单的交付接口：<实际复用项>。
## 场景调用
| 场景 | 接口顺序 | 跨接口数据 |
| --- | --- | --- |
| <角色 + 动作> | <入口> → <接口> | `<id>` |
<仅当页面内操作不发新请求时，补一句 ID 在首次详情结果中流转。>
## 接口规划
### 1. <查询接口业务名>
**`<METHOD> /path`**
<一句话：谁在什么入口调用，粒度是什么。>
#### 请求
| 字段 | 规则 |
| --- | --- |
| `<field>` | <必填或选填、匹配方式、与其他字段的约束> |
<仅当有请求里没有的默认过滤时，补一句固定范围。>
#### 响应
<开场一句：返回粒度和不含什么。>
- 定位：<后续请求或跳转要用的 ID>
- 展示：<列表可见字段，短语罗列>
- 跳转：<带哪个 ID 打开哪>
<!-- 详情把本节换成对象图，再补树装不下的绑定规则。 -->
#### 不做
- <读者可能以为在本接口里发生、实际没有的事。没有误读时删除本节。>
### 2. <命令接口业务名>
**`<METHOD> /path`**
<一句话：谁在什么入口调用。>
#### 请求
```text
<field> <规则>
<field>[]
├── <child> <规则>
```
<!-- 扁平请求改用两列表。只剩一个 ID 时改成一句话，不要空表。 -->
#### 执行条件
<已确认且应由服务端判断的条件。没有独立条件时省略。>
#### 成功副作用
<状态迁移与同一操作内必须完成的事。成功是否返回业务对象。>
#### 失败
<触发条件、整批或单条、留下什么、面向办理人的业务文案。>
#### 不做
- <读者可能以为在本接口里发生、实际没有的事。没有误读时删除本节。>
## 内部入口
这些能力改变业务状态，但不对前端新增路由。
### <入口名>
<触发方、生成或迁移什么、不走哪条公开路由。>
<!-- 没有内部入口时删除本章。 -->
## 停用公开入口
| 现有路由 | 原因 |
| --- | --- |
| `<METHOD> /...` | <已确认的停用原因> |
<!-- 没有停用入口时删除本章。 -->