You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
haoliang-net/docs/05-修改请求预处理协议.md

397 lines
17 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 修改请求预处理协议
> 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 → ✅ 完成