规范：统一4个文件的职责划分——03只管URL，数据结构由页面文件§9定义

AGENTS.md

@@ -32,7 +32,7 @@
 │   │   ├── 03-界面变更执行规范.md      # ⚠️ AI助手执行界面变更时必读
 │   │   ├── 大屏/                       # 大屏看板模块
 │   │   └── 管理后台/                   # 12个子模块（登录/仪表盘/设备/品牌/采集地址/员工/产量/告警/系统/车间/操作日志/大屏配置）
-│   ├── 03-API接口设计.md              # 13模块83端点，含Mock映射+DB表对照
+│   ├── 03-API接口设计.md              # 13模块83端点（URL+Method两列对照）
 │   └── 04-后端开发规范.md              # ⚠️ 后端必读：技术栈/项目结构/命名/注释/测试/分层/依赖注入规范
 ├── frontend/                          # 前端工程（Vue3+Vite+TypeScript+Element Plus）
 │   ├── mock/                          # Mock数据定义（按模块拆分）
@@ -52,7 +52,7 @@
 | 新增功能模块文档 | `docs/02-功能清单/02-文件夹创建规范.md` | 目录结构/命名/内容模板规范 |
 | AI助手执行界面变更 | `docs/02-功能清单/03-界面变更执行规范.md` | ⚠️ 必读：最小必读文件+变更清单+联动同步规则 |
 | 后端开发规范 | `docs/04-后端开发规范.md` | ⚠️ 后端必读：技术栈/项目结构/命名/注释/测试/分层/依赖注入 |
-| API接口设计 | `docs/03-API接口设计.md` | 13模块83端点，含Mock映射+DB表对照 |
+| API接口设计 | `docs/03-API接口设计.md` | 13模块83端点（URL+Method两列对照，不含数据结构） |
 | 品牌采集数据格式 | `发那科系统采集示例.txt` | FANUC品牌JSON结构示例 |
 | 管理后台某模块设计 | `docs/02-功能清单/管理后台/{编号}-{模块名}/` | 每模块含索引+规范+页面文件 |
 | 大屏看板设计 | `docs/02-功能清单/大屏/` | 索引+规范+页面 |

docs/02-功能清单/03-界面变更执行规范.md

@@ -67,13 +67,12 @@ AI助手执行任何界面变更前，只需读以下文件：
 
 **规则5**：修改了`02-前端全局规范.md`中的全局规范 → 必须检查各模块规范文件是否冲突
 
-**规则6（接口变更同步）**：新增或变更接口时，必须在 `03-API接口设计.md` 对应模块的端点清单中**同时维护两列**：
+**规则6（接口变更同步）**：新增或变更接口时，必须同步以下3处：
-- **正式API列**：RESTful 风格（PUT/DELETE + 路径参数）
+- **端点清单**（`03-API接口设计.md` §3.x）：**同时维护两列**——正式API列（RESTful）+ Mock URL列（POST简化），禁止只新增一列
-- **Mock URL列**：Mock 开发风格（POST 简化）
+- **页面文件§9**（接口引用与数据结构）：定义该接口的Request/Response数据结构（这是数据结构的唯一来源）
-- 禁止只新增一列而遗漏另一列
+- **Mock文件**（`frontend/mock/*.ts`）：按页面文件§9的数据结构生成Mock数据
-- 同步在对应 Mock 文件（`frontend/mock/*.ts`）中按 Mock URL 列新增 Mock 数据
 
-**记忆口诀**：改页面→查索引；改路由→查双向索引；增删页面/模块→三处同步（索引+进度表+总览）；增改接口→两列URL同时更新
+**记忆口诀**：改页面→查索引；改路由→查双向索引；增删页面/模块→三处同步（索引+进度表+总览）；增改接口→三处同步（端点清单两列URL + 页面§9数据结构 + Mock文件）
 
 ---
 

docs/03-API接口设计.md

@@ -343,8 +343,6 @@
 | 4 | `/api/admin/worker/list` | GET | `/mock-api/admin/worker/list` | 设备管理、产量报表 |
 | 5 | `/api/admin/collect-address/list` | GET | `/mock-api/admin/collect-address/list` | 设备管理 |
 
-> 返回格式统一为 `{ "code": 0, "data": { "items": [...] } }`，只包含 id 和名称字段，不含分页。
-
 ---
 
 ## 四、端点汇总
@@ -379,9 +377,10 @@
 
 **Mock不动规则（限定为返回数据结构）**：
 
-1. **返回数据结构不动**：正式 API 返回的 `data` 内部 JSON 结构（字段名、嵌套关系、items包裹等）必须与 Mock 保持一致。这是前后端联调的基础。
+1. **返回数据结构不动**：正式 API 返回的 `data` 内部 JSON 结构（字段名、嵌套关系、items包裹等）必须与页面文件§9（接口引用与数据结构）中定义的数据结构保持一致。Mock 文件按页面文件§9生成，后端也必须对齐§9的数据结构。
 2. **URL路径和HTTP方法按RESTful**：正式 API 的 URL 路径和 HTTP 方法使用 §1.3 定义的 RESTful 风格，不必与 Mock 的 URL 路径和方法完全一致。
-3. **端点清单是唯一合同**：每个模块的端点清单（§3.1~3.13）同时列出了"正式API"和"Mock URL"两列，两边各自按自己的列实现/调用即可。
+3. **端点清单是路由合同**：每个模块的端点清单（§3.1~3.13）同时列出了"正式API"和"Mock URL"两列，两边各自按自己的列实现/调用即可。端点清单只定义URL和方法，不定义返回数据结构。
+4. **数据结构定义在页面文件§9**：每个接口的具体Request/Response数据结构由对应的页面文件§9（接口引用与数据结构）定义，这是数据结构的唯一来源。
 
 **两列URL差异说明**：
 - 写操作：Mock 用 `POST /xxx/update`、`POST /xxx/delete`，正式API 用 `PUT /xxx/{id}`、`DELETE /xxx/{id}`
@@ -392,7 +391,8 @@
 **新增或变更接口时的流程**：
 
 1. 先在对应模块的端点清单（§3.x）中**同时新增两行**：正式API列（RESTful）+ Mock URL列（POST简化）
-2. 在对应模块的 Mock 文件（`frontend/mock/*.ts`）中按 Mock URL 列新增 Mock 数据
+2. 在对应模块的页面文件§9中定义该接口的Request/Response数据结构
-3. 后端按正式API列实现接口，返回数据结构对齐 Mock 中定义的 JSON
+3. 在对应模块的 Mock 文件（`frontend/mock/*.ts`）中按页面文件§9的数据结构生成 Mock 数据
-4. 前端 Mock 开发时按 Mock URL 列调用，正式联调时切换到正式API列
+4. 后端按正式API列实现接口，返回数据结构严格对齐页面文件§9的定义
-5. 禁止只新增一列而遗漏另一列——每次新增接口必须两列同时更新
+5. 前端 Mock 开发时按 Mock URL 列调用，正式联调时切换到正式API列
+6. 禁止只新增一列而遗漏另一列——每次新增接口必须两列同时更新

docs/04-后端开发规范.md

@@ -244,7 +244,7 @@ public class ApiResponse<T>
 
 ### 5.2.1 Mock数据结构对齐（强制）
 
-> **核心原则：后端 API 返回的 `data` 内部结构必须严格匹配 Mock 文件中的定义。前端代码按 Mock 结构取值，后端返回格式不一致将导致前端取不到数据。**
+> **核心原则：后端 API 返回的 `data` 内部结构必须严格匹配页面文件§9（接口引用与数据结构）中定义的数据结构。页面文件§9是数据结构的唯一来源，Mock文件按§9生成，后端也必须对齐§9。**
 >
 > **注意：此规则仅约束返回的 JSON 数据结构，不约束 URL 路径和 HTTP 方法。** URL 和方法按 §1.3 RESTful 规范实现，与 Mock 可能有差异（差异对照见 `03-API接口设计.md` 端点清单的双列URL）。
 
@@ -281,10 +281,10 @@ return Ok(ApiResponse<PagedResult<MachineListItem>>.Success(result));
 #### 检查方法
 
 每个接口开发完成后，必须：
-1. 打开对应的 Mock 文件（`frontend/mock/*.ts`），找到该 URL 的 `response` 定义
+1. 打开对应的页面文件§9（接口引用与数据结构），找到该接口的 Response 定义
-2. 确认 Mock 中 `data` 的结构（是 `{ items: [...] }` 还是 `{ ... }` 或是 `null`）
+2. 确认页面文件§9中 `data` 的结构（是 `{ items: [...] }` 还是 `{ ... }` 或是 `null`）
 3. 确认后端 `ApiResponse<T>` 中的 `T` 能序列化出相同结构
-4. 如有差异，调整后端返回格式以匹配 Mock
+4. 如有差异，调整后端返回格式以匹配页面文件§9的定义
 
 ### 5.3 异常处理