first commit

2025-11-21 17:15:27 +08:00
commit c7cbe7edb7
152 changed files with 17423 additions and 0 deletions
--- a/.agent/rules/api-rules.md
+++ b/.agent/rules/api-rules.md
@@ -0,0 +1,222 @@
+---
+trigger: always_on
+---
+
+# Backend API Specification (backend.md)
+
+---
+
+## 目標範圍
+
+* 使用 Laravel (RESTful API)
+* 資料庫：MySQL（migration + seeder）
+* 提供給現有 Android 團隊的完整 API 規格（JSON 格式）
+
+---
+
+## 認證與安全
+
+* 採用 JWT 或 Laravel Sanctum
+* 所有需要授權的 API 回傳 401/403 規範
+* Error 格式：
+
+```json
+{
+  "success": false,
+  "code": 401,
+  "message": "Unauthorized",
+  "errors": null
+}
+```
+
+---
+
+## 一般回應格式
+
+成功：
+
+```json
+{
+  "success": true,
+  "code": 200,
+  "message": "OK",
+  "data": { }
+}
+```
+
+錯誤：同上 Error 範例
+
+---
+
+## API 清單（建議先開發順序）
+
+1. Auth (登入/登出/註冊/權杖)
+2. User / Profile
+3. Device / Machine (機台管理、狀態回傳、日誌)
+4. Order / ShoppingCart（若需）
+5. Notification / Push 訊息
+6. Activity / Campaign
+7. Report / Analytics
+8. Admin CRUD for resources
+
+---
+
+## 主要 Endpoints 範例
+
+### 1) Auth
+
+* POST /api/v1/auth/login
+
+  * request:
+
+  ```json
+  {"email":"user@example.com","password":"pa55"}
+  ```
+
+  * response:
+
+  ```json
+  {"success":true,"code":200,"data":{"token":"...","user":{"id":1,"name":"..."}}}
+  ```
+
+* POST /api/v1/auth/logout
+
+  * header: Authorization: Bearer <token>
+  * response: 200
+
+* POST /api/v1/auth/refresh
+
+---
+
+### 2) User / Profile
+
+* GET /api/v1/users/{id}
+* PUT /api/v1/users/{id}
+* GET /api/v1/users (admin)
+
+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:
+
+  ```json
+  {
+    "temperature": 23.4,
+    "status_code": "OK",
+    "firmware_version": "1.2.3",
+    "timestamp": "2025-11-20T15:00:00Z"
+  }
+  ```
+
+* GET /api/v1/machines/{id}/logs
+
+---
+
+### 4) Orders / ShoppingCart
+
+* POST /api/v1/cart/add
+* GET /api/v1/cart
+* POST /api/v1/orders
+* GET /api/v1/orders/{id}
+
+支付與第三方串接請另行設計 callback endpoint。
+
+---
+
+### 5) Notification
+
+* POST /api/v1/notifications/send (admin)
+* GET /api/v1/notifications (user)
+
+Payload for push could include: title, body, target_user_ids, data
+
+---
+
+### 6) Activity / Campaign
+
+* GET /api/v1/campaigns
+* POST /api/v1/campaigns
+* PUT /api/v1/campaigns/{id}
+
+---
+
+### 7) Report / Analytics
+
+* GET /api/v1/reports/machines/summary?from=YYYY-MM-DD&to=YYYY-MM-DD
+* GET /api/v1/reports/sales/summary
+
+Response should include aggregated numbers and paginated lists when needed.
+
+---
+
+## Database 基本表（初步）
+
+* users
+* roles
+* machines
+* machine_logs
+* orders
+* order_items
+* carts
+* notifications
+* campaigns
+* activity_logs
+* translations (i18n)
+
+（每張表建議 migration 欄位、index、外鍵，請於開發前定稿）
+
+---
+
+## API 規格輸出
+
+* 建議產出 Swagger (OpenAPI 3.0) 與 Postman Collection
+* 每個 endpoint 必要欄位、範例、error code、rate limit
+
+---
+
+## 測試建議
+
+* Unit tests：Laravel Feature tests for API
+* Contract tests：與 Android 團隊一同建立 contract tests（或使用 Postman tests）
+
+---
+
+## 部署與運營
+
+* 建議使用 queue 與 cache（Redis）處理非同步任務
+* Logging: Sentry or similar
+* 定期備份 MySQL
+
+---
+
+## 交付項目清單
+
+1. 完整 Laravel 專案（註冊、登入、ACL）
+2. MySQL migration + seeders
+3. Swagger/OpenAPI 文件
+4. Postman Collection
+5. 後台管理系統（Star Cloud）
+6. 測試報告
+7. 部署腳本與上線說明
+
+---
+
+*註：本檔為初版 backend.md，若要我把 Excel 的每一列功能自動轉成對應的 API endpoint（含 request/response 範例），我可以直接在此檔案中展開更詳細的 endpoint 清單。*
--- a/.agent/rules/backend-rules.md
+++ b/.agent/rules/backend-rules.md
@@ -0,0 +1,528 @@
+---
+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.