api-doc-infer

# 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` 不存在，生成它，包含以下章节： ```markdown # 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` 或文件字段） - 导出功能（如果模块描述提及导出） - 管理端独立列表/详情（如果管理端和用户端的数据结构或业务流程不同） 使用以下接口总览表格式： ```markdown | 序号 | 接口名称 | 方法 | 路径 | 触发页面/动作 | 说明 | ``` **检查点**：接口列表产出后，对照模块描述中的"关键功能"逐项核对，确认每个功能都有对应接口。缺失的补充，多余的标注理由。 ### 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: 补充校验与异常 为每个接口补充校验与异常表： ```markdown | 场景 | 返回/处理 | | --- | --- | | 资源不存在 | 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`。除非用户明确要求重新生成，否则保留已有人工编写内容。 ## 文档模板 每个模块文档严格使用以下结构： ```markdown # {模块中文名} 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） | 统一在"关键假设"中说明选择理由 |