ADR-002: 離線優先同步策略 (Offline-First Sync Strategy)

狀態: 已接受 (Accepted)

日期: 2026-08-02

背景 (Context)

準備認證考試的行動裝置使用者經常在網路連線品質差或無連線的環境中學習 (例如通勤時、偏遠地區)。應用程式必須在離線狀態下可靠地運作，且不能遺失使用者的進度。

決策 (Decision)

使用 PowerSync 結合 SQLCipher 提供本機優先、加密的同步策略。所有的考試互動都會先寫入本機加密的 SQLite 資料庫中，並在恢復連線時非同步同步至後端。

考慮過的替代方案 (Alternatives Considered)

• Firebase 離線持久化:
  • 優點：Firebase 內建，容易啟用。
  • 缺點：快取可能會被作業系統清除，對於長期離線使用不可靠，離線時複雜查詢受限。
• 自訂同步引擎:
  • 優點：完全針對我們的需求量身打造。
  • 缺點：容易出錯，邊緣情況 (衝突解決) 需要大量的開發工作。
• CouchDB/PouchDB:
  • 優點：經過驗證的離線同步。
  • 缺點：Flutter 支援不佳，生態系統不熟悉。

後果 (Consequences)

• 正面影響: 真正的離線能力、即時的 UI 更新 (樂觀 UI)、透過 SQLCipher 確保資料在靜態時的安全。
• 負面影響: 額外的基礎架構設定 (PowerSync 執行個體)、本機結構描述 (schema) 遷移需要仔細管理。

相關文件 (Related Documents)

• 系統設計文件