# 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。