| name | api-doc-infer |
| description | 根据产品说明、页面描述、模块功能、数据库表结构、字段清单、业务规则推理出 RESTful API 接口设计文档，包含接口名称、HTTP 方法、路径、入参、出参、校验规则和 Mermaid 流程图。当用户提到"推理接口"、"设计接口"、"API 文档"、"接口设计"、"推断接口"、"帮我设计接口"、"推导 API"、"根据表结构生成接口"时使用此技能。也适用于用户给出页面、模块、表结构或碎片化需求，需要产出接口文档的场景。 |
API 接口推理技能
目标
将零散的产品信息、模块描述和数据库表结构整理成完整的 RESTful API 接口设计文档。发现不确定问题时，立即通过 AskUserQuestion 向用户提问确认，确保最终文档中的所有内容都是已确认的。
输出规则
- 每个模块一个文档，保存到
docs/api/ 目录
- 文件命名：
api-{模块英文名}.md，如 api-property.md、api-rental-demand.md
- RESTful 风格：资源名用复数名词，路径以
/api/ 为前缀
- 金额字段以分为单位（INT），避免浮点精度问题
工作流
按顺序执行以下步骤。遇到不确定的问题时，立即使用 AskUserQuestion 向用户提问（每次最多 4 个问题），等用户确认后再继续。不要把问题攒到文档末尾，确保最终文档中没有任何未确认的内容。
提问规则
- 发现不确定的推断、有歧义的字段含义、模糊的模块边界时，立即提问
- 将同一步骤中发现的多个问题收集起来，用一次
AskUserQuestion 批量提问（最多 4 个）
- 如果问题超过 4 个，分批提问
- 对于每个问题，提供 2-4 个可选答案（基于你的推断），并允许用户选择"其他"自由输入
- 用户的回答记录到文档的"已确认事项"章节中
Step 1: 收集信息源
读取用户提供的材料，识别：
- 页面和用户操作
- 模块功能和业务动作
- 数据库表、字段、关联关系、枚举值和状态字段
然后检查 docs/api/ 目录：
- 读取公共规范文件：查找
docs/api/api-common.md，获取统一的响应结构、分页参数、错误码规范、金额约定等。这些是全局约定，每个接口文档都必须遵循。如果该文件不存在，先生成它（模板见下方"公共规范文件模板"），再继续。
- 读取已有模块文档：如果
docs/api/ 下已有其他模块文档，识别其命名约定、响应结构风格、字段命名模式，保持一致。
检查点：如果用户没有提供表结构或模块描述中的任何一个，询问是否有相关文档可以补充。
公共规范文件模板
如果 docs/api/api-common.md 不存在，生成它，包含以下章节：
# API 公共规范
## 1. 统一响应结构
{ code, message, data } 的完整定义，包含成功/失败/无数据返回的示例
## 2. 分页查询
请求参数（page/pageSize/sortBy/sortOrder）和响应结构（{ list, total, page, pageSize }）
## 3. 错误码规范
通用错误码（200/400/401/403/404/409/500）和业务错误码区间划分
## 4. 认证方式
token 携带方式（Authorization: Bearer <token>）
## 5. 通用字段约定
id/createdAt/updatedAt/deletedAt/status/createdBy/updatedBy 的类型和格式
## 6. 金额字段
统一以分为单位（Integer），前端展示时除以 100
内容从现有模块文档中提取模式（响应格式、分页结构、错误码等）。如果项目已有类似规范文件但命名不同，优先读取现有文件而非重新生成。
Step 2: 确认模块边界
从材料中提取：
- 哪些实体属于本模块（是 Owner）
- 哪些操作属于本模块，哪些应委托给其他模块
- 特别注意：支付、分账、消息通知等跨模块操作
将提取的边界简要列出，如果存在不明确的边界，使用 AskUserQuestion 向用户提问确认。
Step 3: 推理接口列表
将以下操作视为候选接口：
- 页面加载 → GET 列表/详情
- 表单提交 → POST 创建 / PUT 更新
- 状态流转 → POST
/resources/:id/actions/{action}
- 删除 → DELETE（软删除）
- 查询/筛选 → GET 带查询参数
合并规则：只有当事务边界和响应结构完全相同时，才合并为一个接口。
拆分规则：当流程涉及支付、审核、状态流转时，拆分为独立接口。
注意：不要以权限差异作为接口拆分或合并的依据。权限是业务逻辑，由后端 RBAC 系统控制，不属于接口定义。接口文档只关注契约本身：方法、路径、入参、出参、校验规则。
辅助接口检查：除了核心 CRUD，检查是否遗漏：
- 审核记录查询（如果有审核流程）
- 图片/附件上传和删除（如果有
images 或文件字段）
- 导出功能（如果模块描述提及导出）
- 管理端独立列表/详情（如果管理端和用户端的数据结构或业务流程不同）
使用以下接口总览表格式：
| 序号 | 接口名称 | 方法 | 路径 | 触发页面/动作 | 说明 |
检查点：接口列表产出后，对照模块描述中的"关键功能"逐项核对，确认每个功能都有对应接口。缺失的补充，多余的标注理由。
Step 4: 推理接口参数
请求参数来源：筛选项、表单字段、路径 ID、分页、排序、当前用户上下文。
响应参数来源：页面展示字段、表字段、业务计算值、关联摘要。
规则：
- 列表接口：默认包含
page(1)、pageSize(20)，从表结构中提取可筛选字段。响应返回 { list, total, page, pageSize }（参照 api-common.md 的分页规范）
- 创建接口：排除
id、created_at、updated_at、deleted_at 等自动字段
- 更新接口：同创建，但所有字段非必填
- 详情接口：返回完整对象，可包含关联子资源（如审核记录、跟进记录）
- 状态字段用枚举值，在说明中列出可选值
- 不确定的字段标记为
推断，使用 AskUserQuestion 向用户确认
检查点：对于金额字段，确认单位是分还是元。schema 中 INT UNSIGNED 且 COMMENT 含"分"的，统一为分。
Step 5: 补充校验与异常
为每个接口补充校验与异常表：
| 场景 | 返回/处理 |
| --- | --- |
| 资源不存在 | 404，"xxx不存在" |
| 参数校验失败 | 400，具体失败原因 |
| 状态冲突（如重复操作） | 409，具体冲突原因 |
Step 6: 补充 Mermaid 流程
只为有业务逻辑的接口生成流程图：
- 涉及多步骤的操作（审核、付费查看、提现）
- 涉及状态变更的操作
- 涉及外部系统调用的操作（支付、微信）
简单 CRUD 不需要流程图。
图表类型选择：
- flowchart TD — 表达业务决策分支（审核通过/驳回、支付成功/失败）
- sequenceDiagram — 表达多角色交互（用户、服务端、第三方）
保持 Mermaid 语法可执行；包含标点或复杂文本的节点名称使用引号。
Step 7: 自检与保存
保存前逐项核对产出完整性：
保存到 docs/api/<模块英文名>.md。除非用户明确要求重新生成，否则保留已有人工编写内容。
文档模板
每个模块文档严格使用以下结构：
# {模块中文名} API
> 本文档遵循 [公共规范](api-common.md)，响应结构、分页参数、错误码等均以公共规范为准，不在本文档重复定义。
## 1. 模块范围
- 适用端：
- 涉及页面：
- 核心目标：
- 信息来源：
- 关键假设：
## 2. 数据表映射
| 表名 | 用途 | 关键字段 | 关联关系 |
## 3. 接口总览
| 序号 | 接口名称 | 方法 | 路径 | 触发页面/动作 | 说明 |
## 4. 接口详情
（每个接口包含：方法、路径、请求参数表、响应参数表、出举示例 JSON、业务规则、校验与异常表。不要为接口标注"权限：xxx角色"，权限属于业务逻辑，不在接口文档中定义。）
## 5. 重要流程
（Mermaid flowchart TD 或 sequenceDiagram）
## 6. 已确认事项
| 问题 | 确认结果 | 确认依据 |
（记录推理过程中通过 `AskUserQuestion` 向用户确认的关键决策和推断，确保文档中所有内容都有据可查）
命名规范
- 路径用小写连字符：
/api/rental-demands
- 分页列表接口：GET
/api/resources，含 page、pageSize、排序和筛选字段
- 详情接口：GET
/api/resources/:id
- 创建：POST
/api/resources
- 更新：PUT
/api/resources/:id
- 删除：DELETE
/api/resources/:id（软删除）
- 业务操作：POST
/api/resources/:id/actions/{action}，如 /api/properties/1/actions/submit-audit
边界条件
| 场景 | 处理方式 |
|---|
| 用户只给了表结构，没有模块描述 | 基于表名和字段 COMMENT 推理业务含义，在"关键假设"中标注推断来源 |
已有 docs/api/ 文档存在 | 先读取既有文档的风格和约定，保持一致。除非用户要求重新生成 |
| 字段类型推断有歧义（如 TEXT 类型存 ID） | 使用 AskUserQuestion 向用户确认字段含义和类型，不猜测 |
| 模块涉及跨系统交互（支付、微信） | 只定义本模块的接口，跨系统交互在 Mermaid 流程图中用虚线标注 |
| 简单模块（只有查询，无 CRUD） | 不要强行添加 CRUD，只产出必要的接口。避免过度设计 |
| 金额字段类型不一致（有的 INT 有的 DECIMAL） | 统一在"关键假设"中说明选择理由 |
