116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
# 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。 |