---
trigger: always_on
---

# Backend API Specification (api-rules.md)

---

## 🚀 1. 目標範圍與分類

本系統 API 分為兩大類，遵循不同的設計慣例：

*   **Admin/Web API (`/api/v1/...`)**: 供後台管理介面、APP UI 使用。遵循標準 RESTful 與 JSON 結構。
*   **Machine IoT API (`/api/app/...`)**: 供販賣機、計時器等硬體端點使用。需相容既有 PDF 規格（如 B010, B600），欄位命名多為 `req1`, `req2` 或特定縮寫。

---

## 🔐 2. 認證與安全性

*   **Admin API**: 採用 **Laravel Sanctum (Session/Token)** 認證。
*   **Machine IoT API**: 
    *   **核心機制**: 必須在 Header 帶入 `Authorization: Bearer <api_token>` 進行身份驗證。
    *   **Phase 1 (兼容模式)**: 若為相容既有機動硬體，可暫時接受 Request 包含 `key` 欄位，但後端應過渡至 Bearer 驗證。
    *   **安全性強化**: 改用每台機台專屬的 `api_token` (透過 B010 初始化或派發)，並配合 `serial_no` (即 `workid`) 進行資料歸屬權驗證。
*   **傳輸安全**: 必須強制使用 **HTTPS**。

---

## 📦 3. 回應格式規範

### 3.1 標準回應 (Admin/Web API)
```json
{
  "success": true,
  "code": 200,
  "message": "OK",
  "data": { ... }
}
```

### 3.2 IoT 指令回應 (B010/B055 等)
機台端通常透過 response 的 `status` 欄位或特定的 `message` 字串來執行動作：
*   **成功但有指令**: `{"status": "49", "message": "reload B017"}`
*   **純資料回傳**: 直接返回對象陣列或 PDF 定義的欄位。

---

## 🛠️ 4. 主要 Endpoints 與命名慣例

### 4.1 管理類 (Admin UI)
*   `GET /api/v1/users`: 管理員清單
*   `GET /api/v1/machines`: 機台清單
*   `PUT /api/v1/machines/{id}`: 更新機台參數
*   遵循 **kebab-case** 路由與 **snake_case** JSON 欄位。

### 4.2 終端類 (IoT / Machine) — 須嚴格遵守 PDF 規格
*   **API 識別碼 (workid)**: URL 中的 `{workid}` 參數固定為該 API 的功能代碼 (如 `B010`, `B017`, `B600`)，不隨機台改變。
*   **機台識別方式**: 
    1.  **Header**: 透過 `Authorization: Bearer <api_token>` 識別。
    2.  **Request Body**: 透過 `machine` 或 `serial_no` 等欄位識別具體機台。
*   **主要 Endpoint 範例**:
    *   **心跳上報 (B010)**: `POST /api/app/machine/status/B010`
    *   **交易回傳 (B600)**: `POST /api/app/B600` (Body 欄位 `req2` 為機台編號)
    *   **貨道庫存 (B017)**: `POST /api/app/machine/reload_msg/B017`
    *   **遠端出貨 (B055)**: `POST /api/app/machine/dispense/B055`

---

## ⚡ 5. 高併發處理與隊列

為了系統穩定性，以下 API **嚴禁直寫資料庫**，必須進入 **Redis Queue** 異步處理：
1.  **B010**: 心跳上傳（每 5-10 秒一次）。
2.  **B600 / B602**: 交易與出貨紀錄。
3.  **B220**: 零錢機庫存變動。
4.  **B710**: 計時器狀態同步。

後端應立即回傳 `202 Accepted` 或業務定義的成功碼，由 Job 背景完成數據持久化。

---

## 📄 6. 交付與文件
*   **OpenAPI**: 應區分 `admin.yaml` 與 `iot.yaml`。
*   **Postman**: 提供帶有環境變數（機台金鑰、Base URL）的 Collection。