write-bug

编写 Bug（FOLIO）

FOLIO Bug 报告必须可复现、具体，并有证据支持。读者应该无需猜测就能重现缺陷。

提前搜索上下文

在完成第一版 Bug 草稿之前，一旦受影响的区域和可观察到的症状已明确到足以构造查询，就搜索相关的现有 Jira 问题，并阅读最匹配的结果。这既适用于仅请求起草的情况，也适用于请求创建工单的情况。应涵盖未解决和已解决／已关闭的问题；不要只搜索尚未解决的 Bug。

只询问开始搜索真正需要的信息——一旦区域和症状已明确，就不要等到收集完所有信息后才开始搜索。然后结合搜索结果，针对实际仍缺少的信息提问。

使用已配置的 Jira 搜索／读取能力及其实际架构；此技能中列出的工具名称仅为示例，并非前提条件。如果搜索不可用、不完整或被用户排除，请基于现有证据继续，并说明这一限制。未进行充分搜索时，绝不要声称“没有重复问题”。

有关查询构造、候选问题检查以及结果分类方式，请阅读 references/context-search.md。

如何利用搜索结果

• 只展示相关匹配项：问题编号或链接、状态，以及简短的相关性说明。
• 将重要上下文放在合适的位置——概述、预期结果的依据或补充信息中，而不是放在冗长的 Search Report 部分里。
• 如果某个匹配项很可能是重复问题，应推荐使用现有工单；对于仅请求起草的情况，继续补充该工单所缺少的复现步骤或证据。
• 绝不要主动创建、评论、更新、关联、重新打开或关闭现有问题。即使很可能存在重复问题，也只有在展示两者的关联后，用户明确决定才可创建新工单。

Bug 结构

每个 FOLIO Bug 都必须包含以下部分，且顺序如下。标记为 (optional) 的部分在没有实际价值时可省略。

1. Summary — Jira 问题的一行标题。必须指出受影响的区域和可观察到的症状。请参阅 摘要规则。
2. Overview / Context (recommended) — 用 1–3 句话说明影响、来源（例如，来自 TICKET-123 的回归问题）或业务背景。大多数 FOLIO Bug 都以“Overview:”部分开头；除非缺陷仅凭摘要就能充分说明，否则请包含此部分。
3. Preconditions — 步骤执行前所需的环境、数据、角色、权限、功能标志或先前工单。每项前置条件都必须可独立验证。
4. Steps to reproduce — 按编号列出原子操作。每个步骤只包含一个用户操作。不得假设用户已完成之前的导航。
5. Expected result — 系统应执行的操作；尽可能引用真实依据（规范、验收标准或先前行为）。
6. Actual result — 系统实际执行的操作。逐字引用错误消息，并在相关时提供状态码／ID。
7. Additional information (optional but strongly recommended) — 堆栈跟踪、请求／响应负载、查询计划、日志摘录、屏幕截图、视频、受影响环境的 URL，以及可复现率。

模板

## Overview

[1–3 sentences on impact, affected users, regression source, or related tickets.
Recommended for anything non-trivial — FOLIO bugs conventionally open with this.]

---

## Preconditions

1. [Environment / tenant / user role]
2. [Data state — e.g. "An Order in 'Open' status exists with one PO line"]
3. [Feature flag / configuration]

---

## Steps to reproduce

1. [Single user action]
2. [Single user action]
3. [Single user action]

---

## Expected result

- [Observable outcome #1]
- [Observable outcome #2, referencing spec/AC if applicable]

---

## Actual result

- [Observable outcome #1, including exact error text]
- [HTTP status / error code / record state]

---

## Additional information (optional)

**Reproducibility:** [Always / Intermittent (X of Y) / Once]
**Environment:** [folio-etesting-snapshot / folio-etesting-sprint / local]
**Module versions:** [mod-orders 13.0.5, ui-orders 9.1.2]
**Related tickets / prior fixes:** [PROJECT-123 — state how it relates]
**Regression status / evidence:** [Only when relevant; say whether it is possible or confirmed]
**Workaround:** [Describe any workaround found, or "None" / omit if not applicable]
**Test Cases:** [TestRail IDs, e.g. C15189, C15190 — omit if not used by your team]

\`\`\`
[paste stack trace or log excerpt]
\`\`\`

**Attachments:** screenshots / HAR / video (attach to Jira)

摘要规则

好的摘要必须通过**“快速浏览测试”**——分诊人员仅凭标题就能判断优先级和分派方向。

格式

[<Area/Component>] <symptom> when <trigger/condition>

如果 Jira 项目已能明确指出所属区域（例如，UIOR 表示 Orders UI），则 [<Area>] 前缀可省略。

应当

• 指出可观察到的症状：“返回 500”、“显示重复行”、“未更新”、“未反映更改”。
• 包含触发条件：“移动馆藏时”、“以外币支付发票后”、“订单数超过 5 万的租户上”。
• 仅当 Bug 与环境相关时才注明环境（例如，环境专属问题使用 “M-an dry-run |” 前缀）。

不要

• 不要使用含糊的标题：❌ “订单出错”，❌“无法使用”。
• 不要在标题中指定修复方案：❌“在 X 中添加空值检查”。
• 不要过多描述问题分类人员无法了解的实现细节。

示例（来自真实的 FOLIO 缺陷）

• ✅ “更新 receiptDate 后，POL 审计历史中的 updatedDate 未更新”
• ✅ “订单已支出金额未转换为发票货币”
• ❌ “POL 缺陷”
• ❌ “修复货币处理”

撰写指南

重现步骤

• 从已登录的干净状态开始，或在前置条件中说明。
• 每个步骤只执行一个操作。 将“打开订单并点击接收”拆分为两步。
• 按实际情况描述。 使用准确的界面标签或 API 路径： POST /orders/wrapper-pieces?query=...。
• 通过属性而非 ID 引用数据。 “一个状态为‘Open’且采用 Synchronized receiving 工作流的订单”比“订单 d4e7-...”更合适。
• 在故障发生处停止。 不要描述故障发生后的探索过程。

预期结果与实际结果

• 两者都必须是测试人员可观察到的，而不是内部状态。“未抛出错误”描述得不够明确；“出现‘Order saved’提示，且状态 = Open”则很明确。
• 逐字引用错误信息，包括状态码、错误代码和消息。
• 对比预期结果和实际结果。如果字段值有误，请说明两者的值。

证据

• 堆栈跟踪 → 粘贴到围栏代码块中；Jira 会将其渲染为可滚动的 {code} 块。
• 日志 → 包含时间戳、日志记录器名称、级别和关联 ID。
• SQL / 查询计划 → 性能缺陷需提供。
• 屏幕截图 / 视频 → 附加到 Jira，并注明文件名。
• 重现率对问题分类很重要：始终发生还是偶尔发生（例如“尝试 10 次中发生 3 次”）。

优先级与严重程度（FOLIO 级别）

请以此矩阵为起点；问题分类团队可能会重新分配优先级。

优先级	适用情况
P1 — 严重	严重的正确性或可用性问题：数据丢失或损坏、安全漏洞、财务或计算结果错误、登录 / 身份验证故障、整个应用或主要工作流无法使用、阻碍发布，或影响系统中的下游流程。
P2 — 重大	核心工作流故障或产生错误结果，且没有合理的替代方案，影响许多用户。
P3 — 普通	有替代方案的缺陷，影响特定流程或部分用户。
P4 — 轻微	外观问题、拼写错误、影响较小的边缘情况。
TBD	尚未评估优先级 — 提交时可以接受，但请预期会进行分类。

用户交互流程

在生成最终缺陷报告之前，先检查用户是否提供了必要信息。 如果以下任何信息缺失或含糊，请询问用户（将相关问题合并询问）。如果有可用的问题工具，请使用；否则可以直接在聊天中提问。不要重复询问请求或上下文搜索中已经提供的信息：

1. 目标 Jira 项目（例如 MODORDERS、UIOR、FOLIO）。起草摘要前缀并确定 Jira 创建路径时需要此信息。
2. 发生缺陷的环境（snapshot、bugfest、dry-run、本地环境或特定租户）。
3. 可重现性（始终发生 / 偶尔发生 / 仅发生一次）。此信息会影响问题分类。
4. 重现步骤（如果用户只描述了症状）。
5. 预期行为的依据（规范、工单、“上一版本”）。如果“预期”带有主观性，则需要此信息。
6. 支持证据 — 日志、堆栈跟踪、屏幕截图、HAR、录屏。
7. 优先级建议（如果用户了解影响情况）。

除非用户主动提供，否则不要询问用户可以合理留给问题分类团队处理的部分（修复版本、组件、标签）。

可选：在 Jira 中提交 Bug

用户批准草稿后，询问是否要通过 mcp-atlassian_jira_create_issue 创建工单：

• 使用双方确认的项目键和 issue_type: "Bug"。
• 将 Markdown 草稿转换为 Jira 标记语法（参见 references/jira.md）。
• 只有在用户确认后，才通过 additional_fields 传入 priority、labels、components 和 fixVersions。
• 创建后，返回问题键和 URL。

重复使用本次会话中已审核的上下文搜索结果。当症状、范围、项目或相关证据发生实质变化、有具体理由认为搜索结果已过时，或用户要求刷新时，再刷新结果。不要仅仅因为草稿已获批准，就重复进行没有变化的搜索。

最佳实践

应该 ✓

1. 每张工单只描述一个 Bug。将复合缺陷拆分开。
2. 写明前置条件，让其他人也能进入起始状态。
3. 逐字引用错误信息，包括代码和 ID。
4. 对间歇性 Bug，说明复现率。
5. 链接相关工单和之前的修复，并说明它们之间的关系。
6. 在提交第一份完整草稿前搜索开放和已关闭的问题；如果无法检查，则说明这一点。
7. 根据证据准确表述回归情况：可能或已确认；没有数据支持时，绝不要指明引入问题的工单或提交。

不应该 ✗

1. 不要在摘要或步骤中推测根本原因。将假设放在明确标注为 补充信息 的说明中。
2. 不要在一张工单中混合多个缺陷。
3. 不要使用含糊的动词，例如“无法使用”“坏了”“表现奇怪”。
4. 不要粘贴机密信息（令牌、真实用户邮箱、租户凭据）。
5. 不要在 Bug 本身中写入建议的修复方案——这应放在 PR 或关联的故事中。
6. 不要省略预期结果——“应该能正常工作”无法测试。

快速参考清单

• 摘要指出区域 + 症状 + 触发条件
• 前置条件可独立验证
• 步骤已编号、彼此独立，并从明确的状态开始
• 预期结果引用了权威来源
• 实际结果包含准确的错误文本 / 状态码
• 已说明复现率
• 已记录环境和模块版本
• 已附加或内嵌堆栈跟踪 / 日志 / 截图
• 如有解决方法，已记录
• 不含个人身份信息、机密信息或真实凭据
• 在提交第一份完整草稿前已搜索开放和已关闭的问题；否则已说明限制
• 已标明实际检查过的匹配项及其关系
• 重复问题和回归问题的表述符合证据
• 是否新建工单的决定已考虑搜索结果
• 每张工单只描述一个缺陷

逐节编写指南请参阅 references/section-details.md。 完整 Bug 示例请参阅 references/example.md。 Markdown → Jira 标记语法转换请参阅 references/jira.md。 关于修改前后对比的常见陷阱，请参阅 references/pitfalls.md。 关于上下文搜索范围、检查和分类，请参阅 references/context-search.md。