# B017 API (遠端改庫存) 技術規範與執行指南

本文件記錄 B017 API 的業務邏輯與技術執行細節，用於指導後端管理系統遠端調整機台庫存的實作。

---

## 1. 業務情境與觸發機制 (Trigger)

### 1.1 觸發流程
1.  **管理行為**：管理員在後台管理介面手動修改特定機台的貨道庫存數量。
2.  **指令預備**：後端系統將異動請求寫入 `remote_commands` 表 (type: `stock_update`, payload 含貨道編號與數量)，並在該機台的 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. 欄位定義與對照

| B017 欄位 | 資料庫對應 | 說明 |
|----------|------------|------|
| `channelid` | `machine_slots.slot_no` | 貨道編號 |
| `stock` | `machine_slots.stock` | 該貨道的最新庫存數量 |

---

## 5. 開發建議
*   建立一個專屬的 `StockService` 來處理 Redis 與 DB 的同步，以及異動日誌的寫入。
*   在 `B010` 的回應邏輯中，檢查 `remote_commands` 是否有 pending 的庫存異動指令，以動態切換 `status: 49`。

---

## 6. 庫存衝突處理原則

**以機台實際出貨為最終依據（最終一致性策略）**。

*   **情境**：雲端下發庫存更新（如設為 50），同時機台現場發生實體銷售（賣出 2 個）。
*   **處理原則**：機台在本地執行 `50 - 已出貨量 = 48`，並透過後續的 B602 出貨紀錄上報給雲端，雲端以此為最終庫存數字。
*   **理由**：機台掌握實際出貨資訊，強制以雲端覆蓋將導致帳面庫存與實際庫存不符，引發空貨道但系統顯示有庫存的嚴重問題。

---

## 7. 待確認事項 (已結案)

所有關鍵決策已於 2026-03-12 完成確認。