star-cloud/docs/b220_technical_spec.md

B220 API (零錢機庫存變動) 技術規範與執行指南

本文件定義 B220 API 的技術實作規範，用於監控機台內的硬幣與鈔票庫存數量，並提供補幣紀錄與找零水位告警功能。

---

1. 業務情境與數據特性

1.1 數據採集

• 回報內容：機台定期回報各面額（1, 5, 10, 50, 100, 500, 1000 元）的當前累積總量 (Total Amount)。
• 操作識別：
  • account = 0：消費者交易引起的庫存變動。
  • account != 0：管理員或補貨員進行手動補幣或清空錢箱的操作。

1.2 報表與對帳

• 零錢庫存分析：系統必須保留所有變動紀錄，以提供後台「分析報表 > 零錢庫存分析」選單顯示歷史庫存走勢與補幣紀錄。

---

2. 執行面優化與告警 (Execution & Alerts)

2.1 數據處理頻率

• 回報時機：機台在每次交易完成後（包含消費者找零或管理員補幣）即時呼叫 B220 API 回報最新庫存。
• 快取策略：機台各面額的最新總量應快取於 Redis 或更新至 machines 表的擴充欄位，供後台儀表板即時監看。
• 寫入過濾：為節省儲存空間，僅在資料數值有實際變動時才寫入 coin_inventory_logs。

2.2 找零不足告警 (Low Inventory Warning)

當特定面額低於預設的水位閾值時，系統將觸發告警。

建議水位告警計畫 (Threshold Plan)

面額	告警閾值 (枚數)	說明
1 元	< 50	找零頻率高，需預留較快補幣空間
5 元	< 40
10 元	< 40	主要找零面額，需重點監控
50 元	< 20
100 元以上	—	通常不作為找零面額，僅供庫存監控

• 通知管道：
  1. 後台儀表板：在機台管理介面顯示顯眼的「紅字告警」。
  2. 系統推播：即時發送通知給相關營運或補貨人員。

---

3. 資料庫結構：coin_inventory_logs

欄位	說明	備註
machine_id	機台關聯 ID
value_x	各面額數量	包含 1, 5, 10, 50, 100, 500, 1000
account	操作人識別	0 為消費者，其餘為管理員
created_at	紀錄時間

---

4. 待確認事項 (已結案)

所有關鍵決策已於 2026-03-12 完成確認並由系統規劃水位計畫。