sky121113
f2147ae6c4
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 1m4s
1. 將 B005 (廣告同步) 從 POST 改為 GET，符合 RESTful 規範。
2. 完善 B009 (庫存回報) 回應規格，加入業務代碼 (200 OK)。
3. API 文件 UI 優化：新增 Method Badge (方法標籤)，並修正 JSON 中文/斜線轉義問題。
4. 機台管理介面優化：實作「唯讀庫存與效期」面板，並將日誌圖示改為「👁️」。
5. 標準化 ID 識別邏輯：資料表全面移除對 sku 的依賴，改以 id 為主、barcode 為輔。
6. 新增 Migration：正式移除 sku 欄位並同步 barcode 指向。
7. 更新多語系支援 (zh_TW, en, ja)。
149 lines
6.4 KiB
Markdown
149 lines
6.4 KiB
Markdown
---
|
||
name: API 技術規格與通訊協議規範
|
||
description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與後端 (Cloud) 通訊的 API 細節、參數命名規則、狀態代碼對照與認證機制，作為系統開發的唯一規格來源。
|
||
---
|
||
|
||
# API 技術規格與通訊協議規範 (API Technical Specs)
|
||
|
||
本文件集中定義所有機台與雲端通訊的 API 規格，確保硬體端與軟體端在資料交換格式與業務定義上保持完全一致。
|
||
|
||
## 1. 核心命名原則
|
||
- **語意化優先**：捨棄舊版 `M_` 前綴，統一使用 snake_case (如 `firmware_version`)。
|
||
- **類型嚴格**：文件定義的類型 (Integer, Float, String) 必須在後端 Model 與前端文件中心嚴格遵守。
|
||
|
||
## 2. 身份認證 (Authentication)
|
||
- **Bearer Token**：所有 API 必須在 Header 帶入 `Authorization: Bearer <api_token>`。
|
||
- **身分綁定**：後端透過 Token 自動識別 `machine_id`，禁止在 Body 帶入 `machine` 或 `key` 欄位。
|
||
|
||
---
|
||
|
||
## 3. 機台核心 API (IoT Endpoints)
|
||
|
||
### 3.1 B000: 機台本地管理員同步登入
|
||
用於機台 Android 端維護人員登入與進入設定頁。此 API 無狀態，且為例外不強制檢查 Bearer Token 的端點。
|
||
|
||
- **URL**: `POST /api/v1/app/admin/login/B000`
|
||
- **Request Body:**
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| `machine` | String | 是 | 機台編號 (serial_no) | `M-001` |
|
||
| `Su_Account` | String | 是 | 系統管理員或公司管理員帳號 | `admin` |
|
||
| `Su_Password` | String | 是 | 密碼 | `password123` |
|
||
| `ip` | String | 否 | 用戶端 IP (相容舊版) | `192.168.1.100` |
|
||
| `type` | String | 否 | 裝置類型代碼 (相容舊版) | `2` |
|
||
|
||
- **Response Body:**
|
||
> [!IMPORTANT]
|
||
> 為了相容 Java APP 現有邏輯，這裡嚴格規定成功必須回傳字串 `Success`。
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `message` | String | 驗證結果 (`Success` 或 `Failed`) | `Success` |
|
||
|
||
---
|
||
|
||
### 3.2 B005: 廣告清單同步
|
||
用於機台端獲取目前應播放的廣告檔案 URL 清單。
|
||
|
||
- **URL**: `GET /api/v1/app/machine/ad/B005`
|
||
- **Request Body:** 無 (GET 請求)
|
||
|
||
- **Response Body:**
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `success` | Boolean | 請求是否成功 | `true` |
|
||
| `code` | Integer | 內部業務狀態碼 | `200` |
|
||
| `data` | Array | 廣告物件陣列 | `[{"t070v04": "https://..."}]` |
|
||
|
||
**data 陣列內部欄位：**
|
||
- `t070v01`: 廣告名稱 (Name)
|
||
- `t070v02`: 播放長度 (Duration) — 秒數，若後台未設定，預設為 15 秒。
|
||
- `t070v03`: 廣告位置 (Position/Flag) — (`3`: 待機廣告, `1`: 販賣頁, `2`: 來店禮)。
|
||
- `t070v04`: 廣告 URL。
|
||
- `t070v05`: 播放順位 (Sort Order)。
|
||
|
||
---
|
||
|
||
### 3.3 B009: 貨道庫存即時回報 (Supplementary Report)
|
||
當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。
|
||
|
||
#### B009 權限驗證邏輯 (RBAC Compliance)
|
||
系統會依據 `account` 欄位進行三層式權限核查：
|
||
1. **系統層 (System Admin)**：當 `company_id` 為 `null` 時，具備全局管理權限，直接放行。
|
||
2. **公司層 (Company Admin)**：當 `is_admin` 為 `true` 時，檢查機台的 `company_id` 是否與該帳號一致。
|
||
3. **人員層 (Operator/User)**：當帳號僅為一般人員時，檢查 `machine_user` 授權表，確認該帳號有被分配至此機台。
|
||
|
||
- **URL**: `PUT /api/v1/app/products/supplementary/B009`
|
||
- **Request Body:**
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| `account` | String | 是 | 操作人員帳號 | `0999123456` |
|
||
| `data` | Array | 是 | 貨道數據陣列 | `[{"tid":"1", "t060v00":"1", "num":"10"}]` |
|
||
|
||
- **data 陣列內部欄位：**
|
||
- `tid`: 貨道編號 (Slot No)
|
||
- `t060v00`: **商品資料庫 ID**
|
||
- `num`: 實體剩餘庫存數量
|
||
|
||
- **Response Body (Success 200):**
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `success` | Boolean | 同步是否成功 | `true` |
|
||
| `code` | Integer | 內部業務狀態碼 | `200` |
|
||
| `message` | String | 回應訊息 | `Slot report synchronized success` |
|
||
| `status` | String | 固定回傳 `49` 代表同步完成 | `49` |
|
||
|
||
- **Response Body (Forbidden 403):**
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `success` | Boolean | 同步失敗 | `false` |
|
||
| `status` | String | 回傳空字串 `""` 防止觸發指令 | `""` |
|
||
| `code` | Integer | HTTP 狀態碼 | `403` |
|
||
| `message` | String | 錯誤訊息 | `Unauthorized` |
|
||
|
||
---
|
||
|
||
### 3.4 B010: 心跳上報與狀態同步
|
||
用於確認機台在線狀態、更新感測數據、提交事件日誌並獲取雲端指令。
|
||
|
||
- **URL**: `POST /api/v1/app/machine/status/B010`
|
||
- **Request Body:**
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| `current_page` | Integer | 是 | 當前頁面代碼 (見下表) | `1` |
|
||
| `firmware_version` | String | 是 | 韌體版本號 | `1.0.5` |
|
||
| `model` | String | 是 | 機台型號 | `STAR-V1` |
|
||
| `temperature` | Float | 否 | 環境溫度 | `25.5` |
|
||
| `door_status` | Integer | 否 | 門狀態 (0:關 / 1:開) | `0` |
|
||
| `log` | String | 否 | 事件日誌簡述 | `Door opened` |
|
||
| `log_level` | String | 否 | info, warn, error | `info` |
|
||
| `log_payload` | Object | 否 | 額外日誌 JSON 對象 | `{"code":500}` |
|
||
|
||
- **Response Body:**
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| `success` | Boolean | 請求是否處理成功 | `true` |
|
||
| `code` | Integer | 內部業務狀態碼 | `200` |
|
||
| `message` | String | 回應訊息 | `OK` |
|
||
| `status` | String | **雲端指令代碼** (見下表) | `49` |
|
||
|
||
#### B010 代碼對照表
|
||
|
||
**頁面代碼 (current_page)：**
|
||
- `0`: 離線 / `1`: 主頁面 / `2`: 販賣頁 / `3`: 管理頁
|
||
- `4`: 補貨頁 / `5`: 教學頁 / `6`: 購買中 / `7`: 鎖定頁
|
||
- `60`: 出貨成功 / `61`: 貨道測試 / `62`: 付款選擇
|
||
- `63`: 等待付款 / `64`: 出貨 / `65`: 收據簽單
|
||
- `66`: 通行碼 / `67`: 取貨碼 / `68`: 訊息顯示
|
||
- `69`: 取消購買 / `610`: 購買結束 / `611`: 來店禮
|
||
- `612`: 出貨失敗
|
||
|
||
**雲端指令代碼 (status)：**
|
||
- `49`: reload B017 (貨道同步)
|
||
- `51`: reboot (重啟系統)
|
||
- `60`: reboot card machine (刷卡機重啟)
|
||
- `61`: checkout (觸發結帳)
|
||
- `70`: unlock (解鎖)
|
||
- `71`: lock (鎖定)
|
||
- `85`: reload B0552 (遠端出貨)
|
||
- `待定義`: change (遠端找零 - 註：指令中心有此功能，但目前 Java App 尚無對接對應的連動事件)
|