star-cloud/docs/b602_technical_spec.md

B602 API (出貨回傳) 技術規範與執行指南

本文件定義 B602 API 的技術實作規範，用於紀錄機台實體出貨結果，並作為訂單完結與庫存校準的依據。

---

1. 業務邏輯與交易完結

1.1 串聯機制

• 關聯 ID：必須攜帶 B600 取得的 flow_id，以確保出貨紀錄正確鏈結至對應的 orders。

1.2 多品項交易處理 (Multi-item Orders)

• 一對多關係：系統支持一筆訂單（同一個 flow_id）對應多筆 dispense_records。
• 上報方式：機台每完成一個貨道之出貨即呼叫一次 B602。雲端後端將自動彙整所有關聯之出貨紀錄以計算該訂單之總體狀態。

---

2. 庫存一致性機制 (Stock Consistency)

為確保雲端與機台端的物理庫存同步，系統採以下策略：

1. 強制信任機制：系統將「強制信任」機台在 B602 中回報的 remaining_stock (絕對值)，並直接更新資料庫中的貨道庫存。
2. 異常監控：若機台回報的庫存與系統計算的預期值（原值 - 1）不符時，系統應於後台標記該次出貨為「庫存異動異常」，供管理員檢查是否發生卡貨或漏貨。

---

3. 資料庫結構：dispense_records

欄位	說明	備註
order_id	訂單 ID	透過 flow_id 關聯
product_id	商品 ID	出貨之商品
slot_no	貨道編號	出貨之貨道
dispense_status	出貨狀態	0: 成功, 1: 失敗
remaining_stock	剩餘庫存	機台回報之絕對值
source	來源標記	local (B602), remote (B055)

---

4. 數據完整性與異常處理 (Integrity & Exceptions)

4.1 出貨超時監控 (Dispense Timeout)

• 閾值建議：若系統收到 B600 (金流) 超過 5 分鐘 仍未收到任何對應之 B602 (出貨回報)，雲端後台應自動將該訂單標記為 「出貨超時」。
• 用途：此狀態主要用於輔助對帳，標記可能發生網路中斷或機台異常卡死之交易，需由管理員介入核實。

4.2 出貨失敗處理 (Dispense Failure)

• 狀態遷移：當 B602 回報 dispense_status = 1 (失敗) 時，訂單狀態應更新為 「出貨失敗」。
• 即時通知：系統應立即產出 「後台警示通知」 並推播給營運人員，以便快速處理現場排礙或後續補償。
• 補償與維護策略 (現階段)：
  • 點數/優惠券：目前不採自動退回機制，維持異常狀態由管理員人工處理。
  • 營運維護：目前暫不自動產出維護工單或推播給補貨員，僅紀錄於異常日誌並顯示於後台通知區。

---

5. 待確認事項 (已結案)

所有關於出貨流程與超時判定之技術決策已於 2026-03-12 完成確認。