api-doc-infer

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/ 目录：

1. 读取公共规范文件：查找 docs/api/api-common.md，获取统一的响应结构、分页参数、错误码规范、金额约定等。这些是全局约定，每个接口文档都必须遵循。如果该文件不存在，先生成它（模板见下方"公共规范文件模板"），再继续。
2. 读取已有模块文档：如果 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/api-common.md 已存在（不存在则先生成），且本文档顶部有引用链接
• 模块范围：适用端、涉及页面、关键假设均已填写
• 数据表映射：本模块涉及的表都已列出，关联关系正确
• 接口总览表：每个接口有方法、路径、触发场景
• 接口详情：每个接口有入参表、出参表、JSON 示例、业务规则、校验与异常表
• 公共字段去重：响应结构中的 code/message/data 包裹层和分页参数 page/pageSize 不在出参表中重复列出，而是在 JSON 示例中体现；只有 data 内部的业务字段才写入出参表
• 重要流程：涉及状态变更/支付/审核的接口有 Mermaid 图
• 待确认问题：所有不确定的问题都已通过 AskUserQuestion 向用户确认，文档中不存在未确认的内容
• 已确认事项：用户确认的关键决策已记录到文档的"已确认事项"章节

保存到 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）	统一在"关键假设"中说明选择理由