Star Cloud 智能販賣機管理平台

基於 Docker 的全方位智能販賣機後台管理系統 (Cloud 平台)

Star Cloud 是一個專為智能販賣機設計的後台管理系統，負責管理機台、商品、銷售數據，並為硬體端點提供專用的 API。

---

🚀 技術架構

核心架構

本專案採用 Monorepo 單體式架構，以 Laravel 為核心進行伺服器端渲染 (SSR) 與 API 服務，並搭配 Go MQTT Gateway 作為高併發 IoT 通訊的前置接收層。兩者透過 Redis 進行異步橋接。

服務	容器名稱	技術	用途	本地 Port
應用程式	star-cloud-laravel	Laravel 12 + PHP 8.5	核心業務與渲染	8090
背景隊列	star-cloud-queue	Laravel Queue Worker	異步任務處理	-
資料庫	star-cloud-mysql	MySQL 8.0	數據持久化	3306
快取/隊列	star-cloud-redis	Redis Alpine	IoT 高併發隊列與 MQTT 橋接	6380
MQTT Broker	star-cloud-emqx	EMQX 5.10	機台長連線與訊息路由	1883 / 18083
MQTT Gateway	star-cloud-mqtt-gateway	Go	訂閱 MQTT Topic、轉發至 Redis	-

後端技術棧

• Framework: Laravel 12.x
• Language: PHP 8.5
• Redis: 用於 IoT 高併發隊列與 MQTT 橋接
• Database: MySQL 8.0

IoT 通訊層

• MQTT Broker: EMQX 5.10 (維持機台長連線與訊息路由)
• MQTT Gateway: Go (訂閱 MQTT Topic、預處理訊息、轉發至 Redis)
• 橋接機制: Redis List (mqtt_incoming_jobs)，由 Laravel 常駐指令 (mqtt:listen) 消費

前端技術棧

• View: Laravel Blade
• CSS: Tailwind CSS + Preline UI
• JS: Alpine.js (行為控制)
• Build: Vite

---

🛠️ 開發環境 (Laravel Sail)

本專案建議使用 Laravel Sail 進行開發，避免直接在宿主機執行指令。

前置需求

• Docker Desktop (Windows/Mac) 或 Docker Engine (Linux)
• Git

快速啟動

1. clone 專案並進入目錄
2. cp .env.example .env
3. ./vendor/bin/sail up -d
4. ./vendor/bin/sail composer install
5. ./vendor/bin/sail artisan key:generate
6. ./vendor/bin/sail artisan migrate --seed
7. ./vendor/bin/sail npm install
8. ./vendor/bin/sail npm run dev
9. ./vendor/bin/sail artisan mqtt:sync-auth (同步機台 MQTT 認證至 Redis)
10. ./vendor/bin/sail artisan mqtt:listen (啟動 MQTT 訊息消費者)

常用開發指令

功能	指令
啟動環境	./vendor/bin/sail up -d
停止環境	./vendor/bin/sail down
Artisan 指令	./vendor/bin/sail artisan <cmd>
Composer 指令	./vendor/bin/sail composer <cmd>
NPM 指令	./vendor/bin/sail npm <cmd>
執行測試	./vendor/bin/sail test
MQTT 認證同步	./vendor/bin/sail artisan mqtt:sync-auth
MQTT 隊列監聽	./vendor/bin/sail artisan mqtt:listen
重建 Gateway	docker compose build mqtt-gateway && docker compose up -d mqtt-gateway

---

🔐 API 規範

系統 API 分為兩大類，遵循不同的設計慣例：

1. Admin/Web API (/api/v1/...)

• 對象: 後台管理介面、APP UI。
• 認證: Laravel Sanctum (Session/Token)。
• 格式: 標準 RESTful JSON。

2. Machine IoT API (/api/app/...)

• 對象: 智能販賣機、計時器等硬體。
• 認證: Header Authorization: Bearer <api_token>。
• 高併發處理: 核心日誌 (MQTT 心跳、B600 交易) 嚴禁直寫 DB，必須進入 Redis Queue 背景異步處理。

3. MQTT IoT 通訊

• 對象: 高頻/即時性機台通訊 (心跳、異常、交易)。
• 認證: EMQX 透過 Redis Hash 驗證 (machine_auth:{serial_no} → password 欄位)。
• 資料流向: 機台 ➜ EMQX ➜ Go Gateway ➜ Redis List ➜ Laravel mqtt:listen ➜ Job ➜ MySQL

---

🌐 多語系支援 (I18n)

所有 UI 顯示文字必須支援多語系，禁止 Hard-coded。

• 語系檔案: lang/zh_TW.json, lang/en.json, lang/ja.json。
• 呼叫方式: 使用 __('Phrases in English') 或 @lang('...')。
• 命名規範: 優先使用「英文原始詞彙」作為 Key 名稱。

---

📂 目錄結構

Laravel (PHP)

• app/Http/Controllers/: 控制器
• app/Models/{Domain}/: 分領域的模型 (如 Machine, Member)
• app/Services/{Domain}/: 封裝商業邏輯與資料異動
• app/Jobs/{Domain}/: IoT 異步隊列處理任務 (重要)
• app/Console/Commands/: Artisan 指令 (含 mqtt:listen, mqtt:sync-auth)
• resources/views/: Blade 模板 (按功能分資料夾)
• resources/views/components/: 可重用的 UI 組件
• routes/: 路由定義 (web.php 與 api.php)

MQTT Gateway (Go)

• mqtt-gateway/main.go: 進入點 (MQTT 連線、Redis 初始化)
• mqtt-gateway/config/: 環境變數與連線設定
• mqtt-gateway/internal/handler/: MQTT Topic 訊息處理邏輯
• mqtt-gateway/internal/bridge/: Redis 橋接層 (RPush / Consumer)

---

🚢 CI/CD 與部署

• 自動化工具: Gitea Actions (.gitea/workflows/)。
• Demo 環境: 推送到 demo 分支會自動部署至 demo-cloud.setdomains.work。
• 伺服器路徑: /workspace/mama/star-cloud (透過 ssh demo-sc-103 登入)。

---

授權與版權

© Star Cloud. All Rights Reserved.

---

技術支援

如有問題或建議，請聯繫開發團隊或提交 Issue。