feat: 實作機台日誌核心功能與 IoT 高併發處理架構

.agents/rules/framework.md

@@ -0,0 +1,78 @@
+---
+trigger: always_on
+---
+
+# 開發框架規範說明書：Cloud 後台管理系統 (star-cloud)
+
+## 1. 專案概述
+*   **目標**：打造一個強大且穩定的智能販賣機後台管理系統（Cloud 平台），負責管理機台、商品、銷售數據以及提供給端點機台串接的 API。
+*   **核心架構**：採用 **傳統單體式架構 (Monolithic Architecture)** 配 Laravel Blade 模板引擎進行伺服器端渲染 (SSR)。
+*   **工作流程**：後端處理業務邏輯與資料庫存取，並透過 Blade 引擎渲染包含 Tailwind CSS 類別的 HTML。前端互動行為由輕量級 Alpine.js 負責，UI 元件以 Preline UI 為主體。
+
+## 2. 技術棧 (Tech Stack)
+*   **後端框架**：PHP 8.5 / Laravel 12
+*   **核心組件**：Redis (用於高併發 IoT 隊列與快取，為系統穩定之必要條件)
+*   **前端視圖 (View)**：Laravel Blade
+*   **前端互動 (JS)**：Alpine.js (專注於行為，不負責渲染)
+*   **介面與樣式 (CSS)**：Tailwind CSS + Preline UI (直接寫作於 Blade 模板中)
+*   **前端建置工具**：Vite
+*   **資料庫**：MySQL 8.0
+*   **開發環境**：Laravel Sail (Docker / WSL2)
+
+## 3. 目錄結構與慣例
+
+### 3.1 後端 (Laravel)
+與標準 Laravel 結構保持一致，無過度拆分的模組化（與 ERP 的 Modular Monolith 區別）：
+*   **Controllers**：`app/Http/Controllers/`，負責接收請求並回傳 `view()` 或 JSON。
+*   **Models**：`app/Models/{Domain}/`，按領域分群 (例如 `Machine`, `Member`, `System`)。
+*   **Routes**：`routes/web.php` 用於後台管理介面；`routes/api.php` 提供外部或機台調用介面 (需 V1 版本化)。
+*   **Services** (建議)：`app/Services/{Domain}/`，將商業邏輯與資料異動封裝於 Service 中。
+*   **Traits**：`app/Traits/ApiResponse.php` 用於統一 API JSON 回傳格式。
+*   **Jobs**：`app/Jobs/{Domain}/`，**高併發 IoT 場景之必要實作**。所有日誌、心跳上報必須進入 Redis Queue 進行背景異步處理，嚴禁在 API 直連 DB 寫入日誌。
+
+### 3.2 前端 (Blade / Tailwind / Alpine)
+*   **Views (頁面)**：位於 `resources/views/`。通常依功能建立資料夾（如 `resources/views/admin/machines/index.blade.php`）。
+*   **Layouts (版面)**：位於 `resources/views/layouts/`。定義全站的共用版面結構（如 header, sidebar, footer）。
+*   **Components (組件)**：位於 `resources/views/components/`。封裝可重用的 Blade 元件（如 Button, Modal, Table），支援透過 `<x-button>` 語法呼叫。
+
+## 4. 開發標準 (Coding Standards)
+*   **命名規範**：
+    *   Controllers: `PascalCaseController.php` (例如 `MachineController.php`)
+    *   Models: `PascalCase.php` (例如 `Machine.php`)
+    *   Blade Views: `kebab-case.blade.php` 或按資源名稱 (例如 `index.blade.php`, `create.blade.php`)
+    *   Routes uri: `kebab-case` (例如 `/machine-logs`)
+*   **回傳格式**：
+    *   Web 路由：回傳 `view()`，表單驗證失敗時直接使用 Laravel 內建的 redirect with errors。
+    *   API 路由：回傳標準 JSON 格式的 `JsonResponse`。
+
+## 5. UI 與前端開發指南
+*   **樣式撰寫**：全面使用 Tailwind CSS utility classes，**避免撰寫自訂 CSS**（除非少數特定動畫或覆寫）。
+*   **UI 元件庫**：遵循 **Preline UI** 的類別與 HTML 結構進行開發。
+*   **前端腳本**：
+    *   優先使用 **Alpine.js** (`x-data`, `x-show`, `@click` 等) 在 HTML 標籤內完成簡單的 DOM 狀態切換與互動邏輯。
+    *   避免在 Blade 內撰寫冗長的 `<script>` Vanilla JS；若邏輯過於複雜，可將 Alpine state 獨立成 js 檔案再於 Vite 引入，但原則上保持輕量。
+
+## 6. AI 協作規則 (給 Antigravity AI)
+*   **角色設定**：你是一位專業的全端開發工程師助手。
+*   **代碼生成指令**：
+    *   所有的解釋說明請使用 **繁體中文**。
+    *   **【警告】** 此專案前端禁用 React / Vue / Inertia.js。所有的前端頁面生成必須使用 **Blade 模板** 結合 **Tailwind CSS** 與 **Alpine.js**。
+    *   生成 UI 區塊時，必須優先參考與產生 **Preline UI** 風格與結構的標記語法。
+    *   開發新功能時，請建立標準的 Controller 搭配對應的 `resources/views/.../` 目錄。
+
+## 7. 運行機制 (Docker / Sail)
+由於專案運行在 Docker 容器環境中，請勿直接在宿主機 (Host) 執行 php 或 composer 指令。請使用專案內建的 `sail` 指令：
+
+*   **啟動環境**：`./vendor/bin/sail up -d`
+*   **執行 PHP 指令**：`./vendor/bin/sail php -v`
+*   **執行 Artisan 指令**：`./vendor/bin/sail artisan route:list`
+*   **執行 Composer**：`./vendor/bin/sail composer install`
+*   **執行 Node/NPM**：`./vendor/bin/sail npm run dev`
+
+## 8. 部署與查修環境 (CI/CD)
+*   **自動化部署**：專案具備基於 Gitea Actions 的 CI/CD 自動化部署流程 (`.gitea/workflows/`)。
+*   **Demo 環境 (對應 `demo` 分支)**：
+    *   透過 `deploy-demo.yaml`，合併或推送到 `demo` 分支會自動部署至 `demo-cloud.taiwan-star.com.tw`。
+    *   登入伺服器查修：`ssh gitea_work`，路徑為 `/var/www/star-cloud-demo`。
+*   **Production 環境 (對應 `main` 分支)**：
+    *   透過 `deploy-prod.yaml`，推進到 `main` 會自動部署至正式站。