b21ea670bf
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`) 的設定。
49 lines
2.9 KiB
Markdown
49 lines
2.9 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`。
|
||
|
||
## 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` |