规范:更新§16格式说明,接口引用表只列编号+界面用途不重复URL,数据结构是唯一定义处

main
haoliang 1 week ago
parent 2887568c5f
commit 8b9809e3f6

@ -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 }
```
**强制要求**
- 接口引用表只写端点编号和界面用途不重复URLURL由03统一定义
- 每个接口必须写清 Request body 和 Response 的完整JSON结构
- 写操作的 Request body 中需要包含 id 字段Mock和正式API的id传递方式不同由03的端点清单说明
- 数据结构必须与 Mock 文件(`frontend/mock/*.ts`)中的定义严格一致
---
### 六、三种文件分工

Loading…
Cancel
Save