sky121113
2702e5a655
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 57s
1. 將 B014 (參數下載) 與 B017 (貨道同步) 路由從 POST 改為 GET。 2. 移除 B017 冗餘的 machine 參數，改由 Bearer Token 自動識別。 3. 修正 B017 回傳資料中 expiry_date 的 ISO 8601 格式問題，統一為 Y-m-d。 4. 同步更新所有技術規格文件 (.agents/ 規範) 與 API 說明配置 (config/api-docs.php)。
91 lines
3.9 KiB
Markdown
91 lines
3.9 KiB
Markdown
---
|
||
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>` 識別。針對 B017 等端點，雲端將自動關聯對應機台，**不需**額外帶入機台識別參數。
|
||
2. **Request Body (相容/特定模式)**: 透過 `machine` 或 `serial_no` 等欄位識別。主要用於 B000 登入或尚未取得 Token 的引導階段 (如 B014)。
|
||
* **主要 Endpoint 範例**:
|
||
* **心跳上報 (B010)**: `POST /api/app/machine/status/B010`
|
||
* **交易回傳 (B600)**: `POST /api/app/B600` (Body 欄位 `req2` 為機台編號)
|
||
* **貨道庫存 (B017)**: `GET /api/app/machine/reload_msg/B017`
|
||
* **遠端出貨 (B055)**: `POST /api/app/machine/dispense/B055`
|
||
|
||
---
|
||
|
||
## ⚡ 5. IoT 高併發流向與 MQTT Gateway 整合
|
||
|
||
為了系統穩定性與高吞吐量，機台通訊的架構依循以下規範，**嚴禁直寫資料庫**：
|
||
|
||
### 5.1 MQTT 通訊端點 (高頻與事件驅動)
|
||
以下高頻或即時事件，未來將**全面改採 MQTT 協議**，透過 EMQX 與 Go Gateway 橋接：
|
||
1. **B010 (心跳)**：機台發布至 `machine/{serial_no}/heartbeat`。
|
||
2. **B013 (錯誤與狀態)**：機台發布至 `machine/{serial_no}/error`。
|
||
3. **B600 / B602 (交易紀錄)**：機台發布至 `machine/{serial_no}/transaction`。
|
||
|
||
處理管線：
|
||
`機台 ➜ EMQX ➜ Go Gateway ➜ Redis List (mqtt_incoming_jobs) ➜ Laravel daemon (mqtt:listen) ➜ Job 異步寫入 DB`
|
||
|
||
### 5.2 HTTP 通訊端點 (資料拉取與特殊事件)
|
||
基於歷史相容、大檔傳輸（如 `B012 商品同步`）或高度安全性（如 `B014 金鑰下載`）的端點，維持使用 HTTP REST API。
|
||
若此類 API 產生寫入行為，後端應盡可能立即回傳 `202 Accepted`，並透過 Laravel Job 在背景完成數據持久化。
|
||
|
||
---
|
||
|
||
## 📄 6. 交付與文件
|
||
* **OpenAPI**: 應區分 `admin.yaml` 與 `iot.yaml`。
|
||
* **Postman**: 提供帶有環境變數（機台金鑰、Base URL）的 Collection。
|