# 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.  **通知方式**：觸發告警時的具體通知管道。