问题排查修复流程

⚠️ 强制规则

1. 举一反三：修复后必须扫描同类问题，防止同类bug重复出现
2. 测试补全：bug修复后必须补充测试用例，防止回归
3. 经验归档：必须写入 .learnings/LEARNINGS.md
4. UI双测：涉及UI的问题必须同时执行API+UI测试
5. 按需测试：只执行受影响模块的自动化测试用例，不全量执行

📋 流程（按顺序执行）

1. 接收问题

记录现象、影响范围、严重等级

2. 5Why根因分析

Why1: 为什么发生？
Why2: 为什么导致问题？
Why3: 为什么这样设计？
Why4: 为什么测试没发现？
Why5: (根因) 为什么存在？

3. 举一反三扫描

| 问题类型 | 扫描范围 |

|---------|---------|

| Model缺字段 | 所有Model的fillable |

| API验证缺失 | 所有POST/PUT的validate |

| 前端显示错 | 所有列表页列显示 |

| 权限控制缺失 | 权限中间件和路由 |

4. 需求分析

结合PRD/Spec分析期望行为，制定修复策略。如有需求文档必须同步更新

5. 测试用例同步

根据修复方案补充/更新测试用例，自动化脚本同步更新

6. 代码修复

按修复策略进行精准定位、最小改动

7. 代码影响分析

分析代码改动影响的模块，列出测试执行范围：

| 改动类型 | 影响模块 | 测试范围 |

|---------|---------|---------|

| Model修改 | Model层 | 影响Model的API测试 |

| Controller修改 | Controller层 | 该Controller的API测试 |

| Service修改 | Service层 | 调用该Service的API测试 |

| 前端组件修改 | 前端模块 | 该组件的E2E测试 |

| 中间件修改 | 权限/认证 | 相关API测试+涉及该中间件的E2E |

| 数据库迁移 | 数据层 | 写入相关API测试 |

8. 按需测试

基于步骤7的分析结果，执行指定范围的测试用例：

# API测试（按模块指定）
pytest tests/api/xxx/ -v

# UI测试（按页面/功能指定）
pytest tests/e2e/xxx/ -v

9. 循环修复

测试发现新问题 → 返回步骤2 → 修复 → 再测试 → 直到全通过

10. 经验归档

复盘根因，写入 .learnings/LEARNINGS.md

✅ 完成标准

• [ ] 5Why根因分析完成
• [ ] 举一反三扫描完成
• [ ] 测试用例已补充/更新
• [ ] 代码修复完成
• [ ] 代码影响分析完成（列出影响模块）
• [ ] API测试通过（按需执行）
• [ ] UI测试通过（按需执行，仅UI问题）
• [ ] 经验已归档

📝 经验归档模板

## [LRN-YYYYMMDD-XXX]

**Logged**: YYYY-MM-DD | **Status**: resolved
**UI-Involved**: yes/no

### Summary
问题+解决方案（一句话）

### Root Cause (5Why)
- Why1-4: ...
- Why5(根因): ...

### Same-Type Issues Found
- 列出发现的同类问题

### Code Impact Analysis
- 影响模块：xxx
- 测试范围：tests/api/xxx/, tests/e2e/xxx/

### Test Added
- API: tests/api/xxx/test_xxx.py::test_xxx
- UI: tests/e2e/xxx/test_xxx.py::test_xxx (如涉及)