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

docs/b600_technical_spec.md

@@ -0,0 +1,52 @@
+# B600 API (消費金流回傳) 技術規範與執行指南
+
+本文件定義 B600 API 的技術實作規範，這是系統處理金流交易、訂單生成與跨 API 關聯的核心。
+
+---
+
+## 1. 交易生命週期與 `flow_id` 串聯
+
+為確保一筆交易數據的完整性，系統採用 `flow_id` 串聯三個連續上報的 API：
+
+1.  **B600 (金流上報)**：
+    *   機台於支付成功後即時呼叫。
+    *   雲端收到後產出專屬的 `flow_id` 並回傳給機台。
+2.  **B601 (發票上報)**：
+    *   機台開立發票後，攜帶 B600 取得的 `flow_id` 呼叫。
+    *   系統根據 `flow_id` 將發票資訊與 `orders` 表關聯。
+3.  **B602 (出貨上報)**：
+    *   機台實體出貨後，攜帶 `flow_id` 呼叫。
+    *   系統根據 `flow_id` 更新訂單的出貨狀態。
+
+---
+
+## 2. 金流類型與標準化
+
+### 2.1 類型定義
+根據 B600 PDF 文件規範 (Req3)，系統優先採用以下預定義類型進行處理與對帳。
+
+### 2.2 防重複上報 (Idempotency)
+為防止網路不穩導致機台重複呼叫 B600，系統必須使用機台產生的 `order_no (tid)` 結合 `machine_id` 作為唯一鍵值校驗。
+
+---
+
+## 3. 執行面優化：異步隊列 (Async Queue)
+
+在高併發環境下，為確保機台端不因等待資料庫寫入而時耗，B600 採以下流程：
+
+1.  **即時回應**：API 接收請求後，將原始 JSON 派發至 **Redis Queue**。
+2.  **背景處理**：由 `ProcessTransaction` 任務異步執行：
+    *   建立 `orders` 與 `order_items`。
+    *   計算並異動會員點數/優惠券。
+    *   同步更新儀表板統計數據。
+3.  **異步回傳**：機台呼叫 API 後會收到 `202 Accepted`，`flow_id` 則透過回應檔同步回傳。
+
+---
+
+## 4. 待確認事項 (To-be-confirmed)
+
+### 4.1 數據完整性稽核
+1.  **自動對帳**：是否需要定期自動比對「B600 收取金額」與「B602 實際出貨金額」，並將差異標記為異常訂單？
+
+### 4.2 失敗補償邏輯
+2.  **出貨失敗處理**：若 B602 回報「出貨失敗」，系統是否需觸發自動退款程序（限線上支付）或發送補發通知？