Bug 分级处理与最小修复流程

这份文档用于处理已有上位机项目中的问题。

核心原则不是“所有 Bug 都先调查一大圈”，而是先分级：小问题直接最小修改，明确问题快速修，疑难问题再做完整调查。

1. 先判断问题等级

等级	适合情况	处理方式	是否需要完整调查
L1 直接小改	文案、按钮位置、简单样式、明显错别字、简单空值判断、编译报错位置明确	直接改，做最便宜验证	不需要
L2 快速修复	根因基本明确，例如绑定字段名错、按钮事件漏接、路径写错、配置读取错	看相关代码，做最小修复	不需要完整调查
L3 普通 Bug	现象明确但根因不完全确定，例如数据不刷新、保存结果不对、某流程偶发失败	先做小范围分析，再修复	需要轻量调查
L4 疑难 Bug	通信数据不对、协议解析异常、偶发丢包、现场才复现、数据和设备返回不一致	先调查根因，建立证据链	需要完整调查
L5 高风险问题	涉及真实设备动作、数据库结构、线程模型、协议语义、生产交付、长时间运行	先方案、风险、验证计划，再动代码	必须完整流程

简单判断：

1. 看一眼就知道怎么改的，不要绕一大圈。
2. 根因基本明确的，直接最小修复。
3. 涉及通信、协议、数据正确性、线程、现场偶发的，先调查。
4. 涉及真实设备、数据库、发布交付的，按高风险处理。

2. 不同等级怎么问 AI

L1：直接小改

适合：按钮文字、控件位置、简单布局、明显编译错误、简单显示问题。

这是一个低风险小改，请直接做最小修改，不要做完整 Bug 调查，不要重构。

问题：
【例如：主界面按钮文字显示不对 / 某个按钮位置偏了 / 编译提示某个字段不存在】

期望：
【改成什么样】

要求：
1. 只改必要位置。
2. 不扩大范围。
3. 改完说明怎么验证。

L2：快速修复

适合：根因大致知道，但需要 AI 看相关代码确认。

这是一个根因基本明确的小 Bug，请走快速修复，不要走完整调查流程。

问题现象：
可能原因：
相关截图/代码/报错：
期望行为：

请输出：
1. 最可能需要修改的位置。
2. 最小修复方案。
3. 可能影响范围。
4. 最便宜验证方式。

L3：轻量调查后修复

适合：现象明确，但还不能直接定位。

这是一个普通 Bug，请先做轻量分析，再给最小修复方案。

问题现象：
复现步骤：
出现频率：
最近改动：
截图/日志/相关材料：
期望行为：
实际行为：

请先输出：
1. 可能原因排序。
2. 最需要查看的 3-5 个点。
3. 是否可以直接修复。
4. 如果可以，给最小修复方案。
5. 如果不可以，告诉我还需要补充哪些材料。

L4：疑难 Bug 调查

适合：通信、协议、数据不一致、偶发、现场才出现的问题。

这是一个疑难 Bug，请先只调查根因，不要修改代码。

问题现象：
设备实际返回/上传的数据：
软件显示或保存的数据：
通信日志：
协议说明：
复现步骤：
出现频率：
最近改动：

请输出：
1. 事件时间线。
2. 数据从接收、缓存、解析、业务处理、显示/保存的链路。
3. 哪一步最可能出错。
4. 证据是什么。
5. 需要补充哪些日志或代码。
6. 最小复现和验证方法。

L5：高风险问题

适合：设备动作、数据库、线程、协议语义、正式交付。

这是一个高风险问题。请先不要修改代码。

请先输出：
1. 风险等级判断。
2. 可能影响的设备动作、数据、通信、线程、数据库或交付项。
3. 调查计划。
4. 修复方案候选。
5. 每个方案的风险。
6. 必须做的回归测试和验收项。

3. Bug 信息收集表

不是每个等级都要填满。L1/L2 只填必要信息；L4/L5 尽量补完整。

项目项	填写内容
问题等级	L1 / L2 / L3 / L4 / L5 / 不确定
问题现象	用户看到的具体问题
期望行为	正常情况下应该怎样
实际行为	现在实际发生了什么
复现步骤	能复现就写，不能复现写“不稳定”
出现频率	必现 / 偶发 / 运行一段时间后出现 / 现场才出现
影响范围	UI / 通信 / 数据保存 / 报警 / 设备动作 / 不确定
最近改动	最近改过哪些功能、配置或环境
相关材料	截图、日志、报错、协议、示例数据；知道文件名再写文件名
验证方式	修好后怎么确认

4. 什么时候必须调查

以下情况不要直接改：

1. 软件显示的数据和设备上传的数据不一致。
2. 解析结果和协议文档对不上。
3. 偶发丢包、粘包半包、CRC 错误。
4. 程序运行一段时间后才出问题。
5. 现场环境才复现。
6. 涉及数据库、线程、通信状态机。
7. 涉及真实设备动作或生产数据。

这些问题要先看链路：接收 -> 缓存 -> 解析 -> 业务处理 -> 显示/保存 -> 日志。

5. 最小修复原则

无论哪个等级，修复时都遵守：

1. 不顺手重构。
2. 不扩大修改范围。
3. 不改无关文件。
4. 不直接推翻原结构。
5. 每次只解决一个明确问题。
6. 修改后必须给验证方法。

6. 修复后验证

验证项	L1/L2	L3	L4/L5
编译验证	必做	必做	必做
原问题验证	必做	必做	必做
相关功能回归	简单检查	聚焦检查	系统检查
异常路径验证	可选	按需	必做
日志/数据链路验证	可选	按需	必做
长时间/现场验证	不需要	按需	按需求或交付要求

7. 修复后必须说明

1. 问题等级。
2. 为什么选择这个处理路径。
3. 改了什么。
4. 没改什么。
5. 怎么验证。
6. 还有什么残余风险。