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

.agents/rules/api-rules.md

@@ -0,0 +1,209 @@
+---
+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/{id}/logs** (IoT)
+  *   用於機台回傳日誌，後端固定走 **Redis Queue 異步寫入**。
+  *   回傳 `202 Accepted` 表示任務已接收，由 `ProcessMachineLog` 背景處理。
+  *   Request Example:
+  ```json
+  {
+    "level": "info",
+    "message": "Temperature stabilized at 23C",
+    "context": { "temp": 23.0 }
+  }
+  ```
+
+---
+
+### 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 清單。*

.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` 會自動部署至正式站。

.agents/rules/skill-trigger.md

@@ -0,0 +1,31 @@
+---
+trigger: always_on
+---
+
+# 技能觸發規範 (Skill Trigger Rules)
+
+本文件確保 AI 助手在對話中能**主動辨識**需要參照技能 (Skill) 的時機。
+Skills 位於 `.agents/skills/`，採漸進式揭露以節省 Token。
+**若對話內容命中以下任一觸發條件，必須先使用 `view_file` 讀取對應的 `SKILL.md` 後再進行作業。**
+
+---
+
+## 觸發對照表
+
+| 觸發詞 / 情境 | 對應 Skill | 路徑 |
+|---|---|---|
+| 機台通訊, IoT, 日誌上報, Log Ingestion, 異步隊列, Queue, Heartbeat, 心跳發報 | **IoT 通訊與高併發處理規範** | `.agents/skills/iot-communication/SKILL.md` |
+
+---
+
+## 強制觸發場景
+
+以下場景**無論對話中是否出現觸發詞**，都必須主動載入對應 Skill：
+
+### 🔴 新增機台通訊 API 端點時
+必須讀取：
+1. **iot-communication** — 決定是否使用異步隊列流程
+
+### 🔴 修改 Job 或 Service 邏輯時
+必須讀取：
+1. **iot-communication** — 確保符合高併發處理架構

.agents/skills/iot-communication/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: IoT 通訊與高併發處理規範
+description: 規範智能販賣機與 Cloud 平台間的高頻通訊處理流程，包含 API 接收、異步隊列、業務邏輯拆分與日誌記錄。
+---
+
+# IoT 通訊與高併發處理規範 (IoT Communication Skill)
+
+本規範確保 Star-Cloud 系統在處理成千上萬台機台的高頻發報時，能維持伺服器響應速度與資料一致性。
+
+## 1. 處理管線 (Processing Pipeline)
+
+所有來自機台的非即時性資料（日誌、心跳、狀態上報）必須遵循以下 pipeline：
+
+1.  **API Controller (接收層)**：驗證 Request 合法性，隨即分派 (Dispatch) 任務至 Queue，並回傳 `202 Accepted`。
+2.  **Job (異步層)**：由背景 Worker 讀取隊列任務，呼叫對應 Service 處理。
+3.  **Service (邏輯層)**：封裝商業邏輯，更新資料庫。
+4.  **Model (儲存層)**：執行資料存取。
+
+> [!IMPORTANT]
+> **嚴禁**在 API Controller 直接進行資料庫寫入操作（針對機台發訊端點）。
+
+## 2. 異步任務實作範例
+
+### 2.1 API Endpoint
+```php
+public function storeLog(Request $request, int $id): JsonResponse
+{
+    // 1. 驗證
+    $data = $request->validate([...]);
+    
+    // 2. 異步分派
+    ProcessMachineLog::dispatch($id, $data);
+    
+    // 3. 快速回應
+    return $this->successResponse([], 'Accepted', 202);
+}
+```
+
+### 2.2 Job 處理邏輯
+Job 應保持單純，僅作為 Service 的觸發點：
+```php
+public function handle(MachineService $service): void
+{
+    $service->recordLog($this->machineId, $this->logData);
+}
+```
+
+## 3. 隊列配置規範
+
+- **連接驅動 (Driver)**：預設使用 `Redis` 以確保高併發吞吐量。
+- **重試機制 (Retry)**：IoT 任務應設定合理的重試次數，避免因網路短暫波動遺失日誌。
+- **失敗處理 (Failed Jobs)**：關鍵業務（如訂單同步）必須監控 `failed_jobs`。
+
+## 4. 速率限制 (Rate Limiting)
+
+- 所有的 IoT API 必須在 `routes/api.php` 中使用 `throttle:api` 或自定義 Middleware。
+- 針對單一機台 ID 應限制其每一分鐘的最高連線數，防止遭受攻擊或機台 Bug 導致的連線暴衝。
+
+## 5. 檢核項目 (Checklist)
+- [ ] 是否使用了 `ApiResponse` Trait？
+- [ ] 業務邏輯是否已封裝至 `App\Services`？
+- [ ] 是否使用了 Redis Queue 進行非同步處理？
+- [ ] 是否在 API 層級進行了基礎的參數驗證？