star-cloud/.agent/rules/backend-rules.md

---
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.