f59efc6dc7
1. 移除非必要之 Log 備註：從來店禮使用記錄 (Logs) 的電腦版與行動版畫面中，徹底移除了無業務參考價值的技術備註 (Remark) 欄位，優化排版空間以符合極簡奢華風 UI 設計。 2. 補齊與對齊三語系檔案：補齊來店禮、通行碼與商品領取所缺少的多語系 Key，三個語系 JSON 檔 (zh_TW, en, ja) 的 Key 與行數已 100% 完美對齊 (共 2,255 行) 且完成升冪字母排序 (ksort)。 3. 簡化 Guest 票券大標題：簡化 Guest 端三種票券頁面 (通行碼、取貨碼、來店禮) 的大標題多語系拼接結構，改為單一乾淨的翻譯 Key 呼叫。 4. 口語化翻譯微調：將 Pickup Code 在語系檔中的中文翻譯由「領取碼」微調為更口語、直覺的「取貨碼」。 5. 優化 Guest 頁面欄位：將取貨碼頁面的「機台序號」替換為更具溫度的「機台名稱」；通行碼與來店禮頁面則徹底隱藏機台序號，優化用戶體驗。
49 lines
3.1 KiB
Markdown
49 lines
3.1 KiB
Markdown
---
|
||
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`。必須嚴格遵守「多語系管理與自動對齊規範 (SKILL.md)」，以 `zh_TW.json` 為標準對齊三語系，所有 JSON 檔案須按字母排序 (ksort)，且斜線一律使用 `JSON_UNESCAPED_SLASHES` 還原為 `/`，嚴禁逸出為 `\/`。
|
||
|
||
## 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` |