star-cloud/docs/b017_technical_spec.md

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？