sky121113
f2147ae6c4
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 1m4s
1. 將 B005 (廣告同步) 從 POST 改為 GET，符合 RESTful 規範。
2. 完善 B009 (庫存回報) 回應規格，加入業務代碼 (200 OK)。
3. API 文件 UI 優化：新增 Method Badge (方法標籤)，並修正 JSON 中文/斜線轉義問題。
4. 機台管理介面優化：實作「唯讀庫存與效期」面板，並將日誌圖示改為「👁️」。
5. 標準化 ID 識別邏輯：資料表全面移除對 sku 的依賴，改以 id 為主、barcode 為輔。
6. 新增 Migration：正式移除 sku 欄位並同步 barcode 指向。
7. 更新多語系支援 (zh_TW, en, ja)。
Star Cloud 智能販賣機管理平台
基於 Docker 的全方位智能販賣機後台管理系統 (Cloud 平台)
Star Cloud 是一個專為智能販賣機設計的後台管理系統，負責管理機台、商品、銷售數據，並為硬體端點提供專用的 API。
🚀 技術架構
核心架構
本專案採用 傳統單體式架構 (Monolithic Architecture)，結合 Laravel Blade 引擎進行伺服器端渲染 (SSR)。
| 服務 | 容器名稱 | 技術 | 用途 | 本地 Port |
|---|---|---|---|---|
| 應用程式 | star-cloud-laravel |
Laravel 12 + PHP 8.5 | 核心業務與渲染 | 8090 |
| 資料庫 | star-cloud-mysql |
MySQL 8.0 | 數據持久化 | 3306 |
| 快取/隊列 | star-cloud-redis |
Redis Alpine | IoT 高併發隊列 | 6380 |
後端技術棧
- Framework: Laravel 12.x
- Language: PHP 8.5
- Redis: 用於 IoT 高併發隊列 (B010, B600 等)
- Database: MySQL 8.0
前端技術棧
- 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
快速啟動
clone專案並進入目錄cp .env.example .env./vendor/bin/sail up -d./vendor/bin/sail composer install./vendor/bin/sail artisan key:generate./vendor/bin/sail artisan migrate --seed./vendor/bin/sail npm install./vendor/bin/sail npm run dev
常用開發指令
| 功能 | 指令 |
|---|---|
| 啟動環境 | ./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 |
🔐 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>。 - 高併發處理: 核心日誌 (B010 心跳、B600 交易) 嚴禁直寫 DB，必須進入 Redis Queue 背景異步處理。
🌐 多語系支援 (I18n)
所有 UI 顯示文字必須支援多語系，禁止 Hard-coded。
- 語系檔案:
lang/zh_TW.json,lang/en.json,lang/ja.json。 - 呼叫方式: 使用
__('Phrases in English')或@lang('...')。 - 命名規範: 優先使用「英文原始詞彙」作為 Key 名稱。
📂 目錄結構
app/Http/Controllers/: 控制器app/Models/{Domain}/: 分領域的模型 (如Machine,Member)app/Services/{Domain}/: 封裝商業邏輯與資料異動app/Jobs/{Domain}/: IoT 異步隊列處理任務 (重要)resources/views/: Blade 模板 (按功能分資料夾)resources/views/components/: 可重用的 UI 組件routes/: 路由定義 (web.php與api.php)
🚢 CI/CD 與部署
- 自動化工具: Gitea Actions (
.gitea/workflows/)。 - Demo 環境: 推送到
demo分支會自動部署至demo-cloud.taiwan-star.com.tw。 - 伺服器路徑:
/var/www/star-cloud-demo(透過ssh gitea_work登入)。
授權與版權
© Star Cloud. All Rights Reserved.
技術支援
如有問題或建議，請聯繫開發團隊或提交 Issue。