[DOCS] 新增並更新 Phase 1 核心機台通訊 API 技術規範文件 (B010~B710)

docs/b602_technical_spec.md

@@ -0,0 +1,50 @@
+# 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.  **現金交易失敗**：出貨失敗且為現金交易時，是否應產出待維護工單或通知補貨員。