---
trigger: always_on
---

# 開發框架規範說明書：Cloud 後台管理系統 (star-cloud)

## 1. 專案概述 & 技術棧
*   **目標**：智能販賣機後台管理系統，負責機台、商品、銷售數據與 IoT API。
*   **核心架構**：Monorepo 單體式架構。
    *   **後端核心**：PHP 8.5 / Laravel 12, MySQL 8.0, Redis（快取與異步橋接）。
    *   **IoT 通訊層**：EMQX 5 (MQTT Broker) + Go MQTT Gateway。
    *   **前端視圖**：Laravel Blade (SSR) + Alpine.js (互動) + Tailwind CSS + Preline UI (組件)。
    *   **開發環境**：Laravel Sail (Docker / WSL2)

## 2. 系統架構與資料流向

本系統採用 **MQTT 與 HTTP 雙軌並行** 策略：

```text
機台 (Android APP)
     │
     ├─ [高頻/即時] MQTT ──→ EMQX Broker ──→ Go Gateway ──→ Redis List ──→ Laravel Job ──→ MySQL
     │
     └─ [低頻/大檔] HTTP REST ──→ Laravel API Controller ──→ MySQL
```

*   **Go Gateway 職責**：僅限「接收、驗證、轉發」。**嚴禁**在 Go 中實作商業邏輯，統一交由 Laravel Service/Job 處理。
*   **橋接機制**：Go 收到 MQTT 訊息後轉為 JSON，推入 Redis List，Laravel 透過常駐指令 (`mqtt:listen`) 消費並分派至對應的 Job 處理。

## 3. 核心目錄結構特徵
除標準 Laravel 結構外，本專案的特殊慣例：
*   **`mqtt-gateway/`**：Go 獨立專案目錄，負責 MQTT 訊息接收與轉發。
*   **`app/Jobs/`**：用於處理 Go 轉發過來的 IoT 非同步資料寫入與背景邏輯。
*   **`app/Console/Commands/`**：包含常駐守護進程 (如 `mqtt:listen`)。
*   **`resources/views/components/`**：全站共用的 Blade UI 元件（如 `<x-button>`），支援 x- 前綴呼叫。

## 4. 前端與 UI 開發規範
*   **樣式與組件**：全面使用 Tailwind CSS utility classes，遵循 Preline UI 的 HTML 結構進行開發。**避免撰寫自訂 CSS**。
*   **互動邏輯**：優先使用輕量級 **Alpine.js** (`x-data`, `x-show`, `@click`) 於 Blade 內完成，**禁用 React / Vue / Inertia.js**。
*   **【警告：Preline 冗餘】**：Preline 官方範例常有多餘控制項。必須確保介面佈局極簡，嚴格遵守「極簡奢華風 UI 實作規範 (SKILL.md)」。
*   **多語系 (I18n)**：所有 UI 可見文字必須使用 `@lang('key')` 或 `__('key')` 處理。Key 統一採用**英文原始詞彙**，並同步更新 `zh_TW.json`, `en.json`, `ja.json`。

## 5. 運行與測試機制
*   **啟動環境**：`./vendor/bin/sail up -d`
*   **執行指令**：透過 `./vendor/bin/sail php` / `artisan` / `composer` / `npm`
*   **CI/CD 部署**：具備 Gitea Actions 自動化部署 (`demo` 分支會自動部署至 `demo-cloud.setdomains.work`)。
*   **瀏覽器測試**：
    *   本地測試網址：`http://localhost:8090/` (注意 Port 為 **8090**)
    *   預設管理員帳號 / 密碼：`admin` / `Star82779061`