diff --git a/.agent/rules/backend-rules.md b/.agent/rules/backend-rules.md deleted file mode 100644 index 966d2bb..0000000 --- a/.agent/rules/backend-rules.md +++ /dev/null @@ -1,528 +0,0 @@ ---- -trigger: always_on ---- - -STAR CLOUD 後台管理系統 - 智能販賣機管理平台 - -一、儀錶板模組 (Dashboard) -1.1 主頁面 - -功能描述: 系統總覽與關鍵數據展示 -主要內容: - -即時銷售數據 -機台運行狀態 -庫存警示 -營收統計圖表 - - - - -二、應用程式管理 (Application Management) -2.1 個人檔案 - -功能描述: 使用者個人資訊管理 -包含功能: - -基本資料編輯 -密碼修改 -通知設定 - - - - -三、機台管理模組 (Machine Management) -3.1 機台日誌 - -功能描述: 機台操作歷史紀錄回溯 -資料內容: - -操作時間戳記 -事件類型 -操作人員 -詳細描述 - - - -3.2 機台列表 - -功能描述: 所有機台資訊總覽 -顯示資訊: - -溫度監控 -下位機狀態 -刷卡機連線 -掃碼機狀態 -機台回傳訊息 - - - -3.3 機台權限 - -功能描述: 機台存取權限控管 -設定項目: - -人員權限分配 -操作級別設定 - - - -3.4 機台稼動率 - -功能描述: 機台運行效率分析 -統計數據: - -運行時間 -停機時間 -稼動率百分比 - - - -3.5 效期管理 - -功能描述: 商品效期與貨道出貨控制 -管理項目: - -設定貨道是否可出貨 -效期到期提醒 -商品下架設定 - - - -3.6 維修管理單 - -功能描述: 機台維修工單系統 -包含功能: - -報修單建立 -維修進度追蹤 -維修歷史紀錄 - - - -3.7 機台管理擴充欄位 - -新增欄位: - -保固區間 -交機日期 -租賃區間 -保內/保外狀態顯示 - - - -3.8 機台設定參數 - -刷卡機秒數: 刷卡逾時設定 -卡機結帳時間: 結帳流程時間限制 -卡機結帳時間2: 備用結帳時間設定 -金流緩衝時間: 金流處理緩衝時間 -刷卡機編號: 刷卡機裝置識別 -發票狀態碼: 發票開立狀態管理 - -3.9 APP到期提醒 - -功能描述: APP授權到期通知系統 - - -四、APP管理模組 (APP Management) -4.1 UI元素設定 - -功能描述: APP版面配置設定 -注意事項: 與新版差異較大,需特別處理 - -4.2 小幫手設定 - -功能描述: APP內建輔助功能設定 - -4.3 問卷設定 - -功能描述: 互動問卷建立與管理 - -4.4 互動遊戲設定 - -功能描述: APP互動遊戲配置 - -4.5 計時器 - -功能描述: 時間相關功能設定 - - -五、倉庫管理模組 (Warehouse Management) -5.1 倉庫列表 - -5.1.1 倉庫列表(全部): 顯示所有倉庫 -5.1.2 倉庫列表(個人): 顯示個人負責倉庫 - -5.2 庫存管理單 - -功能描述: 倉庫庫存異動管理 - -5.3 調撥單 - -功能描述: 倉庫間商品調撥作業 - -5.4 採購單 - -功能描述: 商品採購申請與管理 - -5.5 機台補貨管理 - -5.5.1 機台補貨單: 補貨工單建立 -5.5.2 機台補貨紀錄: 個別補貨歷史 -5.5.3 機台補貨紀錄(總): 所有補貨總覽 - -5.6 庫存查詢 - -5.6.1 機台庫存: 各機台即時庫存 -5.6.2 人員庫存: 人員持有庫存 - -5.7 回庫單 - -功能描述: 商品退回倉庫管理 - - -六、銷售管理模組 (Sales Management) -6.1 銷售&金流紀錄 - -功能描述: 銷售交易與金流明細 -包含項目: - -現金出貨 API -發票系統整合 -各種出貨方式整理 - - - -6.2 取貨碼設定 - -功能描述: 取貨驗證碼管理 - -6.3 購買單 - -功能描述: 購買訂單管理 - -6.4 促銷時段設定 - -功能描述: 促銷活動時間設定 -重要功能: (W) 重啟掃描商品 API - -6.5 通行碼設定 - -功能描述: 特殊通行碼權限管理 - -6.6 來店禮設定 - -功能描述: 來店優惠活動設定 -包含: 來店禮開關控制 - - -七、分析管理模組 (Analysis Management) -7.1 零錢庫存分析 - -功能描述: 機台零錢數量監測與分析 - -7.2 機台報表分析 - -功能描述: 機台運營數據分析報表 - -7.3 商品報表分析 - -功能描述: 商品銷售數據分析 - -7.4 互動問卷分析 - -功能描述: 問卷結果統計與分析 - - -八、稽核管理模組 (Audit Management) -8.1 採購單稽核 - -功能描述: 採購單審核流程 - -8.2 調撥單稽核 - -功能描述: 調撥單審核流程 - -8.3 補貨單稽核 - -功能描述: 補貨單審核流程 - - -九、資料設定模組 (Data Configuration) -9.1 機台管理 - -功能描述: 機台基本資料設定 - -9.2 商品管理 - -功能描述: 商品資料維護 - -9.3 廣告管理 - -功能描述: 機台廣告影片管理 -用途: 機台可讀取後台廣告影片 - -9.4 管理者可賣商品 - -功能描述: 管理者商品銷售權限 - -9.5 帳號管理 - -功能描述: 主帳號管理 - -9.6 子帳號管理 - -功能描述: 子帳號建立與管理 - -9.7 子帳號角色管理 - -功能描述: 子帳號權限角色設定 - -9.8 點數設定 - -功能描述: 客戶點數系統設定 -特殊功能: 支援客戶自行新增點數 - -9.9 識別證管理 - -功能描述: 識別證資料管理 -用途: 安霸系統使用 - - -十、遠端管理模組 (Remote Management) -10.1 機台庫存 - -功能描述: 遠端修改機台庫存 - -10.2 機台重啟 - -功能描述: 遠端重啟機台系統 - -10.3 卡機重啟 - -功能描述: 遠端重啟刷卡機 - -10.4 遠端結帳 - -功能描述: 遠端執行結帳流程 - -10.5 遠端鎖定頁 - -功能描述: 遠端鎖定機台頁面 - -10.6 遠端找零 - -功能描述: 遠端執行找零功能 - -10.7 遠端出貨 - -功能描述: 遠端控制商品出貨 - - -十一、Line管理模組 (Line Integration) -11.1 Line會員管理 - -功能描述: Line會員資料管理 - -11.2 Line機台管理 - -功能描述: Line綁定機台管理 - -11.3 Line商品管理 - -功能描述: Line商城商品設定 - -11.4 Line生活圈 - -功能描述: Line官方帳號整合 - -11.5 Line商城訂單 - -功能描述: Line商城訂單管理 - -11.6 Line優惠券 - -功能描述: Line優惠券發放與管理 - - -十二、預約系統模組 (Reservation System) -12.1 Line會員管理 - -功能描述: 預約系統會員管理 - -12.2 Line店家管理 - -功能描述: 店家資訊設定 - -12.3 Line時段組合 - -功能描述: 預約時段設定 - -12.4 Line場地管理 - -功能描述: 場地資源管理 - -12.5 Line優惠券管理 - -功能描述: 預約優惠券管理 - -12.6 Line預約管理 - -功能描述: 預約單管理 - -12.7 Line訂單管理 - -功能描述: 預約訂單處理 - - -十三、特殊權限管理模組 (Special Permissions) -13.1 庫存清空 - -功能描述: 特殊權限庫存清空功能 - -13.2 APK版本管理 - -功能描述: APP版本控制與更新 - -13.3 Discord通知設定 - -功能描述: Discord通知整合設定 - - -十四、權限設定模組 (Permission Management) -14.1 功能權限設定 - -14.1.1 APP功能管理: APP功能權限 -14.1.2 資料設定: 資料設定權限 -14.1.3 銷售管理: 銷售管理權限 -14.1.4 機台管理: 機台管理權限 -14.1.5 倉庫管理: 倉庫管理權限 -14.1.6 分析管理: 分析管理權限 -14.1.7 稽核管理: 稽核管理權限 -14.1.8 遠端管理: 遠端管理權限 -14.1.9 Line管理: Line管理權限 - -14.2 權限角色設定 - -功能描述: 角色權限組合設定 - -14.3 其他功能管理 - -功能描述: 其他特殊功能權限 - -14.4 AI智能預測 - -功能描述: AI功能權限設定 - - -資料庫設計建議 -主要資料表規劃 -machines # 機台資料表 -├── warehouses # 倉庫資料表 -├── products # 商品資料表 -├── machine_stocks # 機台庫存表 -├── warehouse_stocks # 倉庫庫存表 -├── sales_records # 銷售紀錄表 -├── purchase_orders # 採購單表 -├── transfer_orders # 調撥單表 -├── replenishment_orders # 補貨單表 -├── maintenance_orders # 維修單表 -├── machine_logs # 機台日誌表 -├── users # 使用者表 -├── roles # 角色表 -├── permissions # 權限表 -├── line_members # Line會員表 -├── reservations # 預約表 -└── advertisements # 廣告表 - -API 端點規劃 -機台管理 API - -GET /api/machines - 取得機台列表 -POST /api/machines - 新增機台 -PUT /api/machines/{id} - 更新機台 -DELETE /api/machines/{id} - 刪除機台 -GET /api/machines/{id}/logs - 取得機台日誌 -POST /api/machines/{id}/restart - 遠端重啟 - -倉庫管理 API - -GET /api/warehouses - 取得倉庫列表 -GET /api/warehouses/{id}/stocks - 取得倉庫庫存 -POST /api/transfer-orders - 建立調撥單 -POST /api/purchase-orders - 建立採購單 -POST /api/replenishment-orders - 建立補貨單 - -銷售管理 API - -GET /api/sales - 取得銷售紀錄 -POST /api/sales/cash - 現金出貨 -GET /api/sales/invoice - 發票查詢 -POST /api/pickup-codes - 建立取貨碼 - -遠端控制 API - -POST /api/remote/checkout - 遠端結帳 -POST /api/remote/dispense - 遠端出貨 -POST /api/remote/change - 遠端找零 -POST /api/remote/lock - 遠端鎖定 - - -技術架構建議 -後端技術 - -框架: Laravel 10+ -資料庫: MySQL 8.0+ -快取: Redis -佇列: Laravel Queue (Redis Driver) -API文件: Swagger/OpenAPI - -前端技術 - -模板引擎: Blade -CSS框架: Tailwind CSS -JavaScript: Alpine.js / Vue.js -圖表庫: Chart.js / ApexCharts - -第三方整合 - -Line API: Line Messaging API -Discord: Discord Webhook -金流: 藍新、綠界等 -發票: 電子發票整合 - - -開發優先順序建議 -Phase 1 - 核心功能 (1-2個月) - -使用者認證與權限系統 -機台管理基本功能 -倉庫管理基本功能 -銷售紀錄查詢 - -Phase 2 - 進階功能 (2-3個月) - -遠端控制功能 -報表分析功能 -稽核流程 -APP管理功能 - -Phase 3 - 整合功能 (1-2個月) - -Line整合 -預約系統 -AI智能預測 -Discord通知 - - -注意事項 - -安全性: 所有遠端控制功能需要雙重驗證 -權限控管: 嚴格的角色權限分離 -日誌記錄: 所有重要操作需記錄日誌 -API限流: 防止API濫用 -資料備份: 定期自動備份機制 -錯誤處理: 完善的異常處理機制 -測試: 重要功能需撰寫測試案例 -RetryClaude can make mistakes. Please double-check responses. \ No newline at end of file diff --git a/.agent/rules/api-rules.md b/.agents/rules/api-rules.md similarity index 88% rename from .agent/rules/api-rules.md rename to .agents/rules/api-rules.md index e5c4cb3..fbd203d 100644 --- a/.agent/rules/api-rules.md +++ b/.agents/rules/api-rules.md @@ -100,34 +100,21 @@ Request / Response 均採 JSON,個資欄位請遵守最小授權原則。 ### 3) Machine (機台) -* GET /api/v1/machines - - * Params: page, per_page, status - -* GET /api/v1/machines/{id} - -* POST /api/v1/machines - -* PUT /api/v1/machines/{id} - -* DELETE /api/v1/machines/{id} - -* POST /api/v1/machines/{id}/status - - * 用於下位機或 APP 回傳機台狀態 - * request example: - +* **GET /api/v1/machines** + * Params: page, per_page, status +* **GET /api/v1/machines/{id}** +* **POST /api/v1/machines/{id}/logs** (IoT) + * 用於機台回傳日誌,後端固定走 **Redis Queue 異步寫入**。 + * 回傳 `202 Accepted` 表示任務已接收,由 `ProcessMachineLog` 背景處理。 + * Request Example: ```json { - "temperature": 23.4, - "status_code": "OK", - "firmware_version": "1.2.3", - "timestamp": "2025-11-20T15:00:00Z" + "level": "info", + "message": "Temperature stabilized at 23C", + "context": { "temp": 23.0 } } ``` -* GET /api/v1/machines/{id}/logs - --- ### 4) Orders / ShoppingCart diff --git a/.agents/rules/framework.md b/.agents/rules/framework.md new file mode 100644 index 0000000..f11ffe0 --- /dev/null +++ b/.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),支援透過 `` 語法呼叫。 + +## 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 內撰寫冗長的 `