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 高頻數據處理 (待確認頻率)

• 快取策略：機台各面額的最新總量應快取於 Redis 或更新至 machines 表的擴充欄位，供後台儀表板即時監看。
• 寫入過濾：為節省儲存空間，建議僅在資料數值有實際變動時才寫入 coin_inventory_logs。

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

• 機制：當特定面額（如 5 元、10 元硬幣）低於預設的水位閾值時，系統應：
  • 在管理後台儀表板顯示紅字告警。
  • （選配）發送推播或系統通知給補貨人員。

---

3. 資料庫結構：coin_inventory_logs

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

---

4. 待確認事項 (To-be-confirmed)

4.1 系統效能與頻率

1. 回報頻率：確認機台呼叫 B220 的頻率（是每次交易後即時回報，還是定時回報？）。

4.2 告警配置

2. 水位閾值：各面額的最低告警水位數值（如 5 元低於多少枚觸發告警）。
3. 通知方式：觸發告警時的具體通知管道。