From d2b44d2c6419d5655d9507d30bf2e7a798e3522a Mon Sep 17 00:00:00 2001
From: haoliang <821644@qq.com>
Date: Wed, 29 Apr 2026 17:13:59 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=A2=9E=E5=8A=A0=E4=BF=AE=E6=94=B9?=
 =?UTF-8?q?=E8=AF=B7=E6=B1=82=E9=A2=84=E5=A4=84=E7=90=86=E5=8D=8F=E8=AE=AE?=
 =?UTF-8?q?=E2=80=94=E2=80=94=E6=AF=8F=E6=AC=A1=E4=BF=AE=E6=94=B9=E5=89=8D?=
 =?UTF-8?q?=E5=BF=85=E9=A1=BB=E5=88=86=E6=9E=90=E5=BD=B1=E5=93=8D=E9=9D=A2?=
 =?UTF-8?q?=E5=B9=B6=E7=AD=89=E5=BE=85=E7=A1=AE=E8=AE=A4?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 AGENTS.md | 221 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 221 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 62c7f89..2313dcd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -128,6 +128,227 @@
   - 如必须用PowerShell写入，需用 `[System.IO.File]::WriteAllText($path, $content, [System.Text.UTF8Encoding]::new($false))` 避免BOM
   - 已有BOM文件修复：`node -e "const fs=require('fs');let b=fs.readFileSync('文件路径');if(b[0]===0xEF&&b[1]===0xBB&&b[2]===0xBF)b=b.slice(3);let t=b.toString('utf8').replace(/\r\n/g,'\n');fs.writeFileSync('文件路径',t,'utf8')"`
 
+## 修改请求预处理协议（强制执行）
+
+AI助手收到任何修改/新增/删除请求时，除非用户明确指示"直接执行"（或等效表述），必须先完成影响面分析并向用户报告，等待确认后再开始实施。
+
+### 第一步：影响面分类
+
+识别本次修改涉及的领域（可多选）：
+
+| 标记 | 领域 | 说明 |
+|------|------|------|
+| F | 前端 | 涉及Vue组件、样式、路由、Mock数据、页面交互 |
+| B | 后端 | 涉及Controller/Service/Repository/Model、C#代码 |
+| D | 数据库 | 涉及表结构变更、新增表、字段增删改 |
+| A | API接口 | 涉及端点新增/修改、请求响应格式变更 |
+| R | 需求文档 | 涉及需求变更、架构决策调整 |
+
+### 第二步：规范路由
+
+根据分类结果，列出本次修改必须遵循的规范文件：
+
+| 涉及领域 | 必读规范 | 关键检查项 |
+|---------|---------|-----------|
+| F 前端 | `03-界面变更执行规范.md` + `02-前端全局规范.md` | 联动同步规则、CRUD必填项、Mock/API切换Checklist、组件规范 |
+| B 后端 | `04-后端开发规范.md` | 分层职责、命名后缀、测试覆盖(100%方法/95%分支)、Mock数据结构对齐、端点对照表、DTO断言完整性 |
+| D 数据库 | `01-数据库设计.md` | 双库归属判断、DDL幂等、是否需要数据迁移脚本 |
+| A API接口 | `03-API接口设计.md` | 双列URL同步（Mock列+正式列）、页面§9数据结构同步 |
+| R 需求文档 | `00-需求与设计文档.md` | 检查是否与已确认架构决策冲突 |
+
+### 第三步：输出修改计划摘要
+
+向用户展示以下信息，等待确认：
+
+```
+修改分类：[标记组合]
+必读规范：[列出具体文件名]
+涉及文件：[逐文件列出变更内容]
+联动影响：[需同步更新的文件清单，按03-界面变更执行规范.md联动规则逐条检查]
+预估步骤：[1-N步]
+```
+
+### 豁免条件
+
+以下情况可跳过预处理直接执行：
+
+1. 用户明确说"直接执行"/"不用分析"/"直接改"等等效表述
+2. 修复代码中的typo/注释修改等纯文本变更（不涉及逻辑）
+3. 用户已经在上文给出了完整的修改方案（等同于已确认）
+
+### 示例
+
+**示例1：纯前端修改**
+
+> 用户："告警列表页的告警等级用不同颜色标签展示，紧急红色、重要橙色、一般黄色、提示蓝色"
+
+AI回复：
+
+> 修改分类：F（前端）
+>
+> 必读规范：
+> - `03-界面变更执行规范.md` → 第二节B"修改页面"
+> - `02-前端全局规范.md` → 组件规范（el-tag size=small, 按状态配color）
+>
+> 涉及文件：
+> - `docs/02-功能清单/管理后台/08-告警中心/08-01-告警中心页面.md` → 列表字段区，告警等级列增加颜色定义
+> - `frontend/src/views/alert/AlertPage.vue` → 实际组件代码
+> - `frontend/mock/alert.ts` → Mock数据中告警等级字段确保覆盖4种等级
+>
+> 联动影响（按`03-界面变更执行规范.md`第三节）：
+> - 规则1：不涉及路由/跳转变更 → 无需更新索引文件
+> - 规则2：不涉及新增数据字段 → 无需更新数据需求章节
+> - 规则3：不涉及新增/删除页面 → 无需更新进度表
+> - 无后端/API/数据库变更
+>
+> 预估步骤：
+> 1. 读取 `08-01-告警中心页面.md` 确认当前告警等级列定义
+> 2. 更新页面文件中告警等级列的展示方式（增加颜色映射表）
+> 3. 更新 `AlertPage.vue` 中 el-tag 的 type/color 绑定
+> 4. 验证 Mock 数据覆盖4种等级
+>
+> 是否按此方案执行？
+
+**示例2：前端+API+后端联动**
+
+> 用户："设备列表加一个按品牌筛选的条件"
+
+AI回复：
+
+> 修改分类：F + A + B
+>
+> | 标记 | 领域 | 变更内容 |
+> |------|------|---------|
+> | F | 前端 | 设备列表页查询条件区新增「品牌」下拉（filterable, clearable） |
+> | A | API | GET `/api/admin/machine` 增加 `brandId` 可选查询参数 |
+> | B | 后端 | MachineQuery DTO 增加 BrandId 字段；Repository SQL 增加 WHERE 条件 |
+>
+> 必读规范：
+> - `03-界面变更执行规范.md` → B"修改页面" + 规则6"接口变更同步"
+> - `02-前端全局规范.md` → 组件规范（el-select: filterable=true, clearable=true）
+> - `04-后端开发规范.md` → §5.2.1 Mock数据结构对齐、§3.4 控制器路由规范
+> - `03-API接口设计.md` → §3.3 设备管理模块，双列URL同步
+>
+> 涉及文件（共8处）：
+>
+> | 文件 | 变更 |
+> |------|------|
+> | `docs/02-功能清单/管理后台/03-设备管理/03-01-设备列表页面.md` | §3 查询条件表增加品牌行 |
+> | `docs/03-API接口设计.md` | §3.3 设备列表端点，参数列增加 brandId |
+> | `frontend/mock/machine.ts` | Mock 列表接口支持 brandId 过滤 |
+> | `frontend/src/views/machine/MachineListPage.vue` | 查询区增加品牌下拉 |
+> | `src/CncModels/Dto/MachineQuery.cs` | 新增 `public int? BrandId { get; set; }` |
+> | `src/CncRepository/Impl/MachineRepository.cs` | GetList SQL 增加 `AND brand_id = @BrandId` 条件 |
+> | `src/CncService/Impl/MachineService.cs` | 无变更（透传参数） |
+> | `tests/CncService.Tests/MachineServiceTests.cs` | 新增 `GetList_FilterByBrandId` 测试用例 |
+>
+> 联动影响（按规则6接口变更同步）：
+> - ✅ 端点清单（`03-API接口设计.md`）：Mock列 + 正式列 同时更新参数说明
+> - ✅ 页面§9（`03-01-设备列表页面.md`）：接口请求参数增加 brandId
+> - ✅ Mock文件（`frontend/mock/machine.ts`）：支持按 brandId 过滤返回数据
+> - 无数据库变更（`cnc_machine` 表已有 `brand_id` 字段）
+> - 无需求文档变更
+>
+> 预估步骤：
+> 1. 读取 `03-01-设备列表页面.md` 确认当前查询条件和§9接口定义
+> 2. 更新页面文件 §3 查询条件 + §9 接口参数
+> 3. 更新 `03-API接口设计.md` 端点参数
+> 4. 更新 Mock 文件支持过滤
+> 5. 后端：DTO + Repository SQL + 测试用例
+> 6. 前端组件增加品牌下拉
+>
+> 是否按此方案执行？
+
+**示例3：全栈变更（数据库+后端+API+前端）**
+
+> 用户："设备表增加一个「最后采集时间」字段，前端详情页和列表页都要显示"
+
+AI回复：
+
+> 修改分类：D + B + A + F
+>
+> | 标记 | 领域 | 变更内容 |
+> |------|------|---------|
+> | D | 数据库 | `cnc_machine` 表新增 `last_collect_time DATETIME` 字段 |
+> | B | 后端 | Entity 增加属性、Repository SELECT 增加字段、详情/列表 DTO 增加字段 |
+> | A | API | 设备列表、设备详情接口响应增加 `lastCollectTime` 字段 |
+> | F | 前端 | 列表页增加列、详情页增加展示行 |
+>
+> 必读规范：
+> - `01-数据库设计.md` → §2.4 cnc_machine 表结构，确认字段命名规范
+> - `04-后端开发规范.md` → §3.3 Entity映射、§5.2.1 Mock对齐、§6 测试规范（新增字段需同步测试断言）
+> - `03-界面变更执行规范.md` → B"修改页面" + 规则6 接口变更同步
+> - `02-前端全局规范.md` → 列表字段规范
+>
+> 涉及文件（共12+处）：
+>
+> | 层 | 文件 | 变更 |
+> |----|------|------|
+> | D | `database/` 下新建增量迁移脚本 | ALTER TABLE ADD COLUMN，幂等 |
+> | D | `docs/01-数据库设计.md` | §2.4 表DDL增加字段说明 |
+> | B | `src/CncModels/Entity/Machine.cs` | 新增 `public DateTime? LastCollectTime { get; set; }` |
+> | B | `src/CncModels/Dto/MachineListItem.cs` | 新增 `public DateTime? LastCollectTime { get; set; }` |
+> | B | `src/CncModels/Dto/MachineDetail.cs` | 新增 `public DateTime? LastCollectTime { get; set; }` |
+> | B | `src/CncRepository/Impl/MachineRepository.cs` | SELECT 列增加 `last_collect_time` |
+> | B | `tests/CncRepository.Tests/MachineRepositoryTests.cs` | 断言增加 LastCollectTime 字段 |
+> | B | `tests/CncService.Tests/MachineServiceTests.cs` | DTO 断言完整性（§6.12，每个字段必须断言） |
+> | A | `docs/03-API接口设计.md` | 设备列表/详情端点响应字段更新 |
+> | F | `docs/02-功能清单/管理后台/03-设备管理/03-01-设备列表页面.md` | §4 列表字段增加「最后采集时间」列 |
+> | F | `docs/02-功能清单/管理后台/03-设备管理/03-02-设备详情页面.md` | §3 数据区块增加展示行 |
+> | F | `frontend/mock/machine.ts` | Mock 数据增加 lastCollectTime |
+> | F | `frontend/src/views/machine/MachineListPage.vue` | el-table 增加列 |
+> | F | `frontend/src/views/machine/MachineDetailPage.vue` | 详情展示增加 |
+>
+> 联动影响：
+> - 规则2：页面新增展示字段 → 更新§9数据需求章节
+> - 规则6：接口响应变更 → 端点清单 + 页面§9 + Mock 三处同步
+> - `04-后端开发规范.md` §6.12 DTO断言完整性：列表DTO和详情DTO新增字段，对应测试必须增加断言
+> - 数据库变更需幂等脚本（`database/` 目录规范）
+>
+> 预估步骤：
+> 1. 数据库迁移脚本 + 更新设计文档
+> 2. 后端 Entity/DTO/Repository/Service + 测试
+> 3. API文档更新 + Mock更新
+> 4. 前端页面文件更新 + 组件更新
+>
+> 是否按此方案执行？
+
+**示例4：纯后端Bug修复**
+
+> 用户："MachineService.GetList 分页 page=0 时报错，应该自动修正为1"
+
+AI回复：
+
+> 修改分类：B（后端）
+>
+> 必读规范：
+> - `04-后端开发规范.md` → §5 编码规范、§6 测试规范
+>
+> 涉及文件：
+> - `src/CncService/Impl/MachineService.cs` → GetList 方法增加 page 参数修正逻辑
+> - `tests/CncService.Tests/MachineServiceTests.cs` → 新增/补充分页边界测试
+>
+> 关键约束（从§6必测场景清单提取）：
+> - §G 分页参数场景：`page=0或负数 → 自动修正为page=1`（已定义为必须覆盖的场景）
+> - 需要补充测试：`GetList_PageIsZero_CorrectsToPage1`、`GetList_PageIsNegative_CorrectsToPage1`
+>
+> Bugfix原则（最小修复）：
+> - 只修分页参数修正逻辑，不重构 GetList 方法
+> - 不涉及前端、数据库、API文档变更
+>
+> 预估步骤：
+> 1. 先写失败测试 `GetList_PageIsZero_CorrectsToPage1`
+> 2. 修改 Service 逻辑
+> 3. 确认测试通过
+>
+> 是否按此方案执行？
+
+**示例5：豁免直达**
+
+> 用户："设备列表的分页 pageSize 上限从100改成200，直接执行"
+
+AI跳过预处理，直接开始修改。
+
 ## Git提交规范（强制要求）
 
 - **每次代码改动，编译/验证成功后，必须提交到Git并Push到远程仓库**