diff --git a/AGENTS.md b/AGENTS.md index 619ef74..62c7f89 100644 --- a/AGENTS.md +++ b/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-功能清单/大屏/` | 索引+规范+页面 | diff --git a/docs/02-功能清单/03-界面变更执行规范.md b/docs/02-功能清单/03-界面变更执行规范.md index 2a969b9..5e88de4 100644 --- a/docs/02-功能清单/03-界面变更执行规范.md +++ b/docs/02-功能清单/03-界面变更执行规范.md @@ -67,13 +67,12 @@ AI助手执行任何界面变更前,只需读以下文件: **规则5**:修改了`02-前端全局规范.md`中的全局规范 → 必须检查各模块规范文件是否冲突 -**规则6(接口变更同步)**:新增或变更接口时,必须在 `03-API接口设计.md` 对应模块的端点清单中**同时维护两列**: -- **正式API列**:RESTful 风格(PUT/DELETE + 路径参数) -- **Mock URL列**:Mock 开发风格(POST 简化) -- 禁止只新增一列而遗漏另一列 -- 同步在对应 Mock 文件(`frontend/mock/*.ts`)中按 Mock URL 列新增 Mock 数据 +**规则6(接口变更同步)**:新增或变更接口时,必须同步以下3处: +- **端点清单**(`03-API接口设计.md` §3.x):**同时维护两列**——正式API列(RESTful)+ Mock URL列(POST简化),禁止只新增一列 +- **页面文件§9**(接口引用与数据结构):定义该接口的Request/Response数据结构(这是数据结构的唯一来源) +- **Mock文件**(`frontend/mock/*.ts`):按页面文件§9的数据结构生成Mock数据 -**记忆口诀**:改页面→查索引;改路由→查双向索引;增删页面/模块→三处同步(索引+进度表+总览);增改接口→两列URL同时更新 +**记忆口诀**:改页面→查索引;改路由→查双向索引;增删页面/模块→三处同步(索引+进度表+总览);增改接口→三处同步(端点清单两列URL + 页面§9数据结构 + Mock文件) --- diff --git a/docs/03-API接口设计.md b/docs/03-API接口设计.md index 95734b0..01285e1 100644 --- a/docs/03-API接口设计.md +++ b/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 数据 -3. 后端按正式API列实现接口,返回数据结构对齐 Mock 中定义的 JSON -4. 前端 Mock 开发时按 Mock URL 列调用,正式联调时切换到正式API列 -5. 禁止只新增一列而遗漏另一列——每次新增接口必须两列同时更新 +2. 在对应模块的页面文件§9中定义该接口的Request/Response数据结构 +3. 在对应模块的 Mock 文件(`frontend/mock/*.ts`)中按页面文件§9的数据结构生成 Mock 数据 +4. 后端按正式API列实现接口,返回数据结构严格对齐页面文件§9的定义 +5. 前端 Mock 开发时按 Mock URL 列调用,正式联调时切换到正式API列 +6. 禁止只新增一列而遗漏另一列——每次新增接口必须两列同时更新 diff --git a/docs/04-后端开发规范.md b/docs/04-后端开发规范.md index a5505a7..7d99844 100644 --- a/docs/04-后端开发规范.md +++ b/docs/04-后端开发规范.md @@ -244,7 +244,7 @@ public class ApiResponse ### 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>.Success(result)); #### 检查方法 每个接口开发完成后,必须: -1. 打开对应的 Mock 文件(`frontend/mock/*.ts`),找到该 URL 的 `response` 定义 -2. 确认 Mock 中 `data` 的结构(是 `{ items: [...] }` 还是 `{ ... }` 或是 `null`) +1. 打开对应的页面文件§9(接口引用与数据结构),找到该接口的 Response 定义 +2. 确认页面文件§9中 `data` 的结构(是 `{ items: [...] }` 还是 `{ ... }` 或是 `null`) 3. 确认后端 `ApiResponse` 中的 `T` 能序列化出相同结构 -4. 如有差异,调整后端返回格式以匹配 Mock +4. 如有差异,调整后端返回格式以匹配页面文件§9的定义 ### 5.3 异常处理