|
|
|
|
@ -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`)中的定义严格一致
|
|
|
|
|
|
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
### 六、三种文件分工
|
|
|
|
|
|