Vincent5588 Wiki

多日離線行程設計

閱讀時間約 8 分鐘

多日離線行程設計

探洞 / 雪山 / 沙漠等場景多日無訊號是常態。app 不能假設「網路恢復就能即時同步」——客人可能整週才上線一次。離線優先架構是這個 project 的工程核心。

跟一般小程序的差別

一般 booking app戶外探險 app
訊號假設全程在城市多日無訊號
同步策略即時 push / pull批次同步、回程才送
操作模式即時生效本地排隊 → 同步後生效
失敗處理retry 一兩次多次重試 + 指數退避

三層離線設計

層 1：純讀取（離線可看）

出發前下載到手機本地的內容：

內容大小級數必要
行程詳情 / 時程表< 100 KB🔴 必須
裝備清單 / 行前確認與安全流程 簽過的同意書< 200 KB🔴 必須
領隊聯絡資訊 / 緊急聯絡< 10 KB🔴 必須
離線地圖（路線 + 等高線）5–50 MB🟠 重要
過往團相簿（同行程）10–100 MB🟢 nice

實作：在出發前一天的 Wi-Fi 環境，app 自動下載所有資料到本地 wx.setStorage() + 檔案系統。

層 2：本地操作（離線可寫）

行程中可離線執行的動作：

動作寫到哪裡何時同步
拍照打卡本地相簿 + 暫存 metadata回網路時上傳
GPS 軌跡記錄本地時序 buffer回網路時 batch upload
簽到（團員到齊）本地狀態回網路時同步
SOS 觸發紀錄（離線無法真送，但記錄當下狀態）本地 log回網路時送出 + 通知
Q&A / 心得草稿本地草稿回網路時 publish

實作：所有操作走「outbox queue」模式——寫到本地佇列，上線時依序送出。每筆有 unique ID 防重複。

層 3：批次同步（回網路時）

同步策略：

1. 偵測到網路恢復
2. 顯示「同步中」狀態（讓使用者知道在做事）
3. 批次上傳 outbox queue（按時間順序）
4. 每筆失敗時記錄、繼續下一筆（不阻擋）
5. 全部送完 → 拉取 server 的更新（行程變動、其他團員的內容）
6. 完成 → 清 outbox、更新本地 cache

注意衝突解決：同一筆資料 server 端跟本地都改過怎麼辦？

  • last-write-wins：簡單但可能丟資料
  • CRDT：技術正確但實作複雜
  • 業務解：對探險場景來說，本地優先（畢竟客人在現場才是真相），同步時把 server 端版本當「老資料」覆蓋

技術選型建議

Storage API

選項容量適合
wx.setStorage()10 MB / 域結構化資料（行程、簽到）
wx.saveFile()1 GB / 用戶照片、地圖瓦片、PDF
雲端（騰訊雲開發 / 自建）不限上線時的目標

State 管理

微信小程序框架選擇 提到 wenaox 是輕量 state 管理；本場景適合搭配 outbox queue 設計。

也可以裸寫 — 探險 app 的狀態相對單純（行程 / 客人 / 操作 queue 三大塊），不需要重型 framework。

資料結構建議

每個本地操作物件：

{
  id: "uuid-v4",                          // 唯一 ID 防重複
  type: "checkin" | "photo" | "gps" | "sos",
  payload: { ... },                       // 動作內容
  timestamp: 1714200000000,               // 本地時間
  synced: false,                          // 是否已上傳
  retry_count: 0,                         // 失敗重試次數
  created_offline: true,                  // 是否離線時建立
}

對 UI 的設計含義

同步狀態必須永遠可見

App 頂端 / 底部要永遠顯示同步指示器：

🔴 離線（5 筆待同步）
🟡 同步中（3/5）
🟢 同步完成

不要藏起來——客人需要知道資料安不安全。

操作後立刻反饋成功（樂觀更新）

不要等 server 回應才顯示「成功」——本地寫入後立刻顯示「已記錄」，加個「同步中」icon 即可。

拍照 → 立刻顯示在相簿 → 標「同步中」icon → 上傳成功後 icon 變綠 → 失敗變黃

容錯訊息要明確

不要「網路錯誤」——要「已記錄到本地，待回到有訊號時自動上傳」。降低使用者焦慮。

反模式

❌ 同步用 polling（每 30 秒檢查網路）→ 耗電 ❌ 同步阻塞 UI（等同步完才能繼續用）→ 客人在山上沒得用 ❌ 本地資料沒加版本號（無法處理衝突） ❌ outbox 沒上限（萬一 buffer 爆滿）→ 應有 100 / 500 筆上限，超過提醒使用者 ❌ 同步失敗就丟資料（探險場景照片是無法重來的）

對 戶外探險旅遊小程序核心功能清單 的影響

幾乎所有 v1 + v2 功能都要考慮離線：

功能離線支援
#1 出團列表出發前下載
#2 行前 Q&A出發前 cache
#3 報名支付必須有訊號（沒法離線付）
#4 行前確認出發前完成、行中離線可查
#5 行程公告出發前 cache、行中收不到新公告
#6 領隊資料出發前 cache
#7 SOS離線可記錄、回程同步（真送出要訊號）
#8 離線地圖整個就是這個概念
#9 活動相簿行中拍 + 離線存 + 回程上傳
#10 簽到離線可簽
#11 裝備清單出發前 cache
#12 天氣出發前 cache（行中拿不到 real-time）

相關概念

強連結（戶外探險專屬）

強連結（一般技術）

深入閱讀（外部資源）

← 回到 wiki

關係圖譜

反向連結