ai-zidong-tibug

# 一句话 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`