bug-fix

Bug 修复验证

用于验证 Bug 修复的系统化工作流，确保质量并防止回归。

何时使用此技能

在以下情况下使用此技能：

• 修复报告的 Bug
• 为 Bug 修复创建 PR
• 需要记录 Bug 修复验证
• 希望确保修复不会引入回归
• 需要采用结构化的方法解决 Bug

为什么 Bug 修复验证很重要

解决的问题

• ❌ 修复表面症状，而非根本原因
• ❌ 修复旧 Bug 时引入新 Bug
• ❌ 对边缘情况测试不充分
• ❌ 没有证据证明 Bug 确实已修复
• ❌ 修复原因的文档记录不充分

优点

• ✅ 确认 Bug 确实已修复（而非被掩盖）
• ✅ 记录根本原因分析
• ✅ 通过测试防止回归
• ✅ 为相关方提供明确证据
• ✅ 增进团队对代码库的了解

Bug 修复工作流

第 1 步：修复前复现

重要：修复 Bug 前，务必先复现。

复现检查清单

• 记录准确的复现步骤
• 通过截图记录错误消息或行为
• 记录发生频率（100% 可复现、间歇性发生等）
• 如果涉及 UI 或复杂交互，则录制视频
• 确定受影响的版本和环境
• 记录用户找到的任何临时解决方法
• 在干净环境中确认 Bug 存在（而非仅在本地环境中）

复现文档模板

## Bug Reproduction

### Steps to Reproduce
1. Navigate to `/dashboard`
2. Click "Export Data" button
3. Select date range: Jan 1 - Dec 31
4. Click "Generate Report"

### Expected Behavior
- Report downloads as CSV file
- File contains all transactions for date range
- Download completes in < 5 seconds

### Actual Behavior
- Error appears: "Failed to generate report"
- Console error: `TypeError: Cannot read property 'map' of undefined`
- No file downloads
- Issue occurs 100% of the time

### Environment
- Browser: Chrome 120.0.6099.109
- OS: macOS 14.2
- User Role: Admin
- Data Size: ~10,000 transactions

### Screenshots
![Error message](screenshots/export-error.png)
![Console error](screenshots/console-error.png)

第 2 步：根本原因分析

调查 Bug 为什么发生，而不仅仅是发生了什么。

调查步骤

1. 查看错误日志：检查服务日志、浏览器控制台和错误跟踪记录
2. 追踪代码路径：从触发点追踪执行过程，直到出错
3. 找出故障点：找到 Bug 发生的确切代码行或函数
4. 了解上下文：代码为何会如此运行？
5. 检查近期更改：近期提交是否引入了此问题？
6. 查看相关代码：其他地方是否存在类似模式？

根本原因文档

## Root Cause Analysis

### Investigation
- Error occurs in `generateReport()` function at line 45
- Function assumes `transactions` array always exists
- When date range returns no results, backend returns `null`
- Frontend doesn't handle `null` case, tries to call `.map()` on `null`

### Root Cause
- Missing null check before array operations
- Backend API doesn't return consistent data structure (sometimes `[]`, sometimes `null`)
- No validation of API response shape

### Why This Wasn't Caught
- Unit tests only covered happy path (data exists)
- Integration tests didn't test empty result scenario
- Backend inconsistency not documented in API contract

第 3 步：实施修复

修复根本原因，而非表面症状。

修复指南

• 尽量减少更改：只修复必要的部分
• 防御式编码：添加验证或保护逻辑
• 保持模式一致：遵循现有的错误处理模式
• 类型安全：使用类型防止类似 Bug
• 添加文档：为不明显的修复添加注释

修复示例

// BEFORE (Bug)
function generateReport(transactions) {
  return transactions.map(t => ({
    date: t.date,
    amount: t.amount,
  }));
}

// AFTER (Fixed)
function generateReport(transactions) {
  // Guard against null/undefined from backend
  if (!transactions || !Array.isArray(transactions)) {
    console.warn('No transactions to export');
    return [];
  }

  return transactions.map(t => ({
    date: t.date,
    amount: t.amount,
  }));
}

第 4 步：验证修复

通过系统化测试证明 Bug 已修复。

验证检查清单

• 按照相同的复现步骤操作
• 确认 Bug 不再发生
• 测试修复涉及的边缘情况
• 确认未引入新错误
• 检查修复在不同环境（开发、预发布）中是否有效
• 验证修复符合预期行为

验证文档

## Fix Verification

### Testing Performed
1. ✅ Followed original reproduction steps - bug no longer occurs
2. ✅ Tested with empty date range - shows "No data to export" message
3. ✅ Tested with valid date range - exports successfully
4. ✅ Tested with large dataset (50k+ transactions) - works correctly
5. ✅ Tested in Chrome, Firefox, Safari - all working
6. ✅ Tested on staging environment - fix confirmed

### Edge Cases Tested
- Empty result set → Shows appropriate message
- Null response from API → Handled gracefully
- Single transaction → Exports correctly
- Malformed transaction data → Logs error, doesn't crash

### No New Issues
- ✅ No console errors
- ✅ No memory leaks
- ✅ No performance degradation
- ✅ Other export features still work

第 5 步：添加测试以防止回归

重要：每项 Bug 修复都必须包含测试。

测试要求

• 添加可复现原始 Bug 的测试（修复后应通过）
• 添加调查过程中发现的边缘情况测试
• 如果 Bug 涉及多个组件，则添加集成测试
• 如果现有测试需要处理新的场景，则更新这些测试

测试示例

describe('generateReport', () => {
  // Test that reproduces original bug
  it('should handle null transactions gracefully', () => {
    const result = generateReport(null);
    expect(result).toEqual([]);
    expect(console.warn).toHaveBeenCalledWith('No transactions to export');
  });

  // Edge cases
  it('should handle undefined transactions', () => {
    const result = generateReport(undefined);
    expect(result).toEqual([]);
  });

  it('should handle empty array', () => {
    const result = generateReport([]);
    expect(result).toEqual([]);
  });

  it('should handle single transaction', () => {
    const transactions = [{ date: '2025-01-01', amount: 100 }];
    const result = generateReport(transactions);
    expect(result).toHaveLength(1);
    expect(result[0]).toEqual({ date: '2025-01-01', amount: 100 });
  });

  // Original happy path (should still work)
  it('should transform multiple transactions correctly', () => {
    const transactions = [
      { date: '2025-01-01', amount: 100 },
      { date: '2025-01-02', amount: 200 },
    ];
    const result = generateReport(transactions);
    expect(result).toHaveLength(2);
  });
});

第 6 步：在 PR 中记录

为 Bug 修复编写全面的 PR 描述。

Bug 修复 PR 模板

## Bug Fix: [Brief Description]

**Ticket**: #123 / ENG-456 / JIRA-789

### Problem
[Clear description of the bug]

### Reproduction Steps (Before Fix)
1. [Step 1]
2. [Step 2]
3. [Error occurs]

**Expected**: [What should happen]
**Actual**: [What happened instead]

### Root Cause
[Detailed explanation of why bug occurred]

- Where: `src/utils/report.ts`, line 45
- Why: Null check missing before array operation
- Impact: Affects all users trying to export with empty date ranges

### Solution
[Explanation of how fix works]

- Added null/undefined check before array operations
- Return empty array instead of crashing
- Added user-facing warning message
- Updated API response handling to be more defensive

### Fix Verification (After)
1. ✅ Followed reproduction steps - bug no longer occurs
2. ✅ Tested edge cases (null, undefined, empty array)
3. ✅ Tested across browsers (Chrome, Firefox, Safari)
4. ✅ Verified on staging environment
5. ✅ No new console errors or warnings

### Test Coverage
- Added unit tests for null/undefined handling
- Added tests for empty array edge case
- Updated integration tests for export feature
- All existing tests still passing

**Coverage**: +15 lines covered, 0 lines uncovered

### Regression Prevention
- [x] Tests added that would catch this bug if reintroduced
- [x] Similar patterns checked in codebase (found 2, fixed in this PR)
- [x] Documentation updated to note API response inconsistency

### Screenshots/Evidence
**Before (Bug)**:
![Error state](screenshots/before-error.png)

**After (Fixed)**:
![Success state](screenshots/after-success.png)
![Empty state](screenshots/after-empty.png)

### Deployment Notes
- No migrations required
- No environment variable changes
- Safe to deploy immediately
- Rollback: Revert this commit

### Related Issues
- Closes #123
- Related to #456 (similar null handling issue)

应避免的常见陷阱

调查期间

• ❌ 未经验证就认定自己知道原因
• ❌ 修复表面症状，而非根本原因
• ❌ 未检查其他地方是否存在类似 Bug
• ❌ 跳过在干净环境中的复现

实施期间

• ❌ 进行超出 Bug 修复范围的更改
• ❌ 在 Bug 修复 PR 中重构无关代码
• ❌ 修复 Bug 时添加功能
• ❌ 未处理发现的所有边缘情况

验证期间

• ❌ 修复后只测试正常流程
• ❌ 未在多个环境中测试
• ❌ 跳过回归测试
• ❌ 未记录已测试的内容

编写文档时

• ❌ PR 描述含糊（“修复了 bug”）
• ❌ 未说明根本原因
• ❌ 缺少修复前后的证据
• ❌ 未链接到原始 bug 报告

Bug 修复质量标准

最低要求

• ✅ 已识别并记录根本原因
• ✅ 修复精简且有针对性
• ✅ 已添加测试以防止回归
• ✅ 已通过证据记录验证过程
• ✅ 未引入新 bug
• ✅ 在所有受支持的环境中均可运行

卓越指标

• ✅ 已检查并修复类似模式
• ✅ 已测试多种边缘情况
• ✅ 已衡量性能影响
• ✅ 已共享团队知识（更新 wiki/文档）
• ✅ 已提出预防措施建议

自动化支持

Bug 修复 PR 模板

创建 .github/PULL_REQUEST_TEMPLATE/bug_fix.md：

## Bug Fix

**Ticket**: [Ticket number/link]

### Problem
[Description of bug]

### Reproduction Steps (Before Fix)
1.
2.
3.

**Expected**:
**Actual**:

### Root Cause
[Explanation of why bug occurred]

### Solution
[How fix works]

### Verification (After)
- [ ] Original reproduction steps no longer trigger bug
- [ ] Edge cases tested
- [ ] Tested in multiple browsers/environments
- [ ] No new errors or warnings

### Test Coverage
- [ ] Tests added for bug scenario
- [ ] Tests added for edge cases
- [ ] All existing tests passing

### Screenshots
**Before**: [Screenshot]
**After**: [Screenshot]

用于 Bug 修复 PR 的 GitHub Actions

name: Bug Fix Verification
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  verify-bug-fix:
    if: contains(github.event.pull_request.labels.*.name, 'bug')
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check PR description
        run: |
          PR_BODY="${{ github.event.pull_request.body }}"
          if [[ ! "$PR_BODY" =~ "Root Cause" ]]; then
            echo "::error::Bug fix PR must document root cause"
            exit 1
          fi
          if [[ ! "$PR_BODY" =~ "Verification" ]]; then
            echo "::error::Bug fix PR must document verification steps"
            exit 1
          fi

      - name: Run tests
        run: npm test

      - name: Check test coverage
        run: |
          COVERAGE=$(npm test -- --coverage --json | jq '.total.lines.pct')
          if (( $(echo "$COVERAGE < 90" | bc -l) )); then
            echo "::warning::Test coverage is below 90%"
          fi

成功标准

满足以下条件时，Bug 修复即告完成

• ✅ 无法再复现该 bug
• ✅ 已了解并记录根本原因
• ✅ 修复精简且有针对性
• ✅ 测试可防止回归
• ✅ 已处理边缘情况
• ✅ 在所有环境中均可运行
• ✅ PR 文档详尽
• ✅ 未引入新问题

相关技能

• universal-verification-pre-merge - 合并前验证清单
• universal-verification-screenshot - UI bug 的视觉验证
• universal-debugging-systematic-debugging - 系统化调试方法
• universal-debugging-root-cause-tracing - 根本原因分析技术
• universal-testing-testing-anti-patterns - 应避免的测试模式