排程工作

Saavo 使用 Cloudflare Workers Cron Triggers 定期啟動系統維護工作。目前專案註冊了三條排程規則，分別負責使用權益週期檢查、過期資料清理，以及統計資料保留期間的清理。

Cron 只負責「準時觸發」。實際工作可能在目前的排程請求中完成，也可能轉換成 Reaction 事件，再交由背景佇列處理。排查問題時，需要繼續確認後續執行流程，不能只看 Cloudflare 是否曾觸發 Cron。

內建排程工作

Cloudflare Cron 依 UTC 時區執行。目前設定如下：

Cron 運算式同時存在於兩個位置：

• wrangler.jsonc 的 triggers.crons，決定 Cloudflare 何時呼叫 Worker。
• src/entry/index.ts 的常數與 scheduledEntry 分支，決定觸發後執行哪項工作。

兩處字串必須完全相同。目前入口沒有針對未知運算式提供專門的錯誤或警示。如果只修改其中一處，Cloudflare 仍可能顯示觸發成功，卻沒有進入任何業務分支。

各項工作如何執行

處理使用權益週期

每日 Cron 會查找下一筆到期紀錄，並發出 EntitlementCycleDueEvent。後續的 process-due-entitlement-cycles 是非同步 Command，預設每批最多處理 30 筆到期紀錄。

使用權益系統也會透過 Timer Durable Object，安排下一次精確重設，並預留 10 秒緩衝。因此，每日 Cron 主要負責定期檢查與復原，不是權益重設唯一依賴的計時器。

清理過期業務資料

資料清理工作會依 UTC 日期產生穩定的等冪鍵，同一天重複觸發，只會產生一次有效事件。背景 Command 會清理過期的登入工作階段、電子郵件驗證工作階段、密碼重設工作階段、OAuth 授權工作階段、失效的 OAuth 權杖與授權碼，以及符合條件且已虛刪除的 OAuth 用戶端。

多數資料以「一天前」作為清理界線，已過期的雙重驗證設定工作階段則會直接清理。不要透過提高 Cron 頻率來改變保留政策，應在負責該資料的服務中調整規則。

清理過期統計資料

統計清理直接在 scheduled 執行階段操作 ANALYTICS_DB，不會進入 async-policy-task。它依批次與執行資源限制，刪除過期的原始事件。一次未清理完的部分，會留給後續 Cron 繼續處理。

保留天數由 config/deploy.ts 的 analytics.retention.rawDays 管理，調整 rawDays 不需要修改 Cron 運算式。具體行為請參考流量統計。

新增排程工作

新增 Cron 時，應完成下列變更：

1. 在 wrangler.jsonc 的 triggers.crons 新增運算式。
2. 在 src/entry/index.ts 定義對應常數。
3. 在 scheduledEntry 新增精確比對的分支。
4. 沿用入口已建立的 scheduled WorkerCtx，將業務規則交給所屬 service。
5. 如果工作耗時較長、需要可靠的重試機制，或會呼叫外部服務，透過 Reaction Event / Command 進入既有的背景工作處理流程。
6. 為新分支補上觸發、重複執行與失敗情境的測試。

不要直接在 scheduledEntry 撰寫 SQL，也不要從非 HTTP 入口呼叫 resolveFetchWorkerCtx。需要非同步執行的業務功能，可以透過 Reaction 加入佇列，後續執行方式請參考背景工作。

部署與排查

部署後，可以在 Cloudflare 儀表板確認 Cron 是否準時觸發。對於進入 Reaction 的工作，也應檢查：

/dashboard/reaction/events
/dashboard/reaction/commands

統計資料清理不經過 Reaction，應查看 scheduled 記錄、警示，以及 ANALYTICS_DB 中超過保留期間的資料是否持續減少。

如果工作沒有執行，請依序排查：

1. 比對 wrangler.jsonc 與入口常數，確認字串與空白完全一致。
2. 確認部署環境使用最新的 Worker 設定。
3. 確認 Cloudflare 已產生 Cron 觸發紀錄。
4. 檢查入口記錄，確認是否進入預期分支。
5. 對於進入 Reaction 的工作，檢查事件、Command 與佇列取用者。
6. 對於直接執行的統計清理，檢查資料庫繫結、保留設定與資料堆積警示。

上線檢查

• wrangler.jsonc 中的三條運算式與入口常數完全相同。
• 已依 UTC 時區核對預期執行時間。
• 三項內建工作都已在部署環境中成功執行至少一次。
• 使用權益週期與資料清理的 Reaction 事件、Command 都有正常紀錄。
• 統計清理沒有持續出現新增速度高於清理速度的資料堆積警示。
• 新增工作已涵蓋重複觸發、部分失敗與安全重試情境。
• 排程入口只負責排程，沒有略過 service 或 repository，直接操作業務資料庫。

常見問題

接下來

• 了解加入佇列後的執行方式：背景工作
• 調整統計資料保留期間：流量統計
• 了解使用權益週期：權限與使用權益