terrylee/star-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
f59efc6dc7
star-cloud/.agents/rules/framework.md
sky121113 f59efc6dc7 [FIX] 補齊與優化來店禮、通行碼、取貨碼之多語系與介面欄位呈現 
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 頁面欄位：將取貨碼頁面的「機台序號」替換為更具溫度的「機台名稱」；通行碼與來店禮頁面則徹底隱藏機台序號，優化用戶體驗。
2026-05-22 14:46:26 +08:00

3.1 KiB
Raw Blame History

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 雙軌並行 策略：

機台 (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