Defect Management

---
name: defect-management
description: "缺陷管理——缺陷单写法、严重度与优先级、状态流转与关闭、重复/无效单处理、每周缺陷复盘，附 TAPD 等工具导出 CSV 的统计脚本。当用户说「bug 单怎么写」「严重度和优先级怎么定」「做个缺陷周报」时使用。"
author: Captain
version: 0.1.0
display_name: "缺陷管理"
display_name_en: "Defect Management"
description_zh: "团队用 TAPD 或类似工具管缺陷：缺陷单模板（标题公式、复现步骤、期望/实际、环境、附件清单）、严重度×优先级矩阵、状态流转规则、重复与无效单处理、每周复盘统计口径；附 Python 标准库脚本，读取导出 CSV（列名可配置）统计严重度、模块、状态、存活天数并输出复盘摘要。"
description_en: "Write clear bug reports, set severity and priority, run the status workflow, handle duplicates and invalid reports, and produce a weekly defect review from a TAPD-style CSV export with a configurable standard-library script."
tags:
  - "缺陷管理"
  - "bug 管理"
  - "缺陷单"
  - "TAPD"
  - "严重度"
  - "优先级"
  - "缺陷复盘"
  - "bug report"
  - "defect tracking"
  - "QA"
examples_zh:
  - "这个 bug 帮我按规范的缺陷单写法整理一下"
  - "这个问题的严重度和优先级怎么定？算 P1 吗"
  - "从 TAPD 导出的缺陷 CSV，帮我做个缺陷周报"
examples_en:
  - "Rewrite this bug as a proper defect report with repro steps"
  - "Build a weekly defect review from our TAPD CSV export"
---

# 缺陷管理

定位一句话：**缺陷单要让开发不用回问就能复现；严重度看影响、优先级看先修谁；状态有规则地流转；每周用同一套口径复盘。**

字段名、状态名、严重度取值在不同项目里不一样——本技能给通用写法与建议默认规则，TAPD 里的实际字段以你所在项目的 TAPD 配置为准。

## 何时使用

- 「这个 bug 帮我写成规范的缺陷单」
- 「严重度和优先级怎么定？这个算 P1 吗」
- 「开发说是重复单 / 无法复现，怎么处理」
- 「帮我们定一套缺陷状态流转规则」
- 「从 TAPD 导出了缺陷 CSV，帮我做本周复盘」

不适用（遇到时这样处理）：
- 定位代码根因、修 bug：交给调试或代码类技能，或直接转给开发。
- 线上事故复盘（故障定级、时间线、改进项）：交给事故复盘类技能；本技能只管缺陷单与缺陷数据。
- 在 TAPD 里改字段、改工作流：需要项目管理员操作，本技能只给规则建议，官方说明见 TAPD 帮助中心「缺陷」「工作流」「自定义字段」相关章节（章节名以帮助中心为准）。

## 流程

### 一、把缺陷写清楚

标题公式：**【模块】在什么条件下 + 做了什么 + 出现什么问题（+ 影响范围）**。
例：`【支付】iOS 17 使用 Apple Pay 支付成功后，订单仍显示「待支付」（约 3% 订单）`

正文按顺序写：基本信息（模块、严重度、优先级建议、复现概率、版本、环境、设备与系统、账号与数据）→ 复现步骤（从干净状态开始，每步一个动作，写具体输入值）→ 期望结果（写依据：需求文档、设计稿或旧版本行为）→ 实际结果（写现象不写推测，报错原样贴）→ 附件清单（截图、录屏、日志时间段、请求 ID、抓包，全部先脱敏）→ 补充（影响范围、标明「推测」的初步判断、关联单）。

可直接粘贴的模板、复现步骤规矩和一份写好的示例见 [references/bug-report-template.md](references/bug-report-template.md)。

### 二、定严重度与优先级

- 严重度由提单人按**影响**定：致命（核心不可用、数据或资金错误、安全漏洞）→ 严重 → 一般 → 轻微 → 建议。
- 优先级由负责人按**先修谁**定：P0 立即处理 → P1 本迭代必修 → P2 排期 → P3 有空再修。
- 默认用「严重度 × 影响面」矩阵给优先级，负责人可调整但要写理由。严重度低、优先级高的典型：支付成功页错别字。

完整矩阵、判断标准与例子见 [references/severity-priority-workflow.md](references/severity-priority-workflow.md)。

### 三、状态流转与关闭

新建 → 已确认 / 已指派 → 处理中 → 已解决（待验证）→ 已关闭；分支：拒绝（重复 / 无法复现 / 设计如此 / 不修复，须写理由，提单人确认后关闭）、重新打开、挂起（写原因与复查日期）。开发不关自己修的单；验证用原复现步骤、在修复版本上做。

重复单：关联原单后关闭，把新信息合并到原单；无法复现：先补录屏和日志，约定期限内仍无补充再关；设计如此：由产品引用需求文档确认；不修复：写明理由和风险接受人。细则同上链接。

### 四、每周缺陷复盘

口径固定：统计日、区间、新增、关闭（含无效类，单独列）、净增、未关闭存量、严重度与模块分布、存活天数、解决周期、长期未关闭清单、无效率、重开率。口径定义与 30 分钟复盘会流程见 [references/weekly-review.md](references/weekly-review.md)。

统计脚本（路径相对本技能目录；Excel 先另存为 CSV）：

```bash
python3 scripts/defect_stats.py bugs.csv --today 2026-09-26 --since 2026-09-19 --until 2026-09-25
python3 scripts/defect_stats.py bugs.csv --map severity=严重级别 --map module=所属模块 --closed-status 已上线
python3 scripts/defect_stats.py bugs.csv --today 2026-09-26 --format json -o review.json
```

- 列名自动匹配常见中英文写法（ID、标题、严重程度、优先级、状态、模块、处理人、创建时间、解决时间、关闭时间、重新打开次数……）；对不上就用 `--map 角色=列名`。只有「状态」列必需，缺别的列就跳过对应统计并在报告里写明。
- 状态按内置词表归为待处理 / 已解决待验证 / 挂起 / 已关闭 / 无效，词表外的列进「数据问题」，用 `--open-status`、`--closed-status` 等补充后重跑。
- 编码自动尝试 UTF-8 与 GB18030；分隔符自动识别逗号、制表符、分号；日期认 `2026-09-26`、`2026/9/26`、`2026年9月26日` 和 Excel 序列日期；重复 ID 默认只算一次。
- 输出八节：总体、严重度、模块、状态、存活天数、解决周期、需要关注、数据问题。同样的输入和 `--today` 得到同样的结果。

## 信息不全或出错时

| 情况 | 怎么处理 | 对用户说的话（模板） |
|---|---|---|
| 写缺陷单缺关键信息 | 只问 3 个：在什么环境 / 版本、怎么操作出现的、期望是什么；其余字段留 [待补] | 「补三件事我就能写完整：哪个版本和设备、操作步骤、你期望看到什么。」 |
| 描述自相矛盾（说必现，又说只出现过一次） | 指出矛盾，给两种写法让用户选 | 「复现概率两种说法：①必现；②只出现过一次。按哪种写？偶现的话建议附录屏。」 |
| 复盘缺统计日或区间 | 默认统计日 = 今天，区间 = 最近 7 天，交付物里标 [待确认] | 「我先按今天、最近 7 天统计，标了 [待确认]，要改告诉我。」 |
| 脚本报「未识别的状态 / 严重度」 | 问这个值的实际含义，用 `--open-status` 等补充后重跑 | 「『待确认』在你们项目里是还没处理，还是已经不算缺陷？」 |
| 时间紧，只要最小版 | 缺陷单：标题 + 复现步骤 + 期望 / 实际 + 环境一行；复盘：新增 / 关闭 / 净增 + 长期未关闭清单 + 1 条行动 | 「先给最小版，其余字段 [待补]。」 |
| 超出范围：定位根因、评估修复工期、改 TAPD 配置 | 转给开发或项目管理员；可以帮忙整理要问的问题 | 「根因需要开发看代码，我把复现信息整理好，方便他直接查。」 |
| 用户坚持按人头排名缺陷数 | 不做排名，改为负载视图与模块视图 | 「按人排名会让大家不敢提单或拆单，我改成按处理人的未关闭负载。」 |

脚本退出码：

| 退出码 / 报错 | 原因 | 修正办法 |
|---|---|---|
| 0 | 成功 | — |
| 1「找不到『状态』列」 | 列名不在自动匹配范围 | `--map status=你的状态列名` |
| 1「--map …：CSV 里没有这一列」 | 列名写错 | 按报错里列出的现有列名改 |
| 1「日期写法不对 / --since 晚于 --until」 | 参数格式 | 用 `2026-09-26` 这种格式 |
| 2「找不到文件 / 无法识别编码 / 只有表头」 | 文件问题 | 检查路径；`--encoding gb18030`；确认导出时勾选了数据 |
| 2「写文件失败」 | 输出目录不存在或无权限 | 换一个存在的目录 |
| 130 | Ctrl+C 中断 | 重跑即可 |

## 输出契约

按交付物类型用固定骨架，顺序不变，缺项写 [待补]：
- **缺陷单**：标题 → 基本信息 → 复现步骤 → 期望结果 → 实际结果 → 附件清单 → 补充。
- **定级建议**：严重度 + 理由 → 影响面 → 矩阵给出的默认优先级 → 是否建议调整及理由。
- **周复盘**：一句话结论 → 总体数字 → 需要关注清单 → 聚集分析（推测要标注）→ 行动（≤3 条，含负责人和日期）→ 数据问题 → 附脚本完整输出。

占位符：用户没给的写 [待补]；推断出来的写 [待确认]；原因分析里的猜测写「推测」。

交付前自检（逐条判是/否）：
- [ ] 标题符合「模块 + 条件 + 操作 + 现象」，不含猜测的原因。
- [ ] 复现步骤每步一个动作，有具体输入值，期望结果写了依据。
- [ ] 严重度与优先级分开给，调整矩阵默认值时写了理由。
- [ ] 复盘报告写明了统计日与区间，数字都来自脚本输出。
- [ ] 「数据问题」里的每一项都有处理说明。
- [ ] 附件与报告里没有未脱敏的手机号、令牌、客户信息，也没有按人排名。

## 示例

> 示例对话，内容虚构。

**用户**：苹果手机用 Apple Pay 付完款，订单还显示待支付，过一会儿又好了，帮我提个单。

**助手**：补三件事：①哪个 App 版本、手机和系统版本？②大概试了几次、出现几次？③在测试环境还是线上？

**用户**：5.2.0 测试包，iPhone 15、iOS 17.5，10 次出现 3 次，测试环境；iPhone 12 没出现。

**助手（交付物）**：

```
【标题】【支付】iOS 17 使用 Apple Pay 支付成功后，订单仍显示「待支付」（偶现 3/10）

【基本信息】
- 模块：支付
- 严重度：严重（已扣款但订单状态错误，可能导致重复支付或投诉）
- 优先级建议：P1（矩阵：严重 × 特定条件；负责人可调整）
- 复现概率：偶现（10 次出现 3 次）
- 发现版本：App 5.2.0 测试包
- 环境：测试环境
- 设备与系统：iPhone 15 / iOS 17.5；iPhone 12 未复现 [待确认：iPhone 12 的系统版本]
- 账号与数据：[待补：测试账号类型、出现问题的订单号]

【复现步骤】
1. 前置条件：登录测试账号，购物车有 1 件商品。
2. 点「去结算」→ 选择 Apple Pay → 确认支付。
3. 支付成功弹窗出现后，点「查看订单」。

【期望结果】订单状态为「已支付」（依据：[待补：支付需求文档章节]）。
【实际结果】订单状态显示「待支付」，约 1 分钟后自动变为「已支付」[待确认：具体间隔]。

【附件清单】
- [ ] 录屏（偶现问题必附）[待补]
- [ ] 日志时间段与请求 ID [待补]

【补充】影响范围：目前仅见 iOS 17 + Apple Pay；初步判断（推测）：支付回调与订单状态刷新存在时序问题。
```

每周复盘的完整示例（含故意放入脏数据的 CSV、两次运行、脚本真实输出和发群摘要）见 [examples/weekly-review-example.md](examples/weekly-review-example.md)。

## 常见问题（FAQ）

**严重度和优先级到底有什么区别？** 严重度是「坏到什么程度」，提单人按影响定；优先级是「先修谁」，负责人按业务和排期定。两者可以不一致。

**开发说「无法复现」怎么办？** 先补录屏、日志时间段和请求 ID，对齐环境和数据；约定期限内仍无法复现再关闭，再出现时重新打开并附新证据。

**一个问题在多个页面出现，提一个单还是多个？** 同一原因提一个单，列出所有出现位置；不确定是否同因，先提一个并写明「可能相关」，由开发判断是否拆分。

**需求没写清导致的问题算缺陷吗？** 先按缺陷提，写清「需求文档未说明」，由产品判断是改需求还是修缺陷；不要因为归属不清就不提。

**TAPD 导出的列名和脚本对不上？** 看报告第一段的「列对应」和「未找到的列」，用 `--map 角色=列名` 指定；字段名以你所在项目的 TAPD 配置为准。

**能直接帮我在 TAPD 里建单、改状态吗？** 不代为操作系统。我给可以直接粘贴的内容，由你提交。

**复盘要不要按人统计缺陷数？** 只看「处理人名下未关闭数」来排负载，不做排名。

## 常见错误（反模式）

- 标题写「支付有问题」→ 没法搜索、没法判断 → 用「模块 + 条件 + 操作 + 现象」。
- 严重度一律填「严重」→ 分级失效，真严重的被淹没 → 按判断标准定，拿不准就写理由让负责人定。
- 复现步骤写「随便点几下就出现」→ 开发无法复现，来回问 → 从干净状态开始，每步一个动作。
- 附件带着令牌和手机号上传 → 泄露风险 → 上传前脱敏。
- 重复单直接关掉、不关联 → 新信息丢失 → 关联原单并合并补充信息。
- 挂起不写复查日期 → 永远挂着 → 写原因和复查日期，复盘时检查。
- 按人头排名缺陷数 → 大家不敢提单或拆单 → 看负载与模块。
- 只看本周数字 → 看不出积压 → 固定口径，和上周、上上周比。

## 边界与不做什么

- 不代替用户在 TAPD 或其他系统里建单、改状态、关单、改配置；不用脚本批量抓取 TAPD 页面或他人项目的数据，只处理你有权限导出的文件。
- 不定位代码根因、不承诺修复时间；原因分析只标「推测」。
- 不把缺陷统计用于个人绩效排名。
- 附件与日志先脱敏；不在报告里出现客户个人信息与凭据。
- TAPD 的字段、状态、工作流以你所在项目的配置和 TAPD 帮助中心为准，本技能不编造产品功能。