sky121113
8ee14eaa29
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 48s
628 lines
28 KiB
Markdown
628 lines
28 KiB
Markdown
# Star Cloud — 智能販賣機管理平台技術架構規劃
|
||
|
||
> **目標**：為上千至上萬台智能販賣機建構集中式管理後台，承接所有機台透過 API 回寫的資料，並提供完整的營運管理介面。
|
||
|
||
---
|
||
|
||
## 一、系統架構全景
|
||
|
||
```
|
||
┌──────────────────────────────────────────────┐
|
||
│ Star Cloud 管理後台 │
|
||
│ (Laravel 12 + Blade + Tailwind) │
|
||
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
|
||
│ │ 儀表板 │ │ 機台管理 │ │ 銷售分析 │ │
|
||
│ │ Dashboard │ │ Machines │ │ Analytics │ │
|
||
│ └──────────┘ └──────────┘ └───────────┘ │
|
||
│ ┌──────────┐ ┌──────────┐ ┌───────────┐ │
|
||
│ │ 倉庫管理 │ │ 會員系統 │ │ 遠端操控 │ │
|
||
│ │Warehouses │ │ Members │ │ Remote │ │
|
||
│ └──────────┘ └──────────┘ └───────────┘ │
|
||
└──────────┬───────────────┬───────────────────┘
|
||
│ Web Routes │
|
||
│ (Blade SSR) │
|
||
┌──────────┴───────────────┴───────────────────┐
|
||
│ Laravel Application │
|
||
│ │
|
||
│ Controllers → Services → Models → MySQL │
|
||
│ │
|
||
└──────┬────────────────────┬──────────────────┘
|
||
│ │
|
||
┌──────────┴────┐ ┌───────┴───────┐
|
||
│ API Routes │ │ Redis Queue │
|
||
│ /api/v1/app │ │ (異步處理) │
|
||
└──────┬────────┘ └───────┬───────┘
|
||
│ │
|
||
┌──────┴────────┐ ┌───────┴───────┐
|
||
│ API Controller│──────►│ Jobs │
|
||
│ (驗證 + 分派) │ dispatch│ (Worker 執行) │
|
||
└───────────────┘ └───────┬───────┘
|
||
▲ │
|
||
┌────────────────┤ ▼
|
||
│ │ ┌──────────────┐
|
||
┌─────┴─────┐ ┌────┴─────┐ │ Services │
|
||
│ 販賣機 #1 │ │販賣機 #N │ │ (業務邏輯) │
|
||
│ B010 │ │ B600 │ └──────┬───────┘
|
||
│ B600 │ │ B602 │ │
|
||
│ B602 │ │ ... │ ▼
|
||
└────────────┘ └──────────┘ ┌──────────────┐
|
||
│ MySQL │
|
||
│ (持久化) │
|
||
└──────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、技術棧確認
|
||
|
||
| 層級 | 技術 | 說明 |
|
||
|------|------|------|
|
||
| **後端框架** | PHP 8.5 / Laravel 12 | 單體架構，Blade SSR |
|
||
| **資料庫** | MySQL 8.0 | 資料持久化 |
|
||
| **快取/隊列** | Redis | B010 心跳、B600 金流等高頻 API 必須異步 |
|
||
| **前端視圖** | Blade + Tailwind CSS + Preline UI | 極簡奢華風 |
|
||
| **前端互動** | Alpine.js | 輕量 DOM 互動 |
|
||
| **建置工具** | Vite | 前端資源編譯 |
|
||
| **開發環境** | Laravel Sail (Docker) | 本地開發 |
|
||
| **IoT 通訊** | Redis Queue + Jobs | 異步寫入，避免 API 直連 DB |
|
||
| **認證** | Laravel Sanctum | 後台用 Session，API 用 Token |
|
||
|
||
---
|
||
|
||
## 三、多租戶與權限架構 (Multi-Tenant RBAC)
|
||
|
||
為支援系統管理員（內部營運）與租戶（客戶公司及子帳號）的雙層管理模式，平台採用以下三層級權限隔離架構：
|
||
|
||
### 3.1 租戶隔離層 (Tenant Isolation)
|
||
* **核心機制**：導入 `companies` 資料表作為租戶實體，所有歸屬於客戶的資源（`users`, `machines` 等）均需綁定 `company_id`。
|
||
* **身份判定**：
|
||
* **系統管理員 (內部)**：`company_id = null`，具備跨租戶檢視與管理機台、設定全局參數的最高權限。
|
||
* **客戶端帳號 (租戶)**：`company_id` 有值，所有查詢（透過 Eloquent Global Scopes 或 Middleware）自動注入 `where('company_id', $user->company_id)`，達成資料物理隔離。
|
||
|
||
### 3.2 角色與權限層 (Roles & Permissions)
|
||
* 採用 `spatie/laravel-permission` 套件並進行多租戶改造。
|
||
* **多租戶角色 (Tenant-Aware Roles)**：擴充 `roles` 表，加入 `company_id` 欄位。
|
||
* **系統預設角色** (`company_id = null`)：如 Super Admin, System Support。
|
||
* **客戶自建角色** (`company_id = N`)：如客戶建立的「分區維修員」、「會計」，確保客戶只能看見與分配屬於自己公司的角色給員工。
|
||
* **權限 (Permissions)**：定義系統最小操作單位（如 `machine.view`, `user.create`），供角色綁定。
|
||
|
||
### 3.3 流程控制與防禦 (Flow Control)
|
||
* **介面隔離**：依據身份動態隱藏/顯示系統級選單（例如「全站設定」、「合約管理」等多租戶不可見的功能）。
|
||
* **越權防禦**：客戶創建子帳號時，後端必定強制攔截並覆寫 `user->company_id = Auth::user()->company_id`，確保子帳號牢牢綁在自己的公司名下。同時限制其只能撈與分配自己公司名下的 Role。
|
||
|
||
---
|
||
|
||
## 四、資料庫完整設計
|
||
|
||
### 4.1 資料表總覽
|
||
|
||
分為 **6 大領域**，共 **28 張表**：
|
||
|
||
```mermaid
|
||
graph LR
|
||
subgraph 系統管理
|
||
A1[users] --> A2[sessions]
|
||
A1 --> A3[personal_access_tokens]
|
||
A4[failed_jobs]
|
||
end
|
||
|
||
subgraph 機台領域
|
||
B1[machines] --> B2[machine_slots]
|
||
B1 --> B3[machine_logs]
|
||
B1 --> B4[coin_inventories]
|
||
B1 --> B5[timer_statuses]
|
||
B1 --> B6[remote_commands]
|
||
B1 --> B7[machine_heartbeats]
|
||
end
|
||
|
||
subgraph 商品領域
|
||
C1[products]
|
||
C2[product_categories]
|
||
end
|
||
|
||
subgraph 交易領域
|
||
D1[orders] --> D2[order_items]
|
||
D1 --> D3[invoices]
|
||
D1 --> D4[dispense_records]
|
||
D5[payment_types]
|
||
end
|
||
|
||
subgraph 會員領域
|
||
E1[members] --> E2[social_accounts]
|
||
E1 --> E3[member_wallets]
|
||
E3 --> E4[wallet_transactions]
|
||
E1 --> E5[member_points]
|
||
E5 --> E6[point_transactions]
|
||
E7[point_rules]
|
||
E8[deposit_bonus_rules]
|
||
E1 --> E9[membership_tiers]
|
||
E1 --> E10[member_memberships]
|
||
E1 --> E11[gift_definitions]
|
||
E1 --> E12[member_gifts]
|
||
end
|
||
|
||
subgraph APP設定
|
||
F1[app_configs]
|
||
end
|
||
```
|
||
|
||
### 4.2 需新增的資料表（Migration 設計）
|
||
|
||
> 以下為 API 分析後推導出的缺失表，搭配各 API 欄位產生對應。
|
||
|
||
---
|
||
|
||
#### 👑 多租戶與權限基礎表 (RBAC & Tenant)
|
||
|
||
##### 🆕 `companies` — 租戶/客戶主表
|
||
所有客戶端的資料邊界，用來實現資料物理隔離。
|
||
|
||
| 欄位 | 類型 | 說明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | — |
|
||
| `name` | VARCHAR(255) | 公司/組織名稱 |
|
||
| `tax_id` | VARCHAR(20) NULL | 統一編號 |
|
||
| `contact_name` | VARCHAR(100) NULL | 聯絡人姓名 |
|
||
| `contact_phone` | VARCHAR(50) NULL | 聯絡電話 |
|
||
| `status` | TINYINT DEFAULT 1 | 狀態 (1:啟用, 0:停用) |
|
||
| `valid_until` | DATE NULL | 合約使用期限 |
|
||
| `timestamps` | — | — |
|
||
| `deleted_at` | TIMESTAMP NULL | 軟刪除 (SoftDeletes) |
|
||
|
||
##### 🟡 `users` 表 — 需擴充欄位
|
||
將 Laravel 預設的使用者表與租戶綁定。
|
||
|
||
| 新增欄位 | 類型 | 說明 |
|
||
|----------|------|------|
|
||
| `company_id` | BIGINT FK NULL | → `companies` (NULL 代表系統管理員) |
|
||
| `status` | TINYINT DEFAULT 1 | 帳號狀態 (1:啟用, 0:停用) |
|
||
|
||
##### 🟡 `roles` 表 (Spatie 權限擴充)
|
||
Spatie 預設的 roles 表必須加上多租戶設計，確保留戶只能管理自己的角色。
|
||
|
||
| 新增/調整欄位 | 類型 | 說明 |
|
||
|----------|------|------|
|
||
| `company_id` | BIGINT FK NULL | → `companies` (NULL 代表系統全域角色) |
|
||
| **UNIQUE** | `(name, guard_name, company_id)` | 原套件無 `company_id`，需修改為複合唯一鍵 |
|
||
|
||
---
|
||
|
||
#### 🟡 `machines` 表 — 需擴充欄位
|
||
|
||
現有 `machines` 表僅有基礎欄位，需為 B010 API 補充：
|
||
|
||
| 新增欄位 | 類型 | 說明 | 來源 API |
|
||
|----------|------|------|----------|
|
||
| `serial_no` | `VARCHAR UNIQUE` | 機台序號（API 用此識別） | B010 `machine` |
|
||
| `model` | `VARCHAR` | 機台型號 | B010 `M_Stus` |
|
||
| `current_page` | `TINYINT` | 當前頁面狀態碼 | B010 `M_Stus2` |
|
||
| `door_status` | `VARCHAR` | 門禁狀態 | B010 `door` |
|
||
| `is_online` | `BOOLEAN` | 是否在線（心跳超時判斷） | 計算欄位 |
|
||
| `api_token` | `VARCHAR` | 機台專屬 API Token | 取代硬編碼 key |
|
||
|
||
---
|
||
|
||
#### 🆕 `products` — 商品資料
|
||
|
||
| 欄位 | 類型 | 說明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | — |
|
||
| `name` | VARCHAR(255) | 商品名稱 (預設語系) |
|
||
| `name_dictionary_key` | VARCHAR(100) NULL | 多語系字典鍵值 (對應 translations 表) |
|
||
| `sku` | VARCHAR(100) UNIQUE | 商品編號 |
|
||
| `price` | DECIMAL(10,2) | 售價 |
|
||
| `cost` | DECIMAL(10,2) NULL | 成本 |
|
||
| `category_id` | BIGINT FK NULL | → product_categories |
|
||
| `image` | VARCHAR NULL | 圖片 URL |
|
||
| `barcode` | VARCHAR NULL | 條碼 |
|
||
| `is_timer_product` | BOOLEAN | 是否為計時型商品 |
|
||
| `is_active` | BOOLEAN | 是否上架 |
|
||
| `timestamps` | — | — |
|
||
|
||
---
|
||
|
||
#### 🌐 多語系支援表 (i18n)
|
||
|
||
為了支援後台介面與 APP 端顯示的多語系內容（如商品名稱、分類名稱、系統提示），統一採用字典表架構。
|
||
|
||
##### 🆕 `translations` — 多語系字典表
|
||
|
||
| 欄位 | 類型 | 說明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | — |
|
||
| `group` | VARCHAR(50) | 分組 (例如: `product`, `category`, `system`) |
|
||
| `key` | VARCHAR(100) | 字典鍵值 (例如: `prod_name_001`) |
|
||
| `locale` | VARCHAR(10) | 語系代碼 (例如: `zh_TW`, `en_US`, `ja_JP`) |
|
||
| `value` | TEXT | 翻譯內容 |
|
||
| `timestamps` | — | — |
|
||
| **UNIQUE** | `(group, key, locale)` | 確保同一組鍵值在同一語系下唯一 |
|
||
|
||
> **多語系實作策略**：
|
||
> 1. **靜態文案**：後台介面的靜態文字直接使用 Laravel 內建的 `lang/` 目錄 (JSON 或 PHP 陣列)。
|
||
> 2. **動態資料**：資料庫內容（如商品名稱 `products.name`）保留預設語系供後台快速搜尋。同時新增 `name_dictionary_key`。當對接外部 APP 或前台需要多語系時，透過 API 關聯 `translations` 表，回傳當前語系對應的 `value`。
|
||
|
||
---
|
||
|
||
#### 🆕 `machine_slots` — 機台貨道
|
||
|
||
| 欄位 | 類型 | 說明 | 來源 |
|
||
|------|------|------|------|
|
||
| `id` | BIGINT PK | — | — |
|
||
| `machine_id` | BIGINT FK | → machines | B017, B055, B710 |
|
||
| `slot_no` | VARCHAR(20) | 貨道編號 | B017 `tid`, B710 `cid` |
|
||
| `product_id` | BIGINT FK NULL | → products | B710 `pid` |
|
||
| `stock` | INT DEFAULT 0 | 當前庫存 | B017 `num` |
|
||
| `max_stock` | INT DEFAULT 0 | 最大容量 | — |
|
||
| `is_active` | BOOLEAN | 是否啟用 | — |
|
||
| `timestamps` | — | — | — |
|
||
| **UNIQUE** | `(machine_id, slot_no)` | 複合唯一鍵 | — |
|
||
|
||
---
|
||
|
||
#### 🆕 `orders` — 訂單主表
|
||
|
||
| 欄位 | 類型 | 說明 | 來源 |
|
||
|------|------|------|------|
|
||
| `id` | BIGINT PK | — | — |
|
||
| `flow_id` | VARCHAR UNIQUE | Cloud 金流 ID | B600 response |
|
||
| `order_no` | VARCHAR | APP 訂單號 | B600 `req9` |
|
||
| `machine_id` | BIGINT FK | → machines | B600 `req2` |
|
||
| `member_id` | BIGINT FK NULL | → members | B650 關聯 |
|
||
| `payment_type` | SMALLINT | 金流類型碼 | B600 `req3` |
|
||
| `total_amount` | DECIMAL(10,2) | 消費金額 | B600 `req7` |
|
||
| `change_amount` | DECIMAL(10,2) | 找零 | B600 `req13` |
|
||
| `points_used` | INT DEFAULT 0 | 使用點數 | B600 `req14` |
|
||
| `original_amount` | DECIMAL(10,2) NULL | 折扣前金額 | B602 `req15` |
|
||
| `payment_status` | TINYINT | 0:失敗/1:成功 | B600 `req12` |
|
||
| `payment_request` | TEXT NULL | 金流送出 data | B600 `req4` |
|
||
| `payment_response` | TEXT NULL | 金流回傳 data | B600 `req5` |
|
||
| `member_barcode` | VARCHAR NULL | 會員條碼 | B600 `req10` |
|
||
| `invoice_info` | VARCHAR NULL | 發票歸戶 | B600 `req8` |
|
||
| `machine_time` | DATETIME NULL | 機台時間 | B600 `req11` |
|
||
| `timestamps` | — | — | — |
|
||
| **INDEX** | `(machine_id, created_at)` | 查詢最佳化 | — |
|
||
| **INDEX** | `(payment_type)` | 金流類型篩選 | — |
|
||
|
||
---
|
||
|
||
#### 🆕 `order_items` — 訂單明細
|
||
|
||
| 欄位 | 類型 | 說明 | 來源 |
|
||
|------|------|------|------|
|
||
| `id` | BIGINT PK | — | — |
|
||
| `order_id` | BIGINT FK | → orders | — |
|
||
| `product_id` | BIGINT FK | → products | B600 `req16.pid` |
|
||
| `quantity` | INT | 數量 | B600 `req16.num` |
|
||
| `unit_price` | DECIMAL(10,2) | 單價 | B600 `req16.amount` |
|
||
| `subtotal` | DECIMAL(10,2) | 小計 | 計算 |
|
||
| `timestamps` | — | — | — |
|
||
|
||
---
|
||
|
||
#### 🆕 `invoices` — 發票紀錄
|
||
|
||
| 欄位 | 類型 | 說明 | 來源 |
|
||
|------|------|------|------|
|
||
| `id` | BIGINT PK | — | — |
|
||
| `order_id` | BIGINT FK | → orders（via flow_id） | — |
|
||
| `flow_id` | VARCHAR | 金流 ID | B601 `req3` |
|
||
| `machine_id` | BIGINT FK | → machines | B601 `req2` |
|
||
| `rtn_code` | VARCHAR NULL | 回傳碼 | B601 `req4` |
|
||
| `rtn_msg` | VARCHAR NULL | 回傳訊息 | B601 `req5` |
|
||
| `invoice_no` | VARCHAR NULL | 發票號碼 | B601 `req6` |
|
||
| `invoice_date` | DATE NULL | 發票日期 | B601 `req7` |
|
||
| `random_number` | VARCHAR NULL | 隨機碼 | B601 `req8` |
|
||
| `love_code` | VARCHAR NULL | 愛心碼 | B601 `req9` |
|
||
| `timestamps` | — | — | — |
|
||
|
||
---
|
||
|
||
#### 🆕 `dispense_records` — 出貨紀錄
|
||
|
||
| 欄位 | 類型 | 說明 | 來源 |
|
||
|------|------|------|------|
|
||
| `id` | BIGINT PK | — | — |
|
||
| `order_id` | BIGINT FK NULL | → orders | — |
|
||
| `flow_id` | VARCHAR NULL | 金流 ID | B602 `req3` |
|
||
| `machine_id` | BIGINT FK | → machines | B602 `req2` |
|
||
| `product_id` | VARCHAR | 商品 ID | B602 `req5` |
|
||
| `slot_no` | VARCHAR | 貨道編號 | B602 `req6` |
|
||
| `amount` | DECIMAL(10,2) | 消費金額 | B602 `req7` |
|
||
| `remaining_stock` | INT NULL | 剩餘庫存 | B602 `req9` |
|
||
| `dispense_status` | TINYINT | 0:成功/1:失敗 | B602 `req13` |
|
||
| `member_barcode` | VARCHAR NULL | 會員條碼 | B602 `req10` |
|
||
| `machine_time` | DATETIME NULL | 機台時間 | B602 `req11` |
|
||
| `points_used` | INT DEFAULT 0 | 使用點數 | B602 `req16` |
|
||
| `timestamps` | — | — | — |
|
||
|
||
---
|
||
|
||
#### 🆕 `remote_commands` — 遠端指令佇列
|
||
|
||
| 欄位 | 類型 | 說明 | 來源 |
|
||
|------|------|------|------|
|
||
| `id` | BIGINT PK | — | — |
|
||
| `machine_id` | BIGINT FK | → machines | — |
|
||
| `command_type` | VARCHAR(20) | 指令類型 | B010 response status |
|
||
| `status` | ENUM | pending/sent/success/failed | — |
|
||
| `payload` | JSON NULL | 指令附加資料 | — |
|
||
| `executed_at` | TIMESTAMP NULL | 執行時間 | — |
|
||
| `timestamps` | — | — | — |
|
||
|
||
> 對應 B010 遠端指令（reboot, lock, unlock, checkout, dispense 等）以及 B055 遠端出貨。
|
||
|
||
---
|
||
|
||
#### 🆕 `coin_inventories` — 零錢機庫存
|
||
|
||
| 欄位 | 類型 | 說明 | 來源 |
|
||
|------|------|------|------|
|
||
| `id` | BIGINT PK | — | — |
|
||
| `machine_id` | BIGINT FK | → machines | B220 `machine` |
|
||
| `value_1` | INT DEFAULT 0 | 1 元 | B220 |
|
||
| `value_5` | INT DEFAULT 0 | 5 元 | B220 |
|
||
| `value_10` | INT DEFAULT 0 | 10 元 | B220 |
|
||
| `value_50` | INT DEFAULT 0 | 50 元 | B220 |
|
||
| `value_100` | INT DEFAULT 0 | 100 元 | B220 |
|
||
| `value_500` | INT DEFAULT 0 | 500 元 | B220 |
|
||
| `value_1000` | INT DEFAULT 0 | 1000 元 | B220 |
|
||
| `operator` | VARCHAR NULL | 操作人 (0=消費者) | B220 `account` |
|
||
| `timestamps` | — | — | — |
|
||
|
||
---
|
||
|
||
#### 🆕 `timer_statuses` — 計時器狀態
|
||
|
||
| 欄位 | 類型 | 說明 | 來源 |
|
||
|------|------|------|------|
|
||
| `id` | BIGINT PK | — | — |
|
||
| `machine_id` | BIGINT FK | → machines | B710 `req2` |
|
||
| `slot_no` | VARCHAR | 貨道 ID | B710 `cid` |
|
||
| `product_id` | BIGINT FK NULL | → products (0=未設定) | B710 `pid` |
|
||
| `status` | TINYINT | 0:未啟用/1:使用中/2:異常 | B710 `status` |
|
||
| `remaining_seconds` | INT | 剩餘秒數 | B710 `num` |
|
||
| `timestamps` | — | — | — |
|
||
|
||
---
|
||
|
||
#### 🆕 `payment_types` — 金流類型參照
|
||
|
||
| 欄位 | 類型 | 說明 |
|
||
|------|------|------|
|
||
| `id` | BIGINT PK | — |
|
||
| `code` | SMALLINT UNIQUE | 金流代碼 (1,2,3...120) |
|
||
| `name` | VARCHAR | 中文名稱 |
|
||
| `category` | VARCHAR | 大分類 |
|
||
| `is_active` | BOOLEAN | 是否啟用 |
|
||
| `timestamps` | — | — |
|
||
|
||
---
|
||
|
||
## 五、IoT API 路由設計
|
||
|
||
### 5.1 路由結構
|
||
|
||
```php
|
||
// routes/api.php
|
||
Route::prefix('v1/app')->middleware(['throttle:iot'])->group(function () {
|
||
|
||
// B010 - 機台狀態上傳 & 指令撈回
|
||
Route::post('/machine/status', [MachineStatusController::class, 'heartbeat']);
|
||
|
||
// B017 - 遠端撈庫存
|
||
Route::post('/machine/reload', [MachineStockController::class, 'reload']);
|
||
|
||
// B055 - 遠端出貨
|
||
Route::post('/machine/dispense', [DispenseController::class, 'getCommands']);
|
||
Route::put('/machine/dispense', [DispenseController::class, 'updateStatus']);
|
||
|
||
// B220 - 零錢機庫存
|
||
Route::post('/coin/inventory', [CoinInventoryController::class, 'store']);
|
||
|
||
// B600 - 消費金流
|
||
Route::post('/transaction', [TransactionController::class, 'store']);
|
||
|
||
// B601 - 發票回傳
|
||
Route::post('/invoice', [InvoiceController::class, 'store']);
|
||
|
||
// B602 - 出貨回傳
|
||
Route::post('/dispense-record', [DispenseRecordController::class, 'store']);
|
||
|
||
// B650 - 驗證會員
|
||
Route::post('/member/verify', [MemberVerifyController::class, 'verify']);
|
||
|
||
// B710 - 計時器狀態
|
||
Route::post('/timer/status', [TimerStatusController::class, 'sync']);
|
||
});
|
||
```
|
||
|
||
### 5.2 處理管線
|
||
|
||
> [!IMPORTANT]
|
||
> 遵循 IoT 通訊技能規範：**嚴禁** API Controller 直接寫入 DB。
|
||
|
||
| API | 處理方式 | 原因 |
|
||
|-----|----------|------|
|
||
| B010 | **異步** (Redis Queue) | 最高頻，每台數秒一次 |
|
||
| B017 | **同步** (直接回應) | 低頻，需即時回傳庫存數據 |
|
||
| B055 GET | **同步** | 需即時回傳指令列表 |
|
||
| B055 PUT | **異步** | 出貨結果可背景處理 |
|
||
| B220 | **異步** | 庫存變動日誌可背景寫入 |
|
||
| B600 | **異步** | 高頻交易，核心數據 |
|
||
| B601 | **異步** | 發票資訊可背景寫入 |
|
||
| B602 | **異步** | 出貨紀錄可背景寫入 |
|
||
| B650 | **同步** | 需即時回傳驗證結果與折抵金額 |
|
||
| B710 | **異步** | 計時器狀態批量更新 |
|
||
|
||
---
|
||
|
||
## 六、後台模組 ↔ 資料表對應
|
||
|
||
| 後台模組（web.php） | 對應資料表 | 資料來源 API |
|
||
|---------------------|-----------|-------------|
|
||
| 1. 儀表板 Dashboard | orders, machines, dispense_records | 統計彙整 |
|
||
| 2. 會員管理 Members | members, social_accounts, member_wallets... | B650 |
|
||
| 3. 機台管理 Machines | machines, machine_logs, machine_slots | B010, B017 |
|
||
| 4. APP 管理 App | app_configs, timer_statuses | B710 |
|
||
| 5. 倉庫管理 Warehouses | products, machine_slots | B017, B602 |
|
||
| 6. 銷售管理 Sales | orders, order_items, dispense_records | B600, B602 |
|
||
| 7. 分析管理 Analysis | orders, dispense_records, coin_inventories | 全部 |
|
||
| 8. 稽核管理 Audit | orders, dispense_records | B600, B602 |
|
||
| 9. 資料設定 DataConfig | products, payment_types, users | — |
|
||
| 10. 遠端管理 Remote | remote_commands | B010, B055 |
|
||
| 11. Line 管理 | members (Line 綁定) | — |
|
||
| 12. 預約系統 Reservation | （未來擴充） | — |
|
||
| 13. 特殊權限 SpecialPerm | machines, app_configs | — |
|
||
| 14. 權限設定 Permission | users, roles | — |
|
||
|
||
---
|
||
|
||
## 七、效能預估與應對
|
||
|
||
### 10,000 台機台的流量預估
|
||
|
||
| API | 頻率 | 每秒請求量 (QPS) | 每日資料量 |
|
||
|-----|------|-----------------|-----------|
|
||
| B010 心跳 | 每 5 秒/台 | **~2,000** | ~173M 筆 |
|
||
| B600 金流 | 每筆交易 | ~10-50 | ~50K-200K 筆 |
|
||
| B602 出貨 | 每筆交易 | ~10-50 | ~50K-200K 筆 |
|
||
| B710 計時器 | 每 10 秒/台 | ~1,000 | ~86M 筆 |
|
||
|
||
### 應對策略
|
||
|
||
| 策略 | 實作方式 |
|
||
|------|----------|
|
||
| **Redis Queue 異步寫入** | 所有高頻 API 進 Queue，Worker 批量寫入 |
|
||
| **心跳資料瘦身** | B010 不逐筆寫 DB，僅更新 `machines` 表的即時欄位 + 異常時寫 log |
|
||
| **資料分區** | `orders` 和 `dispense_records` 按月份分區 |
|
||
| **索引策略** | 所有查詢欄位建立適當 INDEX（machine_id + created_at 複合索引） |
|
||
| **速率限制** | 單台機台 60 req/min，全站 100,000 req/min |
|
||
| **快取** | 機台列表、商品列表等低變動資料用 Redis Cache |
|
||
|
||
---
|
||
|
||
## 八、實作路線圖與預估時程
|
||
|
||
> **總結報告**：為確保開發品質與應對突發狀況，本專案預計總開發時程擴展為 **16 - 18 週**。以 1 人天 = 8 小時純開發時間計算，預估總投入約 **80 - 90 個工作天**。
|
||
|
||
### 🗓️ 專案開發甘特圖 (自動排除週末)
|
||
|
||
```mermaid
|
||
gantt
|
||
title Star Cloud 實作時程規劃
|
||
dateFormat YYYY-MM-DD
|
||
excludes weekends
|
||
|
||
section 第一階段 MVP
|
||
Phase 1 基礎設施與資料表 :active, p1, 2026-03-11, 14d
|
||
Phase 2 IoT API 與異步管線 :p2, after p1, 24d
|
||
Phase 3 後台 MVP 頁面整合 :p3, after p2, 18d
|
||
|
||
section 第二階段 進階
|
||
Phase 4 進階功能與報表分析 :p4, after p3, 30d
|
||
```
|
||
|
||
### 📅 詳細時程對照表
|
||
|
||
| 階段 (Phase) | 關鍵任務摘要 | 預估天數 | 預計工作日期 | 狀態 |
|
||
| :--- | :--- | :---: | :---: | :---: |
|
||
| **Phase 1** | 基礎架構、28張表設計、資料遷移基礎 | 14 工作天 | 03/11 ~ 03/30 | 準備啟動 |
|
||
| **Phase 2** | B010~B710 核心 API、Redis 異步 Job、Service | 24 工作天 | 03/31 ~ 05/01 | 規劃中 |
|
||
| **Phase 3** | 儀表板、機台/銷售/遠端管理 MVP 介面 | 18 工作天 | 05/04 ~ 05/27 | 規劃中 |
|
||
| **Phase 4** | 數據分析統計圖表、補貨演算法、自動對帳模組 | 30 工作天 | 05/28 ~ 07/08 | 規劃中 |
|
||
|
||
---
|
||
|
||
### 🔵 第一階段：MVP 營運核心 (最優先上線)
|
||
**目標**：確保機台金流與指令能穩定連通，完成基礎營運管理功能。
|
||
|
||
#### Phase 1：基礎設施與核心資料表 (預計: 14 工作天)
|
||
- [ ] 擴充 `machines` 表（serial_no, model 等欄位）
|
||
- [ ] 建立 多租戶與權限基礎表 (`companies`, `spatie/laravel-permission` 相關表)
|
||
- [ ] 將 `company_id` 欄位加入 `users`, `machines`, `roles` 等核心表
|
||
- [ ] 建立 `translations` 多語系字典表，並擴充 `products` 語系關聯
|
||
- [ ] 新增 `products` + `product_categories` 表
|
||
- [ ] 新增 `machine_slots` 表
|
||
- [ ] 新增 `orders` + `order_items` 表
|
||
- [ ] 新增 `invoices` + `dispense_records` 表
|
||
- [ ] 新增 `remote_commands` 表 (遠端管理與對接用)
|
||
- [ ] 新增 `payment_types` 表 + Seeder
|
||
|
||
#### Phase 2：核心營運 IoT API 與異步管線 (預計: 24 工作天)
|
||
- [ ] 實作 **B010** API (心跳上報 + 狀態更新 + 遠端管理)
|
||
- [ ] 實作 **B017 / B055** API (遠端改庫存/出貨)
|
||
- [ ] 實作 **B600 / B601 / B602** API (金流/發票/出貨紀錄)
|
||
- [ ] 實作 **B650** API (會員驗證 + 點數折抵)
|
||
- [ ] 建立上述對應的 **Redis Queue Job + Service** 異步處理邏輯
|
||
|
||
#### Phase 3：後台 MVP 頁面整合 (預計: 18 工作天)
|
||
- [ ] **多租戶權限與身份切換機制 (Middleware & Views)**
|
||
- [ ] 儀表板 Dashboard：即時數據看板 (營收、機台數，依據租戶隔離資料)
|
||
- [ ] 機台管理 Machines：連線狀態、貨道庫存、指令操作 UI
|
||
- [ ] 銷售管理 Sales：訂單列表、出貨/發票追蹤
|
||
- [ ] 系統基礎設定：帳號與權限設定 (RBAC UI)、商品建檔、金流代碼設定、**多語系字典維護介面**
|
||
|
||
---
|
||
|
||
### 🟢 第二階段：進階營運與智慧分析 (持續優化)
|
||
**目標**：強化報表分析能力與自動化稽核。
|
||
|
||
#### Phase 4：進階功能與報表分析模組 (預計: 30 工作天)
|
||
- [ ] **分析管理 Analysis**：趨勢圖、商品熱銷分析、機台產能報表
|
||
- [ ] **倉庫管理 Warehouses**：補貨建議、入/出庫流程優化
|
||
- [ ] **擴充支持**：B220 (零錢機) + B710 (計時器) 支援
|
||
- [ ] **自動化稽核 Audit**：對帳機制、異常提醒
|
||
- [ ] **行銷模組**：Line 聯動、預約系統、UI 動態設定
|
||
|
||
|
||
---
|
||
|
||
## 九、目錄結構建議
|
||
|
||
```
|
||
app/
|
||
├── Http/Controllers/
|
||
│ ├── Admin/ ← 後台管理（已存在 14 模組）
|
||
│ └── Api/V1/
|
||
│ ├── App/ ← 機台 IoT API（新增）
|
||
│ │ ├── MachineStatusController.php (B010)
|
||
│ │ ├── MachineStockController.php (B017)
|
||
│ │ ├── DispenseController.php (B055)
|
||
│ │ ├── CoinInventoryController.php (B220)
|
||
│ │ ├── TransactionController.php (B600)
|
||
│ │ ├── InvoiceController.php (B601)
|
||
│ │ ├── DispenseRecordController.php (B602)
|
||
│ │ ├── MemberVerifyController.php (B650)
|
||
│ │ └── TimerStatusController.php (B710)
|
||
│ ├── MemberController.php ← 會員 API（已存在）
|
||
│ └── MachineController.php ← 機台日誌（已存在）
|
||
├── Jobs/
|
||
│ └── Machine/ ← IoT 異步任務（新增）
|
||
│ ├── ProcessHeartbeat.php
|
||
│ ├── ProcessTransaction.php
|
||
│ ├── ProcessDispenseRecord.php
|
||
│ ├── ProcessInvoice.php
|
||
│ ├── ProcessCoinInventory.php
|
||
│ └── ProcessTimerStatus.php
|
||
├── Services/
|
||
│ └── Machine/ ← 業務邏輯（新增）
|
||
│ ├── HeartbeatService.php
|
||
│ ├── TransactionService.php
|
||
│ ├── DispenseService.php
|
||
│ └── MemberVerifyService.php
|
||
└── Models/
|
||
├── Machine/ ← 已存在
|
||
│ ├── Machine.php
|
||
│ └── MachineLog.php
|
||
├── Transaction/ ← 新增
|
||
│ ├── Order.php
|
||
│ ├── OrderItem.php
|
||
│ ├── Invoice.php
|
||
│ ├── DispenseRecord.php
|
||
│ └── PaymentType.php
|
||
├── Product/ ← 新增
|
||
│ ├── Product.php
|
||
│ └── ProductCategory.php
|
||
└── Member/ ← 已存在
|
||
```
|