bug-fix

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bug Fix Verification

Bug修复验证

Systematic workflow for verifying bug fixes to ensure quality and prevent regressions.

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

When to Use This Skill

何时使用此技能

Use this skill when:

Fixing a reported bug
Creating PR for bug fix
Need to document bug fix verification
Want to ensure fix doesn't introduce regressions
Need structured approach to bug resolution

在以下场景使用此技能：

修复已上报的bug
为bug修复创建PR
需要记录bug修复验证过程
希望确保修复不会引入回归问题
需要结构化的bug解决方法

Why Bug Fix Verification Matters

Bug修复验证的重要性

Problems It Solves

解决的问题

❌ Fixing symptoms instead of root cause
❌ Introducing new bugs while fixing old ones
❌ Incomplete testing of edge cases
❌ No proof that bug is actually fixed
❌ Poor documentation of fix reasoning

❌ 只修复症状而非根本原因
❌ 修复旧bug时引入新bug
❌ 未完整测试边缘情况
❌ 没有证据证明bug已实际修复
❌ 修复理由的文档记录不完善

Benefits

带来的好处

✅ Confirms bug is truly fixed (not masked)
✅ Documents root cause analysis
✅ Prevents regression with tests
✅ Provides clear evidence for stakeholders
✅ Improves team knowledge of codebase

✅ 确认bug已真正修复（而非被掩盖）
✅ 记录根本原因分析过程
✅ 通过测试防止回归问题
✅ 为利益相关者提供清晰的证据
✅ 提升团队对代码库的了解

Bug Fix Workflow

Bug修复工作流

Step 1: Reproduce Before Fix

步骤1：修复前复现bug

Critical: Never fix a bug without first reproducing it.

关键：在修复bug之前，必须先复现它。

Reproduction Checklist

复现检查清单

Reproduction Documentation Template

复现文档模板

markdown

undefined

markdown

undefined

Bug Reproduction

Bug复现

Steps to Reproduce

复现步骤

Navigate to
```
/dashboard
```
Click "Export Data" button
Select date range: Jan 1 - Dec 31
Click "Generate Report"

导航至
```
/dashboard
```
点击"导出数据"按钮
选择日期范围：1月1日 - 12月31日
点击"生成报告"

Expected Behavior

预期行为

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

报告以CSV文件形式下载
文件包含所选日期范围内的所有交易记录
下载完成时间<5秒

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

出现错误提示："Failed to generate report"

控制台错误：

TypeError: Cannot read property 'map' of undefined

无文件下载
问题100%可复现

Environment

环境

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

浏览器：Chrome 120.0.6099.109
操作系统：macOS 14.2
用户角色：管理员
数据量：约10,000条交易记录

Screenshots

截图

undefined

undefined

Step 2: Root Cause Analysis

步骤2：根本原因分析

Investigate WHY the bug occurs, not just WHAT happens.

调查bug发生的原因，而非仅仅是发生了什么。

Investigation Steps

调查步骤

Review Error Logs: Check server logs, browser console, error tracking
Trace Code Path: Follow execution from trigger point to error
Identify Breaking Point: Find exact line/function where bug occurs
Understand Context: Why does code behave this way?
Check Recent Changes: Did recent commit introduce this?
Review Related Code: Are there similar patterns elsewhere?

查看错误日志：检查服务器日志、浏览器控制台、错误追踪系统
追踪代码路径：从触发点到错误发生处跟踪执行流程
确定断点：找到bug发生的确切代码行/函数
理解上下文：代码为何会有这样的行为？
检查近期变更：是否是最近的提交引入了这个问题？
查看相关代码：其他地方是否有类似的模式？

Root Cause Documentation

根本原因文档

markdown

undefined

markdown

undefined

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
```

错误发生在
```
generateReport()
```
函数的第45行
函数假设
```
transactions
```
数组始终存在
当日期范围无结果时，后端返回
```
null
```
前端未处理
```
null
```
情况，尝试对
```
null
```
调用
```
.map()
```
方法

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

数组操作前缺少空值检查
后端API返回的数据结构不一致（有时返回
```
[]
```
，有时返回
```
null
```
）
未验证API响应的格式

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

undefined

单元测试仅覆盖了正常路径（存在数据的情况）
集成测试未测试空结果场景
API契约中未记录后端的不一致性

undefined

Step 3: Implement Fix

步骤3：实施修复

Fix the root cause, not the symptom.

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

Fix Guidelines

修复准则

Minimal Change: Fix only what's necessary
Defensive Coding: Add validation/guards
Consistent Patterns: Follow existing error handling patterns
Type Safety: Use types to prevent similar bugs
Documentation: Comment non-obvious fixes

最小变更：仅修复必要的部分
防御性编码：添加验证/保护机制
一致模式：遵循现有的错误处理模式
类型安全：使用类型防止类似bug
文档记录：对不明显的修复添加注释

Example Fix

修复示例

typescript

// 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,
  }));
}

typescript

// 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,
  }));
}

Step 4: Verify Fix

步骤4：验证修复

Prove the bug is fixed through systematic testing.

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

Verification Checklist

验证检查清单

Verification Documentation

验证文档

markdown

undefined

markdown

undefined

Fix Verification

修复验证

Testing Performed

执行的测试

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

✅ 遵循原始复现步骤 - bug不再出现
✅ 测试空日期范围 - 显示“No data to export”提示
✅ 测试有效日期范围 - 导出成功
✅ 测试大数据集（50,000+条交易记录） - 运行正常
✅ 在Chrome、Firefox、Safari中测试 - 均正常工作
✅ 在staging环境中测试 - 修复已确认

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

空结果集 → 显示相应提示
API返回Null → 被优雅处理
单条交易记录 → 导出正常
格式错误的交易数据 → 记录错误，不崩溃

No New Issues

无新问题

✅ No console errors
✅ No memory leaks
✅ No performance degradation
✅ Other export features still work

undefined

✅ 无控制台错误
✅ 无内存泄漏
✅ 无性能下降
✅ 其他导出功能仍正常工作

undefined

Step 5: Add Tests to Prevent Regression

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

Critical: Every bug fix must include tests.

关键：每个bug修复都必须包含测试。

Test Requirements

测试要求

Test that reproduces original bug (should pass after fix)
Tests for edge cases discovered during investigation
Integration test if bug involved multiple components
Update existing tests if they need to handle new scenarios

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

Example Tests

测试示例

typescript

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);
  });
});

typescript

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);
  });
});

Step 6: Document in PR

步骤6：在PR中记录

Comprehensive PR description for bug fixes.

bug修复的全面PR描述。

PR Template for Bug Fixes

bug修复PR模板

markdown

undefined

markdown

undefined

Bug Fix: [Brief Description]

Bug修复：[简要描述]

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

工单：#123 / ENG-456 / JIRA-789

Problem

问题

[Clear description of the bug]

[bug的清晰描述]

Reproduction Steps (Before Fix)

修复前的复现步骤

[Step 1]
[Step 2]
[Error occurs]

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

[步骤1]
[步骤2]
[错误发生]

预期：[应该发生的情况] 实际：[实际发生的情况]

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

[bug发生原因的详细解释]

位置：
```
src/utils/report.ts
```
，第45行
原因：数组操作前缺少空值检查
影响：所有尝试导出空日期范围的用户都会受影响

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

[修复工作的解释]

在数组操作前添加了null/undefined检查
返回空数组而非崩溃
添加了面向用户的警告提示
更新了API响应处理，使其更具防御性

Fix Verification (After)

修复后验证

✅ Followed reproduction steps - bug no longer occurs
✅ Tested edge cases (null, undefined, empty array)
✅ Tested across browsers (Chrome, Firefox, Safari)
✅ Verified on staging environment
✅ No new console errors or warnings

✅ 遵循复现步骤 - bug不再出现
✅ 测试了边缘情况（null、undefined、空数组）
✅ 在多浏览器（Chrome、Firefox、Safari）中测试
✅ 在staging环境中验证
✅ 无新的控制台错误或警告

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

添加了处理null/undefined的单元测试
添加了空数组边缘情况的测试
更新了导出功能的集成测试
所有现有测试仍通过

覆盖率：新增15行覆盖代码，0行未覆盖

Regression Prevention

回归预防

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

添加了测试，若问题再次出现可被捕获
检查了代码库中的类似模式（发现2处，在此PR中修复）
更新文档以记录API响应的不一致性

Screenshots/Evidence

截图/证据

Before (Bug): Error state

After (Fixed): Success state

修复前（bug状态）： Error state

修复后（正常状态）： Success state

Deployment Notes

部署说明

No migrations required
No environment variable changes
Safe to deploy immediately
Rollback: Revert this commit

无需迁移
无需更改环境变量
可立即安全部署
回滚：撤销此提交

Related Issues

Common Pitfalls to Avoid

需避免的常见陷阱

During Investigation

调查阶段

❌ Assuming you know the cause without verifying
❌ Fixing symptoms instead of root cause
❌ Not checking if similar bugs exist elsewhere
❌ Skipping reproduction in clean environment

❌ 未验证就假设知道原因
❌ 修复症状而非根本原因
❌ 未检查其他地方是否存在类似bug
❌ 跳过在干净环境中复现的步骤

During Implementation

实施阶段

❌ Making changes beyond fixing the bug
❌ Refactoring unrelated code in bug fix PR
❌ Adding features while fixing bugs
❌ Not handling all edge cases discovered

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

During Verification

验证阶段

❌ Only testing happy path after fix
❌ Not testing in multiple environments
❌ Skipping regression testing
❌ Not documenting what was tested

❌ 仅测试修复后的正常路径
❌ 未在多环境中测试
❌ 跳过回归测试
❌ 未记录测试内容

During Documentation

文档阶段

❌ Vague PR descriptions ("Fixed bug")
❌ Not explaining root cause
❌ Missing before/after evidence
❌ Not linking to original bug report

❌ PR描述模糊（如"Fixed bug"）
❌ 未解释根本原因
❌ 缺少修复前后的证据
❌ 未链接到原始bug报告

Bug Fix Quality Standards

Bug修复质量标准

Minimum Requirements

最低要求

✅ Root cause identified and documented
✅ Fix is minimal and targeted
✅ Tests added to prevent regression
✅ Verification documented with evidence
✅ No new bugs introduced
✅ Works across all supported environments

✅ 已识别并记录根本原因
✅ 修复最小且针对性强
✅ 添加了防止回归的测试
✅ 验证过程有证据记录
✅ 未引入新bug
✅ 在所有支持的环境中正常工作

Excellence Indicators

优秀指标

✅ Similar patterns checked and fixed
✅ Multiple edge cases tested
✅ Performance impact measured
✅ Team knowledge shared (wiki/docs updated)
✅ Preventive measures suggested

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

Automation Support

自动化支持

Bug Fix PR Template

Bug修复PR模板

Create

.github/PULL_REQUEST_TEMPLATE/bug_fix.md

markdown

undefined

创建

.github/PULL_REQUEST_TEMPLATE/bug_fix.md

：

markdown

undefined

Bug Fix

Bug修复

Ticket: [Ticket number/link]

工单：[工单号/链接]

Problem

问题

[Description of bug]

[bug的描述]

Reproduction Steps (Before Fix)

修复前的复现步骤

Expected: Actual:

预期：实际：

Root Cause

根本原因

[Explanation of why bug occurred]

[bug发生原因的解释]

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

原始复现步骤不再触发bug
测试了边缘情况
在多浏览器/环境中测试
无新错误或警告

Test Coverage

测试覆盖率

Screenshots

截图

Before: [Screenshot] After: [Screenshot]

undefined

修复前：[截图] 修复后：[截图]

undefined

GitHub Actions for Bug Fix PRs

GitHub Actions用于bug修复PR

yaml

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

yaml

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

Success Criteria

成功标准

Bug Fix is Complete When

Bug修复完成的标志

✅ Bug can no longer be reproduced
✅ Root cause is understood and documented
✅ Fix is minimal and targeted
✅ Tests prevent regression
✅ Edge cases are handled
✅ Works in all environments
✅ PR documentation is comprehensive
✅ No new issues introduced

✅ 无法再复现bug
✅ 理解并记录了根本原因
✅ 修复最小且针对性强
✅ 测试可防止回归
✅ 处理了边缘情况
✅ 在所有环境中正常工作
✅ PR文档全面
✅ 未引入新问题