· engineering· 约 27 分钟精读

Offline Ledger Instant Calendar Day Entry Time Granularity — Technical Analysis | KeyRotate Technology

核心要点速览 · TL;DR 概要

现场合规台账要的是"哪一天检验的",代码里存的是一个带亚秒的瞬间。本文把 TagWorks 与 SlingGuard 的日期取值、落盘、比较、显示四段逐行核对:生产路径 7 处日历运算、界面与报告 8 处格式化,没有一处把时刻折到日界。由此讲清事件日期、录入时刻与到期日三种身份如何在同一条记录上互相顶替,以及哪些后果是当场看得见的。

Offline Ledger Instant Calendar Day Entry Time Granularity — Technical Analysis | KeyRotate Technology

一台电钻在 2026 年 5 月 16 日上午 8 点 52 分通过检验,登记册里那台设备的到期日写的是 2026 年 11 月 16 日。到期那天早上 8 点 12 分打开 App,那一行是正常的;8 点 52 分之后再看,日期字符串一个字没变,那一行变成了逾期。中间没有人改过任何数据。

这不是刷新延迟,也不是时钟抖动。把两款产品的日期取值、落盘、比较、显示四段逐行看完,问题落在一个更靠前的选择上:台账要的是”哪一天”,而系统里从来没有”哪一天”这个类型,只有一个瞬间。

本文只回答四件事:被叫做”日期”的其实是哪几种东西;全工程在哪一处做了换算(一处也没有);由此产生的可见后果;以及若要收敛需要动哪几处。

一条检验记录的粒度阶梯:四段,只有一段被截断采集、落盘、比较用的都是时刻;只有显示这一段折成日历天,而读者看到的正是这一段一、采集Date()亚秒级,随表单创建钟点在这一瞬定下刻度最密二、落盘.deferredToDate写成一个秒数,时刻不缩没有一位被舍掉三、比较due <= now时刻对时刻,两端都没有被归到零点到期落在一天的中间四、显示yyyy-MM-dd钟点在这一步全部消失只剩一格:今天阶梯断点之上的三处口径错配(按两款产品源码逐处核对)事件日期被录入时刻顶替检验日期没有输入位,取的是按下保存的那一瞬间TestRecord(date: .now)日界归一化:全工程零处两款生产路径 7 处日历运算,没有一处把时刻折到零点并列时唯一的次级键是随机串两处次序键用 uuidString,与录入先后与业务都无关台账把「日」印给所有人看,把「时刻」留给判定自己用

左右滑动查看完整图表

一、规范要的是一天,代码里存的是一个瞬间

AS/NZS 3760 与 LOLER 1998 附表一所列的记录要素,落到纸上全是日历日:检验完成的日期、下一次彻底检验的到期日、隔离与放行的日期。ISO 8601 对这两类量本来就有清楚的写法:2026-11-16 是一个日历日期,2026-11-16T08:52:31+10:00 是一个带偏移的时刻;RFC 3339 进一步把后者的语法收紧成协议里可直接使用的形式。规范给了两个类型,是可以选的;而两款 App 都只用了后面那个。

同一条记录上,实际存在四种时间身份:

身份它回答的问题该由谁写应有粒度现场能不能改
事件日期检验是哪一天做的检验员日历天TagWorks 不能;SlingGuard 能改日、改不动钟点
录入时刻这条记录几点写进设备系统自动时刻否,也不该是
到期日下一次必须哪天之前做完由事件日期加周期推算日历天否
整改期限补救要哪天之前完成检验员选日历天能选日

这四栏里只有第二栏在两个工程里有统一且诚实的实现,其余三栏都存在被别的栏顶替的位置。顶替不是某个函数写错了,而是类型选择的结果:只有 Date 一个类型时,四种身份共用同一个值域,比较与格式化都按这个值域的字面语义执行,谁写进去的就是什么。

二、普查:全工程零次日界归一化

“把一个时刻折到某个日历日的起点”在 Swift 里有若干标准写法。把这些关键词在三个产品的 Sources 目录里全量扫一遍:

关键词TagWorksSlingGuardQubitLab
startOfDay000
beginningOfDay000
dateInterval(of:)000
date(bySetting:hour:)000
ordinality(of: .day001
生产路径的日历运算250

生产路径那 7 处日历运算分别是:TagWorks 的到期日月加法与预警窗口数日(Domain.swift 第 83 行、第 125 行);SlingGuard 的四处到期推算(RiggingAsset.swift 第 178 行、InspectionRecord.swift 第 187 行、InspectionEntryView.swift 第 63 行、BatchInspectionView.swift 第 54 行),加上三十天窗口的一次日加法(RiggingAsset.swift 第 199 行)。另有 16 处同样的运算出现在演示数据播种代码里,不参与现场判定。7 处运算的输入全是带时分秒的时刻,输出也全是带时分秒的时刻——没有任何一处折到零点。

作为对照,三款产品里唯一一次真正把日期当”日”来算的代码在 QubitLab:每日挑战用 ordinality(of: .day, in: .year, for: Date()) 取当年第几天再对 28 取模,同一小时内多次进入结果一致,跨过午夜才变。两款工业 App 里没有这一类写法。

显示侧的口径也值得数一遍。两款产品合计 14 处日期格式化调用。面向人读的有 8 处:yyyy-MM-dd 2 处(TagWorks 登记册 CSV、状态标签)、dateStyle = .medium 5 处(两款的报告、资产详情、放行页、标签)、MMM yyyy 1 处(标签的月份格),没有一处输出时分。其余 5 处是 ISO 8601 时刻格式,用在两款的 CSV 导出、SlingGuard 的 CSV 导入与备份文件名上。全工程唯一一次把钟点写进给人看的字符串,是 TagWorks 备份文件名里的 yyyy-MM-dd-HHmmss。换句话说,唯一显式使用”时刻”这个概念的地方是一个文件名;所有给人看的日期,都被截断过。

三、TagWorks:检验日期不是填的,是按下保存那一刻

TagWorks 的判定链需要事件日期,TestRecord.date 是必填字段。它的取值写死在保存函数里:

let rec = TestRecord(assetID: asset.id, date: .now, outcome: storedOutcome, ...)
store.records.append(rec)

录入检验结果的整张表单没有任何”检验日期”输入位。全 App 只有 1 处 DatePicker,绑的是检测仪器的校准日期,还被一个默认关闭的开关门控。新建资产的表单里连 Date 这个字都没出现:AddAssetView.swift 对该关键字零命中。

这不是漏了一个字段,而是模型上没有”事件日期”与”录入时刻”的分栏:TestRecord 结构体里只有一个 date,它同时承担两种含义,于是”检验发生在上周三、我在周五的营地补录”这句话在数据结构里无法表达。

对联网工具来说这行代码无所谓——保存即上传,事件与录入的间隔以秒计,还能用服务器时间纠偏。对一款主打地下室、罐体、强电磁、无网络现场的工具,间隔是按小时和天算的:巡检员通常一次进场地测几十台,出来再统一补记。每一次延迟录入,都在把这台设备的整条到期链向后推。到期日由保存时刻加周期得到:

ddue=add ⁣(tsave, N month)d_{\mathrm{due}} = \mathrm{add}\!\left(t_{\mathrm{save}},\, N\ \mathrm{month}\right)

而法定量应当是事件日期加周期。两者的差恰好等于录入延迟本身,并且这个差会一直留在台账里,不会被任何后续操作纠正。更麻烦的是它不留痕迹:记录里没有第二个时间字段可以反推出”这条是补录的”。

四、SlingGuard:能改的那一天,与改不动的那一个钟点

SlingGuard 的检验日期可以改,DatePicker 直接绑在表单状态上,且没有值域限制:

@State private var date: Date = Date()
DatePicker("Date of Examination", selection: $date, displayedComponents: .date)

问题在这个初值。Date() 是”此刻”,含年月日也含时分秒;displayedComponents: .date 只声明呈现哪几个字段,绑定类型仍然是一个完整的时刻,而代码里没有任何一处把没被呈现的那一段清掉。于是一条检验记录的钟点分量,来自表单被创建的那一瞬间,不来自任何业务事件。更关键的是保存时用的是这个值本身,不再刷新,所以先打开的表单即使最后保存,它的排序键仍然更早。同一天里补两条检验,谁排在前面取决于两个表单各自的创建时刻,而不取决于操作顺序。

同一张表单上还有第二个日期:整改期限。它的初值同样是 Date(),同样只呈现日、同样不折算,而且比检验日期多一层——它从不参与任何时间比较。全工程对它的唯一一次判定是:

if actionDeadline == nil { gaps.append("Action deadline") }

判的是”有没有填”,不是”到没到”。这个期限会被打印到报告与 CSV 里,但没有任何一条代码路径拿它和当前时刻比过。界面上写着的”限期整改”,在判定层是一个纯展示字段。

五处 DatePicker 的分布是:检验日期 2 处(单件与批量)、整改期限 2 处、放行日期 1 处。前四处都没有值域,第五处只有下界:

DatePicker("Release date", selection: $releaseDate, in: quarantine.date..., displayedComponents: .date)

这个下界是”隔离记录的那个时刻”,含它的钟点分量;canSave 里还有一条同源的判定 releaseDate >= quarantine.date。而检验表单的 canSave 只要求结论确认与证据齐备,对日期不做上下界校验——一条被填成下个月的检验记录可以正常落盘。同一台吊具上,隔离记录一旦带上一个未来的钟点,释放页面的选择器下界与保存闸门就同时被推到未来。用户能看到的是两个”日”,被比较的是两个”时刻”。

把两款产品里所有拿日期做比较的位置排在一起:

判定位置写法参与比较的是用户能看到的是
TagWorks 状态due <= now两个时刻两个日期字符串
SlingGuard 状态now > due两个时刻两个日期字符串
SlingGuard 放行闸门releaseDate >= quarantine.date两个时刻一个下界日期
TagWorks 缺陷链retest.date < record.date两个时刻两个日期字符串
SlingGuard 三十天窗口due <= now + 30 day两个时刻一个天数
SlingGuard 整改期限无(只判是否为 nil)——一个期限日期

六行里没有一行例外:判定用时刻,呈现用日,两者之间没有换算。

五、投用日期:模型里有,界面上没有

RiggingAsset 有一个法定含义明确的字段——投用日期:

public var commissionDate: Date
// 初始化签名:commissionDate: Date = Date()

而 AddAssetView 里没有它的输入位。这个字段能取到的值只有两个来源:新建资产时取结构体默认参数(即建档那一刻),或从 CSV 导入时被赋值,而导入路径写的是:

let commissionDate = iso8601.date(from: value(commissionIndex)) ?? Date()

只要那一列不是严格的 ISO 8601 时刻格式——手写的 2024-03-01、被表格软件改成的当地短日期、或者干脆空着——它就静默回落成”现在”,不报错、不计入导入错误数。

它的下游是到期推算:

let baseDate = lastInspectionDate ?? commissionDate

两个事实叠起来的结果是:**一台三年前投用、上个月刚做完首次彻底检验的吊索具,如果因为无网现场来不及当场建档而在今天被补录进登记册,它会获得一个从”今天”起算的完整周期。**LOLER 的周期是从设备投用与检验实际发生之日起算的,不是从它被录入一台手机之日起算的。这里 App 并没有说谎——它只是把”我不知道投用日期”实现成了”投用日期等于我不知道的那一刻”。

未检验资产在状态位上是诚实的:status() 先判 lastInspectionDate != nil,为空即返回”未检验”,不会伪装成在用。但报告的排期列照常打印那个推算出来的到期日,读表的人很难看出它是推算值。

六、到期是一个钟点,不是一天

回到开头那个上午正常、下午逾期的行。链条是这样的:TagWorks 的事件日期取保存瞬间,同一个时刻写进 TestRecord.date,证据齐备时再写进 Asset.lastTestDate;到期日由 Calendar.current.date(byAdding: .month, ...) 加出来,这个运算按日历推进年月、把时分秒原样带过去,所以到期时刻落在到期那一天的 08:52:31;状态判定是 due <= now。于是那一天的 8 点 12 分尚未逾期,8 点 52 分之后就逾期了。SlingGuard 写的是 now > due,运算符方向相反,到期那一刻本身算不算逾期在两款产品里也不一致。

同一条记录的到期日字符串在这一整天里没有任何变化,因为格式化只输出年月日。**用户读到的是一天,判定读到的是一个钟点,而这个钟点从来没有出现在任何界面上。**对”到期日之前完成检验即可”这类合规语义,正确的判定应当是”当地日历日是否已经越过到期日”,也就是在比较之前把两端折到同一个日界——正是全工程零处发生的那一步。

同一件事也影响预警窗口:一端是带钟点的到期时刻,另一端是 now 或 now + 30 day,于是”还剩三十天”会在一天之内随钟点进出窗口,而屏幕上只有日期。

落盘这一段同样记一笔。两款产品都没有改 JSONEncoder / JSONDecoder 的日期策略,用的是默认的 .deferredToDate:一个 Date 被编成”距参考时刻的秒数”这样一个 Double,亚秒分量随小数位一起进文件。于是设备上的台账精确到亚秒,同一份数据的任何人类可读载体精确到日。审计时如果有人质疑”这两条同日记录谁在前”,唯一能回答这个问题的字节,恰好是所有界面都不显示的那一段。

七、同一天并列时,谁算”最后一次”

“最后一次检验记录”是台账里被引用最多的概念——状态、报告结论、标签都挂在它上面。它的求值写法在两款产品里共有 12 处:10 处是 .max { $0.date < $1.date },2 处是 .sorted { $0.date > $1.date } 之后取首位(分别在两款产品的资产详情页)。这两种写法在日期互不相同时等价,在同值时不等价。

Apple 现行文档对 sorted(by:) 明确承诺稳定——对比较器无法定序的元素,保留它们在原序列中的相对次序;而对 max(by:),文档只规定比较器必须是严格弱序、以及不可比关系的传递性,没有对并列情形给出任何裁决承诺。也就是说,那 10 处 .max 在同值时拿到哪一条,取决于遍历与替换的实现细节,而不是规范。

更要紧的是”数组顺序”本身在两款产品里含义相反:TagWorks 追加(store.records.append(rec)),SlingGuard 头插(records.insert(record, at: 0))。一旦并列裁决落到数组顺序上,同一份数据在两款 App 里会指向相反的两条记录。

把这两类求值加上三处正序回放(两款的报告历史链)与两处导出侧的全量排序,两款产品按日期定序的写法共 17 处,其中带次级键的只有 2 处,键都是 $0.id.uuidString。随机版本四 UUID 的字典序能让结果确定,但它编码的是”建对象那一刻随机数发生器的输出”,既不是录入顺序也不是业务顺序。可复现但没有含义的顺序,好写测试,不一定好读报告。

最可惜的是,能解决这个问题的字段就在模型里:InspectionRecord 有独立的 createdAt,在构造时取 Date(),是真正的录入时刻。它出现在属性声明里、初始化参数里、编码键表里——然后在两款产品的全部视图与两路导出里被读取了零次。一条记录上存着两个时间,一个是用户选的日配系统的钟点,一个是纯粹的录入时刻;被用来排序的是前者。

八、要收敛的话,动这五处

以下是给这类端侧离线台账的工程做法,不是本次发布内容。

第一,类型上把日历天与时刻分开。事件日期、到期日、整改期限用日历日表示——落盘成 yyyy-MM-dd 字符串或年月日三元组,比较用日历日比较;“这条记录什么时候写的”仍用 Date。这一步之后,“改日不改钟点”在类型层面就不可能出现。

第二,若坚持用 Date 承载日历语义,归一化必须集中且唯一:所有写入口统一折到当地日界,所有比较只允许调用同一个函数。归一化点要挑在”值刚被用户确定”的那一刻,而不是每个读取点。

第三,把事件日期做成真正可输入、可校验的字段,并给出值域:不早于投用日期、不晚于当前时刻。补录必须允许事件日期早于录入日期,同时保留录入时刻以自证。投用日期同样需要输入位,而不是靠默认参数把”没填”变成”今天”。

第四,把”最后一次”收敛成一个比较器,键为(日历日、录入时刻、标识)三段,两处详情视图与两处导出共用同一个;不要用随机串充当业务顺序。

第五,载体口径要一致。同一份台账,界面给日、PDF 给日、CSV 给带偏移的时刻,三者并存时至少要在表头写明每一列的粒度与时区口径,否则核对的人会拿”日期”去对”时刻”。自检的命令很短:在 Sources 下扫日界归一化关键字,命中数应当不少于比较点数。

九、能力边界

必须把这套工具做不到的事说清楚,避免把它当成时间服务。

归一化改变的是判定的一致性,不是记录的真实性。端侧没有办法证明某个时刻确实发生过——把一个补录的检验日期折到零点,不会让它变成当天做的。所有日期字段的证据强度,上限就是”操作员在本机确认过”这一条。

把时刻折到日界,会丢掉同日多件检的先后信息。折之前得先有一个能表达顺序的东西——录入时刻,或者一个显式序号。在没有录入时刻的模型上直接折日界,会让”同一天上午不合格、下午复试合格”这种情形变成两条无法定序的并列记录,那是用一个不确定换另一个不确定。

跨时区与夏令时的现场里,“同一天”本身不唯一。一个不带偏移的 2026-11-16,必须依赖一个默认约定才有含义,而这个约定既没写在记录里,也没写在报告上。

系统时间被手工改动之后,归一化做得再干净也救不了内容——那是记录时刻的可信度问题,与本文的粒度问题是两件事。本文只处理粒度和身份。

QubitLab 的日历量是”第几天进哪一关”,两款工业 App 的日历量是”哪天之前必须检验”。前者的错误代价是重复玩一关,后者的错误代价是一台带病设备继续在役。这也是本文只讨论后两者的原因。

十、小结

同一条检验记录上,被写进设备的、被拿来判定的、被印给人看的,是三种不同粒度、两种不同来源、四种不同身份的量,而把它们换算一次的地方,全工程一个也没有。

已核对到的具体事实:TagWorks 没有事件日期的输入位,检验日期等于按下保存的那一刻,资产上的日期只在证据齐备时被同一个时刻推进;SlingGuard 允许改日但改不动钟点,钟点来自表单创建且保存时不再刷新;投用日期在两款产品的界面上都不存在,CSV 导入解析失败会静默回落成”现在”;到期日是一个钟点而界面显示一个日,于是同一天的两次求值可以给出两个结论;十二处”最后一次”的求值写法里,两处带次级键,键是随机串;模型里那个真正表示录入时刻的字段,被读取了零次;生产路径 7 处日历运算、面向人读的 8 处格式化,日界归一化 0 处。

“数据不出设备”这件事,最终都要落到这些字段的粒度、来源与身份上。哪天检验的,在法律上是一个日历事实;在代码里,它得先真的成为一个日历日才行。

参考资料

  • [1] Standards Australia & Standards New Zealand. AS/NZS 3760:2022 In-service safety inspection and testing of electrical equipment. 标准页
  • [2] Health and Safety Executive. LOLER 1998: thorough examination of lifting equipment(法定文书 1998/2306,第五部分检验周期与附表一报告要素). LOLER
  • [3] ISO. ISO 8601-1:2019 Date and time — Representation and exchange — Part 1: Basic rules. 标准页
  • [4] IETF. RFC 3339 Date and Time Format on the Internet. RFC 3339
  • [5] Apple. Sequence.sorted(by:)(现行文档承诺排序稳定). sorted(by:)
  • [6] Apple. Sequence.max(by:)(只规定严格弱序,未规定并列裁决). max(by:)
  • [7] Apple. Foundation 的 Calendar 类:按日历单位加算、取日界区间两组 API. Calendar
Share:
Back to Blog