star-cloud/README.md

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

快速啟動

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

常用開發指令

功能	指令
啟動環境	./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。