star-cloud/docs/b017_technical_spec.md

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 完成確認。