[DOCS] 新增並更新 Phase 1 核心機台通訊 API 技術規範文件 (B010~B710)

docs/b220_technical_spec.md

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