sky121113
773396fc90
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 52s
61 lines
2.4 KiB
Markdown
61 lines
2.4 KiB
Markdown
# 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 完成確認並由系統規劃水位計畫。
|
||
|