Bugfix 任务模板：日志、复现、补丁、回归测试四段式

┌──────────────┐    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│  第一段：日志  │───▶│  第二段：复现  │───▶│  第三段：补丁  │───▶│  第四段：回归  │
│  采集与分析    │    │  脚本与数据    │    │  最小化修改    │    │  测试与验收    │
└──────────────┘    └──────────────┘    └──────────────┘    └──────────────┘
       │                   │                   │                   │
  输出：                输出：                输出：                输出：
  · 错误堆栈           · repro.py           · diff.patch         · test_report.json
  · 影响范围           · fixture data        · 修改说明           · 覆盖率报告
  · 候选文件           · 预期 vs 实际        · 关联测试           · 验收结论

# bugfix-phase1-log-collection.yaml
name: Bugfix-Phase1-日志采集
version: "1.0"
description: 从错误报告和日志中采集完整的缺陷信息

inputs:
  issue_url:       # Issue 链接或错误报告
  log_source:      # 日志来源：文件路径 / ELK / CloudWatch
  time_range:      # 日志时间范围
  service_name:    # 服务名（微服务场景）

prompt: |
  你是一个缺陷分析专家。请根据以下信息完成日志采集：

  ## 已知信息
  - Issue：{{issue_url}}
  - 日志来源：{{log_source}}
  - 时间范围：{{time_range}}
  - 服务：{{service_name}}

  ## 任务
  1. 提取完整的错误堆栈（不要截断）
  2. 识别错误类型（NullPointerException / TimeoutError / DataError / ...）
  3. 标注错误发生的代码路径（文件:行号）
  4. 列出可能相关的上下文日志（错误前后 30 秒）
  5. 给出候选文件列表（最可能包含 Bug 的文件，按可能性排序）

  ## 输出格式
  严格按以下 JSON 输出：
  ```json
  {
    "error_type": "",
    "error_message": "",
    "stack_trace": "",
    "code_path": ["file:line", ...],
    "context_logs": ["..."],
    "candidate_files": [{"path": "", "reason": "", "confidence": 0.0}],
    "impact_scope": {"affected_modules": [], "affected_users": "unknown"}
  }

### 3.2 日志采集示例输出

```json
{
  "error_type": "DataError",
  "error_message": "Cannot read property 'amount' of undefined at OrderService.calculateTotal",
  "stack_trace": "TypeError: Cannot read property 'amount' of undefined\n  at OrderService.calculateTotal (src/services/order.js:142)\n  at OrderController.checkout (src/controllers/order.js:58)",
  "code_path": ["src/services/order.js:142", "src/controllers/order.js:58"],
  "candidate_files": [
    {"path": "src/services/order.js", "reason": "直接报错位置，order.items 为 undefined", "confidence": 0.85},
    {"path": "src/controllers/order.js", "reason": "调用方，可能传入了不完整的 order 对象", "confidence": 0.45}
  ],
  "impact_scope": {"affected_modules": ["order", "checkout"], "affected_users": "unknown"}
}

# bugfix-phase2-reproduction.yaml
name: Bugfix-Phase2-稳定复现
version: "1.0"

inputs:
  phase1_output:    # 第一段输出
  repo_path:        # 仓库路径
  test_env:         # 测试环境配置

prompt: |
  你是一个测试工程师。根据第一段的日志分析结果，编写稳定的复现脚本。

  ## 错误信息
  {{phase1_output.error_message}}

  ## 候选文件
  {{phase1_output.candidate_files | map('path') | join(', ')}}

  ## 任务
  1. 编写最小复现脚本（Python 或 Shell），不依赖生产数据库
  2. 准备 fixture 数据（JSON 格式），模拟触发 Bug 的输入
  3. 断言"错误情况"（当前行为）和"期望情况"（修复后行为）
  4. 脚本必须能在本地 30 秒内运行完成

  ## 输出
  - tests/reproduce/test_bug_<issue_id>.py
  - tests/reproduce/fixtures/<issue_id>.json
  - 复现命令：pytest tests/reproduce/test_bug_<issue_id>.py -v

# tests/reproduce/test_bug_1234.py
"""
Issue: #1234 订单结算时 amount 为 undefined 导致 500
复现条件：订单包含已下架商品时，items 字段被过滤为空数组
"""
import pytest
from src.services.order import OrderService

def test_calculate_total_with_empty_items():
    """复现：当 order.items 为空时，calculateTotal 应返回 0 而非抛异常"""
    service = OrderService()

    # 模拟已下架商品被过滤后的订单
    order = {
        "id": "ORD-1234",
        "items": [],  # 根因：items 被过滤后为空，但代码假设 items[0] 存在
        "coupon": None,
    }

    # 当前行为：抛出 TypeError
    # 期望行为：返回 total = 0
    result = service.calculate_total(order)
    assert result == {"total": 0, "item_count": 0}

def test_calculate_total_with_none_items():
    """边界：items 字段缺失时不应崩溃"""
    service = OrderService()
    order = {"id": "ORD-1235", "coupon": None}

    result = service.calculate_total(order)
    assert result == {"total": 0, "item_count": 0}

# bugfix-phase3-patch.yaml
name: Bugfix-Phase3-最小补丁
version: "1.0"

inputs:
  phase1_output:    # 日志分析结果
  phase2_output:    # 复现脚本路径
  repo_path:        # 仓库路径

prompt: |
  你是一个高级开发者。根据日志分析和复现脚本，编写最小化补丁。

  ## 约束
  1. 只修改根因相关代码，不做"顺便重构"
  2. 修改行数不超过 20 行（如果超过，说明你没有找到根因）
  3. 必须在修改前阅读相关代码的完整上下文（前后 50 行）
  4. 每次修改必须附带注释说明"为什么这样改"

  ## 修改流程
  1. 阅读候选文件，确认根因位置
  2. 用 grep 搜索相同模式是否在其他地方也存在
  3. 编写修复代码
  4. 运行复现测试，确认通过
  5. 运行相关模块的完整测试套件，确认无回归

  ## 输出
  - 修改的文件列表和 diff
  - 修改说明（每个文件改了什么、为什么）
  - 测试运行结果

{
  "patch_id": "PATCH-1234-001",
  "issue_id": "#1234",
  "root_cause": "OrderService.calculateTotal() 假设 order.items 非空，直接访问 items[0].amount，当 items 为空数组时抛出 TypeError",
  "files_changed": [
    {
      "path": "src/services/order.js",
      "lines_added": 3,
      "lines_removed": 1,
      "change_summary": "在访问 items[0] 前增加空数组检查，items 为空时直接返回 total=0"
    }
  ],
  "total_lines_changed": 4,
  "tests_added": ["tests/reproduce/test_bug_1234.py"],
  "tests_passed": 12,
  "tests_failed": 0,
  "side_effects_checked": [
    {"file": "src/services/refund.js", "reason": "相同模式，已检查，无此问题"},
    {"file": "src/services/shipping.js", "reason": "相同模式，已修复"}
  ],
  "verification_command": "pytest tests/reproduce/test_bug_1234.py tests/services/test_order.py -v"
}

# bugfix-phase4-regression.yaml
name: Bugfix-Phase4-回归验收
version: "1.0"

inputs:
  phase3_output:    # 补丁结果
  repo_path:        # 仓库路径

prompt: |
  你是一个 QA 工程师。验证补丁的正确性和完整性。

  ## 验收清单
  1. 复现测试是否通过（证明 Bug 已修复）
  2. 相关模块测试是否全部通过（证明没有引入回归）
  3. 边界条件是否覆盖（空值、null、极端输入）
  4. 相同模式的代码是否都已修复（grep 搜索结果）
  5. 代码变更是否在 20 行以内（超过需重新评估方案）

  ## 输出格式
  严格按以下 JSON 输出验收报告：
  ```json
  {
    "verdict": "PASS | FAIL | CONDITIONAL_PASS",
    "bug_fixed": true,
    "regression_found": false,
    "coverage_delta": "+0.3%",
    "checks": [...],
    "recommendation": "可以合并 | 需要补充 | 需要重做"
  }

### 6.2 验收报告示例

```json
{
  "verdict": "PASS",
  "bug_fixed": true,
  "regression_found": false,
  "coverage_delta": "+0.3%",
  "checks": [
    {"name": "复现测试通过", "status": "PASS", "detail": "test_bug_1234.py 2/2 通过"},
    {"name": "模块测试通过", "status": "PASS", "detail": "test_order.py 12/12 通过"},
    {"name": "边界条件覆盖", "status": "PASS", "detail": "空数组、null、缺失字段均已覆盖"},
    {"name": "同模式扫描", "status": "PASS", "detail": "refund.js 和 shipping.js 已修复"},
    {"name": "变更行数", "status": "PASS", "detail": "共修改 4 行，低于 20 行阈值"}
  ],
  "recommendation": "可以合并"
}