foodie-server/docs/order-push-overview.md

訂單推送說明（測試參考）

最後更新: 2026-09-29 用途: 列出訂單流程中所有會觸發推送的場景，供測試驗證。

本文推送文案以繁體中文展示。實際推送時文案會跟隨接收人的語言設置自動切換（支援 簡中 / 越南語 / 英文 / 繁中），但下方表格統一以繁中舉例。

---

一、推送基本說明

• 目前服務端普通業務推送預設仍走 uniPush；現有測試環境的 iOS 通知欄與 App「消息中心」按原流程核對。消息中心由原業務路徑寫入，外部推送投遞成功與否不能只憑消息記錄判定。
• 服務端已有 Android FCM / iOS APNs 原生通道，但尚未啟用，也未包含 App 端 token 上報改造；不要把原生通知欄接收當成本文件目前的既有結果。啟用條件與真機驗收見 specs/033-native-push-routing/quickstart.md。
• 外賣與閃送新單對多名騎手的通知：預設 uni 模式維持原本逐人發送；切到原生模式後，Android 騎手按相同語言文案及訂單資料走騎手端 FCM multicast，iOS 騎手仍逐設備走 APNs。每人的消息中心記錄保持獨立。
• 商家門店訂單通知沿用「已登入且有當前通道可用地址的分管帳號優先；沒有符合條件的分管帳號才由主帳號兜底」的規則，兩類帳號不會同時通知。原生模式用當前 deviceToken 判斷，預設 uni 模式用 cid。
• 推送語言跟隨接收人的語言設置（簡中 / 越南語 / 英文 / 繁中），同一場景不同語言賬號看到的文案不同。
• 正文中的 {訂單號} 是實際訂單編號，會替換成真實號碼。

---

二、推送場景

#	觸發操作	推送對象	標題	通知正文（繁中示例）
1	用戶下單成功	商家	消息	有新訂單,NO:{訂單號}
2a	貨到付款下單成功	商家	消息	有新訂單
2b	貨到付款下單成功	附近騎手	消息	有新訂單
3a	商家點擊「出餐」	用戶	消息	商家已經出餐,訂單號:,NO:{訂單號}
3b	商家點擊「出餐」	騎手	消息	商家已經出餐,訂單號:,NO:{訂單號}
4a	騎手點擊「接單」	用戶	消息	騎手已接單,NO:{訂單號}
4a′	騎手點擊「接單」	商家	消息	騎手已接單,NO:{訂單號}
4b	騎手點擊「取餐」（開始配送）	用戶	消息	騎手配送中,NO:{訂單號}
4c	騎手點擊「送達」	用戶	消息	騎手已送達,NO:{訂單號}
5a	平台後台把訂單改為「騎手已接單」	用戶	消息	騎手已接單,NO:{訂單號}
5a′	平台後台把訂單改為「騎手已接單」	商家	消息	騎手已接單,NO:{訂單號}
5b	平台後台把訂單改為「配送中」	用戶	消息	騎手配送中,NO:{訂單號}
5c	平台後台把訂單改為「已送達」	用戶	消息	騎手已送達,NO:{訂單號}

說明：場景 4 是騎手在騎手端 App 操作；場景 5 是平台後台人工改訂單狀態。兩者推送的文案一樣。

---

三、推送文案對照（繁中）

場景 / 含義	繁體中文（zh_TW）
標題（所有推送通用）	消息
有新訂單	有新訂單
商家已經出餐	商家已經出餐,訂單號:
騎手已接單	騎手已接單
騎手配送中	騎手配送中
騎手已送達	騎手已送達

---

四、測試驗證要點

每個場景觸發後，按接收人登錄對應端（用戶 App / 商家端 / 騎手端）檢查：

1. iOS：通知欄收到推送 + App 內消息列表有新記錄。
2. Android（目前預設 uni 模式）：核對 App 內消息列表；FCM 原生通知欄需要切換原生通道及 App 端配套後另行真機驗證。
3. 文案：標題和正文與上表一致；正文末尾的訂單號與實際訂單一致。
4. 多語言：把接收賬號切到不同語言，文案應隨之變成對應語言。
5. 接收人：確認只有「推送對象」列裡的人收到，其他人不收到。

---

五、已知現狀（測試時知悉即可，不算 Bug）

• 貨到付款下單（場景 2）的通知不帶訂單號：商家 / 騎手通知欄只看到「有新訂單」，看不到具體訂單號（點擊進 App 仍可看到訂單詳情）。
• 商家出餐文案略冗餘：顯示為 商家已經出餐,訂單號:,NO:123（冒號和逗號連在一起），現狀如此。
• 暫不存在的業務通知（本次不在範圍，測試時不用驗證）：取消訂單、退款、超時無騎手、抽成返還、自動恢復營業等通知。Android FCM 服務端能力已實作，但原生模式未啟用、真機推送仍待驗證。