# [暫緩執行] B710 API (計時器狀態回傳) 技術規範與執行指南

本文件定義 B710 API 的技術實作規範，用於處理計時型設備（如洗衣服務、按摩服務）的剩餘時間監測與狀態回報。

---

## 1. 業務流程與資料流

### 1.1 狀態回報
*   **回報內容**：機台定期回報特定貨道 (product/timer) 的 `remaining_seconds` (剩餘秒數) 與目前狀態。
*   **資料用途**：
    *   **即時監控**：供管理後台儀表板顯示設備的使用進度。
    *   **稼動分析**：紀錄設備的總租用時數與閒置率。

---

## 2. 執行面機制 (Execution Strategy)

*   **異步處理**：由於計時狀態可能高頻回報，系統應優先將數據更新至 **Redis 快取**，以確保前端查詢的高效能與資料庫的負擔平衡。

---

## 3. 資料庫結構：`timer_statuses`

| 欄位 | 說明 | 備註 |
|------|------|------|
| `machine_id` | 機台 ID | |
| `product_id` | 產品/服務 ID | |
| `remaining_seconds` | 剩餘秒數 | |
| `status` | 運行狀態 | 1:運行中, 0:停止 |

---

## 4. 待確認事項 (To-be-confirmed)

以下議題目前皆列為**待確認**，將於後續開發階段釐清：

### 4.1 回報頻率與快取
1.  **更新頻率**：確認機台呼叫 B710 的精確頻率，以及資料庫寫入的節流策略（例如：僅在關鍵變動或每分鐘寫入一次）。

### 4.2 遠端通知與異常
2.  **結束通知**：倒數結束時，雲端是否需主動對對消費者發送推播或系統訊息？
3.  **斷線判定**：針對長期未回報的計時器，雲端應自動判定為結束還是異常？

### 4.3 復歸機制
4.  **斷電補償**：機台意外斷電重啟後，是否需向雲端 B010 撈回最後的剩餘秒數以恢復服務？

### 4.4 報表需求
5.  **稼動分析**：後台是否需要針對此數據計算「設備利用率」等績效指標。