# 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 完成確認。