# 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 完成確認並由系統規劃水位計畫。