pdlc-fix

name	pdlc-fix
description	全自动 Bug 修复（定位→复现→修复→测试→文档）
argument-hint	<Bug 描述>
allowed-tools	Read, Write, Edit, Glob, Grep, Bash
layer	1
stage	fix
produces	["docs/04_testing/defects/<defect-id>-defect.md"]
requires	[]
next_step	pdlc-ship
terminal_state	fix_done

全自动 Bug 修复

接收一句话 Bug 描述，全自动完成定位、复现、修复、测试、文档更新，中途不暂停、不询问用户。

执行规则

• 全程自动：不在任何步骤暂停等待确认，遇到歧义自行做合理假设并在最终报告中说明
• 严格顺序：必须按阶段一→二→三→四→五顺序执行，不得跳过
• 最小改动原则：只修复 Bug 本身，不顺手重构或优化不相关代码
• 测试验证才结束：全量测试通过后才输出最终报告

---

---

阶段一：问题定位

1. 根据 Bug 描述，搜索相关代码文件，阅读并理解涉及的逻辑
2. 查阅 docs/02_design/ 对应子目录下的设计文档，确认预期正确行为
3. 明确根因：
   • 是代码逻辑错误、边界未处理、还是设计文档遗漏？
   • 影响范围：哪些模块/接口/数据受影响？
4. 若 Bug 描述不足以定位，根据描述做最合理推断，在报告中说明

阶段二：回归测试（红灯）

1. 编写一个能精确复现该 Bug 的测试用例，写到项目既有的测试布局里（定位规则见下）：

2. 测试命名格式：应该_当<触发条件>时_<预期行为>
3. 运行该测试，确认测试失败（红灯），记录失败输出
4. 若已有相关测试但未覆盖该场景，在原测试文件中追加用例

阶段三：代码修复（绿灯）

1. 用最小改动修复 Bug，不改动与 Bug 无关的代码
2. 运行步骤二编写的回归测试，确认通过（绿灯）
3. 若修复过程中发现设计文档有遗漏或错误，同步更新对应设计文档

阶段四：全量测试验证

1. 运行该服务/应用的完整测试套件，确认没有引入新的失败
2. 若有 E2E 测试，运行相关 E2E 用例验证端到端行为正常
3. 如有测试因本次修复而需要更新（如快照测试、预期值变更），同步更新

阶段五：文档更新与最终报告

⚠️ 必须创建文件，不可仅在对话中输出。 以下每份文档都必须作为实际文件写入磁盘。

1. 更新对应服务的 CHANGELOG.md，在 [未发布] 下新增 fix 条目：
   • 格式：- 修复 <简要描述>（<触发条件>）
2. 若涉及设计文档变更，同步更新 docs/02_design/ 下对应文档
3. 【必须创建文件】 在 docs/04_testing/defects/ 下创建缺陷记录：<缺陷ID>-<功能名>-defect.md
   • 文档顶部必须包含 PDLC 追溯头（格式见下方片段）：

• 记录：根因分析、影响范围、修复方案、回归测试覆盖情况
• 创建后验证：确认文件已存在于 docs/04_testing/defects/ 目录

4. 输出最终报告（同时在对话中显示，但报告内容必须已落盘到上述文件中）：

## Bug 修复报告：<简要描述>（<缺陷ID>）

### 根因分析
<一段话描述根本原因>

### 影响范围
- 涉及文件：
- 涉及接口/功能：

### 修复方案
<描述做了什么改动，为什么这样改>

### 测试结果
- 回归测试：通过
- 全量测试：X 个通过 / 0 个失败

### 文档变更
- CHANGELOG.md：已更新
- 设计文档：已更新 / 无需更新

### 假设与说明
（记录执行过程中自行做出的关键假设）

### 上线前待办
（如有需要人工处理的事项，如数据修复脚本、缓存清理等）

---

产出物清单（每项必须作为文件创建）

产出物	路径	必须
缺陷记录	docs/04_testing/defects/<缺陷ID>-<功能名>-defect.md	✅ 必须
回归测试	对应服务测试目录	✅ 必须
CHANGELOG	对应服务 CHANGELOG.md	✅ 必须
设计文档更新	docs/02_design/ 下对应文档	按需

文件落盘规则：所有带编号（缺陷ID）的文档必须作为实际文件写入，不可仅在对话中显示。最终报告完成前，必须确认上述文件均已创建。

要求

• 只修复 Bug，不做额外优化或重构
• 回归测试用例必须保留在代码库中，不得删除
• 日期使用执行当天实际日期，格式 YYYYMMDD

Bug 描述: $ARGUMENTS