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. 待確認事項 (To-be-confirmed)

4.1 訂單完結判斷

1. 超時標記：若雲端收到 B600 但遲遲未收到 B602，預設在多久後應將訂單標記為「出貨超時」？
2. 狀態遷移：出貨失敗 (status=1) 時，訂單的最終顯示文字與處理流程。

4.2 營收與點數處理

3. 出貨失敗補償：若 B602 回報失敗：
   • 行動支付是否自動觸發退款？
   • 是否自動退回該次交易所扣除之會員點數與優惠券？
4. 現金交易失敗：出貨失敗且為現金交易時，是否應產出待維護工單或通知補貨員。