挂钟时间精度系统规范
挂钟时间解析系统规范¶
意图¶
在所选时区中查看日期和时间(例如 Schedule 的周视图或日视图)的人,会得到他们请求的日期上的时刻,包括夏令时或其他偏移量变化跳过或重复某个小时的日子。Core 按照 Temporal 的默认 "compatible" 消歧规则,将具名时区中的日历日期和挂钟时间转换为一个时刻,从而使 Astryx 与使用 Temporal 的代码在每个时刻上保持一致。
非目标¶
- 选择或检测时区,以及将时刻格式化为显示形式。
- 公历以外的日历,以及不涉及时区的日期运算。
- 提供其他 Temporal 消歧模式(
"earlier"、"later"、"reject")作为选项。 - 满足本契约的等效内部实现仍然有效。
- 内部模块、文件、函数名、算法、数据结构、存储布局、清单、日志、锁、事务协议以及 CI 作业/工作流拓扑,除非调用方或互操作系统有意将该确切机制作为公共协议依赖,否则属于架构或实现层面。在这种情况下,需说明谁依赖它,以及为什么等效实现无法满足该契约。
需求¶
- FR1 — 每个日期和挂钟时间对应一个时刻。 来自
@astryxdesign/core/utils的plainDateToInstant(date, timezoneID, hour, minute)必须(MUST)为每个有效的日期、挂钟时间和 IANA 时区恰好返回一个时刻,包括偏移量变化跳过或重复的挂钟时间。hour和minute默认为 0。 - FR2 — 被跳过的挂钟时间向前解析。 当偏移量变化跳过该挂钟时间时,结果必须(MUST)是按变化前生效的偏移量读取该挂钟时间,也就是同一个挂钟时间向前移动一个间隔的长度:在从凌晨 2:00 跳到凌晨 3:00 的日子里,凌晨 2:30 解析为凌晨 3:30。
- FR3 — 重复的挂钟时间解析为较早的那次出现。 当偏移量变化使挂钟时间重复时,结果必须(MUST)是其第一次出现,按变化前生效的偏移量读取,无论时区的偏移量为负还是为正。
- FR4 — 一天的开始落在该日。 使用默认时间时,结果是 FR2 或 FR3 对午夜的解析。当时区如常经历午夜,或其偏移量变化恰好在午夜开始时,那就是该日期的第一个时刻:在时区中读回它是同一日期,而早一毫秒的时刻是前一个日期。时区完全跳过的日期解析为间隔之后的第一个时刻,即下一个日期。
平台支持¶
- 支持的功能/引擎下限:Astryx 支持的每个引擎;时区规则来自引擎的
Intl时区数据。 - 不支持的行为:引擎的
Intl无法识别的时区标识符。 - 浏览器证据:不需要。这些需求关乎时刻,并通过针对具名时区的工具测试来证明;绘制范围的组件保留其自身记录所要求的浏览器证据。
当前状态影响¶
@astryxdesign/core/utils中的plainDateToInstant是受治理的 API。- Lab
Schedule通过它将周范围和日范围中的各天转换为时刻;component:Schedule保留对范围选择和布局方式的归属权。 architecture:public-component-api继续拥有该工具的导出与兼容性。
验证¶
| 契约 | 验证 | 代表性状态 | 变更或失败预期 |
|---|---|---|---|
| FR1–FR3 | plainDate.test.ts |
负偏移量导致的午夜被跳过(America/Santiago、America/Havana);凌晨 2:30 的间隔(America/Los_Angeles);30 分钟的间隔(Australia/Lord_Howe);America/Havana 和 Europe/Berlin 中重复的小时 | 将间隔向后解析,或将重复的挂钟时间解析为其较晚出现的那次,会使时刻断言失败。 |
| FR4 | plainDate.test.ts 以及 Schedule 周和日测试 |
Santiago 和 Havana 的转换周和转换日,包括在跳过的午夜结束的一周和一天;Pacific/Apia 跳过的日期(2011-12-30) | 落在前一个日期的日初时刻会使日期往返校验失败,并使周视图和日视图的列数断言失败。 |
决策日志¶
DEC-1 — Core 遵循 Temporal 的“compatible”消歧¶
参考: spec:AST-067/DEC-1
决策者: cixzhang, 2026-10-14
偏移量变化跳过或重复的挂钟时间需要恰好一个答案,Astryx 以及使用 Temporal 或 Date 构造函数的产品代码必须给出相同的答案;否则,在一个中计算出的范围在另一个中读取时会落在不同的日期。Temporal 的默认 "compatible" 模式就是这个答案。该规则属于 Core,因为每个将日期转换为时刻的工具和组件都依赖它,而不仅仅是 Schedule。
否决:仅在 Lab Schedule 内部修正跳过午夜的情况,这会使 Core 的工具对其他所有调用者仍然返回前一个日期的时刻。
开放问题¶
无。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx