StatusPath Reports使用指南
Jira 报表数据源对比：Project、Filter、JQL、Sprint 与 Epic
当基础规则是 project = KEY 时选择 Project；使用由 Owner 维护、以数字 Filter ID 标识的 Jira 保存查询时选择 Filter；需要精确且自包含的规则时选择 JQL；需要通过 Board 辅助选择一个 Sprint 时选择 Sprint。只有确认 Epic Picker 能在当前 Jira 语言和工作类型配置中找到父项后，才使用 Epic。成功选中有效 Epic 后，StatusPath 构建 parent = key；当前简体中文 Jira 验收环境会因 Picker 搜索 issuetype = Epic 而无法创建新的 Epic 数据源。
Data source（数据源）建立基础候选工作项；可选的 Work item date range（工作项日期范围）再按 Created、Updated 或 Resolved 日期缩小候选范围；Trim History（裁剪历史）独立裁剪已经选中工作项中参与计算的历史。Calendar、Format、报表类型、状态和分组随后决定如何计算与呈现这些历史。
数据源是一份工作项范围约定
工作流报表包含三层必须分开的范围定义：
- Data source：基础 Jira 查询及其稳定身份，即 Project key、数字 Filter ID、完整 JQL、Sprint ID 或父项 key。
- Work item date range：可选的 Created、Updated 或 Resolved 条件，用于进一步筛选工作项。
- Trim History：计算时应用到已选工作项历史的 from/to 边界。
报表类型、状态、Calendar、时区、Format 和分组属于指标配置。改变 Data source 或 Work item date range 可能改变返回 key；改变 Trim History 则可能在 key 不变时改变计算值。Sprint 起止日期、Filter 中的日期条件和 Project 边界都不会自动成为 Trim History。
数据源决定 StatusPath 分析哪些工作项以及由谁维护该范围，但不会改变时长公式。JQL 用于查找匹配工作项，不计算 Jira 状态变化之间的区间。
使用 Jira 工作流报表完整指南把 Data source、Work item date range、Trim History、指标、Calendar、核查证据和输出保存在一起。
本文只负责数据源选择决策；当前控件与具体操作由报表设置和范围文档负责。
五个报表问题对应五种数据源
这份决策记录使用虚构的 SR 和 WEB Jira 身份。它是一份治理模板，不表示五种总体都存在于截图数据或同一个客户站点。每个贴近实际的报表问题只有一个主要数据源，因为其负责人和成员规则不同。
| 报表问题 | 选择 | 为什么由该数据源负责 |
|---|---|---|
当前执行用户在项目 SR 中可见的工作项如何流经工作流，并且 Work item date range 保持为空？ |
Project | 基础查询是 project = SR；最终可见范围仍受 Jira 权限约束。 |
跨 SR 和 WEB 的共享客户升级队列流动情况如何？ |
Filter | 运营团队已经拥有并共享该队列的 Saved Search。 |
SR 和 WEB 中，版本 2026.07 尚未解决的 High 或 Highest 工作项有哪些？ |
JQL | 该范围需要在一段可审核表达式中组合多个明确条件。 |
StatusPath Sprint 24 中的工作项在本次回顾中如何流动？ |
Sprint | Board 用于找到 Sprint；Sprint ID 定义 StatusPath 成员查询。 |
Epic SR-6000 的直接子工作项如何流动？ |
Epic，但必须先验证 Picker | 一个父项 key 是目标边界，但当前 Picker 存在已知的简体中文 Jira 本地化阻塞。 |
把五种数据源作为治理选择进行比较
| 数据源 | 建议维护负责人 | 复用方式 | Board 依赖 | 表达能力 | 审计证据 | 常见失败 |
|---|---|---|---|---|---|---|
| Project | Jira 项目管理员或交付负责人 | 稳定的项目 key | 无 | 低 | 执行用户、Project key、Work item date range 和验收 key | project = KEY 比实际决策范围更宽，或执行用户权限不同。 |
| Filter | 有备份审核人的 Jira Filter Owner | 数字 Filter ID 与当前名称 | 仅当其他 Board 或流程使用该 Filter 时存在 | 中到高 | Filter ID、名称、Owner、共享、当前查询、执行用户和验收 key | 重命名或同名 Filter 让仅记录名称的证据产生歧义；共享或查询变化会改变结果。 |
| JQL | 报表定义负责人 | 随评审记录或 Saved Report 保存的完整查询 | 无；除非查询引用 Board 相关数据 | 最高 | 完整 JQL、Work item date range、报表排序、验收时间、结果数和验收 key | 查询没有负责人或预期结果测试，或把 ORDER BY 误当成成员条件。 |
| Sprint | Scrum Master 或 Sprint Owner | Sprint ID 与 Board 选择上下文 | Board 只供 Picker 使用；最终成员查询使用 Sprint ID | 聚焦 Sprint 成员 | 执行用户、Board ID/名称、Sprint ID/名称、完整 sprint = ID 结果和验收 key |
默认受 Board Filter 约束的原生报表等同于 Sprint-ID 查询。 |
| Epic | Epic 交付负责人 | 验证 Picker 后使用父项 key | 无 | 目标是直接子项成员 | 语言和工作类型配置、父项 key、完整 parent = key 结果和验收 key |
Picker 找不到父项，或默认更深层子项与 Link 都会纳入。 |
这些负责人是治理建议，不是 Jira 权限角色。StatusPath 在当前用户上下文中请求 Jira 数据，因此审核者最终能看到哪些 Project、Filter、Board、Sprint、父项和工作项，仍取决于 Jira 权限。涉及权限的验收必须在 StatusPath 与 Jira 高级搜索中使用同一个 Jira 用户。
Atlassian 的范围模型对选择意味着什么
Atlassian 将高级搜索定义为使用结构化条件查找 Jira 工作项，并在 JQL 字段参考中记录了 sprint、parent 等字段。这些查询确定成员，不计算 Time in Status 时长。
ORDER BY 只改变行序，不改变成员。StatusPath 构建一次运行时会把顶层 ORDER BY 与成员条件分开，以便在排序前加入可选的 Work item date range；报表级工作项排序也可能产生不同的最终行序。由于尚未确认已安装 Marketplace 版本与当前排序实现一致，不要承诺 StatusPath 会保留 Jira 高级搜索的相同行序。应分别记录来源 JQL 和报表排序，并验收返回 key 集合而不是行位置。
Jira 搜索保存后会成为带 Owner 的 Filter。Atlassian 的 Saved Search 文档说明 Owner 可以把 Filter 保持私有，也可以共享给用户、Space 或用户组。StatusPath 保存所选 Filter 的数字 ID，并构建 filter = ID；名称只是显示标签。两者都应记录，因为重命名不会替换稳定 ID，而同名或过期名称会让仅记录名称的审计产生歧义。Owner、共享、当前查询和执行用户可见性也属于报表定义。
当前 StatusPath Sprint 控件只使用 Board 填充 Sprint Picker，随后使用所选 Sprint ID 构建成员查询；应在相同用户的 Jira 高级搜索中用 sprint = 40024 复现该范围。Board Filter 不会加入最终 StatusPath 成员 JQL，因此仅改变 Board Filter 不会改变相同 Sprint ID 和用户返回的 key。Atlassian 说明 Board Filter 基于 JQL，其 Sprint Report 文档明确指出原生报表受 Board 约束，只包含匹配 Board Saved Filter 的工作项。因此原生报表可能比 Sprint-ID 查询更窄。应记录差异，不能把它当作 StatusPath 完整范围的唯一凭据。
Epic 的两个产品步骤具有不同边界。成功选中有效父项后，StatusPath 构建 parent = key，与 Atlassian 记录的直接子项查询一致；但当前 Picker 会先搜索 issuetype = Epic。在已验证的简体中文 Jira 环境中，有效的本地化 Epic 工作类型不会被返回，因此无法新建 Epic 数据源。依赖此来源前，应先在目标语言和工作类型层级中验证 Picker，不要从 parent = key 推断更深后代或 Link 工作项。
Jira 报表概览列出了适用于不同范围和问题的原生报表。选择 StatusPath 数据源不会替代这些原生范围核查；它为基于历史的 StatusPath 报表定义工作项总体。
五个受控问题的配置示例
每份可复用报表旁都应保存一份简短数据源记录。下表是完整示例占位值；应替换为被评审 Jira 站点中的真实身份，并在该站点执行每一项必须纳入与必须排除检查。
| 数据源 | 配置记录 | 必须纳入 | 必须排除 |
|---|---|---|---|
| Project | 项目 key SR；Work item date range 为空 |
SR-6101 |
WEB-7101 |
| Filter | Filter ID 20001；当前名称 StatusPath Customer Escalations；Owner 为 Operations Analytics；共享给评审用户组；记录当前查询 |
SR-6103、WEB-7102 |
SR-6110 |
| JQL | 下方完整查询；Work item date range 为空；单独记录报表排序 | SR-6107、WEB-7105 |
SR-6108 |
| Sprint | Board ID 30000、名称 StatusPath Demo Scrum；Sprint ID 40024、名称 StatusPath Sprint 24；核对 sprint = 40024 |
SR-6111 |
SR-6112 |
| Epic | 仅在 Picker 验证通过后：父项 key SR-6000；核对 parent = SR-6000 的直接子项 |
SR-6116 |
SR-6117 |
JQL 配置为：
project in (SR, WEB)
AND fixVersion = "2026.07"
AND priority in (High, Highest)
AND resolution is EMPTY
ORDER BY key ASC
把它用作报表数据源前，先由同一用户在 Jira 高级搜索中运行，记录结果数，并检查必须纳入和必须排除的 key。ORDER BY key ASC 便于在 Jira 侧审核，但不改变成员，也不承诺未确认安装版本中的 StatusPath 行序。如果保存的 Jira Filter 使用同一表达式，它仍属于不同治理模型，因为 Filter 还包含数字身份、Owner、共享和可变的保存查询。
核查 Epic 时，可以使用 Atlassian 记录的 parent = SR-6000 查找父工作项的直接子项，但只有 StatusPath Picker 在目标 Jira 语言中成功返回父项后，才能与 Epic 数据源 key 比较。当前简体中文验收环境因 issuetype = Epic 本地化阻塞而无法完成该 Picker 步骤。
计算指标前先验收成员
每种数据源都使用同一条验收规则：
必须纳入 key ⊆ 返回 key
必须排除 key ∩ 返回 key = 空集
每次运行都应记录：
- 执行 Jira 用户或受治理角色；
- 稳定数据源标识和当前标签：Project key、数字 Filter ID 与名称、完整 JQL、Board ID/名称与 Sprint ID/名称，或父项 key；
- 验收时间戳和时区；
- 相关 Jira 权限与可见性上下文；
- Work item date range 与 Trim History 的值，包括明确记录为空；
- 返回数量，以及必须纳入和必须排除的结果。
还应在 Jira 中检查至少一个纳入项和一个排除项。只有数量还不够；一项错误纳入与一项遗漏可能让总数保持不变。
成员验收通过后，固定一套指标配置，例如 Time in Status、Work item date range 为空、Trim History 为空以使用完整可用历史、相同状态列、同一个 UTC Calendar 和 Decimal Hours。如果结果不同，先确认返回 key 是否变化，再检查 Trim History、Calendar、时区、Format 或状态配置。
实用的数据源决策顺序
- 先写一句范围定义。 描述工作，而不是控件，例如“SR 和 WEB 中版本 2026.07 尚未解决的高优先级工作”。
- 确认权威边界。 判断该范围由 Project key、Owner 维护的 Filter ID、完整查询、通过 Board 选择的 Sprint ID，还是已验证的父项 key 定义。
- 选择最小且可维护的数据源。 不要只因为 JQL 灵活就使用它，也不要在真实规则更窄时选择 Project。
- 记录负责人和备份人。 明确谁可以批准 Project 约定、Filter 查询和共享、JQL、Sprint 成员或父子规则变化。Board 是 Sprint 选择上下文，不是自动成员条件。
- 测试预期纳入和排除 key。 解释 StatusPath 数值前，先在 Jira 验收总体。
- 保留数据源记录。 保存稳定标识、当前标签、执行用户、验收时间、权限上下文和验收证据。
- 把其余控件单独记录。 分别保存 Work item date range、Trim History、报表类型、Calendar、时区、Format、状态和分组。
常见错误
把最宽的数据源当成最安全的数据源
project = KEY 容易选择，却可能包含当前执行用户可见的不相关团队、工作类型或版本。只有 Project 是目标基础范围时才应选择它，并记录进一步缩小范围的 Work item date range。
复用 Filter 却不记录 Owner
Filter 可以共享和复用，但 Owner 可以修改查询或共享范围。应保存数字 Filter ID、当前名称、Owner、共享、查询、审核时间、执行用户和验收 key。重命名或同名 Filter 会让仅记录名称的证据失去可靠性。
认为 Sprint 名称已经定义总体
StatusPath 需要先选 Board 才能选择 Sprint，但当前成员查询使用所选 Sprint ID。应记录 Board 与 Sprint 身份，用 sprint = ID 验收实际 key，并把受 Board Filter 约束的原生 Sprint Report 作为可能更窄的辅助证据。
把 JQL 当成时长计算
JQL 用于查找匹配工作项，不计算 Jira 状态变化之间的区间。工作项选择与 Time in Status 配置必须分开。
把 ORDER BY 当成成员证据
排序不会增加或删除工作项。应验收 key 集合，单独记录 StatusPath 报表排序，并在确认已安装 Marketplace 版本前，不承诺 Jira 与 StatusPath 行序一致。
认为 Epic 数据源包含所有相关工作项
先确认 Picker 能在目标 Jira 语言和工作类型配置中返回父项。当前简体中文 Jira 验收环境会因 Picker 的 issuetype = Epic 查询而受阻。成功选中后，再核对 parent = key 的直接子项；Link、更深层级和仅提到该 Epic 的工作项不会自动纳入。
比较数据源定义已经变化的报表
即使 Calendar 和状态选择相同，只要 Filter 查询、Work item date range、Sprint 成员、父子关系或 Jira 权限变化，两份报表就不再是同一范围。仅改变 Board Filter 会影响 Picker 或 Jira 原生 Sprint Report 证据；它不会加入最终 StatusPath sprint = ID 成员查询。
常见问题
Jira Filter 与 JQL 相同吗？
不相同。Filter 保存 Jira 查询，并增加数字身份、Owner 和共享方式；内联 JQL 是一段自包含表达式。两者可以使用相同条件，但维护和访问风险仍不同。
JQL 可以计算 Time in Status 吗？
不能。JQL 与可选的 Work item date range 选择匹配工作项；Trim History 决定这些工作项的哪段历史参与计算。Time in Status 还需要状态历史时间戳、Calendar、时区和报表配置。
应使用 Sprint 数据源还是 JQL 中的 sprint = 123？
当 Board 辅助选择和一个 Sprint ID 已经是最清楚的治理定义时，使用 Sprint。在相同 Jira 用户上下文中，当前 Sprint 数据源等价于基础 sprint = ID 成员查询；需要附加条件时再使用 inline JQL。此时应由新增条件解释 key 差异，而不是把差异归因于数据源名称。
Epic 数据源适用于每种 Jira 语言并包含所有后代吗？
不一定。当前 Picker 搜索 issuetype = Epic，已验证的简体中文 Jira 环境不会返回本地化 Epic 工作类型，因此无法创建该来源。如果 Picker 在目标站点成功，StatusPath 会构建 parent = key；应验收这些直接子项 key，不要默认更深后代、Link 或自定义层级类型也会纳入。
Saved Report 会冻结数据源总体吗？
不会。它保存可复用配置。Jira 数据、Filter 条件、Sprint 成员、Epic 子项、权限或可见性变化后，下一次运行可能返回不同工作项。
相关指南
- Jira 工作流报表完整指南：从范围到导出
- 如何使用 JQL 创建 Jira Time in Status 报表
- 如何按 Sprint 创建 Jira Time in Status 报表
- 为什么 Time in Status 报表缺少某个 Jira 状态列
让范围治理与报表结果始终在一起
可辩护的工作流报表会明确谁负责范围、哪些 key 必须纳入或排除，以及使用了哪个数据源版本。在 Atlassian Marketplace 试用 StatusPath Reports，比较 Project、Filter、JQL 和 Sprint 来源。依赖 Epic 前，先确认 Picker 能在目标 Jira 语言中工作，并核对成功选中父项后的 parent = key 结果。将该来源记录与独立的 Work item date range、Trim History 和指标配置一起保存。