All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 48s
475 lines
19 KiB
Markdown
475 lines
19 KiB
Markdown
# 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` | 是否在線 | 由心跳超時判斷 |
|