# 修改请求预处理协议

> 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步]
```

## 第四步：执行中验证（边改边验）

每完成一个文件的修改，立即执行对应的自检动作，不等全部改完再回头检查。

### 自检规则

| 时机 | 验证动作 | 适用范围 |
|------|---------|---------|
| 改完设计文档后 | 读关联文档，检查联动字段是否同步（如页面§9数据结构↔API端点↔Mock） | F/A/D类修改 |
| 改完代码文件后 | `lsp_diagnostics` 检查该文件，确认无error | 所有代码修改 |
| 改完Vue组件后 | 对照对应页面设计文档的字段表逐列核对 | F类修改 |
| 改完C#代码后 | 对照对应后端规范的命名/分层/测试要求 | B类修改 |
| 所有文件改完后 | `npm run build`（前端）或 `dotnet build`（后端）确认编译通过 | 代码修改 |

### 禁止行为

- 禁止跳过自检直接标记任务完成
- 禁止一次性改完全部文件后再统一验证（错误会累积）
- 禁止用 `as any`、`@ts-ignore` 压制诊断错误来通过验证

## 第五步：完成验收（改完后总验）

所有文件修改完成且执行中验证通过后，执行总验收。

### 验收清单

**第1项：变更清单核对**

列出所有已修改的文件，逐文件确认：
- 改动内容与第三步的修改计划摘要一致
- 无遗漏文件（对照计划中的涉及文件清单逐个勾选）
- 无多余改动（未在计划中的文件未被修改）

**第2项：定向验证（按影响面类型）**

| 影响面 | 验证动作 |
|--------|---------|
| F 前端UI | `npm run dev` 启动开发服务器，逐页面检查视觉效果 |
| F 前端逻辑 | grep搜索残留旧代码（旧URL、旧字段名、已删除的组件引用） |
| F Mock数据 | 检查Mock文件与页面§9数据结构一致 |
| B 后端 | `dotnet build` 编译通过 + 测试运行通过 |
| B 后端测试 | 对照 `04-后端开发规范.md` §6 必测7大类场景，确认覆盖 |
| D 数据库 | 迁移脚本幂等性验证（重复执行不报错不丢数据） |
| A API接口 | 双列URL同步检查（Mock列↔正式列同时更新） |
| R 需求文档 | 检查与 `00-需求与设计文档.md` 已确认决策无冲突 |

**第3项：跨文档一致性抽查**

根据修改类型，抽查以下关联一致性：

| 修改类型 | 抽查项 |
|---------|--------|
| 新增/删除字段 | 页面§4列表字段 ↔ API响应JSON ↔ Mock数据 ↔ Entity/DTO |
| 新增/删除接口 | 端点清单(Mock列+正式列) ↔ 页面§10接口引用 ↔ Mock文件 |
| 新增/删除页面 | 路由总表 ↔ 模块进度表 ↔ 菜单映射 |
| 状态变更 | 页面§7状态机 ↔ 组件代码中的状态判断逻辑 |
| 按钮变更 | 页面§5操作按钮 ↔ 组件template中的按钮元素 |

**第4项：Git提交**

- commit message 对应修改计划摘要
- push到远程仓库

### 验收通过标准

以下全部满足方可声明任务完成：

1. ✅ 变更清单核对：计划中的所有文件均已修改，无遗漏无多余
2. ✅ 编译/构建通过（如有代码修改）
3. ✅ 定向验证通过（按影响面类型逐项执行）
4. ✅ 跨文档一致性抽查通过
5. ✅ Git commit + push 完成

## 豁免条件

以下情况可跳过预处理直接执行：

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

### 示例6：前端全局规范修改（含完整执行中验证+完成验收）

> 用户："所有列表页的列宽改为均分，批量操作按钮统一放到上方"

**第一步~第三步**（略，按正常流程输出修改计划摘要）

**第四步：执行中验证**

每改完一个文件后的自检记录：

> 改完 `02-前端全局规范.md`：
> - ✅ 新增"el-table列宽均分规则"和"操作按钮统一布局规则"两个章节
> - ✅ 规则内容与用户需求一致（禁止固定width、操作列例外、批量按钮改页头）
>
> 改完 `03-01-设备列表页面.md`：
> - ✅ §4列表字段：选择框50，数据列全部改"-"，操作列180
> - ✅ §5操作按钮：批量停用/启用从"底部栏"改为"页头"
> - ✅ §2布局图：移除底部批量操作栏，操作栏增加批量按钮
> - ✅ 联动检查：页面文档的列宽值与全局规范新规则一致
>
> 改完 `MachineListPage.vue`：
> - ✅ lsp_diagnostics 无error
> - ✅ 逐列核对：template中的el-table-column属性与页面§4字段表一致
> - ✅ grep搜索 `width=` 无残留（仅操作列和选择框列有width）
> - ✅ grep搜索 `sticky` 或 `底部栏` 无残留
>
> （其余页面同理，每改完一个文件立即自检）

**第五步：完成验收**

> **第1项 变更清单核对：**
>
> | 计划文件 | 状态 | 说明 |
> |---------|------|------|
> | `02-前端全局规范.md` | ✅ | 新增两条规则 |
> | `03-01-设备列表页面.md` | ✅ | 列宽+按钮位置 |
> | `04-01-品牌列表页面.md` | ✅ | 列宽 |
> | `05-01-采集地址页面.md` | ✅ | 列宽 |
> | `06-01-员工管理页面.md` | ✅ | 列宽+按钮位置 |
> | `07-01-产量报表页面.md` | ✅ | 列宽 |
> | `08-01-告警中心页面.md` | ✅ | 列宽 |
> | `11-01-操作日志页面.md` | ✅ | 列宽 |
> | `09-01-系统设置页面.md` | ✅ | 列宽 |
> | `MachineListPage.vue` | ✅ | 列宽+按钮位置 |
> | `WorkerListPage.vue` | ✅ | 列宽+按钮位置 |
> | 其余5个Vue组件 | ✅ | 列宽 |
>
> **第2项 定向验证：**
> - F 前端逻辑：grep搜索 `width=` 在Vue组件中仅命中选择框列和操作列 → ✅
> - F 前端逻辑：grep搜索 `底部栏`/`sticky` 在Vue组件中零命中 → ✅
> - F 前端UI：`npm run dev` 启动，逐页面查看列宽均分效果 → ⏳ 需用户浏览器确认
>
> **第3项 跨文档一致性抽查：**
> - 抽查"设备列表"：页面§4列宽值 ↔ Vue组件el-table-column的width属性 → ✅ 一致
> - 抽查"员工列表"：页面§5批量按钮位置 ↔ Vue组件中批量按钮DOM位置 → ✅ 一致
>
> **第4项 Git提交：**
> - commit: "全局列宽均分+批量按钮统一到上方（8个页面文档+8个Vue组件）"
> - push → ✅ 完成

### 示例7：后端Bug修复（含完整执行中验证+完成验收）

> 用户："MachineService.GetList 分页 page=0 时报错"

**第三步输出计划：**
> 涉及文件：
> - `src/CncService/Impl/MachineService.cs` → GetList 增加 page 修正
> - `tests/CncService.Tests/MachineServiceTests.cs` → 新增边界测试

**第四步：执行中验证**

> 改完 `MachineService.cs`：
> - ✅ lsp_diagnostics 无error
> - ✅ 逻辑：page < 1 时自动修正为 1，无其他改动
>
> 改完 `MachineServiceTests.cs`：
> - ✅ lsp_diagnostics 无error
> - ✅ 新增测试覆盖：page=0、page=-1 两个场景
> - ✅ 测试命名遵循 `MethodName_Scenario_Expected` 模式

**第五步：完成验收**

> **第1项 变更清单核对：**
> - `MachineService.cs` ✅ 仅改分页修正逻辑
> - `MachineServiceTests.cs` ✅ 新增2个测试用例
> - 无多余改动 ✅
>
> **第2项 定向验证：**
> - `dotnet build` → 编译通过 ✅
> - `dotnet test` → 全部测试通过（含新增2个） ✅
> - 对照§6必测场景：§G分页参数场景已覆盖 ✅
>
> **第3项 跨文档一致性抽查：**
> - 本次为纯Bugfix，不涉及文档变更，无跨文档一致性风险 ✅
>
> **第4项 Git提交：**
> - commit: "修复GetList分页page=0报错，增加边界测试"
> - push → ✅ 完成