haoliang-net/docs/05-修改请求预处理协议.md

修改请求预处理协议

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跳过预处理，直接开始修改。