Organize the currently available requirement materials into an interface planning contract API清单.md. Only organize rules already present in the requirement materials, user confirmations, and loaded RULEs; do not supplement experience, conventions, template placeholders, or the current state of the code as new rules. Write the final draft according to the template; object graph depth, number of interfaces, internal entry points, and deprecated entry points are based on this requirement, and omit entire sections that are not present.
Process
1. Load project context
Use the loaded CONTEXT terminology and RULEs. If not yet loaded, follow the project knowledge protocol; if knowledge is unavailable, continue and state so truthfully.
2. Aggregate requirement sources
Use the requirement sources specified by the user; if none are specified, identify materials directly related to interface planning from the current conversation and the repository. Sources may be a PRD, other requirement documents, screenshots, or the current conversation.
Determine the system or service scope of this planning based on the requirement goals; if the requirement does not involve interfaces, stop and explain.
3. Finalize the interface shape
Read the available requirement materials, and against the existing public routes, generated maintenance entry points, and internal calls within the planning scope that change the state of this resource (outbound calls, callbacks, tasks), mark them as modification, addition, internal, or deprecation:
- Modification / Addition: business routes to be called by the front end or other external callers in this phase
- Internal: changes business state, but does not add routes for the front end
- Deprecation: existing public routes taken offline in this phase
Prefer modifying existing routes. New routes follow the existing Controller prefix and POST /{module}/{method} style of that module. When the write semantics are inconsistent with the existing Save, add a command or internal entry point, and list the original public Save as deprecated. When the same route is called by multiple entry points, distinguish them by request fields rather than duplicating multiple interfaces of the same kind.
Common platform capabilities continue to be reused and are not listed as delivery interfaces: login authentication, BPM to-dos and submit/return/reject, public attachment upload/download, and adjacent master data details.
If in-page switching, checking, and batch filling still use the object graph already returned by the detail, do not add query or save interfaces; write "these IDs only flow within the first detail result" in the scenario call.
Sub-resources remain in the aggregate object graph and are not split into routes by table.
For decisions that cannot be confirmed from the requirement materials, user confirmations, loaded RULEs, and the current state of the code, and that would change the overall interface list, object graph boundaries, reuse versus addition, patch versus full-document overwrite, or whether the entire batch rolls back on failure, call ask-me and wait for user confirmation. Do not refer verifiable current-state facts to the user; the current state of the code may only be used to verify existing implementations, and must not be used to add new requirement rules based on it.
Completion criteria: Every interface to be drafted has a status, caller, primary identifier, and object graph boundary; every front-end scenario has interface order and cross-interface IDs; unresolved interface shape decisions have been closed.
4. Draft and write
If the user specifies an output path, use it directly; if a corresponding requirement directory already exists, write to that directory's API清单.md. Otherwise write to docs/scratch/<下一个两位序号>-<中文需求名称>/API清单.md. Overwrite an existing file with the same name without asking whether to publish.
Fill in the template according to the writing conventions. Number public interfaces by their actual call order, and write them all in 接口规划 below; each interface selects only one subset of sections: either query or command.
Completion criteria: The file has been written to the target location; the interface master table covers all public, internal, and deprecated entry points planned for delivery; each public interface appears in at least one scenario; every cross-interface ID can be found in the identifier table with "who produces it / who uses it subsequently"; every writing-rule item has been implemented.
Writing rules
- Contract layer: write routes, business objects, state changes, and cross-interface IDs. Code is used only for verification. Pagination shells, authentication parameters, all snapshot fields, and page visibility are not included in the body.
- Structure matches shape: flat and regular fields use a two-column table; nested fields use an object diagram, with identifiers marked to the right of nodes; list responses are split by locate / display / navigate, while detail responses switch to an object diagram. When the request has only one ID left, write one sentence. When frontend visibility cannot replace execution conditions, add "the server must revalidate". Binding rules that do not fit in the structure follow immediately after, one sentence each.
- Phrases go into cells: each cell in the master table, identifier table, and scenario table contains one phrase. For scenario order use
→。 - Write side effects completely: multiple things that the same operation must complete consecutively use an ordered list, and the title is changed to "Successful side effects, completed within the same business operation". For failures, write the trigger condition, whether the whole batch or a single item, what is left behind, and the business wording for the person handling it. Whether success returns a business object must be stated explicitly.
- Do not create misreadings: list only things readers would think this interface does but it actually does not do; things already written into the request, revalidation, or side effects are not listed separately; if there is no misreading, omit the entire section.
- Define identifiers in one place: external resources and aggregate boundaries are written in Resources and Identifiers. The identifier table includes only IDs that flow across interfaces or are easily confused. Interface bodies reference IDs and do not redefine them.
Template
# <功能名称> API 清单
## 文档用途
本文是接口规划契约，只回答三件事：
1. 本次对外暴露哪些接口、停用哪些接口、哪些能力根本不进 Controller。
2. 每个接口的调用方、标识、对象图边界、副作用和失败语义。
3. 接口之间传递哪些 ID，以及一次用户动作会打到哪些接口。
本文不是 Swagger / OpenAPI，不枚举快照字段、分页外壳和平台通用参数。字段级契约留给实现后的 API 文档；页面显隐、二次确认和节点裁剪留给前端与联调说明。
需求来源：<链接本次使用的需求材料；没有文档时简述需求来自当前对话>。本清单规划 <系统或服务范围>；<其他系统或角色> 是调用方。
## 资源与标识
<对外资源是什么。聚合是详情内部结构时，写明不按表拆 Controller。>
```text
<资源> <主标识>
├── <子资源> <id>
```
| 标识 | 含义 | 谁产生 | 后续谁用 |
| --- | --- | --- | --- |
| `<id>` | | | |
## 接口总表
| 状态 | 接口 | 调用方 | 用途 |
| --- | --- | --- | --- |
| 改造 / 新增 / 内部 / 停用 | `POST /...` 或内部能力名 | | |
平台通用能力继续复用，不写入本清单的交付接口：<实际复用项>。
## 场景调用
| 场景 | 接口顺序 | 跨接口数据 |
| --- | --- | --- |
| <角色 + 动作> | <入口> → <接口> | `<id>` |
<仅当页面内操作不发新请求时，补一句 ID 在首次详情结果中流转。>
## 接口规划
### 1. <查询接口业务名>
**`POST /path`**
<一句话：谁在什么入口调用，粒度是什么。>
#### 请求
| 字段 | 规则 |
| --- | --- |
| `<field>` | <必填或选填、匹配方式、与其他字段的约束> |
<仅当有请求里没有的默认过滤时，补一句固定范围。>
#### 响应
<开场一句：返回粒度和不含什么。>
- 定位：<后续请求或跳转要用的 ID>
- 展示：<列表可见字段，短语罗列>
- 跳转：<带哪个 ID 打开哪>
<!-- 详情把本节换成对象图，再补树装不下的绑定规则。 -->
#### 不做
- <读者可能以为在本接口里发生、实际没有的事。没有误读时删除本节。>
### 2. <命令接口业务名>
**`POST /path`**
<一句话：谁在什么入口调用。>
#### 请求
```text
<field> <规则>
<field>[]
├── <child> <规则>
```
<!-- 扁平请求改用两列表。只剩一个 ID 时改成一句话，不要空表。 -->
#### 服务端必须重校验
<可执行条件。请求不只一个 ID，或页面显隐已等于执行条件时删除本节。>
#### 成功副作用
<状态迁移与同一操作内必须完成的事。成功是否返回业务对象。>
#### 失败
<触发条件、整批或单条、留下什么、面向办理人的业务文案。>
#### 不做
- <读者可能以为在本接口里发生、实际没有的事。没有误读时删除本节。>
## 内部入口
这些能力改变业务状态，但不对前端新增路由。
### <入口名>
<触发方、生成或迁移什么、不走哪条公开路由。>
<!-- 没有内部入口时删除本章。 -->
## 停用公开入口
| 现有路由 | 原因 |
| --- | --- |
| `POST /...` | <为何不能继续用> |
<!-- 没有停用入口时删除本章。 -->