StatusPath Reports使用指南
Jira 工作流报表如何处理夏令时边界
Jira 工作流报表在纽约春季切换日计入 23 个自然小时、秋季切换日计入 25 个自然小时，可能完全正确。原因是地区时区中的两个本地午夜边界，而不是“一工作日等于 23 或 25 小时”的规则。应使用时间戳时刻、命名地区 Calendar 和 UTC 对照证明结果来自哪项政策。
不要混淆四种时区
- StatusPath Calendar 时区定义哪些本地工作窗口与状态区间相交。
- Jira 用户时区控制该用户在 Jira 中看到的日期时间。
- Jira 站点/系统时区可能影响 Jira 默认值和时间戳表示。
- 趋势分桶时区定义趋势报表中的日或周边界。
本指南只隔离第一项。更完整的政策见时区如何影响 Jira 状态时长和趋势报表与如何跨多个地区统计 Jira 工作流时间。
Atlassian 说明，固定 GMT 偏移不会跟随夏令时变化，而地区时区会应用地区规则。Jira 个人设置控制日期时间展示；Atlassian 的 REST 时间戳文档说明了带时区信息的时间戳。应保留源时刻和偏移。
下方 StatusPath 结果是经过本地核验的产品行为，并不是 Atlassian 对 Marketplace 应用计算方式的承诺。
真实 Jira 场景：相同源区间，两套 Calendar 政策
两个工作项都有完整的 29 小时 In Review 源区间。源区间有意覆盖被测试本地日的前后边界，因此结果由 Calendar 而不是源时长造成：
| 工作项 | 进入 In Review | 离开 In Review | 源自然时长 |
|---|---|---|---|
SR-5501 |
2025-03-09T00:00:00Z |
2025-03-10T05:00:00Z |
29h |
SR-5502 |
2025-11-02T00:00:00Z |
2025-11-03T05:00:00Z |
29h |
报表固定 JQL、状态、完整历史、Trim History 和 Decimal Hours，只更换所选 Calendar：
| Calendar | 时区 | 工作日例外 | 结果 |
|---|---|---|---|
| New York DST transition days | America/New_York |
2025-03-09 与 2025-11-02，均为 00:00-00:00 |
23.00、25.00 |
| UTC 24-hour control days | UTC |
相同日期，均为 00:00-00:00 |
24.00、24.00 |
在 StatusPath 中，开始与结束均为 00:00 的时段表示完整本地日，不是零长度区间；文章演示计算包含该规则的自动化测试。每周排班为空，因此只计入两个明确的工作日例外。
人工计算纽约 Calendar 交集
已经发生的 2025 春季切换：
纽约本地开始：2025-03-09 00:00 UTC-05:00 = 2025-03-09 05:00Z
纽约本地结束：2025-03-10 00:00 UTC-04:00 = 2025-03-10 04:00Z
2025-03-10 04:00Z - 2025-03-09 05:00Z = 23 个自然小时
24h - 1h = 23h
已经发生的 2025 秋季切换：
纽约本地开始：2025-11-02 00:00 UTC-04:00 = 2025-11-02 04:00Z
纽约本地结束：2025-11-03 00:00 UTC-05:00 = 2025-11-03 05:00Z
2025-11-03 05:00Z - 2025-11-02 04:00Z = 25 个自然小时
24h + 1h = 25h
这些数值是各 Calendar 交集内的自然小时，并没有重新定义 StatusPath 中“一个工作日”的长度。
用 UTC 对照证明 Calendar 因果关系
对完全相同的两个源区间使用 UTC 对照 Calendar：
春季对照：2025-03-10 00:00Z - 2025-03-09 00:00Z = 24h
秋季对照：2025-11-03 00:00Z - 2025-11-02 00:00Z = 24h
由于源区间和其他报表输入都未改变，23/25 与 24/24 的差异隔离出了 Calendar 时区和边界的影响。
配置核对
- 在 Jira Activity → History 或 changelog 响应中核对每次状态进入与离开。
- 使用
project = SR AND key in (SR-5501, SR-5502) ORDER BY key ASC固定范围。 - 选择 Time in Status、In Review、完整历史、关闭 Trim History，并使用 Decimal Hours。
- 使用
America/New_York和仅包含两个全日例外的 Calendar，确认23.00与25.00。 - 只把 Calendar 切换到 UTC 对照，确认
24.00与24.00。 - 将 Calendar 名称、IANA 时区、每周排班、例外、历史窗口和运行时间与结果一起保存。
普通办公时间 Calendar 只应计算状态区间与所配置本地工作时段的精确交集。如果时钟切换发生在工作时段之外，计入的工作时间可能完全不变。不能未经重算就把全日 23/25 结果用于 09:00-17:00 政策。
工程警告：不要增加 86,400,000 毫秒
构造“下一个本地午夜”时，不要在一个时刻上直接增加 86,400,000 毫秒。跨时钟切换时，这样会得到 24 个自然小时，并可能落在本地 01:00 或 23:00。正确方式是分别在地区时区中构造两个日历日期的 00:00，把它们各自解析为时刻，再比较两个时刻。应使用经过测试、支持 IANA 时区的日期时间库或运行时。
常见错误
用 GMT-5 表示纽约政策
固定偏移不会自动变成 GMT-4。政策需要跟随地区规则时，应使用 America/New_York。
把 00:00-00:00 当作零时长
在这套 Calendar 配置中，它表示完整本地日。把配置复制到其他产品前，应核对对应产品的规则。
把 23 或 25 小时称为“一个工作日”
这些数值是全日 Calendar 交集中的自然小时。工作日单位与办公时间政策是不同定义。
更换 Calendar 时同时修改源范围
如果工作项、状态、历史窗口或源时间戳同时变化，就无法只归因于 Calendar。
把 Jira 展示时区当作计算政策
应记录 Jira 用户/站点展示环境，但还要单独核对 StatusPath Calendar 时区，以及适用时的趋势分桶时区。
常见问题
每个夏令时切换日都是 23 或 25 小时吗？
不是。这些数值只适用于已经发生的 2025 纽约切换和完整本地日。其他地区、日期、历史规则和部分区间可能不同。
更改 Jira 个人时区会改变源自然区间吗？
它会改变该用户看到的展示文字，但不会改变两个源时刻。StatusPath 工作时间是否计入由所选 Calendar 另行控制。
为什么 UTC 对照是 24/24？
UTC 没有夏令时偏移切换。对照使用每个日期的 00:00Z 到次日 00:00Z，所以交集都是 24 个自然小时。
为什么办公时间报表仍可能显示 8 小时？
如果 09:00-17:00 本地时段不包含时钟切换，其交集仍可能是 8 小时。应计算实际工作窗口交集。
跨周期比较应保留哪些证据？
保留源时间戳、Calendar 名称、IANA 时区、排班、例外、Jira 展示时区、历史控制、适用时的趋势分桶时区、时长格式，以及至少一个人工核对边界。
相关指南
将 Calendar 对照与结果一起保留
可解释的 DST 结果需要源时刻、地区边界、人工减法，以及只更换 Calendar 的对照。前往 Atlassian Marketplace 试用 StatusPath Reports，复现纽约 23/25 与 UTC 24/24 的比较，再使用跨夏令时的工作流指标。