sky121113
773396fc90
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 52s
72 lines
3.2 KiB
Markdown
72 lines
3.2 KiB
Markdown
# 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 完成確認。
|