工程 · ArbeitszeitCheck
一次离线打卡的解剖
12:07,工地门口,一格信号都没有。工人照样打了卡。这里是这条打卡在落进工时表之前经历的一切,以及它可能在哪儿出错。
第零分钟:手机连不上服务器
移动应用不会盲目重试,也不会假装成功。这条打卡进入设备上一个加密的 FIFO 队列:AsyncStorage 里的 AES-GCM 密文,数据密钥放在 SecureStore。最后这个细节有真实原因:SecureStore 在 Android 上把值限制在约两 KB,所以那个显而易见的设计(队列放 SecureStore,完事)从来都不存在。队列本身上限 32 条:一个有界缓冲,不是无限承诺。乐观状态立即把工人显示为“已打卡上班”;信号恢复后队列清空。
清空是有意做得较真的:应用在互斥锁下给队列做快照,在锁外做网络活,再把结果合并回去,这样清空期间入队的打卡不会被合并覆盖。这类 bug,只有对并发写入足够偏执才找得到。
重放:先认领,再写入
这条打卡到达服务器时,带着普通打卡没有的两样东西:一个 clientRequestId 和一个 occurredAt 时间戳。服务器不直接应用它。它先写一行认领记录:“这个请求 id 现在归我,结果待定”。然后才去改工时表。如果两次重试撞车,第二次会发现认领已被占,拿到的是第一次尝试的结果,而不是一条重复打卡。
认领行带一个 payload_hash:对动作及其归一化输入做的 sha256。同一个请求 id 配上不同的载荷,得到的是 409,而不是静默覆盖:一个重试“上班打卡”却不小心重发了“下班打卡”的客户端,会看到它能看到的错误,而不是被写坏的数据。待处理超过 300 秒的认领会被回收;整个重放窗口是七天,之后一个清理作业删除这些行。
算数的是谁的钟
手机时钟会漂移,也可能被人故意往回拨,所以合规按 occurredAt 评估:工人真实打卡的那一刻,而不是到达时间。服务器愿意信任这个时间戳到什么程度,是一个有上限的管理员设置,可配置的偏差,往前 24 到 72 小时,往后五分钟。这个上限是故意的;一条“上周四”的打卡需要一个人去看,而不是让一个算法去信。
自助终端这条路径拿到的是同一份契约,加自己的褶皱,一个加密的 NFC 工牌缓存(TTL 七天,上限 500 条),这样地下室走廊里的终端断网时仍能打开正确的操作屏;一次成功的清空还会把新状态写回那个缓存,否则下一次断网会递给工人一批已经错了的操作。
记录在案:还缺什么
两个 缺口。永久失败的打卡会以 failed 标记留在队列里,用户会看到一个 toast,但还没有逐行重试的界面。不认识新字段的旧版本应用则只会在线打卡;什么都不坏,只是没这个功能。两条都写进了决策文档,因为最坏的那种局限,是没人写下来的那种。
完整的决策记录:包括锁顺序和清理作业:就在 AGPL 保证您能读到的仓库里。这是这篇文章答案的另一半:队列不只是被工程化到能挺过信号盲区,它被写了下来,好让您能核实它确实如此。