一句话 Bug 规范化#

目标#

把每个缺陷改写成“单一问题、单一验收点”的标准表达，默认句式：

在【页面/场景】执行【操作】后，实际【结果】，应【期望结果】。

坚持：一条一句、一个问题、一个验收结论。

必加前置条件（强制）#

在输出任何 Bug 前，必须先熟悉对应的需求文档与 UI。

• 需求文档：PRD、需求说明、验收标准、评审结论等。
• UI 依据：Figma/Axure 原型、页面截图、录屏、线上页面。
• 若前置资料不全：先列出缺失项并要求补齐；补齐前不产出正式 Bug 条目。

工作流#

1. 对齐需求与 UI：先确认功能意图、交互预期、展示规范和验收口径。
2. 抽取事实：页面/场景、前置条件、触发动作、实际结果、期望结果。
3. 拆分复合问题：遇到“文案+样式+逻辑”这类混合描述，拆成多条。
4. 生成标题：标题首标签必须为平台（[安卓] 或 [iOS]），模块/页面必须使用全角括号（），正文优先使用“在...后...，应...”句式。
5. 判定严重级别：按影响范围标注 S1-S4。
6. 固定按禅道格式输出：不提供一句话列表或 Jira 样式作为最终结果。
7. 补齐关键管理字段：影响版本、严重级别、优先级、图片/附件。
8. 自检质量：确保可复现、可验收、可指派。
9. 自动登录禅道并逐条提单：先执行 scripts/zentao_login_and_save_state.py 获取/刷新 token 登录态，再执行 scripts/zentao_submit_bugs.py 逐条创建缺陷并上传附件。
10. 回填提单结果：为每条 Bug 回填禅道缺陷 ID/链接/提交状态。

禅道自动登录与自动提单（强制）#

默认行为：生成每条 Bug 后，自动登录禅道并创建缺陷单；仅当用户明确说“只生成不提单”时才跳过提交。

登录脚本（必须使用）：

• 脚本路径： scripts/zentao_login_and_save_state.py
• 执行命令： python3 scripts/zentao_login_and_save_state.py
• 登录产物：token 状态文件（默认 ./playwright/.auth/zentao-storageState.json）
• 必填环境变量： HTTP_USER、 HTTP_PASS、 ZENTAO_USER、 ZENTAO_PASS
• 可选环境变量： ZENTAO_URL、 STORAGE_STATE_PATH、 VERIFY_SSL

提单脚本（必须使用）：

• 脚本路径： scripts/zentao_submit_bugs.py
• 执行命令： python3 scripts/zentao_submit_bugs.py --input <bugs.json> --product-id <产品ID>
• 启用模块自动映射（可选）： --module-map <module-map.json>
• 创建模式（可选）： --create-mode auto|api|legacy
• 附件模式（可选）： --attachment-mode strong|api-link（默认 strong）
• 去重与重试（可选）： --[no-]dedupe、 --retry-attempts <n>
• 结果产物：提单结果文件（默认 ./playwright/.auth/zentao-submit-result.json）
• 输入样例： references/submit-bugs-input.example.json
• 模块映射样例： references/module-map.example.json

执行要求：

• 自动处理登录态：登录失效时自动重新登录。
• 逐条提交：每条 Bug 独立创建 1 条禅道缺陷。
• 自动补齐字段映射：指派人、标题、步骤、期望、影响版本、严重级别、优先级、图片/附件。
• 自动模块映射：优先使用条目内 模块ID，否则按 --module-map 规则匹配，再兜底默认模块。
• 附件处理：默认 strong 模式（legacy files[] 强绑定到禅道附件栏）；可切换 api-link 模式回填附件链接到内容区。
• 去重与重试：默认同产品同标题去重；网络/提单/上传默认自动重试 3 次。
• 提交后回填：返回缺陷 ID、链接、提交状态；失败时给出失败原因与重试建议。

前置资料（首次提单前需具备）：

• 禅道地址（URL）
• 产品ID（必填）
• 项目/执行/模块定位（如有）
• 模块映射文件（可选，建议配置）
• 可用登录态（通过环境变量提供账号密码）

输出模式（唯一）#

所有 Bug 必须按禅道格式输出（强制），无论用户是否额外指定格式。

每条固定字段：

• 指派人
• 标题
• 步骤（固定 4 步，第 4 步写实际结果）
• 期望（步骤后空一行再写； 期望： 冒号后保留 1 个空格）
• 影响版本
• 严重级别（S1-S4，必填）
• 优先级（P1-P4，必填）
• 图片/附件（截图链接、文件名或“待补充”）
• 禅道提交结果（缺陷ID/链接/状态，必填）

标题格式（强制）：

• [安卓]（模块/页面）问题描述
• [iOS]（模块/页面）问题描述

排版格式（强制）：

• 步骤固定写 4 条，第 4 条必须写“实际结果”。
• 步骤块结束后，必须空 1 行再写 期望： 。
• 期望： 中的冒号后必须保留 1 个空格。

说明：严重级别不再放在标题中，只保留在“严重级别”字段里。

指派人规则（平台映射，强制）#

• Android 缺陷： 指派人=孙晓晨
• iOS 缺陷： 指派人=蓝友亮
• 默认平台：安卓。用户未明确平台时，按安卓输出（标题用 [安卓]，指派人用孙晓晨）。
• 同一问题同时影响 Android 与 iOS：拆成两条禅道 Bug，分别按平台指派。
• 标题平台标签与指派人必须一致： [安卓]↔孙晓晨， [iOS]↔蓝友亮。

说明：可以先在内部生成“一句话 Bug”用于组织语言，但最终对外输出必须是禅道字段结构。

严重级别判定（S1-S4）#

• S1：核心流程阻断、数据错误、安全/资金风险。
• S2：关键功能错误，主流程可继续但明显受损。
• S3：局部功能、交互、视觉或状态异常，不阻断主流程。
• S4：轻微样式/文案问题，功能基本不受影响。

优先级判定（P1-P4）#

• P1：需立即处理（通常与 S1 对应，或上线阻断风险高）。
• P2：本迭代优先处理（通常与 S2 对应）。
• P3：可排期处理（通常与 S3 对应）。
• P4：低优先级优化项（通常与 S4 对应）。

说明：严重级别表示“影响程度”，优先级表示“处理先后”，两者可不完全等同，但需给出明确值。

写作硬规则#

• 必须以需求文档和 UI 依据为准，不脱离设计与验收标准主观发挥。
• 最终输出必须是禅道格式；即使用户未指定或提出其他格式，也统一回到禅道字段。
• 标题首标签必须是平台（[安卓] 或 [iOS]），禁止再使用 [S1/S2/S3/S4] 作为标题前缀。
• 只写客观现象，不写原因猜测（如“可能是接口挂了”）。
• 避免模糊词（如“有点”“偶尔”“不太对”）。
• 不能把多个缺陷塞进一条。
• 步骤固定为 4 条，第 4 条必须写实际结果；步骤块与期望字段之间必须空 1 行。
• 期望必须可验收，优先“应/应当/应显示”。
• 缺失信息不得编造：未知字段写“待补充”；平台未指定时默认按安卓映射输出。
• 严重级别与优先级必须明确填写（S1-S4、P1-P4），不得留空。
• 图片/附件字段必须存在：有截图时填链接或文件名；无截图时填“待补充（需上传截图/录屏）”。
• 默认执行自动提单：除非用户明确要求“仅输出不提交”，否则每条 Bug 都要自动提交到禅道。
• 禁止在脚本中硬编码账号密码；凭据仅通过环境变量或运行参数提供。
• 每条 Bug 提交后必须回填禅道提交结果（缺陷ID/链接/状态）；提交失败不得静默，必须反馈失败原因。

批量输入处理#

当输入是会议纪要、聊天记录、截图文字时：

1. 先按模块/页面分组。
2. 再按“动作-现象-期望”拆分。
3. 每组按稳定顺序输出，避免字段缺失。

质量自检清单#

输出前逐条检查：

1. 是否已完成“需求文档 + UI 依据”的对齐检查。
2. 是否包含“场景 + 操作 + 实际 + 期望”。
3. 是否只有一个缺陷。
4. 他人是否能按步骤复现。
5. 是否能清晰判断通过/不通过。
6. 禅道字段是否齐全且顺序稳定（指派人→标题→步骤→期望→影响版本→严重级别→优先级→图片/附件→禅道提交结果）。
7. 步骤是否固定 4 条且第 4 条为实际结果，且步骤块与期望字段之间留有 1 行空行。
8. 标题是否使用平台前缀（[安卓] 或 [iOS]），且模块/页面使用全角括号（），并未使用 [Sx] 前缀。
9. 指派人是否符合平台映射（安卓=孙晓晨；iOS=蓝友亮），且未指定平台时是否已默认按安卓输出。
10. 严重级别与优先级是否均已给出有效值（S1-S4、P1-P4）。
11. 图片/附件字段是否已填写有效证据或“待补充（需上传截图/录屏）”。
12. 是否已完成逐条提单并回填禅道缺陷ID/链接/状态；失败是否已反馈原因。

参考模板#

需要模板、反例改写、批量整理示例时，读取：

• references/templates-zh.md
• references/submit-bugs-input.example.json
• references/module-map.example.json