---
trigger: always_on
---

# Star-Cloud API 整合開發規範

本規範定義了對接 Star-Cloud 後台時的授權與穩定性要求。

## 1. API 授權機制 (Bearer Auth)

> [!IMPORTANT]
> **Star-Cloud 採用的機台預授權模式，要求除 B014 (綁定) 外的所有請求都必須具備身分證明。**

- **機台 Header**：
    - 必須在 Header 帶入 `Authorization: Bearer [MachineToken]`。
    - 即使是管理員登入 (`B000`) 請求，也必須先帶上綁定時獲得的機台 Token。
- **持久化同步**：
    - 任何涉及 `ApiKey` (Token) 的變更，必須同步調用 `StarCloudAPI.persistCurrentSettings()` 寫入資料庫。
    - 嚴禁只更新記憶體變數而不更新 SQLite。

## 2. 網路連線與異常處理規範

- **異常捕捉**：
    - 禁止在網路層級 (Scheduler/API) 使用空白的 catch 區塊。
    - 發生 `IOException` 時，必須將錯誤訊息傳遞至前端 UI 顯示（透過 Toast 或 Handler 訊息）。
- **底層實作建議**：
    - 對於需要高度錯誤診斷的 API（如登入），優先使用原生的 `HttpURLConnection` 封裝，以避開框架內部的隱式錯誤處理。

## 3. 持久化 (Persistence) 邏輯

- **SettingsDao 規則**：
    - 存儲機台設定時應遵循「先刪後插」原則，確保資料庫中針對單一功能（如 `Machine`, `Esunpay`）始終只有一條最新紀錄。