# IoT API 測試與對接文件 (IoT API Testing & Documentation)

本文件紀錄 Star Cloud IoT API 的測試紀錄與對接規格，供後續開發與測試追蹤。

---

## 🟢 B010: 心跳上報與狀態同步 (Heartbeat & Status)
機台定時（建議每 5-10 秒）上送，用於確認連線狀態、溫度及門禁狀態。

### 1. API 資訊
- **Endpoint**: `POST /api/v1/app/machine/status/B010`
- **認證方式**: Bearer Token (或 Request Body 帶 `key`)
- **處理方式**: 異步處理 (Redis Queue)，立即回傳 202。

### 2. 請求範例 (JSON)
```json
{
    "temperature": 5.2,
    "door_status": 0,
    "current_page": "home",
    "firmware_version": "1.0.5",
    "log": "Status heartbeat test",
    "log_level": "info"
}
```

### 3. 回應規格
- **成功**: `202 Accepted`
```json
{
    "success": true,
    "code": 200,
    "message": "OK",
    "status": "49"
}
```

---

## 🔵 B600: 交易紀錄上報 (Transaction Record)
當機台端完成交易（收款或扣點成功）後上傳。

### 1. API 資訊
- **Endpoint**: `POST /api/v1/app/B600`
- **認證方式**: Bearer Token
- **處理方式**: 異步處理 (Redis Queue)。

### 2. 請求範例 (JSON)
```json
{
    "flow_id": "F123456789",
    "total_amount": 100,
    "pay_amount": 100,
    "payment_type": 1,
    "items": [
        {
            "product_id": 1,
            "product_name": "Test Product",
            "price": 50,
            "quantity": 2
        }
    ]
}
```

---

## 📝 測試紀錄 (Test Logs)

### 2026-03-16: B600 交易功能測試
- **測試機台**: `SN001`
- **測試方式**: `curl` 命令模擬
- **驗證項目**:
  - [ ] HTTP 回傳 `202`
  - [ ] 資料庫 `orders` 產生紀錄
  - [ ] 資料庫 `order_items` 產生紀錄
- **結果**: 準備中...

### 2026-03-16: B010 首次演練測試
- **測試機台**: `SN001`
- **測試方式**: `curl` 命令模擬
- **驗證項目**:
  - [x] HTTP 回傳 `202`
  - [x] 資料庫 `machines.last_heartbeat_at` 更新為台北時間
  - [x] `machine_logs` 產生對應日誌
- **測試備註**: 過程中發現 `current_page` 為 `tinyInteger` 導致寫入失敗，已將其修改為 `string` 以支援彈性的頁面名稱。
- **結果**: ✅ **成功 (SUCCESS)**。機台狀態已同步為 5.2度，當前頁面「home」。