sky121113
8f008ffb61
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 52s
1. 強化 B000 登入接口：驗證成功後回傳 Sanctum Token 供後續初始化使用。 2. 實作 B014 (getSettings) API：整合機台、金流與發票設定，並映射至 Android App 預期欄位。 3. 強化安全性：B014 API 掛載 auth:sanctum 並執行 RBAC 權限檢查。 4. 更新 API 說明文件 (iot-spec.md, api-docs.php) 及技術規範 (SKILL.md)。
149 lines
3.9 KiB
Markdown
149 lines
3.9 KiB
Markdown
# IoT API 測試與對接文件 (IoT API Testing & Documentation)
|
||
|
||
本文件紀錄 Star Cloud IoT API 的測試紀錄與對接規格，供後續開發與測試追蹤。
|
||
|
||
---
|
||
|
||
## 🔐 B000: 維運人員登入認證 (Technician Login)
|
||
機台引導階段 (Provisioning) 的第一步，用於核發臨時身份 Token 以便後續下載敏感設定。
|
||
|
||
### 1. API 資訊
|
||
- **Endpoint**: `POST /api/v1/app/admin/login/B000`
|
||
- **認證方式**: 無 (需傳入 `username`, `password`, `machine`)
|
||
- **回應內容**: `token` (Sanctum Token)
|
||
|
||
### 2. 回應範例
|
||
```json
|
||
{
|
||
"message": "Success",
|
||
"token": "3|abcdef1234567890..."
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔑 B014: 機台參數與金鑰下載 (Config Download)
|
||
下載機台運作所需的支付金鑰、電子發票設定與正式通訊 Token。
|
||
|
||
### 1. API 資訊
|
||
- **Endpoint**: `POST /api/v1/app/machine/setting/B014`
|
||
- **認證方式**: **Bearer Token** (需帶上 B000 取得的 Token)
|
||
- **Header**: `Authorization: Bearer {token}`
|
||
|
||
### 2. 請求參數
|
||
- `machine`: 機台序號 (Serial No)
|
||
|
||
### 3. 回應規格 (欄位映射)
|
||
| 欄位 | 說明 | 來源範例 |
|
||
| :--- | :--- | :--- |
|
||
| `t050v01` | 機台序號 | `SN2026041301` |
|
||
| `api_token` | **機台正式 Token** | 後續 B010/B600 認證用 |
|
||
| `t050v41` | 玉山特店編號 | `ESUN_STORE_ID` |
|
||
| `t050v43` | 玉山 Hash Key | `ESUN_HASH` |
|
||
| `t050v34` | 發票特店 ID | `INV_MID` |
|
||
| `TP_APP_ID` | 趨勢支付 AppID | `TP_APP_ID` |
|
||
|
||
### 4. 回應範例 (JSON)
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"data": [
|
||
{
|
||
"t050v01": "SN2026041301",
|
||
"api_token": "mac_token_...",
|
||
"t050v41": "8081234567",
|
||
"t050v42": "9001",
|
||
"t050v43": "password123",
|
||
"t050v34": "2000132",
|
||
"TP_APP_ID": "GREEN_001",
|
||
"...": "..."
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🟢 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」。
|