sky121113
a599b14df1
All checks were successful
star-cloud-deploy-demo / deploy-demo (push) Successful in 1m6s
1. 修復帳號管理與角色權限頁面搜尋功能，支援 Enter 鍵快捷提交。 2. 完成 B013 (機台故障上報) API 實作，改用非同步隊列 (ProcessMachineError) 處理日誌上報。 3. 精簡 B013 API 參數，移除冗餘的 message 欄位，統一由雲端對照表翻譯。 4. 更新技術規格文件 (SKILL.md) 與系統 API 文件配置 (api-docs.php)。 5. 修正平台管理員帳號在搜尋過濾時的資料隔離邏輯。
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。