· engineering· 约 27 分钟精读
站点不是一张表:端侧离线台账里分组键的九种写法与一条改不回去的路
对 TagWorks 与 SlingGuard 的 site / location 字段做全链路源码取证:全工程没有站点实体,站点集合每次从设备字符串现采;两条写入口给出两种字节;update 一个没有、一个零调用;检验记录本身不存地点,报告的站点列是从资产当前值回填的。再对照 LOLER 附表 1、AS/NZS 3760:2022 第 2.6 条与 ISO/IEC 17025 第 6.4.13 条,给出五条不需要服务端的改法。
一台电钻登记在 HQ Office,另有一条记录写着它通过了测试。翻遍这条记录,找不到”检验那天它在哪里”这个信息——地点只存在设备那一行里,而那一行永远显示现在的站点。
密旋科技的两款现场工具都有这么一格:TagWorks 叫 site,SlingGuard 叫 location,两款都按它分组、分页、排序,仪表盘还拿它当导航入口。但这格文字没有对应的实体:没有站点表,没有站点选择器,没有改名通道。所谓”站点的全集”,是每次出报告时从所有设备上现采出来的字符串集合。
于是一串具体问题都能逐行指出来:源码里”设备在哪儿”有九种字面量写法、三个互不相同的默认库位;同一段构造里五个字段两种归一化规则,唯独 location 判空用裁剪后的值而落盘用没裁剪的值;一个带前导空格的站点会让下钻漏掉一半设备,报告却照样为它单独起一页。本文把这条链从输入框走到 PDF 页脚,再对照四份法定与标准文本,给出五条不需要服务端的改法。
左右滑动查看完整图表
核心判断是:把分组键当主键用是工具自己做的选择,它也带来了这个选择自带的那类故障。
一、这个字段没有对应的东西
现场交付的第一道筛子通常不是检验类型,也不是日期,而是”东西在哪”:电气检测台账按办公室、仓库、工地分组,吊索具台账按吊索柜、码头分组,上百件设备的报告因此被拆成几页可执行的清单。
密旋科技的两款现场工具都做了这一层,TagWorks 里它叫 site,SlingGuard 里它叫 location。但翻一遍代码会看到一件比”字段叫什么”重要得多的事:这个字段没有对应的东西。全工程没有 struct Site、没有 enum Site、没有站点列表页、没有站点选择器,也没有任何一处把站点当成可被创建、改名或停用的对象。站点只是每台设备身上的一个字符串,“站点的全集”是每次出报告时从所有设备上现采的。
先把这个没被管起来的字段有几种写法数清楚,下表全部取自源码字面量。
| 出现的字面量 | 所在文件与行 | 什么时候进台账 | 会不会进报告 |
|---|---|---|---|
"" 空串 | tagworks/Models/Domain.swift:74 | 建卡时站点留空 | 会,正文里被改名成 Unassigned |
North Warehouse / HQ Office | tagworks/Services/RegisterStore.swift:85-91,112 | 演示数据播种 | 会 |
Main Yard | slingguard/Models/RiggingAsset.swift:144 | 模型 init 参数默认值 | 当前无调用点,进不去 |
Main Rigging Locker | slingguard/Views/AddAssetView.swift:16 | 新建表单输入框预填 | 会,不改就直接进报告 |
Main Locker | slingguard/Views/AddAssetView.swift:133;CSVImporter.swift:111 | 判空后的兜底替换值 | 会,成为一个从没人输入过的站点 |
Central Equipment Depot | slingguard/Models/CompanyProfile.swift:28 | 公司档案默认值,另一套站点 | 会,印在封面 |
North Harbor Yard | slingguard/Services/RiggingStore.swift:112,135 | 档案播种值 | 会,印在封面 |
Unassigned | tagworks/…/ReportExporter.swift:286;slingguard/…/ReportExporter.swift:145 | 渲染时合成,不落盘 | 会,作分页标题 |
Not recorded | slingguard/Services/ReportExporter.swift:125,187 | 档案或设备站点为空白 | 会,作封面与详情行 |
九个字面量、两个字段。“设备在哪儿”这件事,在 SlingGuard 里同时存在 Main Yard、Main Rigging Locker、Main Locker 三个候选默认值,分别来自模型、表单与导入器,互相不知道对方存在。
二、站点不是对象,是每次现采的派生值
TagWorks 报告封面上”站点”那一行是这么来的:
let sites = Set(assets.map { $0.site }.filter { !$0.isEmpty }).sorted()assets 是设备数组。站点列表就是设备上的站点字符串去空、去重、排序,每次出报告现算一遍;SlingGuard 用同一写法算出 locations。这做法省掉一张站点表,代价是站点从此没有自己的身份。
其一,站点没有生命周期,也没有名字之外的属性。 它因为第一台设备建档而出现,因为最后一台被删除而消失,不存在新建、停用、合并这些动作;想按站点写一句”本站点负责人”,没地方写,想让”三楼机房”排在”一楼大厅”后面,也没地方定序。
其二,站点的键与它的显示文本是同一个字符串。 分组表达式的键就是打印出来那句文本,而多出来的 Unassigned 不是数据、是渲染时合成的,既不在表单里也不在落盘文件里。于是同一份 PDF 内部有两套口径:封面站点行取去空后的集合,正文分页取分组字典,后者多一个合成项。封面数出 4 个站点、正文排出 5 页,完全可能。
其三,SlingGuard 那份现采的 locations 没有任何人读。 在 slingguard/Sources 全目录检索,它只出现在 Summary 的字段声明与赋值两处:每份报告都算,算了不进封面、不进正文、不进任何界面,而 TagWorks 那份同源计算至少有仪表盘在用。
三、写入口不对称:判空用裁剪后的值,落盘用没裁剪的值
两款工具各有两条写入路径,四条路径的归一化规则互不相同。看 SlingGuard 的新建表单,同一段构造里相邻字段都在存裁剪后的值:
tagId: tagId.trimmingCharacters(in: .whitespaces).uppercased(),
name: name.trimmingCharacters(in: .whitespaces),
serialNumber: serialNumber.trimmingCharacters(in: .whitespaces),
location: location.trimmingCharacters(in: .whitespaces).isEmpty ? "Main Locker" : location,
manufacturer: manufacturer.trimmingCharacters(in: .whitespaces),location 这一行是整批里唯一的例外:它算了一次裁剪,但结果只用来判断”是不是空”,真正写进台账的是没裁剪的那个值。差别的量纲是一个空格。
| 现场输入 | name 与 manufacturer 落盘 | location 落盘 | 分组结果 |
|---|---|---|---|
Yard A | Yard A | Yard A | 一个站点 |
" Yard A" 前导空格 | Yard A | " Yard A" | 与上一行是两个站点 |
"Yard A " 尾随空格 | Yard A | "Yard A " | 与前两行是第三个站点 |
" " 只有空格 | "" | "Main Locker" | 冒出一个从没人输入过的站点 |
再看 CSV 导入,规则反过来。SlingGuard 的取值闭包对每个字段都做裁剪:
let value: (Int?) -> String = { index in
guard let index, row.indices.contains(index) else { return "" }
return row[index].trimmingCharacters(in: .whitespacesAndNewlines)
}
...
location: value(locationIndex).isEmpty ? "Main Locker" : value(locationIndex),同一个 " Yard A",从表单进来带空格落盘,从 CSV 进来不带:两条通道写进来的同一字段一个被裁剪一个没被裁剪,之后所有按站点分组、排序、比对的地方都会把它们当成两个地方。
TagWorks 更干脆:这一格从头到尾没被碰过。
TextField("Site / room", text: $site)
...
if !store.add(Asset(name: name, identifier: canonicalIdentifier, site: site)) {同一个 add 调用里,identifier 走 AssetIdentifier.canonicalize(去首尾空白、按竖线拆字段、取 ID: 段),site 原样传值;而 CSV 导入侧反而做了裁剪。于是 TagWorks 的口径与 SlingGuard 正好相反:CSV 进来的站点是干净的,手输的是原样的。
手输站点也没有必填闸门,校验只挂在名字上(.disabled(name.isEmpty)),留空可以一路存到底。而 CSV 的列名匹配表里有六个别名(site、location、building、room、area、facility)折叠进同一字段——一台设备的”楼栋”和”房间”在导入时会被压成同一个字符串。
四、下游四种口径,读同一个站点读出四个结论
| 消费点 | 代码位置 | 读法 | 对 " Yard A" 与 "Yard A" 的结论 |
|---|---|---|---|
| 登记册站点下钻 | RegisterView.swift:18-19 | 字符串相等,不裁剪不折叠大小写 | 两个入口,各显示一半设备 |
| 报告封面站点行 | ReportExporter.swift:159,213 | 去空后集合再拼接 | 并列印出两个看上去一样的名字 |
| 报告正文分页 | ReportExporter.swift:286-288 | 按原样字符串分组 | 两页,页眉文字肉眼无差 |
| 站点入口是否出现 | Domain.swift:74 默认空串 | 空串被过滤剔除 | 无站点设备在仪表盘上没有入口 |
同一个空值在四处得到四种待遇:下钻匹配不上任何入口,封面把它剔掉,正文给它发一个 Unassigned 页,行内拼接又把它整段隐去。一处不留、一处改名、一处藏起来,三个动作同时发生。
五、记录里没有地点:报告的站点是从当前值回填的
TagWorks 的 TestRecord 有设备外键、日期、结论、三项读数、检验员、备注、照片、记录种类、放行授权人、仪器型号、校准日期、规程引用——没有站点。SlingGuard 的 InspectionRecord 同样没有位置字段。检验当时的地点不在证据记录里。
但站点确实印在报告上,它是渲染那一刻从设备上读来的:
let grouped = Dictionary(grouping: assets) { $0.site.isEmpty ? "Unassigned" : $0.site }assets 是这一刻的设备数组,所以报告上”这台设备属于 HQ Office”,准确含义是它现在属于 HQ Office。三年前那次检验发生在哪儿,记录没答,报告也没答,只是借设备的当前值来答。
CSV 侧更直白:测试历史导出用一张字典按设备外键反查,六个字段列全部来自当前设备。
let asset = assetLookup[record.assetID]
...
asset?.name ?? "",
asset?.identifier ?? "",
asset?.site ?? "",?? "" 说明写这段代码时已预期”设备查不到”。一旦查不到,一行真实的检验记录会带着空设备名、空编号、空站点、空类别、空环境、空风险导出,而日期、结论、三项读数仍然完整——台账里多出一条不知道属于谁的检验。
六、一次打错的代价:没有改名通道
TagWorks 的 RegisterStore 提供的改动方法只有 add、addBatch、delete、replaceSnapshot、load、save、flush。没有 update,没有任何形如”把这台设备的站点改成某值”的方法。全工程只有一处直接改写设备字段:
// TestEntryView.swift:268
store.assets[i].lastTestDate = rec.date这是录入时系统自己写的,不是用户改的。用户能改的字段一个也没有,唯一被改动的是 lastTestDate,而且只在证据齐全时前进。
SlingGuard 有 updateAsset,一行实现,按下标整体替换,但它在全部源码里的调用点是零。真正走到 assets[idx] = updated 的只有两处,都是检验结论驱动的状态位与日期回写,并顺手把 updatedAt 推到当前时刻——一个字段名叫”更新”,语义却是”结论变了”。
一个字段都不能改,意味着 Main Locker 那个兜底串要跟着台账走完七年。场景并不复杂:18 件吊索具放在 Crane Yard B,现场图省事接受了表单预填值,报告发出后客户指出库位写错——此时 App 内只有两个选择:接受,或者删了重录。
删除的代价写在两份代码的同一个方法体内:
// TagWorks RegisterStore.swift:232-235
func delete(_ asset: Asset) {
assets.removeAll { $0.id == asset.id }
records.removeAll { $0.assetID == asset.id }
}
// SlingGuard RiggingStore.swift:151-155
public func deleteAssets(ids: Set<UUID>) {
assets.removeAll { ids.contains($0.id) }
records.removeAll { ids.contains($0.assetId) }
releases.removeAll { ids.contains($0.assetId) }
}改一个站点字符串的代价,是那台设备全部检验历史的物理清除,SlingGuard 里还连带隔离与放行链,而这个级联没有确认、没有留痕。工具把不可能的选择摆在现场面前:要么永久错下去,要么删掉法定建议保存七年的证据。
七、法定文本怎么摆这两件事
写进法规的标准,恰恰把”标识这台设备”和”说明在哪儿做的检查”分成两个独立条目。
英国 LOLER 1998 附表 1 列举彻底检查报告应含信息,第 2 条与第 3 条并列:第 2 条是”进行彻底检查的处所的地址”,第 3 条是”足以识别该设备的详情”。前者是事件属性,后者是对象属性。条例第 11 条另设保留期:起重属具报告自出具起保存两年,非属具保留至停止使用。随条例发布的 ACOP(L113)第 365 段要求报告能”清楚识别设备的位置与责任人”。
AS/NZS 3760:2022 的记录条款是 2.6,列举的四项是接地连通电阻、绝缘电阻、泄漏电流、目视检验,没有地点,也没有唯一设备标识符(其 1.4 术语条共 24 条,无唯一标识条目)。2.6.1 在澳大利亚一侧用 should,在新西兰一侧用 shall 并要求附全部被检设备的台账;保留期 2.6.2 宜保留七年。地点不是法定记录要素,“从记录能认出这台设备”才是。
英国 IET 实操规范的模型表格 Form V.1 给出第三种摆法:Address 在表头,一本登记册对应一个处所,行主键是设备编号,Location 只是普通一列。实验室体系再补一层:ISO/IEC 17025:2017 与等同采用的 GB/T 27025-2019 第 6.4.13 条列举设备记录内容,d) 项是”当前的位置”,b) 项是”序列号或其他唯一性标识”,整条以”适用时”起头。
四份文本合起来就是本文论点:位置是属性,标识才是不能含糊的那件事;把属性当主键用,模糊就顺着主键传遍全表。
下钻取左边的集合,正文分组取右边的集合,封面站点行取的是第三个口径。台账里只要存在一个带首尾空白的变体,这个真包含就成立:下钻列不全,报告却照样印出两页看上去同名的表。
八、七天内的一条侧证:考核大纲没有规定台账长什么样
2026 年 11 月 16 日,国家密码管理局连发两则公告:一则公示通过商用密码应用安全性评估业务资质申请材料审查的机构名单(附件按 30 个省级受理组分组,共 81 家机构),一则发布《商用密码检测机构资质认定技术评审能力考核大纲》。逐词检索这份大纲,台账、资产、仪器、归档、保存期限 均为零命中。
这份新文件没有替任何人规定台账长什么样。落下”记录必须可追溯”这条硬约束的是上位规章——《商用密码检测机构管理办法》第十九条要求原始记录与报告归档留存、保证可追溯、保存期限不少于 6 年。它与 AS/NZS 3760 的七年、LOLER 的两年并排起来看,三个体系规定的都是”存多久”与”要能追溯”,没有一个规定”站点必须是一列还是表头”。可追溯是义务,站点建模是设计选择——本文前面那几处口径不一致,没有一处是标准逼出来的。
九、工程线:把分组键降格回属性
以下五条都落在现有代码范围内,不需要服务端。
第一条,把站点收进受管集合,但只收名字。 新增 Site 值类型(名字加稳定 id),建卡表单把输入框换成”从已登记站点里选,或新建站点”。这一步解决两件事:同一个地方不会被拼成三种写法,站点有了改名落点。SlingGuard 那个零调用的 updateAsset 正好可以当这条通道,前提是先接进界面并补变更记录。
第二条,归一化在写入口做,几个字段同一把尺。 抽一个 normalizedField(裁剪加连续空白折叠),设备编号额外大写化,字符串字段一律存归一后的值,CSV 侧共用同一函数:两条通道就不可能给出两种字节。
第三条,空值显式化,不要用字符串冒充一个实在的库位。 三个默认值全删,站点改成可选值,“没填”落成显式状态;报告需要标题时由渲染层写”未分配”,并把这条约定印在首页说明行。空字符串永远不该变成一个看起来真实存在的地方。
第四条,历史事件的属性写进事件记录。 检验记录增加”本次检验所在地点”,由当时的设备站点预填、允许现场改。这一改,第五节”从当前值借答案”的问题才断掉:报告按记录里的地点分组,改站点不再牵动历史;新增字段走增量解码,键缺失时回落。
第五条,改名与删除分家,并把级联代价摆到界面上。 改名产生一条新记录(旧名、新名、谁、何时),历史记录保持被写下时的值;删除设备必须先在确认框里写明”这将同时删除多少条检验记录”,数字当场算出。端侧离线环境里这是最省钱的诚实:没有服务器日志可事后还原,所以事前必须问清。
十、这份普查没有覆盖什么
第一,站点这一列在 AS/NZS 3760 的记录条款里不是法定要素,在 LOLER 附表 1 里对应的是”检查发生的处所”而非”设备的存放地”。本文把它当工程问题讨论,“补上这一列即可满足某标准”的说法排除在外。
第二,两款应用不联网,站点表只在单机内成立。五台手机各建一套站点名,同步靠 CSV 或备份包,归一化再严也无法保证五台机器上的 Main Locker 是同一个柜。这是端侧架构自带的边界。
第三,工具能识别”设备查不到所以六列全空”这种断裂,却无法证明”这条记录当初确实属于这台设备”。记录与设备之间只有那一层 UUID 外键,没有校验和也没有签名;真要防篡改需要链式摘要,那是另一件事,不该被一个站点字段的整改顺手宣称掉。而改名通道一旦开出,也同时开出了”事后重贴地点”的能力:第四条工程线解决显示一致性,解决不了恶意改写,要闭合还需要变更前留痕与系统级保护,ACOP L113 第 373 段说的正是这件事。
十一、结语
一个站点字段在两款现场工具里长这样:没有实体、每次现采、两条写入口给出两种字节、九个字面量互不知晓、四个消费口给出四个结论、update 一个是缺的另一个是死的、级联删除顺手带走全部检验历史。
问题只有一句话:用户做错一次的事,工具没有给任何一次改回来的机会。标准关心能不能从记录认出设备、记录能存多久;站点叫什么名字它不管,工具自己管了,管成了九种写法。
所以整改的落点不在”多补一列”,而在把分组键从主键降回属性:受管的站点名、写入口统一的一把尺、“没填”是一个状态而不是一个假地方、历史事件的地点写进历史事件本身、改名与删除分家并把级联摆在眼前。这五件事在 SwiftUI 与 JSON 快照的范围内全部做得完,不需要一行网络代码:数据不出设备,就意味着设备之内必须把数据的来路、去处与错了之后的补救全部做完。
参考文献
- [1] 英国《1998 年起重设备操作与起重器械条例》(LOLER 1998, SI 1998/2306)附表 1 与第 11 条,引自英国健康与安全执行局官方实务守则 L113 所附法规全文。HSE L113
- [2] HSE, Managing and using lifting equipment: Thorough examination(INDG422)。INDG422
- [3] AS/NZS 3760:2022《在用电气设备与剩余电流装置的服务安全检验与测试》,第 1.4、2.5.2、2.6 条款。SAI Global
- [4] 澳大利亚示范《职业健康与安全条例》第 150 条检测记录四项要素,引自 ACT 通知的执业规范《Managing electrical risks in the workplace》。legislation.act.gov.au
- [5] IET, Model forms for in-service inspection and testing of electrical equipment:Form V.1 与 Form V.2 栏位表。IET 模型表格页
- [6] BS EN 62353:2014《医用电气设备 周期测试与修理后测试》第 6.1 条。IEC 版本页
- [7] MHRA, Managing medical devices: guidance,第 2.4 条。MHRA 指南页
- [8] ISO/IEC 17025:2017《检测和校准实验室能力的通用要求》第 6.4.13、7.4.2 条;等同采用的 GB/T 27025-2019。国家标准全文公开系统
- [9] 国家密码管理局 2026 年 11 月 16 日《关于对通过商用密码检测机构(商用密码应用安全性评估业务)资质申请材料审查的机构名单进行公示的通知》。OSCCA
- [10] 国家密码管理局 2026 年 11 月 16 日《关于发布商用密码检测机构(商用密码应用安全性评估业务)资质认定技术评审能力考核大纲的通知》。OSCCA
- [11] 《商用密码检测机构管理办法》(国家密码管理局令第 2 号)第十九条:原始记录与报告归档留存、保证可追溯、保存期限不少于 6 年。国务院公报