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

docs/b017_technical_spec.md

@@ -0,0 +1,65 @@
+# B017 API (遠端改庫存) 技術規範與執行指南
+
+本文件記錄 B017 API 的業務邏輯與技術執行細節，用於指導後端管理系統遠端調整機台庫存的實作。
+
+---
+
+## 1. 業務情境與觸發機制 (Trigger)
+
+### 1.1 觸發流程
+1.  **管理行為**：管理員在後台管理介面手動修改特定機台的貨道庫存數量。
+2.  **指令預備**：後端系統記錄異動請求，並在該機台的 B010 (心跳) 回應中，將 `status` 設為 `49` (reload B017)。
+3.  **機台拉取**：機台收到心跳回應中的 `49` 代碼後，主動呼叫 B017 API (`/api/app/machine/reload_msg/{workid}`)。
+4.  **數據同步**：機台獲取最新庫存數據並更新本地狀態。
+
+### 1.2 更新範圍
+*   **全量更新 (Full Sync)**：B017 API 回傳該機台**所有貨道**的最新庫存數量，而非僅回傳變動部分。這有助於機台軟體進行「最終狀態一致性」的自我校正。
+
+---
+
+## 2. 資料一致性與日誌 (Consistency & Audit)
+
+### 2.1 更新確認機制
+*   **隱式成功 (Implicit Success)**：機台更新本地庫存後不需要回傳明確的 B017 確認 API。
+*   **驗證方式**：系統將以機台下次呼叫 B010 回報的狀態或機台後續的正常銷售紀錄，視為前次更新成功。
+
+### 2.2 管理員異動日誌 (Audit Log)
+*   **強制要求**：每次後台發起遠端改庫存操作，必須記錄於 `activity_logs` 或特定的 `stock_adjustment_logs`。
+*   *紀錄內容*：管理者 ID、執行時間、機台 ID、調整前後的貨道庫存對照。
+
+### 2.3 庫存衝突處理
+*   *情境*：若雲端下發庫存更新時，機台現場同時發生實體銷售。
+*   *處理原則*：**詳見下方待確認事項**。
+
+---
+
+## 3. 執行面優化 (Execution Strategy)
+
+### 3.1 Redis 緩衝與效能
+*   **快取策略**：機台的貨道結構與庫存數據應快取於 Redis 中。當管理員調整庫存時，同步更新 Redis 與 MySQL。
+*   **讀取優化**：B017 API 應直接從 Redis 讀取數據回傳給機台，以降低 MySQL 的查詢壓力。
+
+---
+
+## 4. 欄位定義與對照
+
+| 欄位名稱 | 資料庫對應 | 說明 |
+|----------|------------|------|
+| `workid` | `machines.serial_no` | 機台識別序號 |
+| `channelid` | `machine_slots.slot_no` | 貨道編號 |
+| `stock` | `machine_slots.stock` | 該貨道的當前可用庫存 |
+
+---
+
+## 5. 開發建議
+*   建立一個專屬的 `StockService` 來處理 Redis 與 DB 的同步，以及異動日誌的寫入。
+*   在 `B010` 的回應邏輯中，檢查 `remote_commands` 是否有 pending 的庫存異動指令，以動態切換 `status: 49`。
+
+---
+
+## 6. 待確認事項 (To-be-confirmed)
+
+1.  **庫存衝突優先權**：當「雲端改庫存」與「現場實體銷售」同時發生時，最終庫存應以何者為準？(待主管確認)。
+2.  **API 欄位對照**：
+    *   `workid` 是否嚴格對應 `serial_no`？
+    *   `channelid` 是否對標 `slot_no`？