Files
star-cloud/docs/api_analysis.md
sky121113 8ee14eaa29
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 48s
[DOCS] 新增並更新 Phase 1 核心機台通訊 API 技術規範文件 (B010~B710)
2026-03-11 17:37:05 +08:00

475 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Star Cloud API 分析與資料庫結構整理
> 基於 `docs/API/` 中 12 個 PDF 文件的完整分析,整理出 API 端點清單、資料流向及推導出的資料庫結構。
---
## 一、API 端點總覽
| 代碼 | 名稱 | URL | Method | 說明 |
|------|------|-----|--------|------|
| B010 | 機台狀態上傳 & 指令撈回 | `/api/app/machine/status/{workid}` | POST | 機台定期心跳上報(狀態、溫度、門禁、版本),並撈回遠端指令。詳見 [b010_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b010_technical_spec.md) |
| B017 | 遠端改庫存 | `/api/app/machine/reload_msg/{workid}` | POST | 機台撈取最新貨道庫存數量。詳見 [b017_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b017_technical_spec.md) |
| B055 | 遠端出貨(取得指令) | `/api/app/machine/dispense/{workid}` | POST | 機台撈取遠端出貨指令列表。詳見 [b055_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b055_technical_spec.md) |
| B055 | 遠端出貨(狀態回傳) | `/api/app/machine/dispense/{workid}` | PUT | 機台回報出貨結果(成功/失敗)及剩餘庫存。詳見 [b055_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b055_technical_spec.md) |
| B220 | 零錢機庫存變動回傳 | `/api/app/coin/inventory/B220` | POST | 零錢機各面額庫存回傳1/5/10/50/100/500/1000 元)。詳見 [b220_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b220_technical_spec.md) |
| B600 | 消費金流回傳 | `/api/app/B600` | POST | 消費交易核心 API — 記錄金流類型、金額、商品、發票、會員等。詳見 [b600_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b600_technical_spec.md) |
| B601 | 發票資訊回傳 | `/api/app/B601` | POST | 開立發票後回傳發票號碼、日期、隨機碼等。詳見 [b601_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b601_technical_spec.md) |
| B602 | 出貨回傳 | `/api/app/B602` | POST | 出貨結果回傳(商品、貨道、金額、庫存、會員條碼等)。詳見 [b602_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b602_technical_spec.md) |
| B650 | 驗證會員 | `/api/app/B650` | POST | 會員驗證(點數折抵、優惠券、取貨碼、線上訂單線下取貨等)。詳見 [b650_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b650_technical_spec.md) |
| B710 | 計時器狀態回傳 | `/api/app/B710` | POST | 計時型機台的貨道使用狀態與倒數秒數回傳。詳見 [b710_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b710_technical_spec.md) |
---
## 二、API 詳細分析
### 2.1 B010 — 機台狀態上傳 & 指令撈回
**用途**:機台定期向 Cloud 回報自身狀態Cloud 透過 response 中的 `status` 碼下發遠端指令。
**Request 欄位**
| 欄位 | 說明 |
|------|------|
| `key` | API 金鑰 (`KahnEwjhfDBHUYS7`) |
| `machine` | 機台序號 |
| `door` | 門禁狀態(非必填) |
| `temperature` | 溫度 |
| `M_Stus` | 機台型號(非必填) |
| `M_Stus2` | 當前頁面狀態碼 |
| `M_Ver` | 當前軟體版本 |
**頁面狀態碼 (M_Stus2)**
- `0`: 離線, `1`: 主頁面, `2`: 販賣頁, `3`: 管理頁, `4`: 補貨頁, `5`: 教學頁
- `6`: 購買中, `7`: 鎖定頁, `60`: 出貨成功, `61`: 貨道測試, `62`: 付款選擇
- `63`: 等待付款, `64`: 出貨, `65`: 收據簽單, `66`: 通行碼, `67`: 取貨碼
- `68`: 訊息顯示, `69`: 取消購買, `610`: 購買結束, `611`: 來店禮, `612`: 出貨失敗
**遠端指令碼 (Response status)**
- `49`: reload B017 (重新載入庫存), `50`: reload B005, `51`: reboot (重啟)
- `60`: reboot card machine, `61`: checkout, `70`: unlock, `71`: lock
- `72`: sellCode reload B023, `75`: exp reload B026, `79`: read B050
- `81`: sync timer status (B710), `85`: reload B055 (遠端出貨)
---
### 2.2 B600 — 消費金流回傳(核心交易 API
**用途**:記錄每筆消費交易的完整資訊,為最核心的銷售數據 API。
**Request 欄位**
| 欄位 | 參數名 | 說明 | 類型 |
|------|--------|------|------|
| req1 | key | API 金鑰 | String |
| req2 | machine | 機台編號 | String |
| req3 | payment_type | 金流類型代碼 | String |
| req4 | payment_request | 金流送出 data | String |
| req5 | payment_response | 金流回傳 data | String |
| req6 | product_id | 商品 ID | String |
| req7 | amount | 消費金額 | String |
| req8 | invoice_info | 發票歸戶資訊(統編-電話) | String |
| req9 | order_no | APP 定義訂單編號 | String |
| req10 | member_barcode | 掃會員得到的條碼 | String |
| req11 | machine_time | 機台時間 | String |
| req12 | status | 金流狀態 (0: 失敗, 1: 成功, 2: 50 結帳) | String |
| req13 | change_amount | 找零金額 | String |
| req14 | points_used | 使用的點數 | String |
| req15 | reserved | 系統保留 | String |
| req16 | items | 商品明細 `[{pid, amount, num}]` | JsonArray |
**金流類型 (req3) 完整對照**
| 代碼 | 說明 |
|------|------|
| 1 | 信用卡 |
| 2 | 悠遊卡/一卡通 |
| 3 | 掃碼支付 |
| 4 | 手機支付 |
| 5 | 通行碼 |
| 6 | 取貨碼 |
| 7 | 來店禮 |
| 8 | 問卷 |
| 9 | 零錢 |
| 21-25 | 線下付款 + (1/2/3/4/9) |
| 30-34 | TapPay (Line/街口/悠遊付/Pi/全盈+) |
| 40 | 會員驗證取貨商品 |
| 41 | 線上訂單線下結帳 |
| 50-54 | 線下付款 + TapPay 系列 |
| 60 | 點數/優惠券全額折抵 |
| 61-64, 69 | 會員 + (1/2/3/4/9) |
| 70 | 官方 LinePay |
| 90-94 | 會員 + TapPay 系列 |
| 101-109 | 大豐環保點數 + 消費 |
| 110-114, 120 | 大豐環保 + TapPay/LinePay |
---
### 2.3 B650 — 驗證會員
**驗證類型 (req6)**
| req6 | 說明 | Response 特殊欄位 |
|------|------|--------------------|
| 0 | 有點擊商品的驗證 | `userToken`, `amount`, `point`, `respondMSG` |
| 1 | 會員純驗證 | 基本驗證回應 |
| 2 | 會員兌換商品列表 | `productList[{pId, pName, token, validityPeriod, num}]` |
| 3 | 線上訂單線下結帳 | `orderUrl`, `orderNumber`, `orderAmount` |
| 4 | 會員贈品 | — |
**Response 狀態碼**
- `100`: 成功 — 無可用點數
- `101`: 成功 — 全額折抵(點數或優惠券)
- `102`: 成功 — 部分折抵
- `103`: 取貨碼驗證成功
- `104`: 線上訂單驗證成功
- `21`: Key Error, `22`: Time Error, `23`: User Token Error
- `25`: 會員平台錯誤, `30`: 會員正在其他機台使用中
- `35`: 無效優惠券, `40`: 已兌換過, `41`: 無效訂單, `42`: 取貨碼錯誤
---
## 三、資料庫結構推導
根據以上 API 的欄位分析,以下是系統需要的**完整資料庫結構**
### 🟢 已存在的資料表(比對現有 migration
| 資料表 | 說明 | 對應 API |
|--------|------|----------|
| `users` | 後台管理員 | — |
| `machines` | 機台基本資料 | B010, B017, B055, B220, B600, B602 |
| `machine_logs` | 機台日誌 | B010 |
| `app_configs` | APP 設定 | — |
| `members` | 會員資料 | B650 |
| `social_accounts` | 社群帳號 | B650 |
| `member_wallets` | 會員錢包 | B650 |
| `wallet_transactions` | 錢包交易 | B600, B650 |
| `member_points` | 點數帳戶 | B650 |
| `point_transactions` | 點數異動 | B650, B600 |
| `point_rules` | 點數規則 | B650 |
| `membership_tiers` | 會員等級 | — |
| `member_memberships` | 會員等級紀錄 | — |
| `gift_definitions` | 禮品定義 | — |
| `member_gifts` | 禮品發放 | — |
| `deposit_bonus_rules` | 儲值回饋規則 | — |
### 🔴 需新增的資料表
以下是從 API 欄位推導出**目前資料庫中缺少**,但系統運作所必需的資料表:
---
#### 1. `products` — 商品資料
> 來源B600 (req6, req16), B602 (req5), B650 (productList), B710 (pid)
```
products
├── id BIGINT PK
├── name VARCHAR 商品名稱
├── price DECIMAL(10,2) 售價
├── cost DECIMAL(10,2) 成本(選填)
├── category_id BIGINT FK 分類(選填)
├── image VARCHAR 商品圖片 URL
├── barcode VARCHAR 商品條碼
├── description TEXT 商品描述
├── is_active BOOLEAN 是否上架
├── created_at TIMESTAMP
└── updated_at TIMESTAMP
```
---
#### 2. `machine_slots` — 機台貨道
> 來源B017 (tid, num), B055 (res2), B602 (req6, req9), B710 (cid)
```
machine_slots
├── id BIGINT PK
├── machine_id BIGINT FK → machines
├── slot_no VARCHAR 貨道編號 (tid/cid)
├── product_id BIGINT FK → products可空
├── stock INT 當前庫存數量
├── max_stock INT 最大容量
├── is_active BOOLEAN 是否啟用
├── created_at TIMESTAMP
└── updated_at TIMESTAMP
```
---
#### 3. `orders` — 訂單(消費紀錄主表)
> 來源B600 (核心), B601, B602
```
orders
├── id BIGINT PK
├── order_no VARCHAR UNIQUE APP 定義訂單編號 (req9)
├── machine_id BIGINT FK → machines (req2)
├── member_id BIGINT FK → members可空
├── payment_type TINYINT 金流類型代碼 (req3)
├── total_amount DECIMAL(10,2) 消費金額 (req7)
├── change_amount DECIMAL(10,2) 找零金額 (req13)
├── points_used INT 使用的點數 (req14)
├── discount_amount DECIMAL(10,2) 折扣前金額 (req15)
├── payment_status TINYINT 金流狀態 (req12: 0失敗/1成功/2:50結帳)
├── payment_request TEXT 金流送出 data (req4)
├── payment_response TEXT 金流回傳 data (req5)
├── member_barcode VARCHAR 會員條碼 (req10)
├── invoice_info VARCHAR 發票歸戶資訊 (req8)
├── machine_time DATETIME 機台時間 (req11)
├── flow_id VARCHAR Cloud 回傳的金流 ID (B600 response message)
├── created_at TIMESTAMP
└── updated_at TIMESTAMP
```
---
#### 4. `order_items` — 訂單明細
> 來源B600 (req16: `[{pid, amount, num}]`)
```
order_items
├── id BIGINT PK
├── order_id BIGINT FK → orders
├── product_id BIGINT FK → products (pid)
├── quantity INT 數量 (num)
├── unit_price DECIMAL(10,2) 單價 (amount)
├── subtotal DECIMAL(10,2) 小計
├── created_at TIMESTAMP
└── updated_at TIMESTAMP
```
---
#### 5. `invoices` — 發票紀錄
> 來源B601
```
invoices
├── id BIGINT PK
├── order_id BIGINT FK → orders透過 flow_id 關聯)
├── flow_id VARCHAR B600 回傳的金流 ID (req3)
├── machine_id BIGINT FK → machines (req2)
├── rtn_code VARCHAR 發票回傳碼 (req4)
├── rtn_msg VARCHAR 發票回傳訊息 (req5)
├── invoice_no VARCHAR 發票號碼 (req6)
├── invoice_date DATE 發票日期 (req7)
├── random_number VARCHAR 隨機碼 (req8)
├── love_code VARCHAR 愛心碼 (req9)
├── business_tax_id VARCHAR 公司統編 (新增)
├── carrier_id VARCHAR 載具編號 (新增)
├── carrier_type VARCHAR 載具類型 (新增)
├── status TINYINT 發票狀態 (1:有效, 0:作廢)
├── created_at TIMESTAMP
└── updated_at TIMESTAMP
```
---
#### 6. `dispense_records` — 出貨紀錄
> 來源B602, B055
```
dispense_records
├── id BIGINT PK
├── order_id BIGINT FK → orders透過 flow_id 關聯)
├── flow_id VARCHAR 金流 ID (req3)
├── machine_id BIGINT FK → machines (req2)
├── product_id BIGINT FK → products (req5)
├── slot_no VARCHAR 貨道編號 (req6)
├── amount DECIMAL(10,2) 消費金額 (req7)
├── remaining_stock INT 貨道剩餘庫存 (req9)
├── member_barcode VARCHAR 會員條碼 (req10)
├── machine_time DATETIME 機台時間 (req11)
├── coupon_order_no VARCHAR 商品券訂單編號 (req12)
├── dispense_status TINYINT 出貨狀態 (req13: 0成功/1失敗)
├── original_price DECIMAL(10,2) 折扣前金額 (req15)
├── points_used INT 使用的點數 (req16)
├── created_at TIMESTAMP
└── updated_at TIMESTAMP
```
---
#### 7. `remote_dispense_commands` — 遠端出貨指令
> 來源B055
```
remote_dispense_commands
├── id BIGINT PK
├── machine_id BIGINT FK → machines
├── command_id VARCHAR 執行命令 ID (res1)
├── slot_no VARCHAR 貨道 ID (res2)
├── status TINYINT 狀態 (0: 待執行, 1: 出貨成功, 2: 出貨失敗)
├── remaining_stock INT 出貨後剩餘庫存
├── created_at TIMESTAMP
└── updated_at TIMESTAMP
```
---
#### 8. `coin_inventory_logs` — 零錢機庫存紀錄
> 來源B220
```
coin_inventory_logs
├── id BIGINT PK
├── machine_id BIGINT FK → machines
├── value_1 INT 1 元庫存
├── value_5 INT 5 元庫存
├── value_10 INT 10 元庫存
├── value_50 INT 50 元庫存
├── value_100 INT 100 元庫存
├── value_500 INT 500 元庫存
├── value_1000 INT 1000 元庫存
├── account VARCHAR 操作人帳號 (0=消費者)
├── created_at TIMESTAMP
└── updated_at TIMESTAMP
```
---
#### 9. `timer_statuses` — 計時器狀態
> 來源B710
```
timer_statuses
├── id BIGINT PK
├── machine_id BIGINT FK → machines
├── slot_no VARCHAR 貨道 ID (cid)
├── product_id BIGINT FK → products (pid, 0=未設定)
├── status TINYINT 狀態 (0: 未啟用, 1: 使用中, 2: 異常)
├── remaining_seconds INT 剩餘秒數 (num)
├── created_at TIMESTAMP
└── updated_at TIMESTAMP
```
---
#### 10. `payment_types` — 金流類型參照表(建議)
> 來源B600 req3 的龐大對照表
```
payment_types
├── id BIGINT PK
├── code INT UNIQUE 金流類型代碼
├── name VARCHAR 名稱(中文)
├── category VARCHAR 分類(信用卡/電子票證/行動支付/TapPay/會員/環保點數...
├── is_active BOOLEAN 是否啟用
├── created_at TIMESTAMP
└── updated_at TIMESTAMP
```
---
## 四、ER 關係圖
```mermaid
erDiagram
machines ||--o{ machine_slots : "擁有"
machines ||--o{ machine_logs : "產生"
machines ||--o{ orders : "交易於"
machines ||--o{ coin_inventory_logs : "零錢記錄"
machines ||--o{ timer_statuses : "計時器"
machines ||--o{ remote_dispense_commands : "遠端指令"
products ||--o{ machine_slots : "放置於"
products ||--o{ order_items : "被購買"
products ||--o{ timer_statuses : "計時商品"
orders ||--o{ order_items : "包含"
orders ||--o| invoices : "開立"
orders ||--o{ dispense_records : "出貨"
orders }o--o| members : "消費者"
orders }o--|| payment_types : "付款方式"
members ||--o{ social_accounts : "社群綁定"
members ||--o| member_wallets : "錢包"
members ||--o| member_points : "點數"
members ||--o{ member_memberships : "會員等級"
members ||--o{ member_gifts : "禮品"
member_wallets ||--o{ wallet_transactions : "異動"
member_points ||--o{ point_transactions : "異動"
membership_tiers ||--o{ member_memberships : "對應等級"
gift_definitions ||--o{ member_gifts : "對應禮品"
```
---
## 五、API 資料流向圖
```
┌─────────────┐
│ 機台 (APP) │
└──────┬──────┘
├── B010 ──► 心跳上報 ──► machine_logs狀態/溫度/版本)
│ ◄── 返回遠端指令碼
├── B017 ──► 撈取庫存 ──► machine_slots最新貨道數量
├── B055 ──► 撈取出貨指令 ──► remote_dispense_commands
│ PUT ──► 回報出貨結果 ──► 更新 command status + 庫存
├── B220 ──► 零錢機庫存 ──► coin_inventory_logs
├── B600 ──► 消費金流 ──► orders + order_items核心交易
│ ◄── 返回金流 ID (flow_id)
├── B601 ──► 發票回傳 ──► invoices關聯 flow_id
├── B602 ──► 出貨回傳 ──► dispense_records關聯 flow_id
├── B650 ──► 驗證會員 ──► members + member_points
│ ◄── 點數折抵/優惠券/取貨碼/線上訂單
└── B710 ──► 計時器狀態 ──► timer_statuses
```
---
## 六、重要觀察與建議
### 6.1 API 金鑰
- 所有 API 使用同一把硬編碼金鑰 `KahnEwjhfDBHUYS7`
- **建議**:遷移到 Star Cloud 後改為每台機台獨立的 API Token使用 Laravel Sanctum 管理
### 6.2 資料一致性
- B600金流→ B601發票→ B602出貨三支 API 透過 `flow_id` 串聯
- 建議資料庫設計中以 `orders.flow_id` 作為三者的關聯基準
### 6.3 高頻 API
- **B010** 為最高頻率 API每台機台數秒呼叫一次必須走 **Redis Queue 異步寫入**
- B220零錢機庫存與 B710計時器也屬於高頻回報建議異步處理
### 6.4 新舊版差異
- B220 和 B600/B602 各有兩個版本的 PDF新舊版新版增加了更多面額500/1000 元)和 TapPay 金流類型
- 建議以**較新版本 (帶日期後綴的)** 為準進行開發
### 6.5 `machines` 表建議補充欄位
根據 B010 API`machines` 表應包含:
| 欄位 | 說明 | 來源 |
|------|------|------|
| `serial_no` | 機台序號 | B010 machine |
| `model` | 機台型號 | B010 M_Stus |
| `current_status` | 當前頁面狀態碼 | B010 M_Stus2 |
| `current_version` | 當前軟體版本 | B010 M_Ver |
| `temperature` | 最新溫度 | B010 temperature |
| `door_status` | 門禁狀態 | B010 door |
| `last_heartbeat_at` | 最後心跳時間 | B010 呼叫時間 |
| `is_online` | 是否在線 | 由心跳超時判斷 |