e779880f9b
1. 整合交易流程：將 B600 (交易紀錄)、B601 (發票紀錄) 與 B602 (出貨紀錄) 整合為單一原子化的 MQTT 'finalize' 操作，確保資料一致性。 2. 實作非同步 Job：新增 ProcessTransactionFinalized Job 負責解析複合式 Payload 並寫入訂單、發票與出貨日誌。 3. 重構交易服務：更新 TransactionService 以支援同時處理訂單與發票資料，並修正產品 ID 驗證邏輯以避免外鍵衝突。 4. 更新技術文件：同步更新 api-docs.php 與 .agents/skills 中的 MQTT 規格，定義詳細的 finalize payload 結構與範例。 5. 優化文件 UI：改善 api-docs.blade.php 的描述渲染，支援換行符號以提升閱讀體驗。 6. 更新監聽指令：在 ListenMqttQueue 中加入 finalize 動作的處理分支並對接至新實作的 Job。
348 lines
14 KiB
Markdown
348 lines
14 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)
|
||
本系統採用兩階段認證模式：
|
||
|
||
### 2.1 維運人員認證 (User Authentication)
|
||
- **核發端點**：B000 (登入)。
|
||
- **使用端點**：B014 (參數下載)。
|
||
- **方式**：使用 Laravel Sanctum 核發之 **User Token**。
|
||
- **Header**：`Authorization: Bearer <user_token>`。
|
||
|
||
### 2.2 機台通訊認證 (Machine Authentication)
|
||
- **適用 API**：B012, B009 等後續通訊。
|
||
- **方式**：使用機台專屬之 **api_token**。
|
||
- **Header**：`Authorization: Bearer <api_token>`。
|
||
|
||
---
|
||
|
||
## 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 |
|
||
| token | String | **臨時身份認證 Token** (用於 B014) | 1|abcdefg... |
|
||
|
||
---
|
||
|
||
### 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)
|
||
當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。
|
||
|
||
|
||
|
||
- **URL**: PUT /api/v1/app/products/supplementary/B009
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body:** 無 (由 Token 自動識別機台)
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| data | Array | 是 | 貨道數據陣列 | [{"tid":"1", "t060v00":"1", "num":"10"}] |
|
||
|
||
- **data 陣列內部欄位：**
|
||
|
||
| 欄位 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| tid | Integer | 貨道編號 (Slot No) | 1 |
|
||
| t060v00 | String | 商品資料庫 ID (或是 Barcode) | "1" |
|
||
| num | Integer | 實體剩餘庫存數量 | 10 |
|
||
| type | Integer | 貨道物理類型 (1: 履帶, 2: 彈簧)。若未提供，預設為 1。 | 1 |
|
||
|
||
> [!TIP]
|
||
> **自動化上限同步邏輯**：
|
||
> 當後端收到 B009 時，會根據 type 自動從該商品的配置中選取 spring_limit 或 track_limit 並自動更新該貨道的 max_stock 欄位。機台端無需手動計算上限。
|
||
|
||
- **Response Body (Success 200):**
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| success | Boolean | 同步是否成功 | true |
|
||
| code | Integer | 內部業務狀態碼 | 200 |
|
||
| message | String | 回應訊息 | Slot report synchronized success |
|
||
| status | String | 固定回傳 49 代表同步完成 | "49" |
|
||
|
||
---
|
||
|
||
|
||
### 3.5 B012: 商品配置與商品主檔同步 (Unified Sync)
|
||
用於機台端獲取目前所有可販售商品的詳細配置。
|
||
|
||
- **URL**: GET /api/v1/app/machine/products/B012
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body:** 無 (由 Token 自動識別機台)
|
||
|
||
#### 運作邏輯 (Client-side Logic):
|
||
- **GET**：執行 **全量同步**。App 應於收到成功回應後，先執行 deleteAll() 再進行 insertAll() 以確保與伺服器完全一致。
|
||
- **PATCH**：執行 **增量更新**。App 於收到成功回應後，僅對記憶體中的既存商品進行欄位值覆蓋 (Patching)。
|
||
|
||
| 欄位 | 型別 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| t060v00 | String | 商品資料庫 ID | "1" |
|
||
| t060v01 | String | 商品名稱 | 可口可樂 330ml |
|
||
| t060v01_en | String | 英文名稱 | Coca Cola |
|
||
| t060v01_jp | String | 日文名稱 | コカコーラ |
|
||
| t060v03 | String | 商品規格/簡述 | Cold Drink |
|
||
| t060v06 | String | 圖片 URL | https://.../coke.png |
|
||
| t060v09 | Float | 標準零售價 | 25.0 |
|
||
| t060v11 | Integer | **貨道庫存上限** (預設履帶) | 10 |
|
||
| t060v30 | Float | 會員價 | 20.0 |
|
||
| t063v03 | Float | 本機銷售價格 (同定價) | 25.0 |
|
||
| t060v40 | String | 行銷計畫 (Marketing Plan) | Buy 1 Get 1 |
|
||
| t060v41 | String | 物料編碼 (Material Code) | SKU-001 |
|
||
| spring_limit | Integer | **彈簧貨道上限** (建議使用此欄位) | 10 |
|
||
| track_limit | Integer | **履帶貨道上限** (建議使用此欄位) | 15 |
|
||
|
||
---
|
||
|
||
### 3.6 B013: [DEPRECATED / REMOVED] 機台故障與異常狀態上報
|
||
> [!WARNING]
|
||
> **此 REST API 已廢棄並移除**。機台異常上報已全面遷移至 **MQTT** 即時通訊架構。
|
||
> 詳細錯誤代碼請參閱：[MQTT 通訊規範 - B013 硬體代碼對照表](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md#32-異常與錯誤上報-b013)
|
||
|
||
### 3.12 B010: [DEPRECATED / REMOVED] 心跳上報與狀態同步
|
||
> [!WARNING]
|
||
> **此 REST API 已廢棄並移除**。機台心跳上報與指令下發已全面遷移至 **MQTT** 架構。
|
||
> (註：溫度數據已標準化為 **Integer**，且雲端採「變動即記錄」規則)。
|
||
> 詳細格式請參閱：[MQTT 通訊規範 - B010 心跳上報](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md#31-心跳上報-b010)
|
||
|
||
---
|
||
|
||
### 3.7 B014: 機台參數與金鑰下載 (Config Download)
|
||
用於機台引導階段 (Provisioning)，向雲端請求支付金鑰、發票設定及機台正式 API Token。
|
||
|
||
- **URL**: GET /api/v1/app/machine/setting/B014
|
||
- **Authentication**: **User Token** (Sanctum Header)
|
||
- **Request Body:** 無 (由 Query String 帶入 `machine` 參數)
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| machine | String | 是 | 機台編號 (serial_no) | M-001 |
|
||
|
||
- **Response Body (Success 200):**
|
||
|
||
| 欄位 (Key) | 說明 | 備註 |
|
||
| :--- | :--- | :--- |
|
||
| **t050v01** | 機台序號 | 即 machine_id |
|
||
| **api_token** | **機台正式 Token** | 初始化後應存於本地，後續 API 認證用 |
|
||
| **t050v41** | 玉山特店編號 | ESUN Merchant ID |
|
||
| **t050v42** | 玉山終端編號 | ESUN Terminal ID |
|
||
| **t050v43** | 玉山 Hash Key | ESUN Hash |
|
||
| **t050v34** | 發票特店 ID | Invoice Merchant ID |
|
||
| **t050v35** | 發票 Hash Key | Invoice Key |
|
||
| **t050v36** | 發票 Hash IV | Invoice IV |
|
||
| **TP_APP_ID** | 趨勢支付 AppID | TrendPay ID |
|
||
| **TP_APP_KEY** | 趨勢支付 Key | TrendPay Key |
|
||
|
||
> [!CAUTION]
|
||
> **安全性規範**：B014 會回傳敏感金鑰與正式 Token，背景必須強制進行 RBAC 校驗。只有當前登入的人員具備該機台管理權限時，後端才允許發放資料。
|
||
|
||
---
|
||
|
||
### 3.8 B017: 貨道庫存同步 (Slot Synchronization)
|
||
用於機台端**主動**向遠端後台拉取目前所有貨道的最新庫存、效期與配置狀態。通常發生於機台開機初始化、補貨/維護模式結束，或是機台需要確保本地端庫存資料與雲端一致時主動請求。
|
||
|
||
- **URL**: GET /api/v1/app/machine/reload_msg/B017
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body:** 無 (由 Token 自動識別機台)
|
||
|
||
- **Response Body:**
|
||
|
||
| 參數 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| success | Boolean | 請求是否成功 | true |
|
||
| code | Integer | 200 | 200 |
|
||
| data | Array | 貨道數據陣列 (依 slot_no 排序) | 見下表 |
|
||
|
||
**data 陣列內部欄位：**
|
||
|
||
| 欄位 | 類型 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| tid | String | 貨道編號 | "1" |
|
||
| num | Integer | 當前庫存數量 | 10 |
|
||
| expiry_date | String | 商品效期 | "2026-12-31" |
|
||
| batch_no | String | 批號 | "B202604" |
|
||
| product_id | Integer | 商品 ID | 1 |
|
||
| capacity | Integer | 貨道容量上限 | 15 |
|
||
| status | String | 貨道狀態 ("1": 啟用, "0": 停用) | "1" |
|
||
|
||
---
|
||
|
||
### 3.9 B660: 取貨碼驗證與消耗 (Pickup Code)
|
||
處理機台端的代碼取貨流程。採用兩階段流程以確保庫存準確性。
|
||
|
||
#### [B660] 取貨碼驗證與消耗 (兩階段)
|
||
* **Path**: `/api/v1/app/machine/pickup/verify/B660`
|
||
* **Method**: `POST` (驗證) / `PUT` (消耗)
|
||
* **Description**: 驗證 8 位數取貨碼，並於出貨完成後回報消耗以扣除庫存。
|
||
|
||
#### [B670] 通行碼驗證 (維護專用)
|
||
* **Path**: `/api/v1/app/machine/passcode/verify/B670`
|
||
* **Method**: `POST`
|
||
* **Description**: 工程人員現場測試專用通行碼，不涉及庫存消耗。
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| code | String | 是 | 使用者輸入的 8 位數取貨碼 | "12345678" |
|
||
|
||
**Response (Success 200):**
|
||
- `pickup_code_id`: 代碼內部 ID，供第二階段 PUT 使用。
|
||
- `slot_no`: 建議出貨貨道。
|
||
|
||
#### B. 消耗階段 (PUT)
|
||
當機台確認出貨成功後發送，雲端此時才正式執行 `decrement` 庫存與標記代碼已使用。
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| pickup_code_id | Integer | 是 | 驗證階段取得的 ID | 45 |
|
||
| status | Integer | 是 | 出貨結果 (1: 成功, 0: 失敗) | 1 |
|
||
|
||
---
|
||
|
||
### 3.10 B670: 通行碼驗證 (Pass Code)
|
||
專供維修或工程人員現場測試使用的通行碼。
|
||
|
||
- **URL**: POST /api/v1/app/machine/passcode/verify/B670
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body:**
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| code | String | 是 | 8 位數通行碼 | "88888888" |
|
||
|
||
**Response (Success 200):**
|
||
- `name`: 持有者姓名 (如：維護部 A 員)。
|
||
- `status`: "active"。
|
||
|
||
> [!WARNING]
|
||
> **鎖定機制**：B660 與 B670 若連續錯誤 5 次，該機台將被鎖定驗證功能 1 分鐘，以防暴力破解。
|
||
|
||
---
|
||
|
||
### 3.10 B027: 贈品碼/優惠券驗證與消耗回報 (Free Gift Verify & Report)
|
||
用於處理行銷贈品券、0 元購活動或特定的優惠券核銷流程。
|
||
|
||
- **URL**: POST|PUT /api/v1/app/sell/free-gift/B027
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **運作模式**:
|
||
- **POST**: 提交 `passCode` 驗證該贈品券是否有效。成功後雲端會回傳對應活動 ID 與商品配置。
|
||
- **PUT**: 當該贈品（0 元商品）出貨完成後，向雲端回報消耗，確保優惠券不會重複核銷。
|
||
|
||
---
|
||
|
||
### 3.11 B650: 會員身分驗證 (Member Verification)
|
||
機台端掃碼後驗證會員身分。
|
||
|
||
- **URL**: POST /api/v1/app/machine/member/verify/B650
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Request Body:**
|
||
|
||
| 參數 | 類型 | 必填 | 說明 | 範例 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| code | String | 是 | 會員代碼 | "MEMBER12345" |
|
||
|
||
---
|
||
|
||
### 3.12 B710: 機台時間同步 (Timer Sync)
|
||
校準機台 RTC 時間。
|
||
|
||
- **URL**: POST /api/v1/app/machine/timer/B710
|
||
- **Authentication**: Bearer Token (Header)
|
||
- **Response:** 回傳當前伺服器 Unix Timestamp。
|
||
|
||
|
||
## 4. 已遷移至 MQTT 的端點索引
|
||
|
||
以下端點的 HTTP REST API 已廢棄，改為透過 MQTT 即時通訊架構處理。詳細的 Payload 定義請參閱 [MQTT 通訊規範](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md)。
|
||
|
||
| 原 API 代碼 | 名稱 | MQTT Topic | 備註 |
|
||
| :--- | :--- | :--- | :--- |
|
||
| B010 | 心跳上報 | `machine/{serial_no}/heartbeat` | [已廢棄](#312-b010-deprecated--removed-心跳上報與狀態同步) |
|
||
| B013 | 異常上報 | `machine/{serial_no}/error` | [已廢棄](#36-b013-deprecated--removed-機台故障與異常狀態上報) |
|
||
| B600 | 交易建立 | `machine/{serial_no}/transaction` | `action: create` |
|
||
| B601 | 發票紀錄 | `machine/{serial_no}/transaction` | `action: invoice` |
|
||
| B602 | 出貨結果 | `machine/{serial_no}/transaction` | `action: dispense` |
|
||
| B600+ | 交易完成(統整) | `machine/{serial_no}/transaction` | `action: finalize` |
|
||
| B055 (PUT) | 遠端出貨回報 | `machine/{serial_no}/command/ack` | GET 查詢路由保留 |
|
||
|
||
---
|
||
|
||
## 附錄 (Appendix)
|
||
|
||
### Appendix A: B600 支付類型對照表 (`payment_type`)
|
||
|
||
此對照表依據機台 B600 規格定義，用於解析 `order.payment_type`：
|
||
|
||
| 代碼 | 支付方式 | 備註 / 說明 |
|
||
| :--- | :--- | :--- |
|
||
| `1` | 信用卡 | 一般實體信用卡刷卡 |
|
||
| `2` | 電子票證 | 包含悠遊卡、一卡通等 |
|
||
| `3` | 掃碼支付 | 一般掃碼支付 |
|
||
| `4` | 投幣機支付 | 實體紙鈔機 |
|
||
| `5` | 通關密碼 | |
|
||
| `6` | 取貨碼 | |
|
||
| `7` | 來店禮 | |
|
||
| `8` | 問卷 | |
|
||
| `9` | 零錢 | 硬幣投幣機 |
|
||
| `21` ~ `25` | 線下付款 + X | `21`=線下+1, `22`=線下+2... `25`=線下+9 |
|
||
| `30` | TapPay - LINE Pay | |
|
||
| `31` | TapPay - 街口支付 | |
|
||
| `32` | TapPay - 悠遊付 | |
|
||
| `33` | TapPay - Pi 拍錢包 | |
|
||
| `34` | TapPay - 全盈+PAY | |
|
||
| `40` | 會員驗證取貨商品 | |
|
||
| `50` ~ `54` | 線下付款 + TapPay | `50`=線下+30, `51`=線下+31... `54`=線下+34 |
|
||
| `60` | 點數 / 優惠卷全額折抵 | 點數全額折抵出貨 或 優惠卷全額折抵出貨 |
|
||
| `61` ~ `69` | 會員 + X | `61`=會員+1, `62`=會員+2... `69`=會員+9 |
|
||
| `90` ~ `94` | 會員 + TapPay | `90`=會員+30, `91`=會員+31... `94`=會員+34 |
|