zentao-bug

Bug (v2)

CRITICAL — 开始前 MUST 先用 Read 工具读取 ../zentao-shared/SKILL.md，其中包含认证、环境变量、错误处理和状态值定义。

严重性判断技巧：ZenTao Bug 的 severity (严重程度) 分 1-5 级，其中 1 为最严重（系统崩溃、数据丢失），5 为最低（功能建议）。创建 Bug 时应根据实际情况选择正确级别：

• severity=1：系统崩溃、功能完全不可用、数据丢失
• severity=2：主要功能失效、有明确 workaround
• severity=3：普通缺陷，有替代方案
• severity=4：轻微问题，界面/体验类
• severity=5：功能建议/优化项

状态与解决方案：Bug 有三个主状态 active(激活) / resolved(已解决) / closed(已关闭)，以及对应的 resolution。resolved 状态的 Bug 需要指定 resolution（fixed/duplicate/notrepro/wonfix/bysdesign），closed 状态需要先 resolved 再关闭。

指派与流转：Bug 创建后可以通过 bug update 指派给开发人员。当 Bug 被修复后，状态变为 resolved；当 Bug 被确认关闭后，状态变为 closed。

友好输出：在输出 Bug 详情时，建议同时输出 Bug 的 URL 链接（ZenTao web UI 地址），便于用户直接点击查看。

Bug Lifecycle

active (激活) ──[修复]──> resolved (已解决) ──[确认]──> closed (已关闭)
    │                         │
    │<────[重打开]─────────────┘
    │
    └──[转为设计/需求]──> changed (已变更)

状态流转规则

当前状态	可转向	操作
active	resolved	修复完成，设置 resolution
active	closed	直接关闭（wonfix/bysdesign 等情况）
resolved	active	重打开 Bug
resolved	closed	确认修复，关闭 Bug
closed	active	重新激活

Severity Levels

Level	Name	Description	Example
1	Critical	系统崩溃、数据丢失、功能完全不可用	页面打不开、关键数据丢失
2	Major	主要功能失效，有 workaround	某核心按钮点击无响应
3	Normal	普通缺陷，有替代方案	某非关键功能异常
4	Minor	轻微问题，界面/体验类	文字显示不全
5	Wishlist	功能建议/优化项	希望增加某功能

Commands

• bug list — List bugs for a product
• bug get — Get bug details
• bug create — Create a new bug
• bug update — Update bug fields
• bug resolve — Resolve a bug
• bug confirm — Confirm a bug
• bug close — Close a bug
• bug activate — Activate a bug
• bug delete — Delete a bug

Common Use Cases

场景 1：查询产品的所有激活 Bug

# 按产品 ID 列出所有激活状态的 Bug
zentao-cli bug list --product 1 --status active

场景 2：创建新 Bug

# 创建严重性为 1 的紧急 Bug
zentao-cli bug create --title "用户登录页面崩溃" --product 1 --severity 1 --pri 1

# 创建带有详细复现步骤的 Bug
zentao-cli bug create \
  --title "上传头像失败" \
  --product 1 \
  --severity 2 \
  --pri 2 \
  --steps "1. 进入个人资料页\n2. 点击上传头像\n3. 选择图片后无响应"

场景 3：更新 Bug 状态和解决方案

# 标记 Bug 为已修复
zentao-cli bug update 123 --status resolved --resolution fixed

# 指派给开发人员
zentao-cli bug update 123 --assigned-to developer-name

# 重打开 Bug
zentao-cli bug update 123 --status active

场景 4：按指派人筛选 Bug

# 查看指定人员的待办 Bug
zentao-cli bug list --product 1 --assigned-to developer-name

Error Handling

常见错误

错误码	说明	解决方案
ZEN_AUTH_FAILED	Token 无效或过期	检查 ZENTAO_TOKEN 配置是否正确
ZEN_NOT_FOUND	Bug 不存在	检查 Bug ID 是否正确
ZEN_CONFIG_INVALID	配置无效	验证 ZENTAO_URL 和 ZENTAO_TOKEN
ZEN_API_ERROR	ZenTao API 返回错误	检查服务器状态或稍后重试
ZEN_PARAM_MISSING	缺少必需参数	确保提供所有必需参数

错误处理示例

# 遇到 auth 错误时检查认证状态
zentao-cli auth status

# 验证配置
echo $ZENTAO_URL
echo $ZENTAO_TOKEN

Examples

# 列出产品 1 下的所有激活状态的 Bug
zentao-cli bug list --product 1 --status active

# 创建 Bug
zentao-cli bug create --title "用户登录页面崩溃" --product 1 --severity 1 --pri 1

# 标记 Bug 为已修复
zentao-cli bug update 123 --status resolved --resolution fixed

# 查看指定人员的待办 Bug
zentao-cli bug list --product 1 --assigned-to developer-name

Gotchas

1. severity vs pri：severity 表示缺陷严重程度（1-5），pri 表示优先级（1-4）。两者概念不同，创建 Bug 时需要分别设置。

2. resolution 依赖 status：只有在 status=resolved 时才需要设置 resolution。fixed/duplicate/notrepro/wonfix/bysdesign 是常见的解决方案。

3. closed 状态不能直接进入：Bug 不能从 active 直接变为 closed，必须先 resolved 再 closed。但 wonfix/bysdesign 等情况可以例外。

4. steps 字段格式：复现步骤建议使用 \n 分隔多行，便于阅读和解析。

5. 关联需求和项目：创建 Bug 时可以通过 --story 和 --project 关联到已有的需求或项目。