# Star Cloud 智能販賣機管理平台

> 基於 Docker 的全方位智能販賣機後台管理系統 (Cloud 平台)

Star Cloud 是一個專為智能販賣機設計的後台管理系統，負責管理機台、商品、銷售數據，並為硬體端點提供專用的 API。

---

## 🚀 技術架構

### 核心架構
本專案採用 **Monorepo 單體式架構**，以 Laravel 為核心進行伺服器端渲染 (SSR) 與 API 服務，並搭配 **Go MQTT Gateway** 作為高併發 IoT 通訊的前置接收層。兩者透過 **Redis** 進行異步橋接。

| 服務 | 容器名稱 | 技術 | 用途 | 本地 Port |
|------|---------|------|------|--------|
| **應用程式** | `star-cloud-laravel` | Laravel 12 + PHP 8.5 | 核心業務與渲染 | 8090 |
| **背景隊列** | `star-cloud-queue` | Laravel Queue Worker | 異步任務處理 | - |
| **資料庫** | `star-cloud-mysql` | MySQL 8.0 | 數據持久化 | 3306 |
| **快取/隊列** | `star-cloud-redis` | Redis Alpine | IoT 高併發隊列與 MQTT 橋接 | 6380 |
| **MQTT Broker** | `star-cloud-emqx` | EMQX 5.10 | 機台長連線與訊息路由 | 1883 / 18083 |
| **MQTT Gateway** | `star-cloud-mqtt-gateway` | Go | 訂閱 MQTT Topic、轉發至 Redis | - |

### 後端技術棧
- **Framework**: Laravel 12.x
- **Language**: PHP 8.5
- **Redis**: 用於 IoT 高併發隊列與 MQTT 橋接
- **Database**: MySQL 8.0

### IoT 通訊層
- **MQTT Broker**: EMQX 5.10 (維持機台長連線與訊息路由)
- **MQTT Gateway**: Go (訂閱 MQTT Topic、預處理訊息、轉發至 Redis)
- **橋接機制**: Redis List (`mqtt_incoming_jobs`)，由 Laravel 常駐指令 (`mqtt:listen`) 消費

### 前端技術棧
- **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`
9. `./vendor/bin/sail artisan mqtt:sync-auth` (同步機台 MQTT 認證至 Redis)
10. `./vendor/bin/sail artisan mqtt:listen` (啟動 MQTT 訊息消費者)

### 常用開發指令
| 功能 | 指令 |
|------|------|
| 啟動環境 | `./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` |
| MQTT 認證同步 | `./vendor/bin/sail artisan mqtt:sync-auth` |
| MQTT 隊列監聽 | `./vendor/bin/sail artisan mqtt:listen` |
| 重建 Gateway | `docker compose build mqtt-gateway && docker compose up -d mqtt-gateway` |

---

## 🔐 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>`。
- **高併發處理**: 核心日誌 (MQTT 心跳、B600 交易) **嚴禁直寫 DB**，必須進入 **Redis Queue** 背景異步處理。

### 3. MQTT IoT 通訊
- **對象**: 高頻/即時性機台通訊 (心跳、異常、交易)。
- **認證**: EMQX 透過 Redis Hash 驗證 (`machine_auth:{serial_no}` → `password` 欄位)。
- **資料流向**: `機台 ➜ EMQX ➜ Go Gateway ➜ Redis List ➜ Laravel mqtt:listen ➜ Job ➜ MySQL`

---

## 🌐 多語系支援 (I18n)

所有 UI 顯示文字必須支援多語系，禁止 Hard-coded。
- **語系檔案**: `lang/zh_TW.json`, `lang/en.json`, `lang/ja.json`。
- **呼叫方式**: 使用 `__('Phrases in English')` 或 `@lang('...')`。
- **命名規範**: 優先使用「英文原始詞彙」作為 Key 名稱。

---

## 📂 目錄結構

### Laravel (PHP)
- `app/Http/Controllers/`: 控制器
- `app/Models/{Domain}/`: 分領域的模型 (如 `Machine`, `Member`)
- `app/Services/{Domain}/`: 封裝商業邏輯與資料異動
- `app/Jobs/{Domain}/`: IoT 異步隊列處理任務 (重要)
- `app/Console/Commands/`: Artisan 指令 (含 `mqtt:listen`, `mqtt:sync-auth`)
- `resources/views/`: Blade 模板 (按功能分資料夾)
- `resources/views/components/`: 可重用的 UI 組件
- `routes/`: 路由定義 (`web.php` 與 `api.php`)

### MQTT Gateway (Go)
- `mqtt-gateway/main.go`: 進入點 (MQTT 連線、Redis 初始化)
- `mqtt-gateway/config/`: 環境變數與連線設定
- `mqtt-gateway/internal/handler/`: MQTT Topic 訊息處理邏輯
- `mqtt-gateway/internal/bridge/`: Redis 橋接層 (RPush / Consumer)

---

## 🚢 CI/CD 與部署

- **自動化工具**: Gitea Actions (`.gitea/workflows/`)。
- **Demo 環境**: 推送到 `demo` 分支會自動部署至 `demo-cloud.setdomains.work`。
- **伺服器路徑**: `/workspace/mama/star-cloud` (透過 `ssh demo-sc-103` 登入)。

---

## 授權與版權
© Star Cloud. All Rights Reserved.

---

## 技術支援

如有問題或建議，請聯繫開發團隊或提交 Issue。