diff --git a/docs/02-功能清单/02-文件夹创建规范.md b/docs/02-功能清单/02-文件夹创建规范.md index 2b6b91c..87bf24c 100644 --- a/docs/02-功能清单/02-文件夹创建规范.md +++ b/docs/02-功能清单/02-文件夹创建规范.md @@ -172,12 +172,64 @@ | 序号 | 内容 | 说明 | |------|------|------| | 13 | 组件规范 | 组件选择、配置 | -| 16 | Mock数据规格 | 完整Request/Response示例 | +| 16 | 接口引用与数据结构 | 引用端点清单编号 + 每个接口的完整Request/Response数据结构定义(见下方详细说明) | | 17 | 键盘操作 | 快捷键 | | 18 | 空状态设计 | 空态展示 | | 19 | 错误码处理 | 错误码映射 | | 20 | 安全规范 | 加密、存储、防护 | +#### §16 接口引用与数据结构 — 详细格式说明 + +**职责划分**(与 `03-API接口设计.md` 端点清单的关系): + +| 文件 | 负责定义 | 不负责 | +|------|---------|--------| +| `03-API接口设计.md` 端点清单(§3.1~3.13) | URL路径、HTTP方法、端点编号(两列URL对照) | **禁止定义返回数据结构** | +| 页面文件 §16 | 引用端点清单编号 + 每个接口的完整Request/Response数据结构 | **不重复定义URL** | + +**§16 必须包含两部分:** + +**第一部分:接口引用表**(只引用编号和界面用途,不重复URL) + +```markdown +#### 接口引用 + +> Mock/正式API的URL、HTTP方法均定义在 `03-API接口设计.md` §3.x 端点清单,本节仅引用编号。 + +| 接口名称 | 端点编号 | 界面用途 | +|---------|---------|---------| +| 配置项列表 | §3.9 #1 | Tab1系统配置列表,渲染表格 | +| 编辑配置项 | §3.9 #2 | Tab1编辑弹窗保存 | +| 车间列表 | §3.9 #4 | Tab2车间管理列表,渲染表格 | +``` + +**第二部分:数据结构定义**(每个接口的完整Request/Response JSON,这是唯一的数据结构定义处) + +```markdown +#### 数据结构 + +**配置项列表(§3.9 #1):** + +Response: +{ "code": 0, "data": { "items": [ + { "id": 1, "configKey": "ping_interval", "configValue": "60", "valueType": "number", "description": "Ping检测间隔(秒)" } +]}} + +**编辑配置项(§3.9 #2):** + +Request body: +{ "id": 1, "configValue": "120" } + +Response: +{ "code": 0, "message": "success", "data": null } +``` + +**强制要求**: +- 接口引用表只写端点编号和界面用途,不重复URL(URL由03统一定义) +- 每个接口必须写清 Request body 和 Response 的完整JSON结构 +- 写操作的 Request body 中需要包含 id 字段(Mock和正式API的id传递方式不同,由03的端点清单说明) +- 数据结构必须与 Mock 文件(`frontend/mock/*.ts`)中的定义严格一致 + --- ### 六、三种文件分工