BlueGrove Labs
帮助中心StatusPath ReportsJira Cloud
联系支持
EN

使用指南

如何使用 JQL 创建 Jira Time in Status 报表

使用 JQL 创建 Jira Time in Status 报表时，应先让 JQL 选择工作项范围，在 Jira 中验证查询，再把它作为报表数据源。然后分别设置历史窗口、工作日历、时长格式和状态列。JQL 负责查找匹配的工作项，不会计算每个工作项在状态中停留了多久。

JQL 选择行，变更历史提供时长

Atlassian 将高级搜索定义为使用 JQL 字段、运算符和值查找工作项。查询可以按项目、工作类型、解决状态、日期范围、负责人、标签或状态历史条件选择工作项。得到这些行之后，仍然需要变更历史（changelog）时间戳才能计算 Time in Status。

应明确区分以下定义：

定义 控制内容
JQL 数据源 包含哪些工作项
工作项日期范围（Work item date range） 额外的 Created、Updated 或 Resolved 工作项范围筛选
裁剪历史（Trim History） 所选工作项的哪一段历史参与计算
工作日历与时区 符合条件的区间中哪些时间被计入，但不改变工作项范围
状态列 显示哪些计算时长

真实 Jira 场景：已解决的发布 Story

发布经理需要查询 SR 项目中在 2026 年 7 月 1 日至 7 月 8 日解决的全部 Story：

project = SR
AND issuetype = Story
AND resolution IS NOT EMPTY
AND resolved >= "2026-07-01"
AND resolved < "2026-07-09"
ORDER BY created ASC

使用排他的上边界可以清楚表达时间段：包含 Jira 配置时区中的 7 月 8 日结果，但不包含该时区中从 7 月 9 日开始的结果。Atlassian 的 JQL 字段参考说明了日期值的解释方式。

使用 JQL 数据源配置的 Jira Time in Status 报表
JQL 数据源把项目、工作类型、解决状态和解决日期规则保存在一份可审核的总体定义中。

该查询返回 6 个已解决 Story。StatusPath 再根据独立的报表设置，从历史记录计算 In Progress、In Review 和 QA 时长。

JQL 选择的六个 Jira Story 的 Time in Status 结果
表格将 JQL 选出的工作项范围与计算状态时长列和解决时间放在一起。

计算和边界示例

SR-3001 的所选状态区间为：

状态 时长
In Progress 8 小时
In Review 4 小时
QA 2 小时
所选状态合计 14 小时 
8 小时 + 4 小时 + 2 小时 = 14 小时

SR-3001 创建于 6 月 30 日，解决于 7 月 1 日，因此符合 JQL 的解决日期条件。其 6 月 30 日历史仍属于完整历史计算。增加 resolved 条件只会选择工作项，不会自动把该工作项的历史裁剪到 7 月 1 日。只有业务问题要求裁剪区间时，才使用裁剪历史（Trim History）。JQL 和工作项日期范围控制工作项范围，裁剪历史控制计算窗口，工作日历与时区控制窗口内哪些时间被计入；这些作用不能互相替代。

按步骤创建报表

1. 先写一句工作项范围定义

在写 JQL 前，用自然语言说明总体：“SR 项目中 7 月 1 日至 7 月 8 日解决的 Story。”这样才能验证查询是否正确。

2. 在 Jira 中验证 JQL

在 Jira 高级搜索中运行查询，确认结果数量，并至少抽查一个应包含和一个应排除的工作项。Atlassian 的 JQL 优化建议要求使用至少包含一项搜索限制的有界查询，不要只写 ORDER BY。

3. 在 StatusPath 中选择 JQL 数据源

打开 StatusPath Reports，选择 JQL，粘贴已验证查询并应用。数据源应保存完整查询，而不只是它的文字说明。当前数据源和历史控件见报表设置与范围。

4. 避免重复筛选总体

如果 JQL 已经选择了解决日期范围，应保持独立的工作项日期范围为空，除非确实需要同时应用两层筛选。重叠定义会让漏项更难排查。

5. 决定是否裁剪历史

如果问题要求所选工作项的全生命周期总时长，保留完整历史。如果只统计与报表窗口重叠的时长，则设置裁剪历史，并随报表记录这一选择。

6. 选择日历、格式和状态

设置自然时间或工作时间、时区、时长格式和所需状态列。这些设置影响数值，不影响 JQL 成员。区间模型参见如何计算 Jira Cloud 中的状态停留时间，计算列、筛选和排序见表格视图。

7. 核查并保存

根据 Jira 历史记录手工还原一行，确认报表数量，再保存配置。只有总体和计算设置都通过审核后才导出。

可复制的 JQL 模式

请将示例值替换为你的 Jira 站点中实际存在的名称和日期。Atlassian 正在引入“工作项”和“空间”术语，但其 JQL 迁移说明指出，现有 project 和 issuetype 查询仍然有效，而新术语可能尚未在所有站点可用。

一个项目和工作类型

project = PAY AND issuetype = Bug ORDER BY created ASC

已完成的发布总体

project = PAY
AND issuetype IN (Story, Bug)
AND resolution IS NOT EMPTY
AND resolved >= "2026-07-01"
AND resolved < "2026-08-01"
ORDER BY created ASC

Atlassian 的 JQL 字段参考指出，Resolution 字段不适用于服务团队管理的空间。如果该字段不可用，应使用符合该空间工作流的状态或状态类别条件，并核查返回的总体。

当前处于 Review 的工作项

project = PAY AND status = "In Review" ORDER BY updated DESC

这只选择当前状态，不会包含历史上曾进入 In Review 的全部工作项。

某时段内进入过 Review 的工作项

project = PAY
AND status CHANGED TO "In Review"
  DURING ("2026/07/01", "2026/08/01")
ORDER BY key ASC

CHANGED 运算符可以根据状态历史和日期条件选择工作项。结果用于确定匹配工作项，报表仍然根据变更历史计算时长。

常见错误

期待 JQL 计算时长

JQL 能找到符合当前或历史状态条件的工作项。标准 JQL 不会把两个状态变化之间的区间转换成 Time in Status 列。

把解决日期窗口当成历史窗口

resolved >= ... 根据解决时间筛选工作项，不会丢弃它们更早的状态历史。

对同一总体筛选两次

同时在 JQL 和工作项日期范围中设置解决窗口，可能重复或不一致。尽量保留一个权威定义。

用相对日期制作评审证据

resolved >= -30d 会每天变化。需要其他评审人复现历史报表时，应使用固定日期。

混用 AND 和 OR 时不加括号

Atlassian 的 JQL 运算符参考说明，复杂查询使用括号控制优先级。预期分组不明显时应明确加括号。

把已保存报表当成冻结快照

已保存报表（Saved Report）会按当前可访问 Jira 数据重新运行 JQL。需要时间点文件时，应导出已审核结果。

常见问题

JQL 能直接计算 Jira Time in Status 吗？

不能。JQL 选择匹配工作项；Time in Status 需要状态变化历史中的时间戳。

日期范围应该放在 JQL 还是报表中？

如果日期决定工作项范围，例如“7 月解决的工作项”，放在 JQL 中。如果只统计所选历史与 7 月重叠的部分，则使用裁剪历史。

可以用 status CHANGED 作为数据源吗？

可以。它能选择发生过特定状态变化的工作项，但不会计算停留时长或变化次数。

为什么同一条 JQL 之后返回了不同数量？

Jira 数据、权限和相对日期都会变化；如果 JQL 引用了已保存筛选条件（Saved Filter），该筛选条件的修改也会改变工作项范围。应记录准确查询和生成时间，并使用固定日期制作可复现评审。

JQL 和已保存筛选条件哪个更好？

需要自包含的工作项范围定义时使用 JQL；团队已经维护和治理同一范围时使用已保存筛选条件。两者都需要明确所有者和变更控制。

相关指南

让总体逻辑和时长逻辑保持可见

可复现报表会同时保留准确的 JQL 工作项范围，以及独立的历史、工作日历和状态计算设置。前往 Atlassian Marketplace 试用 StatusPath Reports，通过已验证的 JQL 数据源运行 Time in Status，核查代表性历史，再保存或导出审核结果。

截图预览