star-cloud/.agents/rules/framework.md

trigger

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. 多語系 I18n 規範 (Multi-language Standards)

• 視圖開發：所有使用者可見的文字、按鈕、提示訊息，必須使用 Laravel 的 @lang('key') 或 __('key') 函式包裹。
• 語系 Key 命名：語系 Key 必須採用 英文原始詞彙 (English phrases) 作為 Key 名稱為原則，以提高代碼可讀性並作為預設回退（除非該字串過長，才建議使用點號分隔的 key）。
  • 範例：使用 __('Account Settings')。
• 翻譯檔維護：
  • 主語系檔案位於 lang/ 目錄。
  • 開發新功能時，必須同步更新以下三個 JSON 翻譯檔：zh_TW.json (主要)、en.json (預設)、ja.json (日文)。

7. AI 協作規則 (給 Antigravity AI)

• 角色設定：你是一位專業的全端開發工程師助手。
• 代碼生成指令：
  • 所有的解釋說明請使用 繁體中文。
  • 【警告】 此專案前端禁用 React / Vue / Inertia.js。所有的前端頁面生成必須使用 Blade 模板 結合 Tailwind CSS 與 Alpine.js。
  • 【多語系強制要求】 任何新增的 Blade UI 區塊，禁止硬編碼 (Hard-coded) 中文或英文。必須使用 __('...') 並同步在 lang/*.json 補上翻譯。
  • 生成 UI 區塊時，必須優先參考與產生 Preline UI 風格與結構的標記語法。
  • 開發新功能時，請建立標準的 Controller 搭配對應的 resources/views/.../ 目錄。

8. 運行機制 (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。

9. 瀏覽器測試規範 (Browser Testing)

當需要進行瀏覽器自動化測試或手動驗證時，必須遵守以下連線資訊：

• 本地測試網址：http://localhost:8090/ (注意：非 8000 或 8080)
• 預設管理員帳號：admin
• 預設管理員密碼：password

Important

在執行 open_browser_url 或進行 E2E 測試時，請務必優先確認 Port 是否為 8090，以避免連線至錯誤的服務環境。

10. 環境與時區規範 (Environment & Timezone Standards)

10.1 時區與語系設定

• 預設時區：必須設定為 Asia/Taipei (UTC+8)。
• 實作細節：
  • .env：必須包含 APP_TIMEZONE=Asia/Taipei。
  • config/app.php：必須改為讀取環境變數 env('APP_TIMEZONE', 'Asia/Taipei')。
  • 目的：確保資料庫時間戳記與日誌紀錄與台灣當地時間完全一致。

10.2 開發慣例與效能優化

• 登入日誌機制：
  • 實作 10 秒防重覆 (Debouncing)：同一 IP 與帳號在 10 秒內的連續登入僅記錄一筆，以避免行動網路環境下的重複上報。
  • 監聽器註冊：嚴禁在多個 ServiceProvider 中重複註冊 Login 事件監聽器，應統一在 EventServiceProvider 中管理。
• 裝置識別：
  • 使用 jenssegers/agent 進行裝置偵測，並將 device_type, browser, platform 儲存於 user_login_logs 表。

10.3 IP 偵測特性 (IP Ingestion)

• 本地開發 (Sail) 特性：
  • 172.x.x.x：為 Docker Network Gateway。當從宿主機以 localhost 存取時，會呈現閘道 IP，此為正常網路行為。
  • 真實區網 IP：若由其他行動裝置透過區域網路存取，可正確擷取 192.168.x.x 等實際 IP。
• 轉發與代理：系統已全域啟用 TrustProxies，在正式環境中配合 Nginx 或 Cloudflare 時，可正確解析外部公網 IP。