sky121113
8ee14eaa29
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 48s
52 lines
2.1 KiB
Markdown
52 lines
2.1 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 高頻數據處理 (待確認頻率)
|
||
* **快取策略**：機台各面額的最新總量應快取於 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. **通知方式**：觸發告警時的具體通知管道。
|