terrylee/star-cloud
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
9bc6450fac
star-cloud/.agents/rules/framework.md
sky121113 b21ea670bf [FIX] 修正遠端指令中心機台列表顯示與規格文件更新 
1. 修正 `tab-machines-index.blade.php` 最後通訊時間的 HTML `<template>` 渲染錯誤，確保正常顯示。
2. 更新 `index.blade.php` 的 `formatTime` 邏輯，超過 2 小時的通訊時間將顯示完整日期與時間，與庫存頁面格式統一。
3. 更新 `tab-machines.blade.php` 與語系檔，將庫存警示相關文案精準化為「庫存警示 (Inventory Alerts)」與「庫存穩定 (Inventory Stable)」。
4. 更新 `api-technical-specs/SKILL.md` 中對於 B017 API 的描述，強調其為機台端主動拉取資料，而非單純依賴 MQTT 觸發。
5. 修正 `iot-communication/SKILL.md` 中 Redis Key 前綴的說明，對齊實際讀取 `.env` (`MQTT_REDIS_PREFIX`) 的設定。
2026-04-22 12:33:01 +08:00

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

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