From 5d1d5ebb272d8e853d89268a5267463219613434 Mon Sep 17 00:00:00 2001
From: haoliang <821644@qq.com>
Date: Wed, 29 Apr 2026 01:17:47 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E5=89=8D=E5=90=8E?=
 =?UTF-8?q?=E7=AB=AF=E6=8E=A5=E5=8F=A3=E8=A7=84=E8=8C=83=EF=BC=8C=E8=A7=A3?=
 =?UTF-8?q?=E5=86=B3Mock=E4=B8=8D=E5=8A=A8=E8=A7=84=E5=88=99=E4=B8=8ERESTf?=
 =?UTF-8?q?ul=E8=A7=84=E8=8C=83=E7=9A=84=E5=86=B2=E7=AA=81?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/02-前端全局规范.md                 | 15 +++++++++
 docs/02-功能清单/03-界面变更执行规范.md |  8 ++++-
 docs/03-API接口设计.md                  | 45 +++++++++++++++++++++----
 docs/04-后端开发规范.md                 |  2 ++
 4 files changed, 62 insertions(+), 8 deletions(-)

diff --git a/docs/02-前端全局规范.md b/docs/02-前端全局规范.md
index 7affb92..752e65e 100644
--- a/docs/02-前端全局规范.md
+++ b/docs/02-前端全局规范.md
@@ -303,6 +303,21 @@ D:\opencode\haoliang\frontend\
 | 后端就绪后 | `http://localhost:5173/dashboard` | 直接对接真实API |
 | 后端就绪后 | `http://localhost:5173/mock/dashboard` | 仍可切回Mock对比 |
 
+#### 双列URL使用规则
+
+接口文档（`docs/03-API接口设计.md` §3.1~3.13）中每个端点同时列出两列URL：
+
+| 列名 | 用途 | HTTP方法 | URL风格 |
+|------|------|---------|---------|
+| **Mock URL 列** | 前端Mock开发阶段使用 | 全部POST（简化） | `/xxx/update`、`/xxx/delete`、`/xxx/detail?id=` |
+| **正式API 列** | 前端正式联调使用 | RESTful（GET/POST/PUT/DELETE） | `/xxx/{id}` 路径参数 |
+
+**前端开发者必须遵守**：
+- Mock 开发阶段（`/mock/` 路径访问）：按 Mock URL 列调用，全部用 POST
+- 正式联调阶段（`/` 路径访问）：按正式API列调用，写操作用 PUT/DELETE，id放URL路径
+- 切换时机：后端接口开发完成并可联调时，逐个接口从Mock风格切换到RESTful风格
+- 禁止在正式环境中残留Mock风格的URL调用
+
 #### Mock模式检测
 
 ```typescript
diff --git a/docs/02-功能清单/03-界面变更执行规范.md b/docs/02-功能清单/03-界面变更执行规范.md
index 9a1655e..2a969b9 100644
--- a/docs/02-功能清单/03-界面变更执行规范.md
+++ b/docs/02-功能清单/03-界面变更执行规范.md
@@ -67,7 +67,13 @@ AI助手执行任何界面变更前，只需读以下文件：
 
 **规则5**：修改了`02-前端全局规范.md`中的全局规范 → 必须检查各模块规范文件是否冲突
 
-**记忆口诀**：改页面→查索引；改路由→查双向索引；增删页面/模块→三处同步（索引+进度表+总览）
+**规则6（接口变更同步）**：新增或变更接口时，必须在 `03-API接口设计.md` 对应模块的端点清单中**同时维护两列**：
+- **正式API列**：RESTful 风格（PUT/DELETE + 路径参数）
+- **Mock URL列**：Mock 开发风格（POST 简化）
+- 禁止只新增一列而遗漏另一列
+- 同步在对应 Mock 文件（`frontend/mock/*.ts`）中按 Mock URL 列新增 Mock 数据
+
+**记忆口诀**：改页面→查索引；改路由→查双向索引；增删页面/模块→三处同步（索引+进度表+总览）；增改接口→两列URL同时更新
 
 ---
 
diff --git a/docs/03-API接口设计.md b/docs/03-API接口设计.md
index 25f76b9..dc4574b 100644
--- a/docs/03-API接口设计.md
+++ b/docs/03-API接口设计.md
@@ -10,6 +10,7 @@
 
 ### 1.1 变更流程（强制遵守）
 
+**设计阶段：**
 ```
 功能需求变更描述 → 前端界面+Mock数据先改 → API接口跟着Mock改 → 数据库最后改
 ```
@@ -19,6 +20,16 @@
 - 正式 API 格式：`/api/admin/xxx`
 - Mock 模式下前端 baseURL 自动切换为 `/mock-api`，正式部署切回 `/api`
 
+**联调阶段：**
+```
+后端按RESTful列实现 → 前端正式代码按RESTful列调整调用方式 → 联调验证
+```
+
+- 前端 Mock 开发阶段：使用端点清单的 **Mock URL 列**（全部POST，简化开发）
+- 前端正式联调阶段：切换到端点清单的 **正式API 列**（RESTful风格：PUT/DELETE + 路径参数）
+- 后端始终按端点清单的 **正式API 列** 实现，不需要实现Mock风格的URL
+- 端点清单（§3.1~3.13）中同时列出了两列URL，是唯一的接口合同
+
 ### 1.2 URL映射规则
 
 | 场景 | Mock URL | 正式 API URL |
@@ -27,19 +38,23 @@
 | 大屏看板 | `/mock-api/screen/xxx` | `/api/screen/xxx` |
 | 采集服务 | - | `http://localhost:{port}/api/collector/xxx` |
 
-### 1.3 RESTful 规范
+### 1.3 RESTful 规范（强制）
 
 | 操作 | Method | URL示例 | 说明 |
 |------|--------|---------|------|
 | 查列表 | GET | `/api/admin/machine` | 分页用 query params |
 | 查详情 | GET | `/api/admin/machine/{id}` | 路径参数 |
 | 新增 | POST | `/api/admin/machine` | Body 传 JSON |
-| 修改 | PUT | `/api/admin/machine/{id}` | Body 传 JSON |
-| 删除 | DELETE | `/api/admin/machine/{id}` | - |
-| 启停 | PUT | `/api/admin/machine/{id}/toggle` | - |
+| 修改 | PUT | `/api/admin/machine/{id}` | Body 传 JSON，id在URL路径中 |
+| 删除 | DELETE | `/api/admin/machine/{id}` | id在URL路径中 |
+| 启停 | PUT | `/api/admin/machine/{id}/toggle` | id在URL路径中 |
 | 批量操作 | POST | `/api/admin/machine/batch-status` | Body 传 ID 数组 |
 
-> **注意**：Mock 中部分接口用 POST 替代 PUT/DELETE（如 `update`/`delete`），这是 Mock 阶段的简化。正式 API 全部使用标准 RESTful 语义，前端 `request.ts` 中的方法调用需同步调整。
+**强制要求**：
+- 后端 API 一律使用上表的 RESTful 风格实现（PUT/DELETE + 路径参数），禁止实现Mock风格的POST路由
+- 前端正式联调代码一律使用 RESTful 风格调用，禁止在正式环境中使用Mock风格的URL（`/update`、`/delete`、`/toggle`等POST路由）
+- 前端 Mock 开发阶段可使用简化的 POST 风格（见端点清单的 Mock URL 列），联调时按正式API列切换
+- 参数传递：RESTful 中资源 ID 通过 URL 路径传递（`/{id}`），不放在 request body 中
 
 ### 1.4 认证机制
 
@@ -587,6 +602,22 @@ Response:
 | `/api/admin/` | `/mock-api/admin/` | 管理后台所有接口 |
 | `/api/screen/` | `/mock-api/screen/` | 大屏看板接口 |
 
-**Mock 不动规则**：正式 API 的 URL 路径（去掉前缀后）与 Mock 保持一致。如正式 `GET /api/admin/machine` 对应 Mock `GET /mock-api/admin/machine`。
+**Mock不动规则（限定为返回数据结构）**：
+
+1. **返回数据结构不动**：正式 API 返回的 `data` 内部 JSON 结构（字段名、嵌套关系、items包裹等）必须与 Mock 保持一致。这是前后端联调的基础。
+2. **URL路径和HTTP方法按RESTful**：正式 API 的 URL 路径和 HTTP 方法使用 §1.3 定义的 RESTful 风格，不必与 Mock 的 URL 路径和方法完全一致。
+3. **端点清单是唯一合同**：每个模块的端点清单（§3.1~3.13）同时列出了"正式API"和"Mock URL"两列，两边各自按自己的列实现/调用即可。
+
+**两列URL差异说明**：
+- 写操作：Mock 用 `POST /xxx/update`、`POST /xxx/delete`，正式API 用 `PUT /xxx/{id}`、`DELETE /xxx/{id}`
+- 详情查询：Mock 用 `GET /xxx/detail?id=`，正式API 用 `GET /xxx/{id}`
+- 参数传递：Mock 把 id 放在 query 或 body 中，正式API 把 id 放在 URL 路径中
+- 读取操作（GET列表）：两列URL完全一致，只有前缀不同
+
+**新增或变更接口时的流程**：
 
-**例外**：正式 API 中使用路径参数的接口（如 `/api/admin/machine/{id}`），Mock 中用 query 参数（如 `/mock-api/admin/machine/detail?id=`）。前端代码通过条件判断区分。
+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. 禁止只新增一列而遗漏另一列——每次新增接口必须两列同时更新
diff --git a/docs/04-后端开发规范.md b/docs/04-后端开发规范.md
index c5463e6..a5505a7 100644
--- a/docs/04-后端开发规范.md
+++ b/docs/04-后端开发规范.md
@@ -245,6 +245,8 @@ public class ApiResponse<T>
 ### 5.2.1 Mock数据结构对齐（强制）
 
 > **核心原则：后端 API 返回的 `data` 内部结构必须严格匹配 Mock 文件中的定义。前端代码按 Mock 结构取值，后端返回格式不一致将导致前端取不到数据。**
+>
+> **注意：此规则仅约束返回的 JSON 数据结构，不约束 URL 路径和 HTTP 方法。** URL 和方法按 §1.3 RESTful 规范实现，与 Mock 可能有差异（差异对照见 `03-API接口设计.md` 端点清单的双列URL）。
 
 #### 规则说明