工程 · 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 保證您能讀到的儲存庫裡。這是這篇文章答案的另一半:佇列不只是被工程化到能挺過訊號死角,它被寫了下來,好讓您能核實它確實如此。