[DOCS] 補齊 B024, B027, B055 API 技術規格與文檔定義

1. 更新技術手冊 (SKILL.md) 與 API 規格文件 (api-docs.php)，補齊 B024, B027, B055 之定義。
2. 修正文件序號跳號問題，確保 B017 序號正確銜接。
3. 詳細說明 B055 之指令 ID 遠端出貨運作機制。

.agents/rules/api-rules.md

@@ -2,208 +2,89 @@
 trigger: always_on
 ---
 
-# Backend API Specification (backend.md)
+# Backend API Specification (api-rules.md)
 
 ---
 
-## 目標範圍
+## 🚀 1. 目標範圍與分類
 
-* 使用 Laravel (RESTful API)
-* 資料庫：MySQL（migration + seeder）
-* 提供給現有 Android 團隊的完整 API 規格（JSON 格式）
+本系統 API 分為兩大類，遵循不同的設計慣例：
+
+*   **Admin/Web API (`/api/v1/...`)**: 供後台管理介面、APP UI 使用。遵循標準 RESTful 與 JSON 結構。
+*   **Machine IoT API (`/api/app/...`)**: 供販賣機、計時器等硬體端點使用。需相容既有 PDF 規格（如 B010, B600），欄位命名多為 `req1`, `req2` 或特定縮寫。
 
 ---
 
-## 認證與安全
+## 🔐 2. 認證與安全性
 
-* 採用 JWT 或 Laravel Sanctum
-* 所有需要授權的 API 回傳 401/403 規範
-* Error 格式：
-
-```json
-{
-  "success": false,
-  "code": 401,
-  "message": "Unauthorized",
-  "errors": null
-}
-```
+*   **Admin API**: 採用 **Laravel Sanctum (Session/Token)** 認證。
+*   **Machine IoT API**: 
+    *   **核心機制**: 必須在 Header 帶入 `Authorization: Bearer <api_token>` 進行身份驗證。
+    *   **Phase 1 (兼容模式)**: 若為相容既有機動硬體，可暫時接受 Request 包含 `key` 欄位，但後端應過渡至 Bearer 驗證。
+    *   **安全性強化**: 改用每台機台專屬的 `api_token` (透過 B010 初始化或派發)，並配合 `serial_no` (即 `workid`) 進行資料歸屬權驗證。
+*   **傳輸安全**: 必須強制使用 **HTTPS**。
 
 ---
 
-## 一般回應格式
-
-成功：
+## 📦 3. 回應格式規範
 
+### 3.1 標準回應 (Admin/Web API)
 ```json
 {
   "success": true,
   "code": 200,
   "message": "OK",
-  "data": { }
+  "data": { ... }
 }
 ```
 
-錯誤：同上 Error 範例
+### 3.2 IoT 指令回應 (B010/B055 等)
+機台端通常透過 response 的 `status` 欄位或特定的 `message` 字串來執行動作：
+*   **成功但有指令**: `{"status": "49", "message": "reload B017"}`
+*   **純資料回傳**: 直接返回對象陣列或 PDF 定義的欄位。
 
 ---
 
-## API 清單（建議先開發順序）
+## 🛠️ 4. 主要 Endpoints 與命名慣例
 
-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
+### 4.1 管理類 (Admin UI)
+*   `GET /api/v1/users`: 管理員清單
+*   `GET /api/v1/machines`: 機台清單
+*   `PUT /api/v1/machines/{id}`: 更新機台參數
+*   遵循 **kebab-case** 路由與 **snake_case** JSON 欄位。
+
+### 4.2 終端類 (IoT / Machine) — 須嚴格遵守 PDF 規格
+*   **API 識別碼 (workid)**: URL 中的 `{workid}` 參數固定為該 API 的功能代碼 (如 `B010`, `B017`, `B600`)，不隨機台改變。
+*   **機台識別方式**: 
+    1.  **Header (推薦)**: 透過 `Authorization: Bearer <api_token>` 識別。針對 B017 等端點，雲端將自動關聯對應機台，**不需**額外帶入機台識別參數。
+    2.  **Request Body (相容/特定模式)**: 透過 `machine` 或 `serial_no` 等欄位識別。主要用於 B000 登入或尚未取得 Token 的引導階段 (如 B014)。
+*   **主要 Endpoint 範例**:
+    *   **心跳上報 (B010)**: `POST /api/app/machine/status/B010`
+    *   **交易回傳 (B600)**: `POST /api/app/B600` (Body 欄位 `req2` 為機台編號)
+    *   **貨道庫存 (B017)**: `GET /api/app/machine/reload_msg/B017`
+    *   **遠端出貨 (B055)**: `POST /api/app/machine/dispense/B055`
 
 ---
 
-## 主要 Endpoints 範例
+## ⚡ 5. IoT 高併發流向與 MQTT Gateway 整合
 
-### 1) Auth
+為了系統穩定性與高吞吐量，機台通訊的架構依循以下規範，**嚴禁直寫資料庫**：
 
-* POST /api/v1/auth/login
+### 5.1 MQTT 通訊端點 (高頻與事件驅動)
+以下高頻或即時事件，未來將**全面改採 MQTT 協議**，透過 EMQX 與 Go Gateway 橋接：
+1.  **B010 (心跳)**：機台發布至 `machine/{serial_no}/heartbeat`。
+2.  **B013 (錯誤與狀態)**：機台發布至 `machine/{serial_no}/error`。
+3.  **B600 / B602 (交易紀錄)**：機台發布至 `machine/{serial_no}/transaction`。
 
-  * request:
+處理管線：
+`機台 ➜ EMQX ➜ Go Gateway ➜ Redis List (mqtt_incoming_jobs) ➜ Laravel daemon (mqtt:listen) ➜ Job 異步寫入 DB`
 
-  ```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
+### 5.2 HTTP 通訊端點 (資料拉取與特殊事件)
+基於歷史相容、大檔傳輸（如 `B012 商品同步`）或高度安全性（如 `B014 金鑰下載`）的端點，維持使用 HTTP REST API。
+若此類 API 產生寫入行為，後端應盡可能立即回傳 `202 Accepted`，並透過 Laravel Job 在背景完成數據持久化。
 
 ---
 
-### 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 清單。*
+## 📄 6. 交付與文件
+*   **OpenAPI**: 應區分 `admin.yaml` 與 `iot.yaml`。
+*   **Postman**: 提供帶有環境變數（機台金鑰、Base URL）的 Collection。

.agents/rules/framework.md

@@ -6,19 +6,29 @@ trigger: always_on
 
 ## 1. 專案概述
 *   **目標**：打造一個強大且穩定的智能販賣機後台管理系統（Cloud 平台），負責管理機台、商品、銷售數據以及提供給端點機台串接的 API。
-*   **核心架構**：採用 **傳統單體式架構 (Monolithic Architecture)** 配 Laravel Blade 模板引擎進行伺服器端渲染 (SSR)。
+*   **核心架構**：採用 **Monorepo 單體式架構**，以 Laravel 為核心進行伺服器端渲染 (SSR) 與 API 服務，並搭配 **Go MQTT Gateway** 作為高併發 IoT 通訊的前置接收層。兩者透過 **Redis** 進行異步橋接，確保職責分離與系統穩定性。
 *   **工作流程**：後端處理業務邏輯與資料庫存取，並透過 Blade 引擎渲染包含 Tailwind CSS 類別的 HTML。前端互動行為由輕量級 Alpine.js 負責，UI 元件以 Preline UI 為主體。
 
 ## 2. 技術棧 (Tech Stack)
+
+### 2.1 後端核心 (Laravel)
 *   **後端框架**：PHP 8.5 / Laravel 12
-*   **核心組件**：Redis (用於高併發 IoT 隊列與快取，為系統穩定之必要條件)
-*   **前端視圖 (View)**：Laravel Blade
-*   **前端互動 (JS)**：Alpine.js (專注於行為，不負責渲染)
-*   **介面與樣式 (CSS)**：Tailwind CSS + Preline UI (直接寫作於 Blade 模板中)
-*   **前端建置工具**：Vite
+*   **核心組件**：Redis (用於高併發 IoT 隊列、MQTT 橋接與快取，為系統穩定之必要條件)
 *   **資料庫**：MySQL 8.0
 *   **開發環境**：Laravel Sail (Docker / WSL2)
 
+### 2.2 IoT 通訊層 (MQTT Gateway)
+*   **MQTT Broker**：EMQX 5 (負責維持機台長連線與訊息路由)
+*   **Gateway 語言**：Go (負責訂閱 MQTT Topic、預處理訊息、轉發至 Redis)
+*   **橋接機制**：Redis List (`mqtt_incoming_jobs`)，由 Laravel 常駐指令 (`mqtt:listen`) 消費
+
+### 2.3 前端
+*   **前端視圖 (View)**：Laravel Blade
+*   **前端互動 (JS)**：Alpine.js (專注於行為，不負責渲染)
+*   **介面與樣式 (CSS)**：Tailwind CSS + Preline UI (直接寫作於 Blade 模板中)。
+    *   **重要規範**：Preline UI 僅作為「原子組件」與「JS 互動邏輯」的參考庫。整體的「佈局」與「美學」必須嚴格遵守「極簡奢華風 UI 實作規範 (SKILL.md)」。
+*   **前端建置工具**：Vite
+
 ## 3. 目錄結構與慣例
 
 ### 3.1 後端 (Laravel)
@@ -28,59 +38,150 @@ trigger: always_on
 *   **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 寫入日誌。
+*   **Jobs**：`app/Jobs/{Domain}/`，用於異步處理 IoT 資料寫入、通知發送等背景任務。
+*   **Console Commands**：`app/Console/Commands/`，包含 MQTT 橋接守護進程 (`mqtt:listen`) 等常駐指令。
 
 ### 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)
+### 3.3 MQTT Gateway (Go)
+Go 專案以 Monorepo 形式置於專案根目錄下的 `mqtt-gateway/` 資料夾，獨立於 Laravel 程式碼：
+*   **進入點**：`mqtt-gateway/main.go`
+*   **模組管理**：`mqtt-gateway/go.mod` / `go.sum`
+*   **內部分層**：
+    *   `mqtt-gateway/internal/handler/` — 各 Topic 的訊息處理邏輯（如 heartbeat、transaction、error）。
+    *   `mqtt-gateway/internal/bridge/` — Redis 橋接層，負責將處理後的 JSON 推入 `mqtt_incoming_jobs` List。
+    *   `mqtt-gateway/config/` — 環境變數與 EMQX / Redis 連線設定。
+
+> [!CAUTION]
+> Go Gateway 的職責僅限於「接收、驗證、轉發」。**嚴禁**在 Go 中實作任何商業邏輯（如庫存扣減、通知發送），所有業務處理必須統一在 Laravel Service 層完成。
+
+## 4. IoT 通訊架構 (MQTT + HTTP 雙軌制)
+
+本系統的機台通訊採用 **MQTT 與 HTTP 雙軌並行** 的策略，依據通訊特性選擇最適合的協議。
+
+### 4.1 整體資料流向
+
+```
+機台 (Android APP)
+     │
+     ├─ [高頻/即時] MQTT 長連線 ──→ EMQX Broker ──→ Go Gateway ──→ Redis List ──→ Laravel mqtt:listen ──→ Job ──→ MySQL
+     │
+     └─ [低頻/大檔] HTTP REST ──→ Laravel API Controller ──→ (必要時) Job ──→ MySQL
+```
+
+### 4.2 MQTT 通訊端點 (高頻與事件驅動)
+以下端點因高頻率或即時性需求，採用 MQTT 協議通訊：
+
+| API 代碼 | Topic 格式 | 用途 | QoS |
+| :--- | :--- | :--- | :--- |
+| B010 | `machine/{serial_no}/heartbeat` | 心跳上報 (每 10 秒) | 0 |
+| B013 | `machine/{serial_no}/error` | 故障與異常狀態上報 | 1 |
+| B600 | `machine/{serial_no}/transaction` | 交易紀錄回傳 | 1 |
+
+**雲端→機台指令下發**：透過 `machine/{serial_no}/command` Topic 推送，取代原本 B010 Response 中的 `status` 欄位輪詢機制，實現毫秒級即時指令。
+
+### 4.3 HTTP 通訊端點 (資料拉取與敏感操作)
+以下端點因資料量大、安全性要求高或為 Request/Response 模式，維持使用 HTTP REST API：
+
+| API 代碼 | 用途 | 維持 HTTP 的原因 |
+| :--- | :--- | :--- |
+| B000 | 維運人員登入 | 無狀態認證，HTTP 更自然 |
+| B012 | 商品配置同步 | 大量資料的 GET 拉取 |
+| B014 | 金鑰與參數下載 | 高安全性敏感操作，需嚴格 RBAC |
+| B009 | 貨道庫存回報 | 低頻操作，由維運人員觸發 |
+
+### 4.4 Redis 橋接機制 (Go ↔ Laravel)
+Go Gateway 與 Laravel 之間透過 Redis List 進行單向異步橋接：
+
+*   **Redis Key**：`mqtt_incoming_jobs`
+*   **Go 端 (生產者)**：將 MQTT 收到的 Payload 包裝成標準 JSON 後，執行 `RPUSH mqtt_incoming_jobs {json}`。
+*   **Laravel 端 (消費者)**：常駐指令 `php artisan mqtt:listen` 持續執行 `BLPOP mqtt_incoming_jobs`，取得 JSON 後解碼並分派至對應的 Laravel Job (如 `ProcessHeartbeat`, `ProcessTransaction`)。
+
+**JSON 橋接格式規範**：
+```json
+{
+  "type": "heartbeat",
+  "serial_no": "M-001",
+  "received_at": "2026-04-14T09:00:00+08:00",
+  "payload": {
+    "current_page": 1,
+    "firmware_version": "1.0.5",
+    "temperature": 25.5
+  }
+}
+```
+
+> [!IMPORTANT]
+> **為何不讓 Go 直接寫入 Laravel Queue？** 因為 Laravel Queue 的 Payload 包含 PHP 序列化物件字串 (`serialize()`)，Go 無法安全產生此格式。透過獨立的 Redis List + 純 JSON，可徹底解耦兩端的技術依賴。
+
+### 4.5 MQTT 連線認證
+機台連線 EMQX 時，使用 `serial_no` 作為 Username、`api_token` 作為 Password。驗證流程：
+
+1.  **Laravel 端 (Token 派發時)**：B014 下發 `api_token` 時，同步執行 `Redis::set("machine_auth:{serial_no}", hash(api_token))`。
+2.  **EMQX 端 (連線驗證時)**：配置 Redis Auth Plugin，直接查詢 Redis 進行極速驗證 (毫秒級)，不經過 MySQL。
+3.  **Token 更新/撤銷時**：Laravel 更新或刪除機台 Token 時，必須同步更新或刪除 Redis 中的對應快取。
+
+## 5. 開發標準 (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`)
+    *   Go 檔案: `snake_case.go` (例如 `heartbeat_handler.go`)
 *   **回傳格式**：
     *   Web 路由：回傳 `view()`，表單驗證失敗時直接使用 Laravel 內建的 redirect with errors。
     *   API 路由：回傳標準 JSON 格式的 `JsonResponse`。
 
-## 5. UI 與前端開發指南
+## 6. 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)
+## 7. 多語系 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` (日文)。
+
+## 8. AI 協作規則 (給 Antigravity AI)
 *   **角色設定**：你是一位專業的全端開發工程師助手。
 *   **代碼生成指令**：
     *   所有的解釋說明請使用 **繁體中文**。
+    *   **【警告：Preline 冗餘】** Preline UI 的官方範例常包含多餘的控制項（如頂部筆數切換）。**嚴禁**照抄其佈局，必須確保頂部工具列（Header/Toolbar）維持極簡，重複功能一律收納至底部。
     *   **【警告】** 此專案前端禁用 React / Vue / Inertia.js。所有的前端頁面生成必須使用 **Blade 模板** 結合 **Tailwind CSS** 與 **Alpine.js**。
+    *   **【多語系強制要求】** 任何新增的 Blade UI 區塊，禁止硬編碼 (Hard-coded) 中文或英文。必須使用 `__('...')` 並同步在 `lang/*.json` 補上翻譯。
     *   生成 UI 區塊時，必須優先參考與產生 **Preline UI** 風格與結構的標記語法。
     *   開發新功能時，請建立標準的 Controller 搭配對應的 `resources/views/.../` 目錄。
+    *   **【Go Gateway 開發】** 修改 `mqtt-gateway/` 內的 Go 程式碼時，嚴禁加入商業邏輯。Go 僅負責訊息接收、格式轉換與 Redis 轉發。
 
-## 7. 運行機制 (Docker / Sail)
+## 9. 運行機制 (Docker / Sail)
 由於專案運行在 Docker 容器環境中，請勿直接在宿主機 (Host) 執行 php 或 composer 指令。請使用專案內建的 `sail` 指令：
 
-*   **啟動環境**：`./vendor/bin/sail up -d`
+*   **啟動環境**：`./vendor/bin/sail up -d`（將同時啟動 Laravel、MySQL、Redis、EMQX、Go Gateway）
 *   **執行 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)
+## 10. 部署與查修環境 (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)
+## 11. 瀏覽器測試規範 (Browser Testing)
 當需要進行瀏覽器自動化測試或手動驗證時，必須遵守以下連線資訊：
 
 *   **本地測試網址**：`http://localhost:8090/` (注意：非 8000 或 8080)
 *   **預設管理員帳號**：`admin`
-*   **預設管理員密碼**：`password`
+*   **預設管理員密碼**：`Star82779061`
 
 > [!IMPORTANT]
 > 在執行 `open_browser_url` 或進行 E2E 測試時，請務必優先確認 Port 是否為 `8090`，以避免連線至錯誤的服務環境。

.agents/rules/rbac-rules.md

@@ -0,0 +1,91 @@
+---
+trigger: always_on
+---
+
+# 多租戶與權限架構實作規範 (RBAC Rules)
+
+本文件定義 Star Cloud 系統的多租戶與權限（RBAC）實作標準，開發者必須嚴格遵守以下準則，以確保資料隔離與安全性。
+
+---
+
+## 1. 資料隔離核心 (Data Isolation)
+
+### 1.1 租戶欄位 (`company_id`)
+任何屬於租戶資源的資料表（如 `users`, `machines`, `transactions` 等），**必須**包含 `company_id` 欄位。
+- `company_id = null`：系統管理員（SaaS 平台營運商）。
+- `company_id = {ID}`：特定租戶。
+
+### 1.2 自動過濾 (Global Scopes)
+- 資源 Model 必須套用 `TenantScoped` Trait。
+- 當非系統管理員登入時，所有 Eloquent 查詢必須自動加上 `where('company_id', auth()->user()->company_id)`。
+- **嚴禁**在 Controller 手動撰寫重複的過濾邏輯，除非是複雜的 Raw SQL。
+
+### 1.3 寫入安全
+- 建立新資源時，必須在背景強制綁定 `company_id`，禁止由前端傳參決定。
+- 範例：`$model->company_id = Auth::user()->company_id;`
+
+### 1.4 角色清單隔離 (Role List Isolation)
+- 租戶管理員 (Tenant Admin) 只能管理隸屬於其公司下的角色。
+- **嚴禁使用**包含 `NULL` 的 `forCompany` 廣義作用域來展示管理清單。
+- 查詢時必須嚴格使用 `where('company_id', auth()->user()->company_id)` 隔離系統 Super Admin 或 角色範本。
+
+---
+
+## 2. 權限開發規範 (spatie/laravel-permission)
+
+### 2.1 租戶感知角色 (Tenant-Aware Roles)
+- `roles` 資料表已擴充 `company_id` 欄位。
+- 撈取角色清單供指派時，必須過濾 `company_id` 或為 null 的系統預設角色。
+
+### 2.2 權限命名
+- 權限名稱應遵循 `[module].[action]` 格式（例如 `machine.view`, `machine.edit`）。
+- 所有租戶共用相同的權限定義。
+
+### 2.3 權限遞迴約束 (Privilege Delegation Constraint)
+為防止權限提升 (Privilege Escalation)：
+- **權限子集驗證**：管理員僅能指派其**自身持有**之權限給其他角色或帳號。
+- **Controller 實作**：在 `store` 或 `update` 時，必須比對傳入的權限集合是否為操作者 `getPermissionNames()` 的子集。
+- **UI 過濾**：權限分配介面應基於當前使用者權限清單進行動態過濾展示。
+
+---
+
+## 3. 介面安全 (UI/Blade)
+
+### 3.1 身份判定 Helper
+使用以下方法進行區分：
+- `$user->isSystemAdmin()`: 判斷是否為平台營運人員。
+- `$user->isTenant()`: 判斷是否為租戶帳號。
+
+### 3.2 Blade 指令
+- 涉及全站管理或跨租戶功能，必須使用 `@if(auth()->user()->isSystemAdmin())` 包裹。
+- 確保租戶登入時，不會在 Sidebar 或選單看到不屬於其權限範圍的項目。
+
+---
+
+## 4. API 安全
+- 所有的 API Route 應預設包含 `CheckTenantAccess` Middleware。
+- 嚴禁透過 URL 修改 ID 存取不屬於該租戶的資料，必須依賴 `company_id` 的 Scope 過濾。
+
+---
+
+## 5. 客戶初次建立與角色初始化 (Role Provisioning)
+
+### 5.1 初始角色建立
+當系統管理員為新客戶（該租戶尚未有任何角色）建立第一個帳號時，應遵循以下邏輯：
+1.  **選取範本**：從系統預設的「全域角色範本」（`company_id = null` 且 `is_system = 1`）中選取一個作為基礎，但必須排除「超級管理員 (`super-admin`)」。
+2.  **自動克隆**：系統會將該範本的權限內容複製一份至該租戶下。
+3.  **統一命名**：克隆後的角色名稱在該租戶公司內應統一命名為**「管理員」**。
+4.  **帳號綁定**：該新客戶帳號將被指派至此新建立的「管理員」角色。
+
+### 5.2 角色權限維護
+- 初始建立後，該租戶的「管理員」角色即成為獨立資源，可由具有權限的帳號進行細部調整。
+
+### 5.3 機台授權原則 (Machine Authorization) [CRITICAL]
+- **以帳號為準**：機台授權是基於「帳號 (User)」而非「角色 (Role)」。
+- **授權層級**：
+    1. **系統管理員 (isSystemAdmin = true)**：具備全系統所有機台之完整權限。
+    2. **租戶/公司帳號 (含管理員)**：僅能存取由「系統管理員」明確授權給該帳號的機台（透過 `machine_user` 關聯）。
+    3. **子帳號**：僅能存取由其「公司管理員」所授權的機台子集。
+- **實作要求**：
+    - `Machine` Model 的全域過濾器**不得**對「管理員 (Tenant Admin)」角色進行例外排除。
+    - 所有的機台存取必須嚴格比對 `machine_user` 表，除非操作者為「系統管理員 (Super Admin)」。

.agents/rules/skill-trigger.md

@@ -14,9 +14,11 @@ Skills 位於 `.agents/skills/`，採漸進式揭露以節省 Token。
 
 | 觸發詞 / 情境 | 對應 Skill | 路徑 |
 |---|---|---|
-| 機台通訊, IoT, 日誌上報, Log Ingestion, 異步隊列, Queue, Heartbeat, 心跳發報 | **IoT 通訊與高併發處理規範** | `.agents/skills/iot-communication/SKILL.md` |
-| 介面, UI, 佈局, CSS, Tailwind, 奢華, 深色模式, Light Mode, Dark Mode, Blade, 樣式, 間距, 陰影, 動畫 | **極簡奢華風 UI 實作規範** | `.agents/skills/ui-minimal-luxury/SKILL.md` |
+| 機台通訊, IoT, 日誌上報, Log Ingestion, 異步隊列, Queue, Heartbeat, 心跳發報, MQTT, Topic, Broker, EMQX | **IoT 通訊與高併發處理規範 / MQTT 通訊規範** | `.agents/skills/iot-communication/SKILL.md` <br> `.agents/skills/mqtt-communication-specs/SKILL.md` |
+| B010, B017, B600, B055, API 規格, 通訊協議, 狀態碼, 頁面碼, 範例, JSON | **API 技術規格與通訊協議規範** | `.agents/skills/api-technical-specs/SKILL.md` |
+| 介面, UI, 設計, 佈局, CSS, Tailwind, 奢華, 深色模式, Light Mode, Dark Mode, Blade, 樣式, 間距, 陰影, 動畫, 畫面, 頁面 | **極簡奢華風 UI 實作規範** | `.agents/skills/ui-minimal-luxury/SKILL.md` |
 | 查詢、撈資料、Query、Controller、下拉選單、Eloquent、N+1、`->get()`、select、交易、Transaction、Bulk、分頁、索引 | **資料庫與 ORM 最佳實踐規範** | `/home/mama/.gemini/antigravity/global_skills/database-best-practices/SKILL.md` |
+| RBAC, 權限, 角色, 租戶, Tenant, Company, Access Control, 多租戶, 權限控管 | **多租戶與權限架構實作規範** | `.agents/rules/rbac-rules.md` |
 
 ---
 
@@ -27,6 +29,7 @@ Skills 位於 `.agents/skills/`，採漸進式揭露以節省 Token。
 ### 🔴 新增或修改頁面 (Views/Blade) 時
 必須讀取：
 1. **ui-minimal-luxury** — 確保符合極簡奢華風視覺與互動規範
+2. **rbac-rules** — 確認 UI 區塊的權限顯示控制
 
 ### 🔴 新增機台通訊 API 端點時
 必須讀取：
@@ -39,3 +42,4 @@ Skills 位於 `.agents/skills/`，採漸進式揭露以節省 Token。
 ### 🔴 新增或修改 API 與 Controller 撈取資料庫邏輯時
 必須讀取：
 1. **database-best-practices** — 確認查詢優化、交易安全、批量寫入與索引規範
+2. **rbac-rules** — 確保 `company_id` 隔離邏輯正確套用

.agents/skills/api-technical-specs/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: API 技術規格與通訊協議規範
+description: 本技能規範定義了 Star Cloud 系統中所有機台 (IoT) 與後端 (Cloud) 通訊的 API 細節、參數命名規則、狀態代碼對照與認證機制，作為系統開發的唯一規格來源。
+---
+
+# API 技術規格與通訊協議規範 (API Technical Specs)
+
+本文件集中定義所有機台與雲端通訊的 API 規格，確保硬體端與軟體端在資料交換格式與業務定義上保持完全一致。
+
+## 1. 核心命名原則
+- **語意化優先**：捨棄舊版 M_ 前綴，統一使用 snake_case (如 firmware_version)。
+- **類型嚴格**：文件定義的類型 (Integer, Float, String) 必須在後端 Model 與前端文件中心嚴格遵守。
+
+## 2. 身份認證 (Authentication)
+本系統採用兩階段認證模式：
+
+### 2.1 維運人員認證 (User Authentication)
+- **核發端點**：B000 (登入)。
+- **使用端點**：B014 (參數下載)。
+- **方式**：使用 Laravel Sanctum 核發之 **User Token**。
+- **Header**：`Authorization: Bearer <user_token>`。
+
+### 2.2 機台通訊認證 (Machine Authentication)
+- **適用 API**：B010, B012, B013, B600 等後續通訊。
+- **方式**：使用機台專屬之 **api_token**。
+- **Header**：`Authorization: Bearer <api_token>`。
+
+---
+
+## 3. 機台核心 API (IoT Endpoints)
+
+### 3.1 B000: 機台本地管理員同步登入
+用於機台 Android 端維護人員登入與進入設定頁。此 API 無狀態，且為例外不強制檢查 Bearer Token 的端點。
+
+- **URL**: POST /api/v1/app/admin/login/B000
+- **Request Body:**
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| machine | String | 是 | 機台編號 (serial_no) | M-001 |
+| Su_Account | String | 是 | 系統管理員或公司管理員帳號 | admin |
+| Su_Password | String | 是 | 密碼 | password123 |
+| ip | String | 否 | 用戶端 IP (相容舊版) | 192.168.1.100 |
+| type | String | 否 | 裝置類型代碼 (相容舊版) | 2 |
+
+- **Response Body:**
+> [!IMPORTANT]
+> 為了相容 Java APP 現有邏輯，這裡嚴格規定成功必須回傳字串 Success。
+
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| message | String | 驗證結果 (Success 或 Failed) | Success |
+| token | String | **臨時身份認證 Token** (用於 B014) | 1|abcdefg... |
+
+---
+
+### 3.2 B005: 廣告清單同步
+用於機台端獲取目前應播放的廣告檔案 URL 清單。
+
+- **URL**: GET /api/v1/app/machine/ad/B005
+- **Request Body:** 無 (GET 請求)
+
+- **Response Body:**
+
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| success | Boolean | 請求是否成功 | true |
+| code | Integer | 內部業務狀態碼 | 200 |
+| data | Array | 廣告物件陣列 | [{"t070v04": "https://..."}] |
+
+**data 陣列內部欄位：**
+- t070v01: 廣告名稱 (Name)
+- t070v02: 播放長度 (Duration) — 秒數，若後台未設定，預設為 15 秒。
+- t070v03: 廣告位置 (Position/Flag) — (3: 待機廣告, 1: 販賣頁, 2: 來店禮)。
+- t070v04: 廣告 URL。
+- t070v05: 播放順位 (Sort Order)。
+
+---
+
+### 3.3 B009: 貨道庫存即時回報 (Supplementary Report)
+當維修或補貨人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。
+
+#### B009 權限驗證邏輯 (RBAC Compliance)
+系統會依據 account 欄位進行三層式權限核查：
+1. **系統層 (System Admin)**：當 company_id 為 null 時，具備全局管理權限，直接放行。
+2. **公司層 (Company Admin)**：當 is_admin 為 true 時，檢查機台的 company_id 是否與該帳號一致。
+3. **人員層 (Operator/User)**：當帳號僅為一般人員時，檢查 machine_user 授權表，確認該帳號有被分配至此機台。
+
+- **URL**: PUT /api/v1/app/products/supplementary/B009
+- **Request Body:**
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| account | String | 是 | 操作人員帳號 | 0999123456 |
+| data | Array | 是 | 貨道數據陣列 | [{"tid":"1", "t060v00":"1", "num":"10"}] |
+
+- **data 陣列內部欄位：**
+
+| 欄位 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| tid | Integer | 貨道編號 (Slot No) | 1 |
+| t060v00 | String | 商品資料庫 ID (或是 Barcode) | "1" |
+| num | Integer | 實體剩餘庫存數量 | 10 |
+| type | Integer | 貨道物理類型 (1: 履帶, 2: 彈簧)。若未提供，預設為 1。 | 1 |
+
+> [!TIP]
+> **自動化上限同步邏輯**：
+> 當後端收到 B009 時，會根據 type 自動從該商品的配置中選取 spring_limit 或 track_limit 並自動更新該貨道的 max_stock 欄位。機台端無需手動計算上限。
+
+- **Response Body (Success 200):**
+
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| success | Boolean | 同步是否成功 | true |
+| code | Integer | 內部業務狀態碼 | 200 |
+| message | String | 回應訊息 | Slot report synchronized success |
+| status | String | 固定回傳 49 代表同步完成 | "49" |
+
+---
+
+### 3.4 B010: 心跳上報與狀態同步
+用於確認機台在線狀態、更新感測數據、提交事件日誌並獲取雲端指令。
+
+- **URL**: POST /api/v1/app/machine/status/B010
+- **Authentication**: Bearer Token (Header)
+- **Request Body:**
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| current_page | Integer | 是 | 當前頁面代碼 (見下表) | 1 |
+| firmware_version | String | 是 | 韌體版本號 | 1.0.5 |
+| model | String | 是 | 機台型號 | STAR-V1 |
+| temperature | Float | 否 | 環境溫度 | 25.5 |
+| door_status | Integer | 否 | 門狀態 (0:關 / 1:開) | 0 |
+| log | String | 否 | 事件日誌簡述 | Door opened |
+| log_level | String | 否 | info, warn, error | info |
+| log_payload | Object | 否 | 額外日誌 JSON 對象 | {"code":500} |
+
+- **Response Body:**
+
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| success | Boolean | 請求是否處理成功 | true |
+| code | Integer | 內部業務狀態碼 | 200 |
+| message | String | 回應訊息 | OK |
+| status | String | **雲端指令代碼** (見下表) | 49 |
+
+#### B010 代碼對照表
+
+**頁面代碼 (current_page)：**
+- 0: 離線 / 1: 主頁面 / 2: 販賣頁 / 3: 管理頁
+- 4: 補貨頁 / 5: 教學頁 / 6: 購買中 / 7: 鎖定頁
+- 60: 出貨成功 / 61: 貨道測試 / 62: 付款選擇
+- 63: 等待付款 / 64: 出貨 / 65: 收據簽單
+- 66: 通行碼 / 67: 取貨碼 / 68: 訊息顯示
+- 69: 取消購買 / 610: 購買結束 / 611: 來店禮
+- 612: 出貨失敗
+
+**雲端指令代碼 (status)：**
+- 49: reload B017 (貨道同步)
+- 51: reboot (重啟系統)
+- 60: reboot card machine (刷卡機重啟)
+- 61: checkout (觸發結帳)
+- 70: unlock (解鎖)
+- 71: lock (鎖定)
+- 85: reload B0552 (遠端出貨)
+
+---
+
+### 3.5 B012: 商品配置與商品主檔同步 (Unified Sync)
+用於機台端獲取目前所有可販售商品的詳細配置。App 端應依據呼叫的方法決定數據處理方式。
+
+- **URL**: GET|PATCH /api/v1/app/machine/products/B012
+- **Authentication**: Bearer Token (Header)
+- **Request Body:** 無 (由 Token 自動識別機台)
+
+#### 運作邏輯 (Client-side Logic):
+- **GET**：執行 **全量同步**。App 應於收到成功回應後，先執行 deleteAll() 再進行 insertAll() 以確保與伺服器完全一致。
+- **PATCH**：執行 **增量更新**。App 於收到成功回應後，僅對記憶體中的既存商品進行欄位值覆蓋 (Patching)。
+
+| 欄位 | 型別 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| t060v00 | String | 商品資料庫 ID | "1" |
+| t060v01 | String | 商品名稱 | 可口可樂 330ml |
+| t060v01_en | String | 英文名稱 | Coca Cola |
+| t060v01_jp | String | 日文名稱 | コカコーラ |
+| t060v03 | String | 商品規格/簡述 | Cold Drink |
+| t060v06 | String | 圖片 URL | https://.../coke.png |
+| t060v09 | Float | 標準零售價 | 25.0 |
+| t060v11 | Integer | **貨道庫存上限** (預設履帶) | 10 |
+| t060v30 | Float | 會員價 | 20.0 |
+| t063v03 | Float | 本機銷售價格 (同定價) | 25.0 |
+| t060v40 | String | 行銷計畫 (Marketing Plan) | Buy 1 Get 1 |
+| t060v41 | String | 物料編碼 (Material Code) | SKU-001 |
+| spring_limit | Integer | **彈簧貨道上限** (建議使用此欄位) | 10 |
+| track_limit | Integer | **履帶貨道上限** (建議使用此欄位) | 15 |
+
+---
+
+### 3.6 B013: 機台故障與異常狀態上報 (Error/Status Report)
+用於接收機台發出的即時硬體狀態代碼（如卡貨、門未關），並自動由雲端後端翻譯為易讀日誌。
+
+- **URL**: POST /api/v1/app/machine/error/B013
+- **Authentication**: Bearer Token (Header)
+- **Request Body:**
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| tid | Integer | 否 | 涉及之貨道編號 (Slot No) | 12 |
+| error_code | String | 是 | 硬體狀態代碼 (4 位 16 進位) | "0403" |
+
+- **回應 (Success 202):**
+
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| success | Boolean | 請求已接收 | true |
+| code | Integer | 200 | 200 |
+
+#### B013 硬體代碼對照表 (由 MachineService 自動翻譯)
+
+| 代碼 | 英文 Key (i18n) | 級別 | 範例繁中翻譯 |
+| :--- | :--- | :--- | :--- |
+| **0402** | Dispense successful | info | 出貨成功 |
+| **0403** | Slot jammed | error | **貨道卡貨** (重大異常) |
+| **0202** | Product empty | warning | 貨道缺貨 |
+| **0412** | Elevator rise error | error | 昇降機上升異常 |
+| **0415** | Pickup door error | error | 取貨門異常 |
+| **5402** | Pickup door not closed | warning | **取貨門未關** (警告) |
+| **5403** | Elevator failure | error | 昇降系統故障 |
+
+---
+
+### 3.7 B014: 機台參數與金鑰下載 (Config Download)
+用於機台引導階段 (Provisioning)，向雲端請求支付金鑰、發票設定及機台正式 API Token。
+
+- **URL**: GET /api/v1/app/machine/setting/B014
+- **Authentication**: **User Token** (Sanctum Header)
+- **Request Body:** 無 (由 Query String 帶入 `machine` 參數)
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| machine | String | 是 | 機台編號 (serial_no) | M-001 |
+
+- **Response Body (Success 200):**
+
+| 欄位 (Key) | 說明 | 備註 |
+| :--- | :--- | :--- |
+| **t050v01** | 機台序號 | 即 machine_id |
+| **api_token** | **機台正式 Token** | 初始化後應存於本地，後續 API 認證用 |
+| **t050v41** | 玉山特店編號 | ESUN Merchant ID |
+| **t050v42** | 玉山終端編號 | ESUN Terminal ID |
+| **t050v43** | 玉山 Hash Key | ESUN Hash |
+| **t050v34** | 發票特店 ID | Invoice Merchant ID |
+| **t050v35** | 發票 Hash Key | Invoice Key |
+| **t050v36** | 發票 Hash IV | Invoice IV |
+| **TP_APP_ID** | 趨勢支付 AppID | TrendPay ID |
+| **TP_APP_KEY** | 趨勢支付 Key | TrendPay Key |
+
+> [!CAUTION]
+> **安全性規範**：B014 會回傳敏感金鑰與正式 Token，背景必須強制進行 RBAC 校驗。只有當前登入的人員具備該機台管理權限時，後端才允許發放資料。
+
+---
+
+### 3.8 B017: 貨道庫存同步 (Slot Synchronization)
+用於機台端獲取目前所有貨道的最新庫存、效期與狀態。通常由 B010 回應 `status: 49` 觸發。
+
+- **URL**: GET /api/v1/app/machine/reload_msg/B017
+- **Authentication**: Bearer Token (Header)
+- **Request Body:** 無 (由 Token 自動識別機台)
+
+- **Response Body:**
+
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| success | Boolean | 請求是否成功 | true |
+| code | Integer | 200 | 200 |
+| data | Array | 貨道數據陣列 (依 slot_no 排序) | 見下表 |
+
+**data 陣列內部欄位：**
+
+| 欄位 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| tid | String | 貨道編號 | "1" |
+| num | Integer | 當前庫存數量 | 10 |
+| expiry_date | String | 商品效期 | "2026-12-31" |
+| batch_no | String | 批號 | "B202604" |
+| product_id | Integer | 商品 ID | 1 |
+| capacity | Integer | 貨道容量上限 | 15 |
+| status | String | 貨道狀態 ("1": 啟用, "0": 停用) | "1" |
+
+> [!IMPORTANT]
+> **同步機制**：B017 為全量同步。App 收到回應後應更新本地資料庫對應貨道的數值。成功請求後，雲端會自動將相關的 `reload_stock` 指令標記為 `success`。
+
+---
+
+### 3.9 B024: 取貨碼/通行碼驗證與消耗回報 (Access Code Verify & Report)
+用於處理機台端的代碼取貨流程。包含驗證代碼有效性（驗證階段）與確認出貨完成後的狀態消耗（回報階段）。
+
+- **URL**: POST|PUT /api/v1/app/sell/access-code/B024
+- **Authentication**: Bearer Token (Header)
+- **Request Body (POST - 驗證階段):**
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| passCode | String | 是 | 使用者輸入的取貨碼/通行碼 | "12345678" |
+
+- **Response Body (POST - 驗證成功 200):**
+雲端將回傳該碼對應的權限或待出貨商品資訊。
+
+| 參數 | 類型 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- |
+| res1 | String | 該代碼在雲端的關聯 ID | "99" |
+| res2 | String | 操作模式 (1: 出貨, 2: 僅驗證) | "1" |
+| res3 | String | 預計出貨商品 ID | "5" |
+| res4 | String | 折扣金額或活動標籤 | "0.0" |
+
+- **Request Body (PUT - 回報階段):**
+當機台端確認實體出貨成功後，必須發送此請求以耗刷該代碼。
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| accessCodeId | String | 是 | 驗證階段取得的 res1 (ID) | "99" |
+| status | String | 是 | 出貨結果 (1: 成功, 0: 失敗) | "1" |
+
+---
+
+### 3.10 B027: 贈品碼/優惠券驗證與消耗回報 (Free Gift Verify & Report)
+用於處理行銷贈品券、0 元購活動或特定的優惠券核銷流程。
+
+- **URL**: POST|PUT /api/v1/app/sell/free-gift/B027
+- **Authentication**: Bearer Token (Header)
+- **運作模式**:
+    - **POST**: 提交 `passCode` 驗證該贈品券是否有效。成功後雲端會回傳對應活動 ID 與商品配置。
+    - **PUT**: 當該贈品（0 元商品）出貨完成後，向雲端回報消耗，確保優惠券不會重複核銷。
+
+> [!NOTE]
+> B027 與 B024 的邏輯具備高度對稱性，區別在於 B027 通常綁定的是特定的行銷活動 (Campaign) 與 0 元出貨邏輯。
+
+---
+
+### 3.11 B055: 遠端指令出貨控制 (Remote Dispense / Force Open)
+用於遠端手動驅動機台出貨。通常用於補償使用者、測試機台或客服協助開門的情景。
+
+- **URL**: POST|PUT /api/v1/app/machine/dispense/B055
+- **Authentication**: Bearer Token (Header)
+- **運作模式**:
+    - **POST (查詢)**: 當 B010 收到 `status: 85` 時呼叫。雲端會回傳待執行的貨道編號與指令 ID。
+    - **PUT (回報)**: 實體出貨完成後回報結果，以便雲端將該指令標記為「已執行」。
+
+- **Request Body (PUT - 回報階段):**
+
+| 參數 | 類型 | 必填 | 說明 | 範例 |
+| :--- | :--- | :--- | :--- | :--- |
+| id | String | 是 | 雲端下發的指令 ID | "20260414001" |
+| type | String | 是 | 出貨類型代碼 (通常為 0) | "0" |
+| stock | String | 是 | 出貨後的貨道剩餘數量 | "9" |

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

@@ -9,13 +9,25 @@ description: 規範智能販賣機與 Cloud 平台間的高頻通訊處理流程
 
 ## 1. 處理管線 (Processing Pipeline)
 
-所有來自機台的非即時性資料（日誌、心跳、狀態上報）必須遵循以下 pipeline：
+所有來自機台的非即時性資料（日誌、心跳、狀態上報）必須遵循以下 pipeline。依據通訊協議不同，進入點有兩條路徑：
 
+### 1.1 HTTP 管線 (低頻/大檔操作)
+適用於 B000, B009, B012, B014, B017 等低頻、同步需求或大資料量的端點：
 1.  **API Controller (接收層)**：驗證 Request 合法性，隨即分派 (Dispatch) 任務至 Queue，並回傳 `202 Accepted`。
 2.  **Job (異步層)**：由背景 Worker 讀取隊列任務，呼叫對應 Service 處理。
 3.  **Service (邏輯層)**：封裝商業邏輯，更新資料庫。
 4.  **Model (儲存層)**：執行資料存取。
 
+### 1.2 MQTT 管線 (高頻/即時操作)
+適用於 B010 (心跳), B013 (異常), B600 (交易) 等高頻或即時性端點：
+1.  **Go Gateway (接收層)**：訂閱 EMQX Topic，提取 `serial_no`，包裝成標準 JSON。
+2.  **Redis List (橋接層)**：Go 執行 `RPUSH mqtt_incoming_jobs {json}`。
+3.  **Laravel `mqtt:listen` (消費層)**：常駐指令 `BLPOP` 取出 JSON，根據 `type` 分派至對應 Job。
+4.  **Job ➜ Service ➜ Model**：與 HTTP 管線後半段相同。
+
+> [!TIP]
+> 兩條管線的 **Job / Service / Model 層完全共用**，差異僅在「進入點」。這確保了業務邏輯不會因為通訊協議不同而分裂。
+
 > [!IMPORTANT]
 > **嚴禁**在 API Controller 直接進行資料庫寫入操作（針對機台發訊端點）。
 
@@ -53,11 +65,34 @@ public function handle(MachineService $service): void
 
 ## 4. 速率限制 (Rate Limiting)
 
-- 所有的 IoT API 必須在 `routes/api.php` 中使用 `throttle:api` 或自定義 Middleware。
+### 4.1 HTTP 端點
+- 所有的 IoT HTTP API 必須在 `routes/api.php` 中使用 `throttle:api` 或自定義 Middleware。
 - 針對單一機台 ID 應限制其每一分鐘的最高連線數，防止遭受攻擊或機台 Bug 導致的連線暴衝。
 
+### 4.2 MQTT 端點
+- 限速由 **EMQX Broker** 的 Rate Limiting 功能負責（非 Laravel Middleware）。
+- Go Gateway 層可額外實作簡易的 Token Bucket，當某台機台每秒超過閾值時丟棄訊息並記錄 Warning Log。
+
 ## 5. 檢核項目 (Checklist)
 - [ ] 是否使用了 `ApiResponse` Trait？
 - [ ] 業務邏輯是否已封裝至 `App\Services`？
 - [ ] 是否使用了 Redis Queue 進行非同步處理？
-- [ ] 是否在 API 層級進行了基礎的參數驗證？
+
+## 6. API 規格定義 (API Specifications)
+
+> [!IMPORTANT]
+> **規格分離原則**：本技能僅規範「通訊處理邏輯」。關於具體的欄位定義與資料格式，請參閱對應的專屬技能規範：
+> - **HTTP 端點**：[API 技術規格與通訊協議規範](file:///home/mama/projects/star-cloud/.agents/skills/api-technical-specs/SKILL.md)
+> - **MQTT 端點**：[MQTT 即時通訊與 Topic 規範](file:///home/mama/projects/star-cloud/.agents/skills/mqtt-communication-specs/SKILL.md)
+
+### 常見端點處理模式
+1.  **B010 (心跳)**：高頻點，走 **MQTT 管線** (`machine/+/heartbeat`)。更新 `last_heard_at` 與感測器快照。
+2.  **B013 (異常)**：事件驅動點，走 **MQTT 管線** (`machine/+/error`)。寫入 `machine_logs` 並觸發告警。
+3.  **B600 (交易)**：高價值點，走 **MQTT 管線** (`machine/+/transaction`)。建立 `Transaction` 紀錄並支援重試。
+4.  **B012 (商品同步)**：大資料量，走 **HTTP 管線**。應確保 Service 層具備緩存 (Cache) 機制。
+5.  **B055 (遠端出貨)**：雲端下發指令，走 **MQTT 下行管線** (`machine/{id}/command`)。
+
+---
+
+> [!CAUTION]
+> **身份識別機制**：禁止在 Body 傳輸 `machine` 或 `key`。系統強制透過 `Bearer Token` 識別並自動關聯資料。

.agents/skills/mqtt-communication-specs/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: MQTT 即時通訊與 Topic 規範
+description: 定義 Star Cloud 與終端機台 (IoT) 之間的 MQTT 全域通訊拓撲、主題 (Topic) 結構、資料載體 (Payload) 格式與安全性認證機制。
+---
+
+# MQTT 即時通訊與 Topic 規範 (MQTT Protocol Specs)
+
+本文件定義機台與 Star Cloud 之間的高併發即時通訊標準。MQTT 主要用於處理高頻率且對即時性要求高的訊息（如心跳、遠端指令），與 HTTP REST API 形成雙軌互補架構。
+
+## 1. 連線基礎設定 (Connection Basics)
+
+### 1.1 Broker 資訊
+- **協議版本**：MQTT v3.1.1 (相容性最高)
+- **預設埠號**：1883 (TCP / 測試用), 8883 (SSL/TLS / 正式用)
+- **Keep-Alive**：建議設定為 30 ~ 60 秒。
+
+### 1.2 身份認證 (Authentication)
+機台連線時必須提供以下憑據：
+- **Username**：機台編號 (`serial_no`)，例如 `M-001`。
+- **Password**：機台正式 Token (`api_token`)，由 B014 API 取得。
+- **Client ID**：建議格式為 `SC_{serial_no}_{random_suffix}`，確保唯一性。
+
+---
+
+## 2. 主題架構 (Topic Topology)
+
+我們採用目錄式的層級結構，方便未來進行萬台設備的管理與 ACL 權限切分。
+
+| 主題名稱 (Topic) | 方向 | QoS | 用途說明 |
+| :--- | :--- | :--- | :--- |
+| `machine/{serial_no}/heartbeat` | 設備 ➜ 雲端 | 0 | 每 10 秒上報心跳、溫度、目前的頁面碼。 |
+| `machine/{serial_no}/error` | 設備 ➜ 雲端 | 1 | 發生硬體故障、卡貨或門未關時立即上報。 |
+| `machine/{serial_no}/transaction` | 設備 ➜ 雲端 | 1 | 交易完成、出貨結果的回報。 |
+| `machine/{serial_no}/command` | 雲端 ➜ 設備 | 1 | 雲端下發的即時指令（出貨、更新、重啟）。 |
+
+---
+
+## 3. 資料載體規範 (Payload Definitions)
+
+所有 Payload 統一採用 **JSON** 格式，字母一律為 **snake_case**。
+
+### 3.1 心跳上報 (Heartbeat) - `machine/{id}/heartbeat`
+比照原 B010 邏輯，但去除不必要的 HTTP Header 開銷。
+
+```json
+{
+  "current_page": 1,
+  "firmware_version": "1.0.5",
+  "temperature": 25.5,
+  "door_status": 0,
+  "timestamp": "2026-04-14T09:00:00+08:00"
+}
+```
+
+### 3.2 異常上報 (Error/Event) - `machine/{id}/error`
+比照原 B013 邏輯。
+
+```json
+{
+  "tid": 12,
+  "error_code": "0403",
+  "log": "Slot jammed at slot 12",
+  "timestamp": "2026-04-14T09:05:00+08:00"
+}
+```
+
+### 3.3 雲端指令 (Downstream Commands) - `machine/{id}/command`
+這是雲端主動下發給機台的訊息，取代原本 B010 Response 的輪詢等待。
+
+```json
+{
+  "command": "dispense",
+  "payload": {
+    "slot_no": 5,
+    "transaction_id": "T202604140001"
+  },
+  "message_id": "MSG_123456789"
+}
+```
+**常用指令集：**
+- `reboot`: 機台重啟。
+- `reload_config`: 重新下載參數 (B014)。
+- `reload_products`: 重新同步商品 (B012)。
+- `dispense`: 遠端出貨指令 (B055)。
+
+---
+
+## 4. 安全與 QOS 規範
+
+1. **存取控制 (ACL)**：EMQX Broker 必須設定 ACL，禁止機台 A 訂閱機台 B 的 Topic。機台僅能訂閱與發布包含自身 `serial_no` 的路徑。
+2. **QoS 策略**：
+   - **QoS 0**：適用於高頻率心跳，即使掉一兩次包也不影響系統判斷。
+   - **QoS 1**：適用於交易與指令，確保「至少送達一次」。App 端收到指令後應回覆回執。
+3. **遺囑訊息 (Last Will and Testament)**：
+   機台 Connect 時應設定 Last Will 於 `machine/{serial_no}/heartbeat`，Payload 為 `{"status": "offline"}`。當連線異常中斷時，雲端能立刻得知。
+
+---
+
+## 5. 與 REST API 的同步關係
+當 MQTT 通訊正常時，機台應停止定時呼叫 B010 HTTP API。若 MQTT 斷線超過 3 分鐘，則退回 (Fallback) 使用 HTTP 輪詢模式以維持基礎通訊。

.agents/skills/ui-minimal-luxury/SKILL.md

@@ -25,8 +25,7 @@ description: 定義 Star Cloud 管理後台的「極簡奢華風」設計規範
 ### 豪華卡片 (Luxury Card)
 ```html
 <div class="luxury-card p-6 rounded-2xl animate-luxury-in">
-    <!-- 內容 -->
-</div>
+    </div>
 ```
 - **特效**: 懸停時帶有 Y 軸平移與深度投影。
 
@@ -45,13 +44,11 @@ description: 定義 Star Cloud 管理後台的「極簡奢華風」設計規範
 - **Ghost**: `.btn-luxury-ghost` (無背景，適用於取消、查看更多)
 
 ```html
-<!-- Primary -->
 <button class="btn-luxury-primary">
-    <i class="lucide-plus size-4"></i>
+    <i class="lucide-plus w-4 h-4"></i>
     <span>建立新機台</span>
 </button>
 
-<!-- Ghost -->
 <button class="btn-luxury-ghost">取消</button>
 ```
 
@@ -60,26 +57,270 @@ description: 定義 Star Cloud 管理後台的「極簡奢華風」設計規範
 ### 進場動畫
 - **`.animate-luxury-in`**: 所有的主內容區域或卡片在頁面載入時，應具備由下而上的淡入效果。
 
+### 互動過渡 (Transitions)
+- **標準時間**: 所有的懸停、色彩變換等過渡效果，統一建議使用 **`duration-300`** (300ms)。
+- **例外**: 極其細微的透明度變化可縮短至 `150ms`，但涉及背景色與位移的互動一律以 `300ms` 為準。
+
 ### Alpine.js 互動模式 (以時間選擇器為例)
 - **互動原則**: 點擊觸發下拉選單時，必須使用 `x-transition` 且帶有 `scale` 偏移。
 - **樣式要求**: 選單背景需使用玻璃擬態 (Glassmorphism) 或帶透明度的深色背景。
 
-## 4. UI 檢查清單 (AI 助手執行前必讀)
-- [ ] 是否使用了正確的 `rounded-2xl` (或更圓) 的導角？
-- [ ] 所有的圖示是否一致使用 `lucide-react` 風格？
-- [ ] 卡片是否有適當的間距 (通常為 `p-6`)？
-- [ ] 文字色階是否符合：標題 (slate-900/white)、副標 (slate-500/slate-400)？
+## 4. 實作檢查清單 (Checklist)
+
+- [x] **列表佈局**: 是否採用「整合式卡片」結構且內距設為 `p-8`？
+- [ ] **分頁與總數**: 列表底部是否正確召喚 `vendor.pagination.luxury`？
+- [ ] **刪除動作**: 是否已全面使用 `<x-delete-confirm-modal />` 封裝執行路徑？
+- [ ] **文字色階**: 符合標題 `slate-900/white` 與標籤 `slate-500` 的對比度。
+- [ ] **可讀性檢查**: 二級資訊是否達到 `text-xs` (12px) 且權重不超過 `font-bold`？
 
 ## 5. 開發注意事項 (Important Notes)
 
 ### 技術限制備忘
-- **CSS 編譯**: 複雜的 `box-shadow` 或漸層應直接寫原生 CSS 屬性，避免在 `@apply` 中使用帶空格的數值導致編譯失敗（詳見 KI: `tailwind-luxury-ui-patterns`）。
+- **CSS 編譯**: 複雜的 `box-shadow` 或漸層應直接寫原生 CSS 屬性，避免在 `@apply` 中使用帶空格的數值導致編譯失敗。
 - **深色模式**: 互動式按鈕在深色模式下必須強化文字亮度（`dark:text-white`），並輔以青色發光效果。
 
 ### 即時動態呈現規範
 - **格式**: `#機台編號 動作內容` (例如 `#V-001 執行出貨`)。
 - **脈絡**: 必須呈現相對時間與機台位置。
 
+## 6. 頁面佈局規範 (Page Layout)
+
+### 佈局決策規則 (Layout Decision Rules)
+
+根據篩選條件的複雜程度，選擇適當的清單頁面佈局：
+
+#### 1. 整合式佈局 (Integrated Layout) - 【預設推薦】
+- **適用場景**: 絕大多數 CRUD 列表。
+- **實作方式**: 篩選器、工具列與資料表格全部封裝在同一個 `luxury-card` 中。
+- **內距規範**: 強制使用 `p-8` 以獲得最佳空氣感。
+- **元件間距**: 篩選區與表格之間固定使用 `mb-10`。
+- **範例**: 帳號管理、角色設定、機台日誌。
+
+#### 2. 分離式佈局 (Split Layout)
+- **適用場景**: 複雜查詢 (Filtered Fields >= 3 或多行篩選)。
+- **實作方式**: 篩選區獨立為一個 `luxury-card`，下方間隔 `mb-6` 後再放置資料清單卡片。
+- **樣式規範**: 篩選卡片通常使用 `p-6`（緊湊式），清單卡片使用 `p-8`（寬鬆式）。
+- **範例**: 交易紀錄、機台日誌。
+
+### 標準寬版佈局 (Wide Layout)
+
+```html
+@section('content')
+<div class="space-y-6">
+    <div class="flex flex-col md:flex-row md:items-center md:justify-between gap-6">
+        <div>
+            <h1 class="text-3xl font-black text-slate-800 dark:text-white tracking-tight font-display">{{ __('Title') }}</h1>
+            <p class="text-sm font-bold text-slate-500 dark:text-slate-400 mt-1 uppercase tracking-widest">{{ __('Subtitle') }}</p>
+        </div>
+        <div class="flex items-center gap-3">
+            <button class="btn-luxury-primary">
+                <i class="lucide-plus w-4 h-4"></i>
+                <span>新增</span>
+            </button>
+        </div>
+    </div>
+
+    <div class="luxury-card rounded-3xl p-8 animate-luxury-in">
+        <div class="flex items-center justify-between mb-10">
+            <form class="relative group">
+                <input type="text" class="luxury-input pl-12 pr-6 w-64" placeholder="{{ __('Search...') }}">
+            </form>
+        </div>
+
+        <div class="overflow-x-auto">
+            <table class="w-full text-left border-separate border-spacing-y-0">
+                <thead>
+                    <tr class="bg-slate-50/50 dark:bg-slate-900/10">
+                        <th class="px-6 py-4 text-[11px] font-black text-slate-400 uppercase tracking-[0.2em] border-b border-slate-100 dark:border-slate-800">{{ __('Name') }}</th>
+                        <th class="px-6 py-4 text-[11px] font-black text-slate-400 uppercase tracking-[0.2em] border-b border-slate-100 dark:border-slate-800 text-right">{{ __('Action') }}</th>
+                    </tr>
+                </thead>
+                <tbody class="divide-y divide-slate-50 dark:divide-slate-800/80">
+                    <tr class="group hover:bg-slate-50/80 dark:hover:bg-slate-800/40 transition-all duration-300">
+                        <td class="px-6 py-6 font-extrabold text-slate-800 dark:text-slate-100">Example Name</td>
+                        <td class="px-6 py-6 text-right"> </td>
+                    </tr>
+                </tbody>
+            </table>
+        </div>
+
+        <div class="mt-8 border-t border-slate-100/50 dark:border-slate-800/50 pt-6">
+            {{ $items->links('vendor.pagination.luxury') }}
+        </div>
+    </div>
+</div>
+@endsection
+```
+
+### 佈局核心原則:
+1. **移除重複內距**: 根容器 `div` 應**禁止**使用 `p-6` 或 `p-10`，因為佈局基底已提供基礎間距。
+2. **區塊間隙**: 建議使用 `space-y-6` 或 `space-y-8` 以獲得最佳空氣感。但在「高密度資料管理」或使用者有特殊緊湊需求的情境下，容許縮減至 **`space-y-2`**。
+3. **主容器樣式**: 強制對齊為 `luxury-card rounded-3xl p-8`。
+3. **標題排版**: 
+   - 主標題需應用 `font-display` (Outfit)。
+   - 描述文字需應用 `uppercase tracking-widest font-bold` 以呈現高級設計感。
+
+## 7. 表單元件規範 (Form Elements)
+
+針對輸入框與下拉選單，強制使用以下類別以確保深色模式質感。
+
+### 輸入框與選單
+- **類別**: `.luxury-input`, `.luxury-select`
+- **特性**: 
+  - 深色模式下具備半透明背景與背景模糊效果。
+  - 統一的 `rounded-xl` 圓角與 `font-bold` 字體。
+  - 聚焦時帶有青色 (`Cyan`) 發光邊框。
+
+```html
+<input type="text" class="luxury-input" placeholder="請輸入內容">
+
+<select class="luxury-select">
+    <option value="1">啟用</option>
+    <option value="0">禁用</option>
+</select>
+
+### 搜尋式下拉選單 (Searchable Select) - 【進階推薦】
+- **組件**: `<x-searchable-select />`
+- **適用場景**: 選項大於 10 筆或具備層級關聯的篩選器（如：公司名稱、機台編號）。
+- **奢華特徵**:
+  - **動態旋轉箭頭**: 透過 `::after` 偽元素實作，選單展開時箭頭執行 `300ms` 的 180 度旋轉動畫。
+  - **即時過濾**: 輸入關鍵字即時隱藏不匹配項。
+  - **選取標示**: 選取的項目右側帶有青色 (`Cyan`) 的勾選小圖標。
+  - **全部選項修復 (Space Fix)**: 若用於篩選（如公司篩選），組件內部已實作「空格佔位符」機制。若選單中的「全部」選項在選取後消失，請確保該選項的值為單個空格 (`value=" "`)。這能繞過 Preline 對空標記的隱藏邏輯，並同步觸發 Laravel 的 `blank()` 判定。
+
+```html
+<x-searchable-select 
+    name="company_id" 
+    :options="$companies" 
+    :selected="request('company_id')" 
+    :placeholder="__('All Companies')"
+    onchange="this.form.submit()" 
+/>
+```
+```
+
+## 8. 編輯與詳情頁規範 (Detail & Edit Views)
+
+為了讓分層資訊更具視覺引導，各個區塊 (Section) 的圖示應採用不同的顏色意象。
+
+### 區塊圖示色彩意象 (Section Icon Palette)
+- **基本資訊 (Basic Info)**: **翠綠色 (`Emerald`)**。代表核心、穩定與起點。
+    - 樣式: `bg-emerald-500/10 text-emerald-500`
+- **硬體/插槽設定**: **琥珀色 (`Amber/Orange`)**。代表動作、物理連接與硬體警告。
+    - 樣式: `bg-amber-500/10 text-amber-500`
+- **系統/進階設定**: **靛藍色 (`Indigo`)**。代表邏輯、權限與深層配置。
+    - 樣式: `bg-indigo-500/10 text-indigo-500`
+- **危險/移除動作**: **玫瑰紅 (`Rose`)**。代表破壞性操作。
+    - 樣式: `bg-rose-500/10 text-rose-500`
+
+## 9. 資料表格規範 (Data Tables)
+
+為了確保管理後台資料的可讀性與精密感，表格內的所有文字級別必須對齊以下規範：
+
+### 文字大小與權重 (Typography Hierarchy)
+- **表頭 (Table Header)**: 
+  - 類別: `text-xs font-bold text-slate-500 dark:text-slate-400 uppercase tracking-[0.15em]`
+  - 作用: 提供清晰的欄位定義而不奪取資料視覺焦點。具備足夠對比度。
+- **主標題 (Primary Item)**: 
+  - 類別: `text-base font-extrabold text-slate-800 dark:text-slate-100`
+  - 範例: 公司名稱、機體名稱。
+- **次要資訊 (Secondary Info)**: 
+  - 類別: `text-xs font-bold text-slate-500 dark:text-slate-400 tracking-wide`
+  - 範例: 使用者帳號、備註、權限名稱。
+- **狀態標籤 (Status Badge)**: 
+  - 範例: 啟用 (`emerald`)、禁用 (`rose`) / 角色名稱 (`sky`/`indigo`)。
+  - 特性: `px-2.5 py-1 rounded-lg text-xs font-bold border tracking-wider`
+
+### 空間與反應 (Spacing & Interaction)
+- **單元格內距**: 統一使用 `px-6 py-6`。
+- **懸停反應**: 必須在 `tr` 套用 `group` 且子<E4B894>### 9.4 標竿刪除確認模式 (Luxury Delete Modal Pattern)
+當執行刪除或具備破壞性的操作時，**禁止**使用瀏覽器原生 `confirm()` 或簡易的 `x-modal`。全站統一使用 **`<x-delete-confirm-modal />`** Blade 組件進行二次確認。
+
+1. **參數配置**: 
+   - `title`: (選填) 預設為「確認刪除」。
+   - `message`: (選填) 定義具體的刪除警告訊息（例如「您確定要永久刪除此帳號嗎？」）。
+2. **視覺特徵**:
+   - **背景**: `bg-slate-900/60 backdrop-blur-sm`。
+   - **容器**: `rounded-3xl shadow-2xl animate-luxury-in`。
+   - **圖示**: 警告圖示使用 `bg-amber-100/10 text-amber-600`。
+   - **按鈕**: 刪除按鈕使用 `bg-rose-500` 搭配 `shadow-rose-200` 投影，取消按鈕使用 `bg-slate-100`。
+3. **交互規範**:
+   - **禁止斜體 (No Italics)**: 彈窗標題與按鈕文字嚴禁使用 `italic`，保持直挺專業感。
+
+```html
+<!-- 使用範例 -->
+<x-delete-confirm-modal :message="__('Are you sure you want to delete this account?')" />
+```
+
+## 10. 系統兼容性與標準化 (Compatibility & Standardization)
+
+為了確保在不同版本的開發環境中（如目前專案使用的 Tailwind CSS v3.1）UI 都能正確呈現，並維持全站操作感一致，必須遵守以下額外規範。
+
+### Tailwind CSS 版本兼容性 (v3.1)
+- **禁止使用 `size-` 屬性**: 舊版不支援 `size-4` 等語法，請一律分拆寫作 `w-4 h-4`。
+- **避免非標準間距**: 避免使用 `4.5` (`18px`) 等任意值，優先使用標準等級如 `4` (`16px`) 或 `5` (`20px`)。
+
+## 11. 字體與技術資訊規範 (Typography & Technical Data)
+
+為了確保全站「次要資訊」具備極一致的高級感，必須遵守以下「機台標竿」規範：
+
+### 核心樣式級別 (Core Typography Scale)
+| 資訊類型 | 客戶/配置名稱 (標題) | 技術代碼 (ID, SN, Code) | 清單時間 (Timestamps) | 分隔符號 (•) |
+| :--- | :--- | :--- | :--- | :--- |
+| **字體族** | `font-sans` (Plus Jakarta Sans) | `font-mono` (微縮型單雙格) | `font-mono` (或 `sans` 視場景) | `font-sans` |
+| **尺寸** | `text-base` | `text-xs` (不可使用 10px) | `text-xs` | `text-xs` |
+| **字重** | `font-extrabold` (800) | `font-bold` (700) | `font-black` (900) | `font-bold` |
+| **字距** | `tracking-tight` (-0.02em) | `tracking-widest` (最寬) | `tracking-widest` | `tracking-normal` |
+| **格式** | 保持原始名稱 | `uppercase` (強制大寫) | `uppercase` | N/A |
+| **色彩** | `slate-900` / `slate-100` | `slate-500` / `slate-400` | `slate-400` / `slate-400/80` | `slate-300` / `slate-700` |
+
+### 實作禁忌與準則
+- **禁止斜體 (No Italics)**: 名稱欄位嚴禁附帶 `italic`（特別是標題或配置名稱），保持直挺專業感。
+- **作用範圍 (Mono Scoping)**: `font-mono` 僅限作用於「純英文/數字」的代碼。Email 或分隔點必須回歸 `font-sans` 以確保圓潤。
+- **權重載入 (Font Weights)**: 確保 HTML Header 載入了 `800` 與 `900` 權重，避免瀏覽器模擬出的假粗體。
+- **清單資訊密度**: 對於高密度清單中的時間資訊，應優先使用 `font-black` 與 `tracking-widest` 來建立明確的「標籤感」，而非僅僅是「微縮文字」。
+
+---
+## 12. 提示與告警規範 (Alerts & Notifications)
+
+為了確保全站操作回饋的一致性與專業感，所有系統內部的提示（成功、錯誤、警告）必須遵循以下規範。
+
+### 1. 懸浮式自動消失提示 (Auto-hiding Toasts)
+- **視覺樣式**: 
+  - 位置: 固定於畫面上方中央 (`fixed top-8 left-1/2 -translate-x-1/2`)。
+  - 特效: 毛玻璃背景 (`backdrop-blur-xl`)、圓角 (`rounded-2xl`)、軟陰影。
+  - 動畫: 滑入 (`translate-y-0`) / 滑出 (`-translate-y-4`)，配合 `opacity` 變化。
+- **型態定義**:
+  - **Success (成功)**: 使用 `emerald` 色系。
+  - **Error (錯誤)**: 使用 `rose` 色系。
+- **時長規範**:
+  - 成功提示: 3 秒後消失。
+  - 錯誤提示: 5 秒後消失（提供使用者更多閱讀錯誤原因的時間）。
+- **組件實作**: 統一調用 `<x-toast />`。
+
+### 2. 視窗內操作警告 (Inline Action Warnings)
+- **適用場景**: 在 Modal 或編輯頁面中，提示可能導致風險的操作（如編輯自身角色）。
+- **視覺樣式**: 
+  - 背景: `bg-amber-500/10` (琥珀色)。
+  - 邊框: `border-amber-500/20`。
+  - 進場動畫: `animate-luxury-in`。
+- **實作範例**:
+```html
+<div class="p-5 bg-amber-500/10 border border-amber-500/20 text-amber-600 rounded-2xl flex items-start gap-4 animate-luxury-in font-bold">
+    <!-- Icon & Text -->
+</div>
+```
+
+### 3. 通用豪華確認與告警視窗 (General Luxury Modals)
+**統一準則**: 所有的系統確認 (Confirm) 或重要告警 (Alert/Warning) **必須** 捨棄 `x-modal` 組件，改用 Section 9.4 定義的自定義 Div 結構。
+
+- **警告模式 (Warning/Alert)**: 
+  - 僅提供「關閉/確定」一個按鈕。
+  - 樣式同 9.4，但隱藏刪除 Form 與相關色彩。
+- **確認模式 (Confirm)**: 
+  - 提供「取消」與「執行」兩個按鈕。
+  - 執行按鈕顏色視操作性質而定 (Delete: `rose`, Save/Action: `cyan`)。
+
 ---
 > [!IMPORTANT]
 > **開發新功能前，必須確認 `app.css` 中的 `.btn-luxury-*` 系列組件是否滿足需求。**

.env.example

@@ -6,7 +6,9 @@ APP_DEBUG=true
 APP_URL=http://localhost:8090
 APP_PORT=8090
 
-APP_LOCALE=en
+APP_LOCALE=zh_TW
+APP_TIMEZONE=Asia/Taipei
+DB_TIMEZONE="+08:00"
 APP_FALLBACK_LOCALE=en
 APP_FAKER_LOCALE=en_US
 
@@ -25,7 +27,7 @@ LOG_LEVEL=debug
 DB_CONNECTION=mysql
 DB_HOST=mysql
 DB_PORT=3306
-DB_DATABASE=star-cloud
+DB_DATABASE=star_cloud
 DB_USERNAME=sail
 DB_PASSWORD=password
 # FORWARD_DB_PORT=3308
@@ -38,7 +40,7 @@ SESSION_DOMAIN=null
 
 BROADCAST_CONNECTION=log
 FILESYSTEM_DISK=local
-QUEUE_CONNECTION=database
+QUEUE_CONNECTION=redis
 
 CACHE_STORE=database
 # CACHE_PREFIX=
@@ -49,7 +51,7 @@ REDIS_CLIENT=phpredis
 REDIS_HOST=redis
 REDIS_PASSWORD=null
 REDIS_PORT=6379
-# FORWARD_REDIS_PORT=6380
+FORWARD_REDIS_PORT=6380
 
 MAIL_MAILER=smtp
 MAIL_SCHEME=null

.gitea/workflows/deploy-demo.yaml

@@ -22,12 +22,12 @@ jobs:
           echo "${{ secrets.DEMO_SSH_KEY }}" > ~/.ssh/id_rsa_demo
           chmod 600 ~/.ssh/id_rsa_demo
           rsync -avz --delete \
-            --exclude='.git' \
-            --exclude='node_modules' \
-            --exclude='vendor' \
-            --exclude='storage' \
-            --exclude='.env' \
-            --exclude='public/build' \
+            --exclude='/.git' \
+            --exclude='/node_modules' \
+            --exclude='/vendor' \
+            --exclude='/storage' \
+            --exclude='/.env' \
+            --exclude='/public/build' \
             -e "ssh -p 2227 -i ~/.ssh/id_rsa_demo -o StrictHostKeyChecking=no" \
             ./ root@220.132.7.82:/var/www/star-cloud-demo/
           rm ~/.ssh/id_rsa_demo
@@ -92,9 +92,13 @@ jobs:
             
             # 3. Laravel 初始化與優化
             php artisan migrate --force &&
+            php artisan storage:link &&
             php artisan optimize:clear &&
             php artisan optimize &&
-            php artisan view:cache
+            php artisan view:cache &&
+            php artisan queue:restart &&
+            php artisan db:seed --class=RoleSeeder --force &&
+            php artisan db:seed --class=AdminUserSeeder --force
            "
            docker exec star-cloud-demo-laravel chmod -R 775 /var/www/html/storage /var/www/html/bootstrap/cache
 

.gitignore

@@ -19,5 +19,6 @@ yarn-error.log
 /.vscode
 /docs/API
 /docs/*.xlsx
+/docs/pptx
 
 

README.md

@@ -1,388 +1,112 @@
 # Star Cloud 智能販賣機管理平台
 
-> 基於 Docker 的全方位智能販賣機後台管理系統
+> 基於 Docker 的全方位智能販賣機後台管理系統 (Cloud 平台)
 
-Star Cloud 是一個專為智能販賣機設計的後台管理系統，提供機台監控、庫存管理、銷售分析與會員管理等完整功能。本專案採用 Docker Compose 容器化架構，實現快速部署與環境一致性。
+Star Cloud 是一個專為智能販賣機設計的後台管理系統，負責管理機台、商品、銷售數據，並為硬體端點提供專用的 API。
 
 ---
 
-## 技術架構
+## 🚀 技術架構
 
-### 容器化架構
-本專案完全運行在 Docker 容器中，包含以下服務：
+### 核心架構
+本專案採用 **傳統單體式架構 (Monolithic Architecture)**，結合 Laravel Blade 引擎進行伺服器端渲染 (SSR)。
 
-| 服務 | 容器名稱 | 技術 | 用途 | 連接埠 |
+| 服務 | 容器名稱 | 技術 | 用途 | 本地 Port |
 |------|---------|------|------|--------|
-| **應用程式** | star-cloud-laravel | Laravel 10 + PHP 8.5 | Web 應用與 API | 8090:80, 5175:5175 |
-| **資料庫** | star-cloud-mysql | MySQL 8.0 | 關聯式資料庫 | 3306:3306 |
-| **快取** | star-cloud-redis | Redis Alpine | 快取與 Session | 6380:6379 |
+| **應用程式** | `star-cloud-laravel` | Laravel 12 + PHP 8.5 | 核心業務與渲染 | 8090 |
+| **資料庫** | `star-cloud-mysql` | MySQL 8.0 | 數據持久化 | 3306 |
+| **快取/隊列** | `star-cloud-redis` | Redis Alpine | IoT 高併發隊列 | 6380 |
 
 ### 後端技術棧
-
-- **Framework**: Laravel 10.x
-- **Language**: PHP 8.5+
+- **Framework**: Laravel 12.x
+- **Language**: PHP 8.5
+- **Redis**: 用於 IoT 高併發隊列 (B010, B600 等)
 - **Database**: MySQL 8.0
-- **Cache/Session**: Redis
-- **Authentication**: Laravel Sanctum (API Token)
-- **Package Manager**: Composer 2.x
 
 ### 前端技術棧
-
-- **Template Engine**: Blade Templates
-- **UI Library**: Preline UI 3.x (Tailwind CSS 組件庫)
-- **CSS Framework**: Tailwind CSS 3.x
-- **JavaScript**: Alpine.js 3.x (輕量級互動框架)
-- **Build Tool**: Vite 5.x
-- **HTTP Client**: Axios
+- **View**: Laravel Blade
+- **CSS**: Tailwind CSS + **Preline UI**
+- **JS**: Alpine.js (行為控制)
+- **Build**: Vite
 
 ---
 
-## 快速開始
+## 🛠️ 開發環境 (Laravel Sail)
+
+本專案建議使用 **Laravel Sail** 進行開發，避免直接在宿主機執行指令。
 
 ### 前置需求
+- Docker Desktop (Windows/Mac) 或 Docker Engine (Linux)
+- Git
 
-確保您的系統已安裝以下軟體：
+### 快速啟動
+1. `clone` 專案並進入目錄
+2. `cp .env.example .env`
+3. `./vendor/bin/sail up -d`
+4. `./vendor/bin/sail composer install`
+5. `./vendor/bin/sail artisan key:generate`
+6. `./vendor/bin/sail artisan migrate --seed`
+7. `./vendor/bin/sail npm install`
+8. `./vendor/bin/sail npm run dev`
 
-- **Docker** 20.10+
-- **Docker Compose** 2.0+
-- **Git**
-
-> **提示**：Windows 使用者建議安裝 [Docker Desktop](https://www.docker.com/products/docker-desktop/)，Linux 使用者可參考 [官方安裝文件](https://docs.docker.com/engine/install/)
-
-### 安裝步驟
-
-#### 1. Clone 專案
-
-```bash
-git clone <repository_url>
-cd star-cloud
-```
-
-#### 2. 環境設定
-
-複製環境變數範例檔案：
-
-```bash
-cp .env.example .env
-```
-
-**重要設定**（`.env` 檔案）：
-
-```env
-# 應用程式設定
-APP_NAME=Star Cloud
-APP_ENV=local
-APP_DEBUG=true
-APP_URL=http://localhost:8090
-
-# 資料庫設定（對應 Docker Compose 服務）
-DB_CONNECTION=mysql
-DB_HOST=mysql
-DB_PORT=3306
-DB_DATABASE=star_cloud
-DB_USERNAME=sail
-DB_PASSWORD=password
-
-# Redis 設定（對應 Docker Compose 服務）
-REDIS_HOST=redis
-REDIS_PASSWORD=null
-REDIS_PORT=6379
-
-# Vite 開發伺服器
-VITE_PORT=5175
-```
-
-#### 3. 啟動 Docker 容器
-
-啟動所有服務（應用程式、資料庫、Redis）：
-
-```bash
-docker compose up -d
-```
-
-> **說明**：`-d` 參數表示背景執行
-
-檢查容器狀態：
-
-```bash
-docker compose ps
-```
-
-預期輸出：
-```
-NAME                 STATUS         PORTS
-star-cloud-laravel   Up X minutes   0.0.0.0:8090->80/tcp, 0.0.0.0:5175->5175/tcp
-star-cloud-mysql     Up X minutes   0.0.0.0:3306->3306/tcp
-star-cloud-redis     Up X minutes   0.0.0.0:6380->6379/tcp
-```
-
-#### 4. 初始化應用程式
-
-**4.1 安裝後端依賴**
-
-```bash
-docker compose exec laravel.test composer install
-```
-
-**4.2 產生應用程式金鑰**
-
-```bash
-docker compose exec laravel.test php artisan key:generate
-```
-
-**4.3 執行資料庫遷移與種子**
-
-```bash
-docker compose exec laravel.test php artisan migrate --seed
-```
-
-> **預設管理員帳號**：
-> - Email: `admin`
-> - Password: `password`
-
-**4.4 安裝前端依賴**
-
-```bash
-docker compose exec laravel.test npm install
-```
-
-**4.5 編譯前端資源**
-
-```bash
-# 開發模式（支援 Hot Module Replacement）
-docker compose exec laravel.test npm run dev
-
-# 或生產模式
-docker compose exec laravel.test npm run build
-```
-
-#### 5. 訪問應用程式
-
-- **應用程式**: http://localhost:8090
-- **Vite Dev Server**: http://localhost:5175
+### 常用開發指令
+| 功能 | 指令 |
+|------|------|
+| 啟動環境 | `./vendor/bin/sail up -d` |
+| 停止環境 | `./vendor/bin/sail down` |
+| Artisan 指令 | `./vendor/bin/sail artisan <cmd>` |
+| Composer 指令 | `./vendor/bin/sail composer <cmd>` |
+| NPM 指令 | `./vendor/bin/sail npm <cmd>` |
+| 執行測試 | `./vendor/bin/sail test` |
 
 ---
 
-## Docker 常用指令
+## 🔐 API 規範
 
-### 容器管理
+系統 API 分為兩大類，遵循不同的設計慣例：
 
-```bash
-# 啟動所有服務
-docker compose up -d
+### 1. Admin/Web API (`/api/v1/...`)
+- **對象**: 後台管理介面、APP UI。
+- **認證**: Laravel Sanctum (Session/Token)。
+- **格式**: 標準 RESTful JSON。
 
-# 停止所有服務
-docker compose down
-
-# 重啟服務
-docker compose restart
-
-# 查看容器日誌
-docker compose logs -f laravel.test
-
-# 進入應用程式容器
-docker compose exec laravel.test bash
-```
-
-### Laravel 指令
-
-所有 Laravel Artisan 指令需在容器內執行：
-
-```bash
-# 執行 Artisan 指令
-docker compose exec laravel.test php artisan <command>
-
-# 範例：清除快取
-docker compose exec laravel.test php artisan cache:clear
-
-# 範例：執行 Migration
-docker compose exec laravel.test php artisan migrate
-
-# 範例：建立新 Controller
-docker compose exec laravel.test php artisan make:controller ExampleController
-```
-
-### 前端開發
-
-```bash
-# 安裝 npm 套件
-docker compose exec laravel.test npm install
-
-# 開發模式（即時編譯）
-docker compose exec laravel.test npm run dev
-
-# 生產編譯
-docker compose exec laravel.test npm run build
-```
-
-### 資料庫操作
-
-```bash
-# 進入 MySQL 容器
-docker compose exec mysql bash
-
-# 直接執行 SQL
-docker compose exec mysql mysql -u sail -ppassword star_cloud
-
-# 備份資料庫
-docker compose exec mysql mysqldump -u sail -ppassword star_cloud > backup.sql
-
-# 還原資料庫
-docker compose exec -T mysql mysql -u sail -ppassword star_cloud < backup.sql
-```
+### 2. Machine IoT API (`/api/app/...`)
+- **對象**: 智能販賣機、計時器等硬體。
+- **認證**: Header `Authorization: Bearer <api_token>`。
+- **高併發處理**: 核心日誌 (B010 心跳、B600 交易) **嚴禁直寫 DB**，必須進入 **Redis Queue** 背景異步處理。
 
 ---
 
-## 主要功能模組
+## 🌐 多語系支援 (I18n)
 
-### 核心功能
-
-| 模組 | 功能描述 |
-|------|---------|
-| **儀錶板** | 銷售數據總覽、機台狀態即時監控、營收統計圖表 |
-| **機台管理** | 機台列表、遠端控制、日誌查詢、維修管理、效期控制 |
-| **倉庫管理** | 倉庫列表、庫存管理、調撥單、採購單、補貨單 |
-| **商品管理** | 商品資料、分類管理、商品報表分析 |
-| **銷售管理** | 交易紀錄、金流管理、促銷設定、營收報表 |
-| **會員系統** | 會員管理、點數系統、來店禮、Line 整合 |
-| **權限控制** | 角色管理、權限分配、功能權限設定 |
-| **遠端管理** | 機台重啟、遠端出貨、遠端結帳、庫存調整 |
+所有 UI 顯示文字必須支援多語系，禁止 Hard-coded。
+- **語系檔案**: `lang/zh_TW.json`, `lang/en.json`, `lang/ja.json`。
+- **呼叫方式**: 使用 `__('Phrases in English')` 或 `@lang('...')`。
+- **命名規範**: 優先使用「英文原始詞彙」作為 Key 名稱。
 
 ---
 
-## Preline UI 組件庫
+## 📂 目錄結構
 
-本專案已整合 **Preline UI 3.x**，這是一個基於 Tailwind CSS 的開源 UI 組件庫，提供 50+ 預構建組件。
-
-### 可用組件類別
-
-- **Navigation**: 導航列、側邊欄、分頁、麵包屑、頁籤
-- **Forms**: 輸入框、選擇器、開關、檔案上傳、日期選擇器
-- **Overlays**: 模態框、抽屜、下拉選單、提示框、彈出框
-- **Data Display**: 表格、卡片、時間軸、折疊面板、徽章
-- **Feedback**: 通知、警告、載入狀態、進度條
-
-### 使用範例
-
-```html
-<!-- 下拉選單 -->
-<div class="hs-dropdown relative inline-flex">
-  <button type="button" class="hs-dropdown-toggle px-4 py-2 bg-blue-600 text-white rounded-lg">
-    選單 <svg class="w-4 h-4 inline ml-2">...</svg>
-  </button>
-  <div class="hs-dropdown-menu hidden bg-white shadow-lg rounded-lg p-2 mt-2">
-    <a class="block px-3 py-2 rounded hover:bg-gray-100" href="#">選項 1</a>
-    <a class="block px-3 py-2 rounded hover:bg-gray-100" href="#">選項 2</a>
-  </div>
-</div>
-
-<!-- 模態框 -->
-<button type="button" data-hs-overlay="#my-modal" class="px-4 py-2 bg-blue-600 text-white rounded-lg">
-  開啟模態框
-</button>
-<div id="my-modal" class="hs-overlay hidden">
-  <!-- 模態框內容 -->
-</div>
-```
-
-**更多資源**：
-- 官方文件: https://preline.co/docs/
-- 組件範例: https://preline.co/examples.html
-- GitHub: https://github.com/htmlstreamofficial/preline
+- `app/Http/Controllers/`: 控制器
+- `app/Models/{Domain}/`: 分領域的模型 (如 `Machine`, `Member`)
+- `app/Services/{Domain}/`: 封裝商業邏輯與資料異動
+- `app/Jobs/{Domain}/`: IoT 異步隊列處理任務 (重要)
+- `resources/views/`: Blade 模板 (按功能分資料夾)
+- `resources/views/components/`: 可重用的 UI 組件
+- `routes/`: 路由定義 (`web.php` 與 `api.php`)
 
 ---
 
-## 故障排除
+## 🚢 CI/CD 與部署
 
-### 容器無法啟動
-
-```bash
-# 檢查容器日誌
-docker compose logs
-
-# 重建容器
-docker compose down
-docker compose up -d --build
-```
-
-### 連接資料庫失敗
-
-確認 `.env` 中 `DB_HOST` 設定為 `mysql`（容器服務名稱），而非 `127.0.0.1`。
-
-### 前端資源編譯失敗
-
-```bash
-# 清除 node_modules 重新安裝
-docker compose exec laravel.test rm -rf node_modules
-docker compose exec laravel.test npm install
-docker compose exec laravel.test npm run build
-```
-
-### 權限問題
-
-```bash
-# 修正儲存目錄權限
-docker compose exec laravel.test chmod -R 775 storage bootstrap/cache
-```
-
----
-
-## 部署至生產環境
-
-### 1. 環境變數設定
-
-將 `.env` 中的設定調整為生產環境：
-
-```env
-APP_ENV=production
-APP_DEBUG=false
-APP_URL=https://your-domain.com
-```
-
-### 2. 編譯前端資源
-
-```bash
-docker compose exec laravel.test npm run build
-```
-
-### 3. 優化 Laravel
-
-```bash
-docker compose exec laravel.test php artisan config:cache
-docker compose exec laravel.test php artisan route:cache
-docker compose exec laravel.test php artisan view:cache
-```
-
-### 4. 設定 HTTPS
-
-建議使用 Nginx Reverse Proxy + Let's Encrypt SSL 憑證。
-
----
-
-## 開發團隊協作
-
-### Git Workflow
-
-```bash
-# 拉取最新程式碼
-git pull origin main
-
-# 重建容器（若 Docker 設定有變更）
-docker compose down
-docker compose up -d
-
-# 更新依賴
-docker compose exec laravel.test composer install
-docker compose exec laravel.test npm install
-
-# 執行 Migration
-docker compose exec laravel.test php artisan migrate
-```
+- **自動化工具**: Gitea Actions (`.gitea/workflows/`)。
+- **Demo 環境**: 推送到 `demo` 分支會自動部署至 `demo-cloud.taiwan-star.com.tw`。
+- **伺服器路徑**: `/var/www/star-cloud-demo` (透過 `ssh gitea_work` 登入)。
 
 ---
 
 ## 授權與版權
-
 © Star Cloud. All Rights Reserved.
 
 ---

app/Http/Controllers/Admin/AdvertisementController.php

@@ -0,0 +1,270 @@
+<?php
+
+namespace App\Http\Controllers\Admin;
+
+use App\Models\Machine\Machine;
+use App\Models\Machine\MachineAdvertisement;
+use App\Models\System\Advertisement;
+use App\Models\System\Company;
+use App\Traits\ImageHandler;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Storage;
+
+class AdvertisementController extends AdminController
+{
+    use ImageHandler;
+
+    public function index(Request $request)
+    {
+        $user = auth()->user();
+        $tab = $request->input('tab', 'list');
+
+        // Tab 1: 廣告列表
+        $advertisements = Advertisement::with('company')->latest()->paginate(10);
+        
+        // Tab 2: 機台廣告設置 (所需資料) - 隱藏已過期的廣告
+        $allAds = Advertisement::playing()->get();
+
+        // Tab 2: 機台廣告設置 (所需資料)
+        // 取得使用者有權限的機台列表 (已透過 Global Scope 過濾)
+        $machines = Machine::select('id', 'name', 'serial_no', 'company_id')->get();
+
+        $companies = $user->isSystemAdmin() ? Company::orderBy('name')->get() : collect();
+
+        return view('admin.ads.index', [
+            'advertisements' => $advertisements,
+            'machines' => $machines,
+            'tab' => $tab,
+            'allAds' => $allAds,
+            'companies' => $companies,
+        ]);
+    }
+
+    /**
+     * 素材 CRUD: 儲存廣告
+     */
+    public function store(Request $request)
+    {
+        $request->validate([
+            'name' => 'required|string|max:255',
+            'type' => 'required|in:image,video',
+            'duration' => 'required|in:15,30,60',
+            'file' => [
+                'required',
+                'file',
+                'mimes:jpeg,png,jpg,gif,webp,mp4,mov,avi',
+                $request->type === 'image' ? 'max:10240' : 'max:51200', // Image 10MB, Video 50MB
+            ],
+            'company_id' => 'nullable|exists:companies,id',
+            'start_at' => 'nullable|date',
+            'end_at' => 'nullable|date|after_or_equal:start_at',
+        ]);
+
+        $user = auth()->user();
+        $file = $request->file('file');
+        
+        if ($request->type === 'image') {
+            $path = $this->storeAsWebp($file, 'ads');
+        } else {
+            $path = $file->store('ads', 'public');
+        }
+
+        if ($user->isSystemAdmin()) {
+            $companyId = $request->filled('company_id') ? $request->company_id : null;
+        } else {
+            $companyId = $user->company_id;
+        }
+
+        $advertisement = Advertisement::create([
+            'company_id' => $companyId,
+            'name' => $request->name,
+            'type' => $request->type,
+            'duration' => (int) $request->duration,
+            'url' => Storage::disk('public')->url($path),
+            'is_active' => true,
+            'start_at' => $request->start_at,
+            'end_at' => $request->end_at,
+        ]);
+
+        if ($request->wantsJson()) {
+            return response()->json([
+                'success' => true,
+                'message' => __('Advertisement created successfully.'),
+                'data' => $advertisement
+            ]);
+        }
+
+        return redirect()->back()->with('success', __('Advertisement created successfully.'));
+    }
+
+    public function update(Request $request, Advertisement $advertisement)
+    {
+        $rules = [
+            'name' => 'required|string|max:255',
+            'type' => 'required|in:image,video',
+            'duration' => 'required|in:15,30,60',
+            'is_active' => 'boolean',
+            'company_id' => 'nullable|exists:companies,id',
+            'start_at' => 'nullable|date',
+            'end_at' => 'nullable|date|after_or_equal:start_at',
+        ];
+
+        if ($request->hasFile('file')) {
+            $rules['file'] = [
+                'file',
+                'mimes:jpeg,png,jpg,gif,webp,mp4,mov,avi',
+                $request->type === 'image' ? 'max:10240' : 'max:51200',
+            ];
+        }
+
+        $request->validate($rules);
+
+        $data = $request->only(['name', 'type', 'duration', 'start_at', 'end_at']);
+        $data['is_active'] = $request->has('is_active');
+        
+        $user = auth()->user();
+        if ($user->isSystemAdmin()) {
+            $data['company_id'] = $request->filled('company_id') ? $request->company_id : null;
+        }
+
+        if ($request->hasFile('file')) {
+            // 刪除舊檔案
+            // 處理 URL 可能包含 storage 或原始路徑的情況
+            $oldPath = str_replace(Storage::disk('public')->url(''), '', $advertisement->url);
+            // 去除開頭可能的斜線
+            $oldPath = ltrim($oldPath, '/');
+            Storage::disk('public')->delete($oldPath);
+
+            // 存入新檔案
+            $file = $request->file('file');
+            if ($request->type === 'image') {
+                $path = $this->storeAsWebp($file, 'ads');
+            } else {
+                $path = $file->store('ads', 'public');
+            }
+            $data['url'] = Storage::disk('public')->url($path);
+        }
+
+        $advertisement->update($data);
+
+        if ($request->wantsJson()) {
+            return response()->json([
+                'success' => true,
+                'message' => __('Advertisement updated successfully.'),
+                'data' => $advertisement
+            ]);
+        }
+
+        return redirect()->back()->with('success', __('Advertisement updated successfully.'));
+    }
+
+    public function destroy(Request $request, Advertisement $advertisement)
+    {
+        // 檢查是否有機台正投放中
+        if ($advertisement->machineAdvertisements()->exists()) {
+            return redirect()->back()->with('error', __('Cannot delete advertisement being used by machines.'));
+        }
+
+        // 刪除實體檔案
+        $path = str_replace(Storage::disk('public')->url(''), '', $advertisement->url);
+        Storage::disk('public')->delete($path);
+
+        $advertisement->delete();
+        if ($request->wantsJson()) {
+            return response()->json([
+                'success' => true,
+                'message' => __('Advertisement deleted successfully.')
+            ]);
+        }
+        
+        return redirect()->back()->with('success', __('Advertisement deleted successfully.'));
+    }
+
+    /**
+     * AJAX: 取得特定機台的廣告投放清單
+     */
+    public function getMachineAds(Machine $machine)
+    {
+        $assignments = MachineAdvertisement::where('machine_id', $machine->id)
+            ->with('advertisement')
+            ->orderBy('sort_order', 'asc')
+            ->get()
+            ->groupBy('position');
+
+        return response()->json([
+            'success' => true,
+            'data' => $assignments
+        ]);
+    }
+
+    /**
+     * 投放廣告至機台
+     */
+    public function assign(Request $request)
+    {
+        $request->validate([
+            'machine_id' => 'required|exists:machines,id',
+            'advertisement_id' => 'required|exists:advertisements,id',
+            'position' => 'required|in:vending,visit_gift,standby',
+            'sort_order' => 'nullable|integer',
+        ]);
+
+        // If sort_order is not provided, append to the end of the current position list
+        $newSortOrder = $request->sort_order;
+        if (is_null($newSortOrder)) {
+            $newSortOrder = MachineAdvertisement::where('machine_id', $request->machine_id)
+                ->where('position', $request->position)
+                ->max('sort_order') + 1;
+        }
+
+        MachineAdvertisement::updateOrCreate(
+            [
+                'machine_id' => $request->machine_id,
+                'position' => $request->position,
+                'advertisement_id' => $request->advertisement_id,
+            ],
+            [
+                'sort_order' => $newSortOrder,
+            ]
+        );
+
+        return response()->json([
+            'success' => true,
+            'message' => __('Advertisement assigned successfully.')
+        ]);
+    }
+
+    /**
+     * 重新排序廣告播放順序
+     */
+    public function reorderAssignments(Request $request)
+    {
+        $request->validate([
+            'assignment_ids' => 'required|array',
+            'assignment_ids.*' => 'exists:machine_advertisements,id'
+        ]);
+
+        foreach ($request->assignment_ids as $index => $id) {
+            MachineAdvertisement::where('id', $id)->update(['sort_order' => $index]);
+        }
+
+        return response()->json([
+            'success' => true,
+            'message' => __('Order updated successfully.')
+        ]);
+    }
+
+    /**
+     * 移除廣告投放
+     */
+    public function removeAssignment($id)
+    {
+        $assignment = MachineAdvertisement::findOrFail($id);
+        $assignment->delete();
+
+        return response()->json([
+            'success' => true,
+            'message' => __('Assignment removed successfully.')
+        ]);
+    }
+}

app/Http/Controllers/Admin/BasicSettings/MachineModelController.php

@@ -0,0 +1,71 @@
+<?php
+
+namespace App\Http\Controllers\Admin\BasicSettings;
+
+use App\Http\Controllers\Admin\AdminController;
+use App\Models\Machine\MachineModel;
+use Illuminate\Http\Request;
+use Illuminate\View\View;
+use Illuminate\Http\RedirectResponse;
+
+class MachineModelController extends AdminController
+{
+    /**
+     * 顯示機台型號列表 (重新導向至機台設定的標籤頁)
+     */
+    public function index(Request $request): RedirectResponse
+    {
+        return redirect()->route('admin.basic-settings.machines.index', ['tab' => 'models']);
+    }
+
+    public function store(Request $request): RedirectResponse
+    {
+        $validated = $request->validate([
+            'name' => 'required|string|max:255',
+        ]);
+
+        MachineModel::create(array_merge($validated, [
+            'company_id' => auth()->user()->company_id,
+            'creator_id' => auth()->id(),
+            'updater_id' => auth()->id(),
+        ]));
+
+        return redirect()->route('admin.basic-settings.machines.index', ['tab' => 'models'])
+            ->with('success', __('Machine model created successfully.'));
+    }
+
+    /**
+     * 顯示編輯頁面 (與 index 共用 Modal 則不需此方法，但 resource 路由建議保留或調整)
+     */
+    public function edit(MachineModel $machine_model): View
+    {
+        // 若採用 index Modal 編輯，此處可回傳 JSON 或維持 Blade
+        return view('admin.basic-settings.machine-models.edit', compact('machine_model'));
+    }
+
+    public function update(Request $request, MachineModel $machine_model): RedirectResponse
+    {
+        $validated = $request->validate([
+            'name' => 'required|string|max:255',
+        ]);
+
+        $machine_model->update(array_merge($validated, [
+            'updater_id' => auth()->id(),
+        ]));
+
+        return redirect()->route('admin.basic-settings.machines.index', ['tab' => 'models'])
+            ->with('success', __('Machine model updated successfully.'));
+    }
+
+    public function destroy(MachineModel $machine_model): RedirectResponse
+    {
+        if ($machine_model->machines()->count() > 0) {
+            return redirect()->back()->with('error', __('Cannot delete model that is currently in use by machines.'));
+        }
+
+        $machine_model->delete();
+
+        return redirect()->route('admin.basic-settings.machines.index', ['tab' => 'models'])
+            ->with('success', __('Machine model deleted successfully.'));
+    }
+}

app/Http/Controllers/Admin/BasicSettings/MachinePhotoController.php

@@ -0,0 +1,76 @@
+<?php
+
+namespace App\Http\Controllers\Admin\BasicSettings;
+
+use App\Http\Controllers\Controller;
+use App\Models\Machine\Machine;
+use App\Traits\ImageHandler;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Log;
+use Illuminate\Support\Facades\Storage;
+
+class MachinePhotoController extends Controller
+{
+    use ImageHandler;
+
+    /**
+     * 更新機台照片
+     */
+    public function update(Request $request, Machine $machine): RedirectResponse
+    {
+        Log::info('Machine Photo Update Request', [
+            'machine_id' => $machine->id,
+            'files' => $request->allFiles()
+        ]);
+        
+        $request->validate([
+            'machine_image_0' => 'nullable|image|mimes:jpeg,png,jpg,gif,webp|max:10240',
+            'machine_image_1' => 'nullable|image|mimes:jpeg,png,jpg,gif,webp|max:10240',
+            'machine_image_2' => 'nullable|image|mimes:jpeg,png,jpg,gif,webp|max:10240',
+        ]);
+
+        try {
+            $images = $machine->images ?? [];
+
+            // 處理 3 個索引位置的圖片
+            for ($i = 0; $i < 3; $i++) {
+                // 先處理刪除標記
+                if ($request->input("delete_photo_{$i}") === '1') {
+                    if (isset($images[$i])) {
+                        unset($images[$i]);
+                    }
+                }
+
+                // 再處理檔案上傳（若有上傳會覆蓋掉刪除邏輯或原有的圖）
+                $fieldName = "machine_image_{$i}";
+                if ($request->hasFile($fieldName)) {
+                    $file = $request->file($fieldName);
+                    
+                    // 轉為 WebP 格式與保存
+                    $path = $this->storeAsWebp($file, "machines/{$machine->id}");
+                    $images[$i] = $path;
+                    
+                    Log::info("Machine image uploaded at slot {$i}", ['path' => $path]);
+                }
+            }
+
+            // 過濾掉 null 並重新整理索引，但這裡我們希望保持 3 個槽位的概念
+            // 如果用戶想保持順序，我們就直接儲存
+            ksort($images);
+
+            $machine->update([
+                'images' => $images,
+                'updater_id' => auth()->id(),
+            ]);
+
+            return back()->with('success', __('Machine images updated successfully.'));
+        } catch (\Exception $e) {
+            Log::error('Machine Photo Update Failed', [
+                'machine_id' => $machine->id,
+                'error' => $e->getMessage()
+            ]);
+            return back()->with('error', __('Failed to update machine images: ') . $e->getMessage());
+        }
+    }
+}

app/Http/Controllers/Admin/BasicSettings/MachineSettingController.php

@@ -0,0 +1,253 @@
+<?php
+
+namespace App\Http\Controllers\Admin\BasicSettings;
+
+use App\Http\Controllers\Admin\AdminController;
+use App\Models\Machine\Machine;
+use App\Models\Machine\MachineModel;
+use App\Models\System\PaymentConfig;
+use App\Traits\ImageHandler;
+use Illuminate\Http\Request;
+use Illuminate\View\View;
+use Illuminate\Http\RedirectResponse;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\Str;
+
+use Illuminate\Support\Facades\Log;
+
+class MachineSettingController extends AdminController
+{
+    use ImageHandler;
+
+    /**
+     * 顯示機台與型號設定列表 (採用標籤頁整合)
+     */
+    public function index(Request $request): View
+    {
+        $tab = $request->input('tab', 'machines');
+        $per_page = $request->input('per_page', 10);
+        $search = $request->input('search');
+
+        // 1. 處理機台清單 (Machines Tab)
+        $machineQuery = Machine::query()->with(['machineModel', 'paymentConfig', 'company']);
+        if ($tab === 'machines' && $search) {
+            $machineQuery->where(function ($q) use ($search) {
+                $q->where('name', 'like', "%{$search}%")
+                  ->orWhere('serial_no', 'like', "%{$search}%");
+            });
+        }
+        $machines = $machineQuery->latest()->paginate($per_page)->withQueryString();
+
+        // 2. 處理型號清單 (Models Tab)
+        $modelQuery = MachineModel::query()->withCount('machines');
+        if ($tab === 'models' && $search) {
+            $modelQuery->where('name', 'like', "%{$search}%");
+        }
+        $models_list = $modelQuery->latest()->paginate($per_page)->withQueryString();
+
+        // 3. 處理機台權限 (Permissions Tab) - 僅顯示 is_admin 帳號
+        $users_list = null;
+        if ($tab === 'permissions') {
+            $userQuery = \App\Models\System\User::query()
+                ->where('is_admin', true)
+                ->with(['company', 'machines']);
+            
+            if ($search) {
+                $userQuery->where(function($q) use ($search) {
+                    $q->where('name', 'like', "%{$search}%")
+                      ->orWhere('username', 'like', "%{$search}%");
+                });
+            }
+
+            if ($request->filled('company_id')) {
+                $userQuery->where('company_id', $request->company_id);
+            }
+
+            $users_list = $userQuery->latest()->paginate($per_page)->withQueryString();
+        }
+
+        // 4. 基礎下拉資料 (用於新增/編輯機台的彈窗)
+        $models = MachineModel::select('id', 'name')->get();
+        $paymentConfigs = PaymentConfig::select('id', 'name')->get();
+        $companies = \App\Models\System\Company::select('id', 'name', 'code')->get();
+
+        return view('admin.basic-settings.machines.index', compact(
+            'machines', 
+            'models_list', 
+            'users_list',
+            'models', 
+            'paymentConfigs', 
+            'companies',
+            'tab'
+        ));
+    }
+
+    /**
+     * 儲存新機台 (僅核心欄位)
+     */
+    public function store(Request $request): RedirectResponse
+    {
+        $validated = $request->validate([
+            'name' => 'required|string|max:255',
+            'serial_no' => 'required|string|unique:machines,serial_no',
+            'company_id' => 'nullable|exists:companies,id',
+            'machine_model_id' => 'required|exists:machine_models,id',
+            'payment_config_id' => 'nullable|exists:payment_configs,id',
+            'location' => 'nullable|string|max:255',
+            'images.*' => 'image|mimes:jpeg,png,jpg,gif,webp|max:10240', // Increase to 10MB
+        ]);
+
+        $imagePaths = [];
+        if ($request->hasFile('images')) {
+            foreach (array_slice($request->file('images'), 0, 3) as $image) {
+                $imagePaths[] = $this->storeAsWebp($image, 'machines');
+            }
+        }
+
+        $machine = Machine::create(array_merge($validated, [
+            'api_token' => \Illuminate\Support\Str::random(60),
+            'creator_id' => auth()->id(),
+            'updater_id' => auth()->id(),
+            'card_reader_seconds' => 30, // 預設值
+            'card_reader_checkout_time_1' => '22:30:00',
+            'card_reader_checkout_time_2' => '23:45:00',
+            'payment_buffer_seconds' => 5,
+            'images' => $imagePaths,
+        ]));
+
+        return redirect()->route('admin.basic-settings.machines.index')
+            ->with('success', __('Machine created successfully.'));
+    }
+
+    /**
+     * 顯示詳細編輯頁面
+     */
+    public function edit(Machine $machine): View
+    {
+        $models = MachineModel::select('id', 'name')->get();
+        $paymentConfigs = PaymentConfig::select('id', 'name')->get();
+        $companies = \App\Models\System\Company::select('id', 'name', 'code')->get();
+
+        return view('admin.basic-settings.machines.edit', compact('machine', 'models', 'paymentConfigs', 'companies'));
+    }
+
+    /**
+     * 更新機台詳細參數
+     */
+    public function update(Request $request, Machine $machine): RedirectResponse
+    {
+        Log::info('Machine Update Request', ['machine_id' => $machine->id, 'data' => $request->all()]);
+
+        try {
+            $validated = $request->validate([
+                'name' => 'required|string|max:255',
+                'serial_no' => 'sometimes|required|string|unique:machines,serial_no,' . $machine->id,
+                'card_reader_seconds' => 'required|integer|min:0',
+                'payment_buffer_seconds' => 'required|integer|min:0',
+                'card_reader_checkout_time_1' => 'nullable|string',
+                'card_reader_checkout_time_2' => 'nullable|string',
+                'heating_start_time' => 'nullable|string',
+                'heating_end_time' => 'nullable|string',
+                'card_reader_no' => 'nullable|string|max:255',
+                'key_no' => 'nullable|string|max:255',
+                'invoice_status' => 'required|integer|in:0,1,2',
+                'welcome_gift_enabled' => 'boolean',
+                'is_spring_slot_1_10' => 'boolean',
+                'is_spring_slot_11_20' => 'boolean',
+                'is_spring_slot_21_30' => 'boolean',
+                'is_spring_slot_31_40' => 'boolean',
+                'is_spring_slot_41_50' => 'boolean',
+                'is_spring_slot_51_60' => 'boolean',
+                'member_system_enabled' => 'boolean',
+                'machine_model_id' => 'required|exists:machine_models,id',
+                'payment_config_id' => 'nullable|exists:payment_configs,id',
+                'location' => 'nullable|string|max:255',
+                'image_0' => 'nullable|image|mimes:jpeg,png,jpg,gif,webp|max:10240',
+                'image_1' => 'nullable|image|mimes:jpeg,png,jpg,gif,webp|max:10240',
+                'image_2' => 'nullable|image|mimes:jpeg,png,jpg,gif,webp|max:10240',
+                'remove_image_0' => 'nullable|boolean',
+                'remove_image_1' => 'nullable|boolean',
+                'remove_image_2' => 'nullable|boolean',
+            ]);
+
+            // 僅限系統管理員可修改公司
+            if (auth()->user()->isSystemAdmin()) {
+                $companyRule = ['company_id' => 'nullable|exists:companies,id'];
+                $companyData = $request->validate($companyRule);
+                $validated = array_merge($validated, $companyData);
+            }
+            
+            Log::info('Machine Update Validated Data', ['data' => $validated]);
+        } catch (\Illuminate\Validation\ValidationException $e) {
+            Log::error('Machine Update Validation Failed', ['errors' => $e->errors()]);
+            throw $e;
+        }
+
+        // 排除虛擬欄位 (圖片上傳、移除標記)，這些欄位不在資料表內
+        $dataToUpdate = \Illuminate\Support\Arr::except($validated, [
+            'image_0', 'image_1', 'image_2', 
+            'remove_image_0', 'remove_image_1', 'remove_image_2'
+        ]);
+
+        $machine->update(array_merge($dataToUpdate, [
+            'updater_id' => auth()->id(),
+        ]));
+
+        // 處理圖片更新 (支援 3 個獨立槽位: image_0, image_1, image_2)
+        $currentImages = $machine->images ?? [];
+        $updated = false;
+
+        for ($i = 0; $i < 3; $i++) {
+            $inputName = "image_$i";
+            $removeName = "remove_image_$i";
+
+            // 如果有新圖片上傳
+            if ($request->hasFile($inputName)) {
+                // 刪除舊圖
+                if (isset($currentImages[$i]) && !empty($currentImages[$i])) {
+                    \Illuminate\Support\Facades\Storage::disk('public')->delete($currentImages[$i]);
+                }
+                // 儲存新圖
+                $currentImages[$i] = $this->storeAsWebp($request->file($inputName), 'machines');
+                $updated = true;
+            } 
+            // 否則，如果有刪除標記
+            elseif ($request->input($removeName) === '1') {
+                if (isset($currentImages[$i]) && !empty($currentImages[$i])) {
+                    \Illuminate\Support\Facades\Storage::disk('public')->delete($currentImages[$i]);
+                    unset($currentImages[$i]);
+                    $updated = true;
+                }
+            }
+        }
+
+        if ($updated) {
+            ksort($currentImages);
+            $machine->update(['images' => array_values($currentImages)]);
+        }
+
+        return redirect()->route('admin.basic-settings.machines.index')
+            ->with('success', __('Machine settings updated successfully.'));
+    }
+
+    public function regenerateToken(Request $request, $serial): \Illuminate\Http\JsonResponse
+    {
+        $machine = Machine::where('serial_no', $serial)->firstOrFail();
+        $newToken = \Illuminate\Support\Str::random(60);
+        $machine->update(['api_token' => $newToken]);
+
+        Log::info('Machine API Token Regenerated', [
+            'machine_id' => $machine->id,
+            'serial_no' => $machine->serial_no,
+            'user_id' => auth()->id()
+        ]);
+
+        return response()->json([
+            'success' => true,
+            'message' => __('API Token regenerated successfully.'),
+            'api_token' => $newToken
+        ]);
+    }
+
+
+}

app/Http/Controllers/Admin/BasicSettings/PaymentConfigController.php

@@ -0,0 +1,106 @@
+<?php
+
+namespace App\Http\Controllers\Admin\BasicSettings;
+
+use App\Http\Controllers\Admin\AdminController;
+use App\Models\System\PaymentConfig;
+use Illuminate\Http\Request;
+use Illuminate\View\View;
+use Illuminate\Http\RedirectResponse;
+
+class PaymentConfigController extends AdminController
+{
+    /**
+     * 顯示金流配置列表
+     */
+    public function index(Request $request): View
+    {
+        $per_page = $request->input('per_page', 20);
+        $configs = PaymentConfig::query()
+            ->when($request->search, function ($query, $search) {
+                $query->where('name', 'like', "%{$search}%")
+                    ->orWhereHas('company', function ($q) use ($search) {
+                        $q->where('name', 'like', "%{$search}%");
+                    });
+            })
+            ->with(['company', 'creator'])
+            ->latest()
+            ->paginate($per_page)
+            ->withQueryString();
+
+        return view('admin.basic-settings.payment-configs.index', [
+            'paymentConfigs' => $configs
+        ]);
+    }
+
+    /**
+     * 顯示新增頁面
+     */
+    public function create(): View
+    {
+        $companies = \App\Models\System\Company::select('id', 'name', 'code')->get();
+        return view('admin.basic-settings.payment-configs.create', compact('companies'));
+    }
+
+    /**
+     * 儲存金流配置
+     */
+    public function store(Request $request): RedirectResponse
+    {
+        $request->validate([
+            'name' => 'required|string|max:255',
+            'company_id' => 'required|exists:companies,id',
+            'settings' => 'required|array',
+        ]);
+
+        PaymentConfig::create([
+            'name' => $request->name,
+            'company_id' => $request->company_id,
+            'settings' => $request->settings,
+            'creator_id' => auth()->id(),
+            'updater_id' => auth()->id(),
+        ]);
+
+        return redirect()->route('admin.basic-settings.payment-configs.index')
+            ->with('success', __('Payment Configuration created successfully.'));
+    }
+
+    /**
+     * 顯示編輯頁面
+     */
+    public function edit(PaymentConfig $paymentConfig): View
+    {
+        $companies = \App\Models\System\Company::select('id', 'name')->get();
+        return view('admin.basic-settings.payment-configs.edit', compact('paymentConfig', 'companies'));
+    }
+
+    /**
+     * 更新金流配置
+     */
+    public function update(Request $request, PaymentConfig $paymentConfig): RedirectResponse
+    {
+        $request->validate([
+            'name' => 'required|string|max:255',
+            'settings' => 'required|array',
+        ]);
+
+        $paymentConfig->update([
+            'name' => $request->name,
+            'settings' => $request->settings,
+            'updater_id' => auth()->id(),
+        ]);
+
+        return redirect()->route('admin.basic-settings.payment-configs.index')
+            ->with('success', __('Payment Configuration updated successfully.'));
+    }
+
+    /**
+     * 刪除金流配置
+     */
+    public function destroy(PaymentConfig $paymentConfig): RedirectResponse
+    {
+        $paymentConfig->delete();
+        return redirect()->route('admin.basic-settings.payment-configs.index')
+            ->with('success', __('Payment Configuration deleted successfully.'));
+    }
+}

app/Http/Controllers/Admin/CompanyController.php

@@ -0,0 +1,243 @@
+<?php
+
+namespace App\Http\Controllers\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\System\Company;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+
+class CompanyController extends Controller
+{
+    /**
+     * Display a listing of the resource.
+     */
+    public function index(Request $request)
+    {
+        $query = Company::query()->withCount(['users', 'machines'])
+            ->with(['contracts.creator:id,name']);
+
+        // 搜尋
+        if ($search = $request->input('search')) {
+            $query->where(function($q) use ($search) {
+                $q->where('name', 'like', "%{$search}%")
+                  ->orWhere('code', 'like', "%{$search}%");
+            });
+        }
+
+        // 狀態篩選
+        if ($request->filled('status')) {
+            $query->where('status', $request->status);
+        }
+
+        $per_page = $request->input('per_page', 10);
+        $companies = $query->latest()->paginate($per_page)->withQueryString();
+
+        // 取得可供選擇的客戶角色範本 (系統層級的角色，排除 super-admin)
+        $template_roles = \App\Models\System\Role::whereNull('company_id')
+            ->where('name', '!=', 'super-admin')
+            ->get();
+
+        return view('admin.companies.index', compact('companies', 'template_roles'));
+    }
+
+    /**
+     * Store a newly created resource in storage.
+     */
+    public function store(Request $request)
+    {
+        $validated = $request->validate([
+            'name' => 'required|string|max:255',
+            'code' => 'required|string|max:50|unique:companies,code',
+            'original_type' => 'required|string|in:buyout,lease',
+            'tax_id' => 'nullable|string|max:50',
+            'contact_name' => 'nullable|string|max:255',
+            'contact_phone' => 'nullable|string|max:50',
+            'contact_email' => 'nullable|email|max:255',
+            'start_date' => 'required|date',
+            'end_date' => 'nullable|date',
+            'warranty_start_date' => 'nullable|date',
+            'warranty_end_date' => 'nullable|date',
+            'software_start_date' => 'nullable|date',
+            'software_end_date' => 'nullable|date',
+            'status' => 'required|boolean',
+            'note' => 'nullable|string',
+            'settings' => 'nullable|array',
+            // 帳號相關欄位 (可選)
+            'admin_username' => 'nullable|string|max:255|unique:users,username',
+            'admin_password' => 'nullable|string|min:8',
+            'admin_name' => 'nullable|string|max:255',
+            'admin_role' => 'nullable|string|exists:roles,name',
+        ]);
+
+        // 確保 settings 中的值為布林值
+        if (isset($validated['settings'])) {
+            $validated['settings']['enable_material_code'] = filter_var($validated['settings']['enable_material_code'] ?? false, FILTER_VALIDATE_BOOLEAN);
+            $validated['settings']['enable_points'] = filter_var($validated['settings']['enable_points'] ?? false, FILTER_VALIDATE_BOOLEAN);
+        }
+
+        DB::transaction(function () use ($validated) {
+            $company = Company::create([
+                'name' => $validated['name'],
+                'code' => $validated['code'],
+                'original_type' => $validated['original_type'],
+                'current_type' => $validated['original_type'], // 新增時同步
+                'tax_id' => $validated['tax_id'] ?? null,
+                'contact_name' => $validated['contact_name'] ?? null,
+                'contact_phone' => $validated['contact_phone'] ?? null,
+                'contact_email' => $validated['contact_email'] ?? null,
+                'start_date' => $validated['start_date'] ?? null,
+                'end_date' => $validated['end_date'] ?? null,
+                'warranty_start_date' => $validated['warranty_start_date'] ?? null,
+                'warranty_end_date' => $validated['warranty_end_date'] ?? null,
+                'software_start_date' => $validated['software_start_date'] ?? null,
+                'software_end_date' => $validated['software_end_date'] ?? null,
+                'status' => $validated['status'],
+                'note' => $validated['note'] ?? null,
+                'settings' => $validated['settings'] ?? [],
+            ]);
+
+            // 記錄合約歷程
+            $company->contracts()->create([
+                'type' => $company->original_type,
+                'start_date' => $company->start_date,
+                'end_date' => $company->end_date,
+                'warranty_start_date' => $company->warranty_start_date,
+                'warranty_end_date' => $company->warranty_end_date,
+                'software_start_date' => $company->software_start_date,
+                'software_end_date' => $company->software_end_date,
+                'note' => __('Initial contract registration'),
+                'creator_id' => auth()->id(),
+            ]);
+
+            // 如果有填寫帳號資訊，則建立管理員帳號
+            if (!empty($validated['admin_username']) && !empty($validated['admin_password'])) {
+                $user = \App\Models\System\User::create([
+                    'company_id' => $company->id,
+                    'username' => $validated['admin_username'],
+                    'password' => \Illuminate\Support\Facades\Hash::make($validated['admin_password']),
+                    'name' => $validated['admin_name'] ?: ($validated['contact_name'] ?: $validated['name']),
+                    'status' => 1,
+                ]);
+
+                // 角色初始化與克隆邏輯 (優先使用選擇的角色，否則使用預設)
+                $selected_role_name = $validated['admin_role'] ?? '客戶管理員角色模板';
+                $role_to_assign = null;
+
+                $template_role = \App\Models\System\Role::where('name', $selected_role_name)
+                    ->whereNull('company_id')
+                    ->where('name', '!=', 'super-admin')
+                    ->first();
+
+                if ($template_role) {
+                    // 克隆範本為該公司的「管理員」
+                    $role_to_assign = \App\Models\System\Role::query()->create([
+                        'name' => '管理員',
+                        'guard_name' => 'web',
+                        'company_id' => $company->id,
+                        'is_system' => false,
+                    ]);
+                    $role_to_assign->syncPermissions($template_role->getPermissionNames());
+                } else {
+                    // 如果找不到選定的角色範本，退而求其次嘗試指派現有角色 (通常不應發生)
+                    $role_to_assign = $selected_role_name;
+                }
+
+                $user->assignRole($role_to_assign);
+            }
+        });
+
+        return redirect()->back()->with('success', __('Customer created successfully.'));
+    }
+
+    /**
+     * Update the specified resource in storage.
+     */
+    public function update(Request $request, Company $company)
+    {
+        $validated = $request->validate([
+            'name' => 'required|string|max:255',
+            'code' => 'required|string|max:50|unique:companies,code,' . $company->id,
+            'current_type' => 'required|string|in:buyout,lease',
+            'tax_id' => 'nullable|string|max:50',
+            'contact_name' => 'nullable|string|max:255',
+            'contact_phone' => 'nullable|string|max:50',
+            'contact_email' => 'nullable|email|max:255',
+            'start_date' => 'required|date',
+            'end_date' => 'nullable|date',
+            'warranty_start_date' => 'nullable|date',
+            'warranty_end_date' => 'nullable|date',
+            'software_start_date' => 'nullable|date',
+            'software_end_date' => 'nullable|date',
+            'status' => 'required|boolean',
+            'note' => 'nullable|string',
+            'settings' => 'nullable|array',
+        ]);
+
+        // 確保 settings 中的值為布林值，避免 JSON 存儲為字串導致前端判斷錯誤
+        if (isset($validated['settings'])) {
+            $validated['settings']['enable_material_code'] = filter_var($validated['settings']['enable_material_code'] ?? false, FILTER_VALIDATE_BOOLEAN);
+            $validated['settings']['enable_points'] = filter_var($validated['settings']['enable_points'] ?? false, FILTER_VALIDATE_BOOLEAN);
+        }
+
+        DB::transaction(function () use ($validated, $company) {
+            $company->update($validated);
+
+            // 記錄合約歷程
+            $company->contracts()->create([
+                'type' => $company->current_type,
+                'start_date' => $company->start_date,
+                'end_date' => $company->end_date,
+                'warranty_start_date' => $company->warranty_start_date,
+                'warranty_end_date' => $company->warranty_end_date,
+                'software_start_date' => $company->software_start_date,
+                'software_end_date' => $company->software_end_date,
+                'note' => $validated['note'] ?? __('Contract information updated'),
+                'creator_id' => auth()->id(),
+            ]);
+        });
+        
+        // 分支邏輯：若停用客戶，連帶停用其所有帳號
+        if ($validated['status'] == 0) {
+            $company->users()->update(['status' => 0]);
+        }
+
+        return redirect()->back()->with('success', __('Customer updated successfully.'));
+    }
+
+    /**
+     * 切換客戶狀態
+     */
+    public function toggleStatus(Company $company)
+    {
+        $newStatus = $company->status == 1 ? 0 : 1;
+        $company->update(['status' => $newStatus]);
+
+        // 若切換為停用，同步更新所有旗下帳號
+        if ($newStatus == 0) {
+            $company->users()->update(['status' => 0]);
+            return redirect()->back()->with('success', __('Customer and associated accounts disabled successfully.'));
+        }
+
+        return redirect()->back()->with('success', __('Customer enabled successfully.'));
+    }
+
+    /**
+     * Remove the specified resource from storage.
+     */
+    public function destroy(Company $company)
+    {
+        if ($company->users()->count() > 0) {
+            return redirect()->back()->with('error', __('Cannot delete company with active accounts.'));
+        }
+
+        // 為了解決軟刪除導致的唯一索引佔用問題，刪除前先重新命名唯一欄位
+        $timestamp = now()->getTimestamp();
+        $company->code = $company->code . '.deleted.' . $timestamp;
+        $company->save();
+
+        $company->delete();
+
+        return redirect()->back()->with('success', __('Customer deleted successfully.'));
+    }
+}

app/Http/Controllers/Admin/DashboardController.php

@@ -8,26 +8,38 @@ use Illuminate\Http\Request;
 
 class DashboardController extends Controller
 {
-    public function index()
+    public function index(Request $request)
     {
+        // 每頁顯示筆數限制 (預設為 10)
+        $perPage = (int) request()->input('per_page', 10);
+        if ($perPage <= 0)
+            $perPage = 10;
+
         // 從資料庫獲取真實統計數據
         $totalRevenue = \App\Models\Member\MemberWallet::sum('balance');
-        $activeMachines = Machine::where('status', 'online')->count();
-        $alertsPending = Machine::where('status', 'error')->count();
+        $activeMachines = Machine::online()->count();
+        $offlineMachines = Machine::offline()->count();
+        $alertsPending = Machine::hasError()->count();
         $memberCount = \App\Models\Member\Member::count();
 
-        // 獲取最新動態 (最近 3 筆機台日誌)
-        $latestActivities = \App\Models\Machine\MachineLog::with('machine')
-            ->latest()
-            ->limit(3)
-            ->get();
+        // 獲取機台列表 (分頁)
+        $machines = Machine::when($request->search, function ($query, $search) {
+            $query->where(function ($q) use ($search) {
+                $q->where('name', 'like', "%{$search}%")
+                    ->orWhere('serial_no', 'like', "%{$search}%");
+            });
+        })
+            ->orderByDesc('last_heartbeat_at')
+            ->paginate($perPage)
+            ->withQueryString();
 
         return view('admin.dashboard', compact(
             'totalRevenue',
             'activeMachines',
+            'offlineMachines',
             'alertsPending',
             'memberCount',
-            'latestActivities'
+            'machines'
         ));
     }
 }

app/Http/Controllers/Admin/DataConfigController.php

@@ -25,23 +25,6 @@ class DataConfigController extends Controller
         ]);
     }
 
-    // 管理者可賣商品
-    public function adminProducts()
-    {
-        return view('admin.placeholder', [
-            'title' => '管理者可賣商品',
-            'description' => '管理者商品銷售權限',
-        ]);
-    }
-
-    // 帳號管理
-    public function accounts()
-    {
-        return view('admin.placeholder', [
-            'title' => '帳號管理',
-            'description' => '主帳號管理',
-        ]);
-    }
 
     // 子帳號管理
     public function subAccounts()

app/Http/Controllers/Admin/Machine/MachinePermissionController.php

@@ -0,0 +1,121 @@
+<?php
+
+namespace App\Http\Controllers\Admin\Machine;
+
+use App\Http\Controllers\Admin\AdminController;
+use App\Models\System\Company;
+use App\Models\Machine\Machine;
+use App\Models\System\User;
+use Illuminate\Http\Request;
+use Illuminate\View\View;
+use Illuminate\Http\JsonResponse;
+use Illuminate\Support\Facades\Log;
+
+class MachinePermissionController extends AdminController
+{
+    /**
+     * 顯示機台權限管理列表
+     */
+    public function index(Request $request): View
+    {
+        $per_page = $request->input('per_page', 10);
+        $search = $request->input('search');
+        $company_id = $request->input('company_id');
+
+        $currentUser = auth()->user();
+
+        // 僅列出租戶中具有「is_admin」標記的角色帳號以供分配
+        $userQuery = User::query()
+            ->with(['machines' => function($query) {
+                $query->withoutGlobalScope('machine_access')
+                      ->select('machines.id', 'machines.name', 'machines.serial_no');
+            }])
+            ->whereNotNull('company_id');
+
+        // 非系統管理員僅能看到同公司的帳號 (因 User Model 排除 TenantScoped 全域過濾，需手動注入)
+        if (!$currentUser->isSystemAdmin()) {
+            $userQuery->where('company_id', $currentUser->company_id);
+        } elseif ($company_id) {
+            // 系統管理員的篩選邏輯
+            $userQuery->where('company_id', $company_id);
+        }
+
+        if ($search) {
+            $userQuery->where(function ($q) use ($search) {
+                $q->where('name', 'like', "%{$search}%")
+                  ->orWhere('username', 'like', "%{$search}%")
+                  ->orWhere('email', 'like', "%{$search}%");
+            });
+        }
+
+        $users_list = $userQuery->latest()->paginate($per_page)->withQueryString();
+        $companies = $currentUser->isSystemAdmin() ? Company::all() : collect();
+
+        return view('admin.machines.permissions', compact('users_list', 'companies'));
+    }
+
+    /**
+     * AJAX: 取得特定帳號的機台分配狀態
+     */
+    public function getAccountMachines(User $user): JsonResponse
+    {
+        $currentUser = auth()->user();
+
+        // 安全檢查：只能操作自己公司的帳號（除非是系統管理員）
+        if (!$currentUser->isSystemAdmin() && $user->company_id !== $currentUser->company_id) {
+            return response()->json(['error' => 'Unauthorized'], 403);
+        }
+
+        // 取得該使用者所屬公司之所有機台 (忽略個別帳號的 machine_access 限制，以公司為單位顯示)
+        $machines = Machine::withoutGlobalScope('machine_access')
+            ->where('company_id', $user->company_id)
+            ->get(['id', 'name', 'serial_no']);
+            
+        $assignedIds = $user->machines()->pluck('machines.id')->toArray();
+
+        return response()->json([
+            'user' => $user,
+            'machines' => $machines,
+            'assigned_ids' => $assignedIds
+        ]);
+    }
+
+    /**
+     * AJAX: 儲存特定帳號的機台分配
+     */
+    public function syncAccountMachines(Request $request, User $user): JsonResponse
+    {
+        $currentUser = auth()->user();
+
+        // 安全檢查
+        if (!$currentUser->isSystemAdmin() && $user->company_id !== $currentUser->company_id) {
+            return response()->json(['error' => 'Unauthorized'], 403);
+        }
+
+        $request->validate([
+            'machine_ids' => 'nullable|array',
+            'machine_ids.*' => 'exists:machines,id'
+        ]);
+
+        // 加固驗證：確保所有機台 ID 都屬於該使用者的公司 (使用 withoutGlobalScope 避免管理員自身權限影響驗證邏輯)
+        if ($request->has('machine_ids')) {
+            $machineIds = array_unique($request->machine_ids);
+            $validCount = Machine::withoutGlobalScope('machine_access')
+                ->where('company_id', $user->company_id)
+                ->whereIn('id', $machineIds)
+                ->count();
+            
+            if ($validCount !== count($machineIds)) {
+                return response()->json(['error' => 'Invalid machine IDs provided.'], 422);
+            }
+        }
+
+        $user->machines()->sync($request->machine_ids ?? []);
+
+        return response()->json([
+            'success' => true, 
+            'message' => __('Permissions updated successfully'),
+            'assigned_machines' => $user->machines()->select('machines.id', 'machines.name', 'machines.serial_no')->get()
+        ]);
+    }
+}

app/Http/Controllers/Admin/MachineController.php

@@ -3,80 +3,186 @@
 namespace App\Http\Controllers\Admin;
 
 use App\Models\Machine\Machine;
+use App\Services\Machine\MachineService;
 use Illuminate\Http\Request;
 use Illuminate\View\View;
 
 class MachineController extends AdminController
 {
-    /**
-     * 顯示所有機台列表
-     */
+    public function __construct(protected MachineService $machineService)
+    {
+    }
+
     public function index(Request $request): View
     {
-        $machines = Machine::query()
-            ->when($request->status, function ($query, $status) {
-                return $query->where('status', $status);
-            })
-            ->latest()
-            ->paginate(10);
+        $per_page = $request->input('per_page', 10);
+
+        $query = Machine::query();
+
+        // 搜尋：名稱或序號
+        if ($search = $request->input('search')) {
+            $query->where(function ($q) use ($search) {
+                $q->where('name', 'like', "%{$search}%")
+                    ->orWhere('serial_no', 'like', "%{$search}%");
+            });
+        }
+
+        // 預加載統計資料
+        $machines = $query->orderBy("last_heartbeat_at", "desc")
+            ->orderBy("id", "desc")
+            ->paginate($per_page)
+            ->withQueryString();
 
         return view('admin.machines.index', compact('machines'));
     }
 
+    /**
+     * 更新機台基本資訊 (目前僅名稱)
+     */
+    public function update(Request $request, Machine $machine)
+    {
+        $validated = $request->validate([
+            'name' => 'required|string|max:255',
+        ]);
+
+        $machine->update($validated);
+
+        return redirect()->route('admin.machines.index')
+            ->with('success', __('Machine updated successfully.'));
+    }
+
     /**
      * 顯示特定機台的日誌與詳細資訊
      */
     public function show(int $id): View
     {
-        $machine = Machine::with(['logs' => function ($query) {
+        $machine = Machine::with([
+            'logs' => function ($query) {
                 $query->latest()->limit(50);
-        }])->findOrFail($id);
+            }
+        ])->findOrFail($id);
 
         return view('admin.machines.show', compact('machine'));
     }
 
+
     /**
-     * 顯示所有機台日誌列表
+     * AJAX: 取得機台抽屜面板所需的歷程日誌
      */
-    public function logs(Request $request): View
+    public function logsAjax(Request $request, Machine $machine)
     {
-        $logs = \App\Models\Machine\MachineLog::with('machine')
+        $per_page = $request->input('per_page', 20);
+
+        $startDate = $request->get('start_date');
+        $endDate = $request->get('end_date');
+
+        $logs = $machine->logs()
             ->when($request->level, function ($query, $level) {
                 return $query->where('level', $level);
             })
-            ->when($request->machine_id, function ($query, $machineId) {
-                return $query->where('machine_id', $machineId);
+            ->when($startDate, function ($query, $start) {
+                return $query->where('created_at', '>=', str_replace('T', ' ', $start));
+            })
+            ->when($endDate, function ($query, $end) {
+                return $query->where('created_at', '<=', str_replace('T', ' ', $end));
+            })
+            ->when($request->type, function ($query, $type) {
+                return $query->where('type', $type);
             })
             ->latest()
-            ->paginate(20);
+            ->paginate($per_page);
 
-        $machines = Machine::select('id', 'name')->get();
-
-        return view('admin.machines.logs', compact('logs', 'machines'));
+        return response()->json([
+            'success' => true,
+            'data' => $logs->items(),
+            'pagination' => [
+                'total' => $logs->total(),
+                'current_page' => $logs->currentPage(),
+                'last_page' => $logs->lastPage(),
+            ]
+        ]);
     }
 
-    /**
-     * 機台權限設定 (開發中)
-     */
-    public function permissions(Request $request): View
-    {
-        return view('admin.machines.index', ['machines' => Machine::paginate(1)]); // Placeholder
-    }
 
     /**
-     * 機台使用率統計 (開發中)
+     * 機台使用率統計
      */
     public function utilization(Request $request): View
     {
-        return view('admin.machines.index', ['machines' => Machine::paginate(1)]); // Placeholder
+        // 取得當前使用者有權限的所有機台 (已透過 Global Scope 過濾)
+        $machines = Machine::all();
+
+        $date = $request->get('date', now()->toDateString());
+        $service = app(\App\Services\Machine\MachineService::class);
+        $fleetStats = $service->getFleetStats($date);
+
+        return view('admin.machines.utilization', [
+            'machines' => $machines,
+            'fleetStats' => $fleetStats,
+            'compactMachines' => $machines->map(fn($m) => [
+                'id' => $m->id,
+                'name' => $m->name,
+                'serial_no' => $m->serial_no,
+                'status' => $m->status
+            ])->values()
+        ]);
     }
 
     /**
-     * 機台到期管理 (開發中)
+     * AJAX: 取得機台所有貨道資訊 (供效期管理視覺化圖表使用)
      */
-    public function expiry(Request $request): View
+    public function slotsAjax(Machine $machine)
     {
-        return view('admin.machines.index', ['machines' => Machine::paginate(1)]); // Placeholder
+        $slots = $machine->slots()->with('product:id,name,image_url')->orderByRaw('CAST(slot_no AS UNSIGNED) ASC')->get();
+
+        return response()->json([
+            'success' => true,
+            'machine' => $machine->only(['id', 'name', 'serial_no']),
+            'slots' => $slots
+        ]);
+    }
+
+    /**
+     * AJAX: 更新貨道資訊 (庫存、效期、批號)
+     */
+    public function updateSlotExpiry(Request $request, Machine $machine)
+    {
+        $validated = $request->validate([
+            'slot_no' => 'required|integer',
+            'stock' => 'nullable|integer|min:0',
+            'expiry_date' => 'nullable|date',
+            'batch_no' => 'nullable|string|max:50',
+        ]);
+
+        $this->machineService->updateSlot($machine, $validated, auth()->id());
+
+        session()->flash('success', __('Slot updated successfully.'));
+
+        return response()->json([
+            'success' => true,
+            'message' => __('Slot updated successfully.')
+        ]);
+    }
+
+    /**
+     * 取得機台統計數據 (AJAX)
+     */
+    public function utilizationData(Request $request, $id = null)
+    {
+        $date = $request->get('date', now()->toDateString());
+        $service = app(\App\Services\Machine\MachineService::class);
+
+        if ($id) {
+            $machine = Machine::findOrFail($id);
+            $stats = $service->getUtilizationStats($machine, $date);
+        } else {
+            $stats = $service->getFleetStats($date);
+        }
+
+        return response()->json([
+            'success' => true,
+            'data' => $stats
+        ]);
     }
 
     /**

app/Http/Controllers/Admin/MaintenanceController.php

@@ -0,0 +1,108 @@
+<?php
+
+namespace App\Http\Controllers\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\Machine\Machine;
+use App\Models\Machine\MaintenanceRecord;
+use App\Traits\ImageHandler;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Auth;
+use Illuminate\Support\Facades\Storage;
+
+class MaintenanceController extends Controller
+{
+    use ImageHandler;
+
+    /**
+     * 維修紀錄列表
+     */
+    public function index(Request $request)
+    {
+        $this->authorize('viewAny', MaintenanceRecord::class);
+
+        $query = MaintenanceRecord::with(['machine', 'user', 'company'])
+            ->whereHas('machine') // 確保僅顯示該帳號「看得見」的機台紀錄，避開因權限隔離導致的 null 報錯
+            ->latest('maintenance_at');
+
+        // 搜尋邏輯
+        if ($request->filled('search')) {
+            $search = $request->search;
+            $query->whereHas('machine', function($q) use ($search) {
+                $q->where('serial_no', 'like', "%{$search}%")
+                  ->orWhere('name', 'like', "%{$search}%");
+            });
+        }
+
+        if ($request->filled('category')) {
+            $query->where('category', $request->category);
+        }
+
+        $records = $query->paginate(15)->withQueryString();
+
+        return view('admin.maintenance.index', compact('records'));
+    }
+
+    /**
+     * 顯示新增維修單頁面
+     */
+    public function create(Request $request, $serial_no = null)
+    {
+        $this->authorize('create', MaintenanceRecord::class);
+
+        $machine = null;
+        if ($serial_no) {
+            $machine = Machine::where('serial_no', $serial_no)->firstOrFail();
+        }
+
+        // 供手動新增時選擇的機台清單 (僅限有權限存取的)
+        $machines = Machine::all();
+
+        return view('admin.maintenance.create', compact('machine', 'machines'));
+    }
+
+    /**
+     * 儲存維修單
+     */
+    public function store(Request $request)
+    {
+        $this->authorize('create', MaintenanceRecord::class);
+
+        $validated = $request->validate([
+            'machine_id' => 'required|exists:machines,id',
+            'category' => 'required|in:Repair,Installation,Removal,Maintenance',
+            'content' => 'nullable|string',
+            'maintenance_at' => 'required|date',
+            'photos.*' => 'nullable|image|max:5120', // 每張上限 5MB
+            'is_confirmed' => 'required|accepted',
+        ]);
+
+        $machine = Machine::findOrFail($validated['machine_id']);
+        
+        $photoPaths = [];
+        if ($request->hasFile('photos')) {
+            foreach ($request->file('photos') as $photo) {
+                if (!$photo) continue;
+                if (count($photoPaths) >= 3) break;
+                
+                // 轉為 WebP 格式與保存
+                $path = $this->storeAsWebp($photo, "maintenance/{$machine->id}");
+                $photoPaths[] = $path;
+            }
+        }
+
+        $record = MaintenanceRecord::create([
+            'company_id' => $machine->company_id, // 從機台帶入歸屬客戶
+            'machine_id' => $machine->id,
+            'user_id' => Auth::id(),
+            'category' => $validated['category'],
+            'content' => $validated['content'],
+            'photos' => $photoPaths,
+            'maintenance_at' => $validated['maintenance_at'],
+            'is_confirmed' => true, // 既然通過驗證(accepted)，則存為 true
+        ]);
+
+        return redirect()->route('admin.maintenance.index')
+            ->with('success', __('Maintenance record created successfully'));
+    }
+}

app/Http/Controllers/Admin/PermissionController.php

@@ -7,111 +7,589 @@ use Illuminate\Http\Request;
 
 class PermissionController extends Controller
 {
-    // APP功能管理
-    public function appFeatures()
-    {
-        return view('admin.placeholder', [
-            'title' => 'APP功能管理',
-            'description' => 'APP功能權限設定',
-        ]);
-    }
-
-    // 資料設定權限
-    public function dataConfig()
-    {
-        return view('admin.placeholder', [
-            'title' => '資料設定權限',
-            'description' => '資料設定功能權限',
-        ]);
-    }
-
-    // 銷售管理權限
-    public function sales()
-    {
-        return view('admin.placeholder', [
-            'title' => '銷售管理權限',
-            'description' => '銷售管理功能權限',
-        ]);
-    }
-
-    // 機台管理權限
-    public function machines()
-    {
-        return view('admin.placeholder', [
-            'title' => '機台管理權限',
-            'description' => '機台管理功能權限',
-        ]);
-    }
-
-    // 倉庫管理權限
-    public function warehouses()
-    {
-        return view('admin.placeholder', [
-            'title' => '倉庫管理權限',
-            'description' => '倉庫管理功能權限',
-        ]);
-    }
-
-    // 分析管理權限
-    public function analysis()
-    {
-        return view('admin.placeholder', [
-            'title' => '分析管理權限',
-            'description' => '分析管理功能權限',
-        ]);
-    }
-
-    // 稽核管理權限
-    public function audit()
-    {
-        return view('admin.placeholder', [
-            'title' => '稽核管理權限',
-            'description' => '稽核管理功能權限',
-        ]);
-    }
-
-    // 遠端管理權限
-    public function remote()
-    {
-        return view('admin.placeholder', [
-            'title' => '遠端管理權限',
-            'description' => '遠端管理功能權限',
-        ]);
-    }
-
-    // Line管理權限
-    public function line()
-    {
-        return view('admin.placeholder', [
-            'title' => 'Line管理權限',
-            'description' => 'Line管理功能權限',
-        ]);
-    }
-
     // 權限角色設定
     public function roles()
     {
-        return view('admin.placeholder', [
-            'title' => '權限角色設定',
-            'description' => '角色權限組合設定',
-        ]);
+        $per_page = request()->input('per_page', 10);
+        $user = auth()->user();
+        $query = \App\Models\System\Role::query()->with(['permissions', 'users', 'company']);
+
+        // 租戶隔離：租戶只能看到自己公司的角色
+        if (!$user->isSystemAdmin()) {
+            $query->where('company_id', $user->company_id);
         }
 
-    // 其他功能管理
-    public function others()
-    {
-        return view('admin.placeholder', [
-            'title' => '其他功能管理',
-            'description' => '其他特殊功能權限',
-        ]);
+        // 搜尋：角色名稱
+        if ($search = request()->input('search')) {
+            $query->where('name', 'like', "%{$search}%");
         }
 
-    // AI智能預測
-    public function aiPrediction()
+        // 篩選：公司名稱 (僅限系統管理員)
+        if ($user->isSystemAdmin() && request()->filled('company_id')) {
+            if (request()->company_id === 'system') {
+                $query->whereNull('company_id');
+            } else {
+                $query->where('company_id', request()->company_id);
+            }
+        }
+
+        $roles = $query->latest()->paginate($per_page)->withQueryString();
+        $companies = $user->isSystemAdmin() ? \App\Models\System\Company::all() : collect();
+        
+        // 權限分組邏輯中的標題與過濾
+        $isSubAccountRoles = request()->routeIs('*.sub-account-roles');
+        $title = $isSubAccountRoles ? __('Sub Account Roles') : __('Role Settings');
+        $permissionQuery = \Spatie\Permission\Models\Permission::query();
+        if (!$user->isSystemAdmin()) {
+            $permissionQuery->whereIn('name', $user->getAllPermissions()->pluck('name'));
+        }
+
+        // 權限分組邏輯
+        $all_permissions = $permissionQuery->get()
+            ->reject(fn($p) => $p->name === 'menu.data-config.sub-account-roles')
+            ->groupBy(function($perm) {
+                if (str_starts_with($perm->name, 'menu.')) {
+                    return 'menu';
+                }
+                return 'other';
+            });
+
+        $currentUserRoleIds = $user->roles->pluck('id')->toArray();
+        return view('admin.permission.roles', compact('roles', 'all_permissions', 'title', 'currentUserRoleIds', 'companies'));
+    }
+
+    /**
+     * Show the form for creating a new role.
+     */
+    public function createRole()
     {
-        return view('admin.placeholder', [
-            'title' => 'AI智能預測',
-            'description' => 'AI功能權限設定',
+        $role = new \App\Models\System\Role();
+        $user = auth()->user();
+
+        // 權限遞迴約束
+        $permissionQuery = \Spatie\Permission\Models\Permission::query();
+        if (!$user->isSystemAdmin()) {
+            $permissionQuery->whereIn('name', $user->getAllPermissions()->pluck('name'));
+        }
+
+        $all_permissions = $permissionQuery->get()->groupBy(fn($p) => str_starts_with($p->name, 'menu.') ? 'menu' : 'other');
+
+        $title = request()->routeIs('*.sub-account-roles.create') ? __('Create Sub Account Role') : __('Create New Role');
+        $back_url = request()->routeIs('*.sub-account-roles.create') 
+            ? route('admin.data-config.sub-accounts', ['tab' => 'roles']) 
+            : route('admin.permission.roles');
+
+        return view('admin.permission.roles-edit', compact('role', 'all_permissions', 'title', 'back_url'));
+    }
+
+    /**
+     * Show the form for editing the specified role.
+     */
+    public function editRole($id)
+    {
+        $role = \App\Models\System\Role::findOrFail($id);
+        $user = auth()->user();
+
+        // 權限遞迴約束：租戶管理員只能看到並指派自己擁有的權限
+        $permissionQuery = \Spatie\Permission\Models\Permission::query();
+        if (!$user->isSystemAdmin()) {
+            $permissionQuery->whereIn('name', $user->getAllPermissions()->pluck('name'));
+        }
+
+        // 權限分組邏輯
+        $all_permissions = $permissionQuery->get()
+            ->reject(fn($p) => $p->name === 'menu.data-config.sub-account-roles')
+            ->groupBy(function($perm) {
+                if (str_starts_with($perm->name, 'menu.')) {
+                    return 'menu';
+                }
+                return 'other';
+            });
+
+        // 根據路由決定標題
+        $title = request()->routeIs('*.sub-account-roles.edit') ? __('Edit Sub Account Role') : __('Edit Role Permissions');
+        
+        // 麵包屑/返回路徑
+        $back_url = request()->routeIs('*.sub-account-roles.edit') 
+            ? route('admin.data-config.sub-accounts', ['tab' => 'roles']) 
+            : route('admin.permission.roles');
+
+        return view('admin.permission.roles-edit', compact('role', 'all_permissions', 'title', 'back_url'));
+    }
+
+    /**
+     * Store a newly created role in storage.
+     */
+    public function storeRole(Request $request)
+    {
+        $is_system = auth()->user()->isSystemAdmin() && $request->boolean('is_system');
+        $company_id = $is_system ? null : auth()->user()->company_id;
+
+        $validated = $request->validate([
+            'name' => [
+                'required', 'string', 'max:255',
+                \Illuminate\Validation\Rule::unique('roles', 'name')->where(function ($query) use ($company_id) {
+                    return $query->where('company_id', $company_id);
+                })
+            ],
+            'permissions' => 'nullable|array',
+            'permissions.*' => 'string|exists:permissions,name',
         ]);
+
+        $role = \App\Models\System\Role::query()->create([
+            'name' => $validated['name'],
+            'guard_name' => 'web',
+            'company_id' => $is_system ? null : auth()->user()->company_id,
+            'is_system' => $is_system,
+        ]);
+
+        if (!empty($validated['permissions'])) {
+            $perms = $validated['permissions'];
+            
+            // 權限遞迴約束驗證
+            if (!auth()->user()->isSystemAdmin()) {
+                $currentUserPerms = auth()->user()->getAllPermissions()->pluck('name');
+                if (collect($perms)->diff($currentUserPerms)->isNotEmpty()) {
+                    return redirect()->back()->with('error', __('You cannot assign permissions you do not possess.'));
+                }
+            }
+
+            // 如果不是系統角色，排除主選單的系統權限
+            if (!$is_system) {
+                $perms = array_diff($perms, ['menu.basic-settings', 'menu.permissions']);
+            }
+            $role->syncPermissions($perms);
+        }
+
+        $target_route = request()->routeIs('*.sub-account-roles.*') ? route('admin.data-config.sub-accounts', ['tab' => 'roles']) : route('admin.permission.roles');
+        return redirect()->to($target_route)->with('success', __('Role created successfully.'));
+    }
+
+    /**
+     * Update the specified role in storage.
+     */
+    public function updateRole(Request $request, $id)
+    {
+        $role = \App\Models\System\Role::findOrFail($id);
+
+        $is_system = $role->is_system;
+        $company_id = $role->company_id;
+
+        $validated = $request->validate([
+            'name' => [
+                'required', 'string', 'max:255',
+                \Illuminate\Validation\Rule::unique('roles', 'name')
+                    ->ignore($id)
+                    ->where(function ($query) use ($company_id) {
+                        return $query->where('company_id', $company_id);
+                    })
+            ],
+            'permissions' => 'nullable|array',
+            'permissions.*' => 'string|exists:permissions,name',
+        ]);
+
+        if ($role->name === 'super-admin') {
+             return redirect()->back()->with('error', __('The Super Admin role is immutable.'));
+        }
+
+        if (!auth()->user()->isSystemAdmin() && $role->is_system) {
+             return redirect()->back()->with('error', __('System roles cannot be modified by tenant administrators.'));
+        }
+
+        $is_system = auth()->user()->isSystemAdmin() ? $request->boolean('is_system') : $role->is_system;
+
+        $updateData = [
+            'name' => $validated['name'],
+            'is_system' => $is_system,
+            'company_id' => $is_system ? null : $role->company_id,
+        ];
+
+        $role->update($updateData);
+
+        $perms = $validated['permissions'] ?? [];
+
+        // 權限遞迴約束驗證
+        if (!auth()->user()->isSystemAdmin()) {
+            $currentUserPerms = auth()->user()->getAllPermissions()->pluck('name');
+            if (collect($perms)->diff($currentUserPerms)->isNotEmpty()) {
+                return redirect()->back()->with('error', __('You cannot assign permissions you do not possess.'));
+            }
+        }
+
+        // 如果不是系統角色，排除主選單的系統權限
+        if (!$is_system) {
+            $perms = array_diff($perms, ['menu.basic-settings', 'menu.permissions']);
+        }
+        $role->syncPermissions($perms);
+
+        $target_route = request()->routeIs('*.sub-account-roles.*') ? route('admin.data-config.sub-accounts', ['tab' => 'roles']) : route('admin.permission.roles');
+        return redirect()->to($target_route)->with('success', __('Role updated successfully.'));
+    }
+
+    /**
+     * Remove the specified role from storage.
+     */
+    public function destroyRole($id)
+    {
+        $role = \App\Models\System\Role::findOrFail($id);
+
+        if ($role->name === 'super-admin') {
+            return redirect()->back()->with('error', __('The Super Admin role cannot be deleted.'));
+        }
+
+        if (!auth()->user()->isSystemAdmin() && $role->is_system) {
+            return redirect()->back()->with('error', __('System roles cannot be deleted by tenant administrators.'));
+        }
+
+        if ($role->users()->count() > 0) {
+            return redirect()->back()->with('error', __('Cannot delete role with active users.'));
+        }
+
+        $role->delete();
+
+        if (request()->routeIs('*.sub-account-roles.*')) {
+            return redirect()->route('admin.data-config.sub-accounts', ['tab' => 'roles'])->with('success', __('Role deleted successfully.'));
+        }
+
+        return redirect()->back()->with('success', __('Role deleted successfully.'));
+    }
+
+    // 帳號管理
+    public function accounts(Request $request)
+    {
+        $user = auth()->user();
+        $isSubAccountRoute = $request->routeIs('admin.data-config.sub-accounts');
+        $tab = $request->input('tab', 'accounts');
+
+        // 初始化變數
+        $users = collect();
+        $roles = collect();
+        $paginated_roles = collect();
+        $all_permissions = collect();
+        $currentUserRoleIds = $user->roles->pluck('id')->toArray();
+        $companies = $user->isSystemAdmin() ? \App\Models\System\Company::all() : collect();
+
+        if ($isSubAccountRoute && $tab === 'roles') {
+            // 處理角色分頁邏輯 (移植自 roles())
+            $per_page = $request->input('per_page', 10);
+            $roles_query = \App\Models\System\Role::query()->with(['permissions', 'users', 'company']);
+
+            if (!$user->isSystemAdmin()) {
+                $roles_query->where('company_id', $user->company_id);
+            }
+
+            if ($search = $request->input('search')) {
+                $roles_query->where('name', 'like', "%{$search}%");
+            }
+
+            if ($user->isSystemAdmin() && $request->filled('company_id')) {
+                if ($request->company_id === 'system') {
+                    $roles_query->where('is_system', true);
+                } else {
+                    $roles_query->where('company_id', $request->company_id);
+                }
+            }
+
+            $paginated_roles = $roles_query->latest()->paginate($per_page)->withQueryString();
+
+            // 權限分組邏輯
+            $permissionQuery = \Spatie\Permission\Models\Permission::query();
+            if (!$user->isSystemAdmin()) {
+                $permissionQuery->whereIn('name', $user->getAllPermissions()->pluck('name'));
+            }
+
+            $all_permissions = $permissionQuery->get()
+                ->reject(fn($p) => $p->name === 'menu.data-config.sub-account-roles')
+                ->groupBy(fn($p) => str_starts_with($p->name, 'menu.') ? 'menu' : 'other');
+        } else {
+            // 處理帳號名單邏輯
+            $query = \App\Models\System\User::query()->with(['company', 'roles', 'machines']);
+
+            if (!$user->isSystemAdmin()) {
+                $query->where('company_id', $user->company_id);
+            }
+
+            if ($search = $request->input('search')) {
+                $query->where(function($q) use ($search) {
+                    $q->where('name', 'like', "%{$search}%")
+                      ->orWhere('username', 'like', "%{$search}%")
+                      ->orWhere('email', 'like', "%{$search}%");
+                });
+            }
+
+            if ($user->isSystemAdmin() && $request->filled('company_id')) {
+                if ($request->company_id === 'system') {
+                    $query->whereNull('company_id');
+                } else {
+                    $query->where('company_id', $request->company_id);
+                }
+            }
+
+            $per_page = $request->input('per_page', 10);
+            $users = $query->latest()->paginate($per_page)->withQueryString();
+
+            $roles_query = \App\Models\System\Role::query();
+            if (!$user->isSystemAdmin()) {
+                $roles_query->forCompany($user->company_id);
+            }
+            $roles = $roles_query->get();
+        }
+
+        $title = $isSubAccountRoute ? __('Sub Account Management') : __('Account Management');
+
+        return view('admin.data-config.accounts', compact(
+            'users', 'companies', 'roles', 'paginated_roles', 'all_permissions', 'title', 'tab', 'currentUserRoleIds'
+        ));
+    }
+
+    /**
+     * Store a newly created account in storage.
+     */
+    public function storeAccount(Request $request)
+    {
+        $validated = $request->validate([
+            'name' => 'required|string|max:255',
+            'username' => 'required|string|max:255|unique:users,username',
+            'email' => 'nullable|email|max:255|unique:users,email',
+            'password' => 'required|string|min:8',
+            'role' => 'required|string',
+            'status' => 'required|boolean',
+            'company_id' => 'nullable|exists:companies,id',
+            'phone' => 'nullable|string|max:20',
+        ]);
+
+        $company_id = auth()->user()->isSystemAdmin() ? ($validated['company_id'] ?? null) : auth()->user()->company_id;
+
+        // 查找角色：優先尋找該公司的角色，若無則尋找全域範本
+        $role = \App\Models\System\Role::where('name', $validated['role'])
+            ->where(function($q) use ($company_id) {
+                $q->where('company_id', $company_id)->orWhereNull('company_id');
+            })
+            ->first();
+
+        if (!$role) {
+            return redirect()->back()->with('error', __('Role not found.'));
+        }
+
+        // 驗證角色與公司的匹配性 (RBAC Safeguard)
+        if ($company_id !== null) {
+            // 如果是租戶帳號，絕對不能指派超級管理員角色 (super-admin)
+            if ($role->name === 'super-admin') {
+                return redirect()->back()->with('error', __('Super-admin role cannot be assigned to tenant accounts.'));
+            }
+            // 如果角色有特定的 company_id，必須匹配
+            if ($role->company_id !== null && $role->company_id != $company_id) {
+                return redirect()->back()->with('error', __('This role belongs to another company and cannot be assigned.'));
+            }
+        } else {
+            // 如果是系統層級帳號，只能選全域系統角色 (is_system = 1)
+            if (!$role->is_system) {
+                return redirect()->back()->with('error', __('Only system roles can be assigned to platform administrative accounts.'));
+            }
+        }
+
+        // 角色初始化與克隆邏輯 (只有 super-admin 在幫空白公司開帳號時觸發)
+        $company_id = auth()->user()->isSystemAdmin() ? ($validated['company_id'] ?? null) : auth()->user()->company_id;
+
+        if ($company_id && $role && $role->company_id === null && $role->name !== 'super-admin') {
+            // 檢查該公司是否已有名為「管理員」的角色
+            $existingRole = \App\Models\System\Role::where('company_id', $company_id)
+                ->where('name', '管理員')
+                ->first();
+
+            if (!$existingRole) {
+                // 克隆範本為該公司的「管理員」
+                $newRole = \App\Models\System\Role::query()->create([
+                    'name' => '管理員',
+                    'guard_name' => 'web',
+                    'company_id' => $company_id,
+                    'is_system' => false,
+                ]);
+                $newRole->syncPermissions($role->getPermissionNames());
+                $role = $newRole;
+            } else {
+                // 如果已存在名為「管理員」的角色，則直接使用它
+                $role = $existingRole;
+            }
+        }
+
+        $user = \App\Models\System\User::create([
+            'name' => $validated['name'],
+            'username' => $validated['username'],
+            'email' => $validated['email'],
+            'password' => \Illuminate\Support\Facades\Hash::make($validated['password']),
+            'status' => $validated['status'],
+            'company_id' => $company_id,
+            'phone' => $validated['phone'] ?? null,
+            'is_admin' => (auth()->user()->isSystemAdmin() && !empty($validated['company_id'])),
+        ]);
+
+        $user->assignRole($role);
+
+        return redirect()->back()->with('success', __('Account created successfully.'));
+    }
+
+    /**
+     * Update the specified account in storage.
+     */
+    public function updateAccount(Request $request, $id)
+    {
+        $user = \App\Models\System\User::findOrFail($id);
+
+        if ($user->hasRole('super-admin') && !auth()->user()->hasRole('super-admin')) {
+            return redirect()->back()->with('error', __('System super admin accounts can only be modified by other super admins.'));
+        }
+
+        $validated = $request->validate([
+            'name' => 'required|string|max:255',
+            'username' => 'required|string|max:255|unique:users,username,' . $id,
+            'email' => 'nullable|email|max:255|unique:users,email,' . $id,
+            'password' => 'nullable|string|min:8',
+            'role' => 'required|string',
+            'status' => 'required|boolean',
+            'company_id' => 'nullable|exists:companies,id',
+            'phone' => 'nullable|string|max:20',
+        ]);
+
+        $target_company_id = auth()->user()->isSystemAdmin() ? ($validated['company_id'] ?? null) : auth()->user()->company_id;
+
+        // 查找角色：優先尋找該公司的角色，若無則尋找全域範本
+        $roleObj = \App\Models\System\Role::where('name', $validated['role'])
+            ->where(function($q) use ($target_company_id) {
+                $q->where('company_id', $target_company_id)->orWhereNull('company_id');
+            })
+            ->first();
+
+        if (!$roleObj) {
+            return redirect()->back()->with('error', __('Role not found.'));
+        }
+
+        // 驗證角色與公司的匹配性 (RBAC Safeguard)
+        if ($user->id !== auth()->id()) { // 排除編輯自己 (super-admin 有特殊邏輯)
+            if ($target_company_id !== null) {
+                // 租戶層級排除 super-admin
+                if ($roleObj->name === 'super-admin') {
+                    return redirect()->back()->with('error', __('Super-admin role cannot be assigned to tenant accounts.'));
+                }
+                if ($roleObj->company_id !== null && $roleObj->company_id != $target_company_id) {
+                    return redirect()->back()->with('error', __('This role belongs to another company and cannot be assigned.'));
+                }
+            } else {
+                if (!$roleObj->is_system) {
+                    return redirect()->back()->with('error', __('Only global system roles can be assigned to platform administrative accounts.'));
+                }
+            }
+        }
+
+        $updateData = [
+            'name' => $validated['name'],
+            'username' => $validated['username'],
+            'email' => $validated['email'],
+            'status' => $validated['status'],
+            'phone' => $validated['phone'] ?? null,
+        ];
+
+        // 只有系統管理員在編輯租戶帳號時，且該帳號原本不是管理員，才可能觸發標記（視需求而定）
+        // 這裡我們維持 storeAccount 的邏輯：如果是系統管理員幫公司「開站」或「首配」，才自動標記
+        // 為求嚴謹，我們檢查該公司是否已經有 is_admin，如果沒有，當前這個人可以是第一個
+        if (auth()->user()->isSystemAdmin() && !empty($validated['company_id']) && !$user->is_admin) {
+            $hasAdmin = \App\Models\System\User::where('company_id', $validated['company_id'])
+                ->where('is_admin', true)
+                ->exists();
+            if (!$hasAdmin) {
+                $updateData['is_admin'] = true;
+            }
+        }
+
+        if (auth()->user()->isSystemAdmin()) {
+            // 防止超級管理員不小心把自己綁定到租客公司或降級
+            if ($user->id === auth()->id()) {
+                $updateData['company_id'] = null;
+                $validated['role'] = 'super-admin';
+            } else {
+                $updateData['company_id'] = $validated['company_id'];
+            }
+        }
+
+        if (!empty($validated['password'])) {
+            $updateData['password'] = \Illuminate\Support\Facades\Hash::make($validated['password']);
+        }
+
+        // 角色初始化與克隆邏輯
+        $target_company_id = auth()->user()->isSystemAdmin() ? ($validated['company_id'] ?? null) : auth()->user()->company_id;
+
+        if ($target_company_id && $roleObj && $roleObj->company_id === null && $roleObj->name !== 'super-admin') {
+            // 檢查該公司是否已有名為「管理員」的角色
+            $existingRole = \App\Models\System\Role::where('company_id', $target_company_id)
+                ->where('name', '管理員')
+                ->first();
+
+            if (!$existingRole) {
+                $newRole = \App\Models\System\Role::query()->create([
+                    'name' => '管理員',
+                    'guard_name' => 'web',
+                    'company_id' => $target_company_id,
+                    'is_system' => false,
+                    'is_admin' => true,
+                ]);
+                $newRole->syncPermissions($roleObj->getPermissionNames());
+                $roleObj = $newRole;
+            } else {
+                $roleObj = $existingRole;
+            }
+        }
+
+        $user->update($updateData);
+
+        // 如果是編輯自己且原本是超級管理員，強制保留 super-admin 角色
+        if ($user->id === auth()->id() && auth()->user()->isSystemAdmin()) {
+            $user->syncRoles(['super-admin']);
+        } else {
+            $user->syncRoles([$roleObj]);
+        }
+
+        return redirect()->back()->with('success', __('Account updated successfully.'));
+    }
+
+    /**
+     * Remove the specified account from storage.
+     */
+    public function destroyAccount($id)
+    {
+        $user = \App\Models\System\User::findOrFail($id);
+        
+        if ($user->hasRole('super-admin') && !auth()->user()->hasRole('super-admin')) {
+            return redirect()->back()->with('error', __('System super admin accounts can only be deleted by other super admins.'));
+        }
+
+        if ($user->id === auth()->id()) {
+            return redirect()->back()->with('error', __('You cannot delete your own account.'));
+        }
+
+        // 為了解決軟刪除導致的唯一索引佔用問題，刪除前先重命名唯一欄位
+        $timestamp = now()->getTimestamp();
+        $user->username = $user->username . '.deleted.' . $timestamp;
+        $user->email = $user->email . '.deleted.' . $timestamp;
+        $user->save();
+
+        $user->delete();
+
+        return redirect()->back()->with('success', __('Account deleted successfully.'));
+    }
+
+    public function toggleAccountStatus($id)
+    {
+        $user = \App\Models\System\User::findOrFail($id);
+        
+        // 非超級管理員禁止切換 Super Admin 狀態
+        if ($user->hasRole('super-admin') && !auth()->user()->hasRole('super-admin')) {
+            return back()->with('error', __('Only Super Admins can change other Super Admin status.'));
+        }
+
+        $user->status = $user->status ? 0 : 1;
+        $user->save();
+
+        $statusText = $user->status ? __('Enabled') : __('Disabled');
+        return back()->with('success', __('Account :name status has been changed to :status.', ['name' => $user->name, 'status' => $statusText]));
     }
 }

app/Http/Controllers/Admin/ProductCategoryController.php

@@ -0,0 +1,167 @@
+<?php
+
+namespace App\Http\Controllers\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\Product\ProductCategory;
+use App\Models\System\Translation;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Str;
+
+class ProductCategoryController extends Controller
+{
+    /**
+     * 顯示商品分類清單 (主要用於 AJAX 或內嵌在商品管理頁面)
+     */
+    public function index(Request $request)
+    {
+        $user = auth()->user();
+        $query = ProductCategory::with(['translations']);
+
+        if ($user->isSystemAdmin() && $request->filled('company_id')) {
+            $query->where('company_id', $request->company_id);
+        }
+
+        $categories = $query->latest()->get();
+
+        if ($request->wantsJson()) {
+            return response()->json([
+                'success' => true,
+                'data' => $categories
+            ]);
+        }
+
+        return redirect()->route('admin.data-config.products.index', ['tab' => 'categories']);
+    }
+
+    /**
+     * 儲存新分類
+     */
+    public function store(Request $request)
+    {
+        $validated = $request->validate([
+            'names.zh_TW' => 'required|string|max:255',
+            'names.en' => 'nullable|string|max:255',
+            'names.ja' => 'nullable|string|max:255',
+            'company_id' => 'nullable|exists:companies,id',
+        ]);
+
+        try {
+            DB::beginTransaction();
+
+            $dictKey = Str::uuid()->toString();
+            $company_id = (auth()->user()->isSystemAdmin() && $request->filled('company_id')) 
+                ? $request->company_id 
+                : auth()->user()->company_id;
+
+            // 儲存多語系翻譯
+            foreach ($request->names as $locale => $value) {
+                if (empty($value)) continue;
+                Translation::withoutGlobalScopes()->create([
+                    'group' => 'category',
+                    'key' => $dictKey,
+                    'locale' => $locale,
+                    'value' => $value,
+                    'company_id' => $company_id,
+                ]);
+            }
+
+            $category = ProductCategory::create([
+                'company_id' => $company_id,
+                'name' => $request->names['zh_TW'] ?? (collect($request->names)->first() ?? 'Untitled'),
+                'name_dictionary_key' => $dictKey,
+            ]);
+
+            DB::commit();
+
+            return redirect()->back()->with('success', __('Category created successfully'));
+
+        } catch (\Exception $e) {
+            DB::rollBack();
+            return redirect()->back()->with('error', $e->getMessage())->withInput();
+        }
+    }
+
+    /**
+     * 更新分類
+     */
+    public function update(Request $request, $id)
+    {
+        $category = ProductCategory::findOrFail($id);
+
+        $validated = $request->validate([
+            'names.zh_TW' => 'required|string|max:255',
+            'names.en' => 'nullable|string|max:255',
+            'names.ja' => 'nullable|string|max:255',
+        ]);
+
+        try {
+            DB::beginTransaction();
+
+            $dictKey = $category->name_dictionary_key ?: Str::uuid()->toString();
+            $company_id = $category->company_id;
+
+            foreach ($request->names as $locale => $value) {
+                if (empty($value)) {
+                    Translation::withoutGlobalScopes()->where([
+                        'group' => 'category',
+                        'key' => $dictKey,
+                        'locale' => $locale
+                    ])->delete();
+                    continue;
+                }
+
+                Translation::withoutGlobalScopes()->updateOrCreate(
+                    [
+                        'group' => 'category',
+                        'key' => $dictKey,
+                        'locale' => $locale,
+                    ],
+                    [
+                        'value' => $value,
+                        'company_id' => $company_id,
+                    ]
+                );
+            }
+
+            $category->update([
+                'name' => $request->names['zh_TW'] ?? $category->name,
+                'name_dictionary_key' => $dictKey,
+            ]);
+
+            DB::commit();
+
+            return redirect()->back()->with('success', __('Category updated successfully'));
+
+        } catch (\Exception $e) {
+            DB::rollBack();
+            return redirect()->back()->with('error', $e->getMessage())->withInput();
+        }
+    }
+
+    /**
+     * 刪除分類
+     */
+    public function destroy($id)
+    {
+        try {
+            $category = ProductCategory::findOrFail($id);
+
+            // 檢查是否已有商品使用此分類
+            if ($category->products()->count() > 0) {
+                return redirect()->back()->with('error', __('Cannot delete category that has products. Please move products first.'));
+            }
+
+            if ($category->name_dictionary_key) {
+                Translation::withoutGlobalScopes()->where('group', 'category')->where('key', $category->name_dictionary_key)->delete();
+            }
+
+            $category->delete();
+
+            return redirect()->back()->with('success', __('Category deleted successfully'));
+        } catch (\Exception $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+}

app/Http/Controllers/Admin/ProductController.php

@@ -0,0 +1,345 @@
+<?php
+
+namespace App\Http\Controllers\Admin;
+
+use App\Http\Controllers\Controller;
+use App\Models\Product\Product;
+use App\Models\Product\ProductCategory;
+use App\Models\System\Company;
+use App\Models\System\Translation;
+use App\Traits\ImageHandler;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\Str;
+
+class ProductController extends Controller
+{
+    use \App\Traits\ImageHandler;
+    public function index(Request $request)
+    {
+        $user = auth()->user();
+        $query = Product::with(['category.translations', 'translations', 'company']);
+        
+        // 搜尋
+        if ($request->filled('search')) {
+            $search = $request->search;
+            $query->where(function($q) use ($search) {
+                $q->where('name', 'like', "%{$search}%")
+                  ->orWhere('barcode', 'like', "%{$search}%")
+                  ->orWhere('spec', 'like', "%{$search}%");
+            });
+        }
+
+        // 分類篩選
+        if ($request->filled('category_id')) {
+            $query->where('category_id', $request->category_id);
+        }
+
+        $per_page = $request->input('per_page', 10);
+        
+        $companyId = $user->company_id;
+        if ($user->isSystemAdmin()) {
+            if ($request->filled('company_id')) {
+                $companyId = $request->company_id;
+                $query->where('company_id', $companyId);
+            }
+        }
+
+        $products = $query->latest()->paginate($per_page)->withQueryString();
+        $categories = ProductCategory::with('translations')->get();
+        $companies = $user->isSystemAdmin() ? Company::all() : collect();
+        
+        // 系統管理員在過濾特定公司時，應顯示該公司的功能開關 (如物料代碼、點數規則)
+        $selectedCompany = $companyId ? Company::find($companyId) : $user->company;
+        $companySettings = $selectedCompany ? ($selectedCompany->settings ?? []) : [];
+        
+        $routeName = 'admin.data-config.products.index';
+
+        return view('admin.products.index', [
+            'products' => $products,
+            'categories' => $categories,
+            'companies' => $companies,
+            'companySettings' => $companySettings,
+            'routeName' => $routeName
+        ]);
+    }
+
+    public function create(Request $request)
+    {
+        $user = auth()->user();
+        $categories = ProductCategory::with('translations')->get();
+        $companies = $user->isSystemAdmin() ? Company::all() : collect();
+
+        // If system admin, check if company_id is provided in URL to get settings
+        $companyId = $request->query('company_id') ?? $user->company_id;
+        $selectedCompany = $companyId ? Company::find($companyId) : $user->company;
+        $companySettings = $selectedCompany ? ($selectedCompany->settings ?? []) : [];
+
+        return view('admin.products.create', [
+            'categories' => $categories,
+            'companies' => $companies,
+            'companySettings' => $companySettings,
+        ]);
+    }
+
+    public function edit($id)
+    {
+        $user = auth()->user();
+        // 繞過 TenantScoped 載入翻譯，確保系統管理員能看到租戶公司的翻譯資料
+        $product = Product::with(['company'])->findOrFail($id);
+        $product->setRelation('translations', 
+            Translation::withoutGlobalScopes()
+                ->where('group', 'product')
+                ->where('key', $product->name_dictionary_key)
+                ->get()
+        );
+        $categories = ProductCategory::with('translations')->get();
+        $companies = $user->isSystemAdmin() ? Company::all() : collect();
+        
+        // Use the product's company settings for editing
+        $companySettings = $product->company ? ($product->company->settings ?? []) : [];
+
+        return view('admin.products.edit', [
+            'product' => $product,
+            'categories' => $categories,
+            'companies' => $companies,
+            'companySettings' => $companySettings,
+        ]);
+    }
+
+    public function store(Request $request)
+    {
+        $validated = $request->validate([
+            'names.zh_TW' => 'required|string|max:255',
+            'names.en' => 'nullable|string|max:255',
+            'names.ja' => 'nullable|string|max:255',
+            'barcode' => 'nullable|string|max:100',
+            'spec' => 'nullable|string|max:255',
+            'category_id' => 'nullable|exists:product_categories,id',
+            'manufacturer' => 'nullable|string|max:255',
+            'track_limit' => 'required|integer|min:1',
+            'spring_limit' => 'required|integer|min:1',
+            'price' => 'required|numeric|min:0',
+            'cost' => 'required|numeric|min:0',
+            'member_price' => 'required|numeric|min:0',
+            'metadata' => 'nullable|array',
+            'is_active' => 'nullable|boolean',
+            'company_id' => 'nullable|exists:companies,id',
+            'image' => 'nullable|image|mimes:jpeg,png,jpg,gif,webp|max:10240', // Increase to 10MB
+        ]);
+
+        try {
+            DB::beginTransaction();
+
+            $dictKey = \Illuminate\Support\Str::uuid()->toString();
+            // Determine company_id: prioritized from request (for sys admin) then from user
+            $company_id = (auth()->user()->isSystemAdmin() && $request->filled('company_id')) 
+                ? $request->company_id 
+                : auth()->user()->company_id;
+
+            // 儲存多語系翻譯（繞過 TenantScoped，避免系統管理員操作租戶資料時被過濾）
+            foreach ($request->names as $locale => $name) {
+                if (empty($name)) continue;
+                Translation::withoutGlobalScopes()->create([
+                    'group' => 'product',
+                    'key' => $dictKey,
+                    'locale' => $locale,
+                    'value' => $name,
+                    'company_id' => $company_id,
+                ]);
+            }
+
+
+
+            $imageUrl = null;
+            if ($request->hasFile('image')) {
+                $path = $this->storeAsWebp($request->file('image'), 'products');
+                $imageUrl = Storage::url($path);
+            }
+
+            $product = Product::create([
+                'company_id' => $company_id,
+                'category_id' => $request->category_id,
+                'name' => $request->names['zh_TW'] ?? (collect($request->names)->first() ?? 'Untitled'), // Fallback if zh_TW is missing
+                'name_dictionary_key' => $dictKey,
+                'image_url' => $imageUrl,
+                'barcode' => $request->barcode,
+                'spec' => $request->spec,
+                'manufacturer' => $request->manufacturer,
+                'track_limit' => $request->track_limit,
+                'spring_limit' => $request->spring_limit,
+                'price' => $request->price,
+                'cost' => $request->cost,
+                'member_price' => $request->member_price,
+                'metadata' => $request->metadata ?? [],
+                'is_active' => $request->boolean('is_active', true),
+            ]);
+
+            DB::commit();
+
+            if ($request->wantsJson()) {
+                return response()->json([
+                    'success' => true,
+                    'message' => __('Product created successfully'),
+                    'data' => $product
+                ]);
+            }
+
+            return redirect()->route('admin.data-config.products.index')->with('success', __('Product created successfully'));
+
+        } catch (\Exception $e) {
+            DB::rollBack();
+            if ($request->wantsJson()) {
+                return response()->json(['success' => false, 'message' => $e->getMessage()], 500);
+            }
+            return redirect()->back()->with('error', $e->getMessage())->withInput();
+        }
+    }
+
+    public function update(Request $request, $id)
+    {
+        $product = Product::findOrFail($id);
+
+        $validated = $request->validate([
+            'names.zh_TW' => 'required|string|max:255',
+            'names.en' => 'nullable|string|max:255',
+            'names.ja' => 'nullable|string|max:255',
+            'barcode' => 'nullable|string|max:100',
+            'spec' => 'nullable|string|max:255',
+            'category_id' => 'nullable|exists:product_categories,id',
+            'manufacturer' => 'nullable|string|max:255',
+            'track_limit' => 'required|integer|min:1',
+            'spring_limit' => 'required|integer|min:1',
+            'price' => 'required|numeric|min:0',
+            'cost' => 'required|numeric|min:0',
+            'member_price' => 'required|numeric|min:0',
+            'metadata' => 'nullable|array',
+            'is_active' => 'nullable|boolean',
+            'image' => 'nullable|image|mimes:jpeg,png,jpg,gif,webp|max:10240', // Increase to 10MB
+            'remove_image' => 'nullable|boolean',
+        ]);
+
+        try {
+            DB::beginTransaction();
+
+            $dictKey = $product->name_dictionary_key ?: \Illuminate\Support\Str::uuid()->toString();
+            $company_id = $product->company_id;
+
+            // 更新或建立多語系翻譯（繞過 TenantScoped，避免系統管理員操作租戶資料時被過濾）
+            foreach ($request->names as $locale => $name) {
+                if (empty($name)) {
+                    Translation::withoutGlobalScopes()->where([
+                        'group' => 'product',
+                        'key' => $dictKey,
+                        'locale' => $locale
+                    ])->delete();
+                    continue;
+                }
+
+                Translation::withoutGlobalScopes()->updateOrCreate(
+                    [
+                        'group' => 'product',
+                        'key' => $dictKey,
+                        'locale' => $locale,
+                    ],
+                    [
+                        'value' => $name,
+                        'company_id' => $company_id,
+                    ]
+                );
+            }
+
+            $data = [
+                'category_id' => $request->category_id,
+                'name' => $request->names['zh_TW'] ?? ($product->name ?? 'Untitled'),
+                'name_dictionary_key' => $dictKey,
+                'barcode' => $request->barcode,
+                'spec' => $request->spec,
+                'manufacturer' => $request->manufacturer,
+                'track_limit' => $request->track_limit,
+                'spring_limit' => $request->spring_limit,
+                'price' => $request->price,
+                'cost' => $request->cost,
+                'member_price' => $request->member_price,
+                'metadata' => $request->metadata ?? [],
+                'is_active' => $request->boolean('is_active', true),
+            ];
+
+            if ($request->hasFile('image')) {
+                // Delete old image
+                if ($product->image_url) {
+                    $oldPath = str_replace('/storage/', '', $product->image_url);
+                    Storage::disk('public')->delete($oldPath);
+                }
+                $path = $this->storeAsWebp($request->file('image'), 'products');
+                $data['image_url'] = Storage::url($path);
+            } elseif ($request->boolean('remove_image')) {
+                if ($product->image_url) {
+                    $oldPath = str_replace('/storage/', '', $product->image_url);
+                    Storage::disk('public')->delete($oldPath);
+                }
+                $data['image_url'] = null;
+            }
+
+            $product->update($data);
+
+            DB::commit();
+
+            if ($request->wantsJson()) {
+                return response()->json([
+                    'success' => true,
+                    'message' => __('Product updated successfully'),
+                    'data' => $product
+                ]);
+            }
+
+            return redirect()->route('admin.data-config.products.index')->with('success', __('Product updated successfully'));
+
+        } catch (\Exception $e) {
+            DB::rollBack();
+            if ($request->wantsJson()) {
+                return response()->json(['success' => false, 'message' => $e->getMessage()], 500);
+            }
+            return redirect()->back()->with('error', $e->getMessage())->withInput();
+        }
+    }
+
+    public function toggleStatus($id)
+    {
+        try {
+            $product = Product::findOrFail($id);
+            $product->is_active = !$product->is_active;
+            $product->save();
+
+            $status = $product->is_active ? __('Enabled') : __('Disabled');
+            return redirect()->back()->with('success', __('Product status updated to :status', ['status' => $status]));
+        } catch (\Exception $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+
+    public function destroy($id)
+    {
+        try {
+            $product = Product::findOrFail($id);
+            
+            // 刪除與此商品關聯的翻譯資料（繞過 TenantScoped）
+            if ($product->name_dictionary_key) {
+                Translation::withoutGlobalScopes()->where('key', $product->name_dictionary_key)->delete();
+            }
+
+            // Delete image
+            if ($product->image_url) {
+                $oldPath = str_replace('/storage/', '', $product->image_url);
+                Storage::disk('public')->delete($oldPath);
+            }
+
+            $product->delete();
+
+            return redirect()->back()->with('success', __('Product deleted successfully'));
+        } catch (\Exception $e) {
+            return redirect()->back()->with('error', $e->getMessage());
+        }
+    }
+}

app/Http/Controllers/Admin/QrCodeController.php

@@ -0,0 +1,34 @@
+<?php
+
+namespace App\Http\Controllers\Admin;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use SimpleSoftwareIO\QrCode\Facades\QrCode;
+
+class QrCodeController extends Controller
+{
+    /**
+     * Generate a QR Code image.
+     *
+     * @param  \Illuminate\Http\Request  $request
+     * @return \Illuminate\Http\Response
+     */
+    public function generate(Request $request)
+    {
+        $data = $request->query('data');
+        $size = $request->query('size', 250);
+
+        if (!$data) {
+            return response()->noContent();
+        }
+
+        // Generate SVG QR Code
+        $qrCode = QrCode::size($size)
+            ->format('svg')
+            ->margin(1)
+            ->generate($data);
+
+        return response($qrCode)->header('Content-Type', 'image/svg+xml');
+    }
+}

app/Http/Controllers/Admin/RemoteController.php

@@ -4,69 +4,131 @@ namespace App\Http\Controllers\Admin;
 
 use App\Http\Controllers\Controller;
 use Illuminate\Http\Request;
+use App\Models\Machine\Machine;
+use App\Models\Machine\RemoteCommand;
+use Illuminate\Support\Facades\Auth;
 
 class RemoteController extends Controller
 {
-    // 機台庫存
-    public function stock()
+    /**
+     * 遠端管理指揮中心
+     */
+    public function index(Request $request)
     {
-        return view('admin.placeholder', [
-            'title' => '遠端修改機台庫存',
-            'description' => '遠端修改機台庫存數量',
+        $machines = Machine::withCount(['slots'])->orderBy('last_heartbeat_at', 'desc')->orderBy('id', 'desc')->get();
+        $selectedMachine = null;
+        $history = RemoteCommand::where('command_type', '!=', 'reload_stock')->with(['machine', 'user'])->latest()->limit(50)->get();
+
+        if ($request->has('machine_id')) {
+            $selectedMachine = Machine::with(['slots.product', 'commands' => function($query) {
+                $query->where('command_type', '!=', 'reload_stock')
+                      ->latest()
+                      ->limit(5);
+            }])->find($request->machine_id);
+        }
+
+        if ($request->ajax()) {
+            return response()->json([
+                'success' => true,
+                'machine' => $selectedMachine,
+                'commands' => $selectedMachine ? $selectedMachine->commands : []
             ]);
         }
 
-    // 機台重啟
-    public function restart()
-    {
-        return view('admin.placeholder', [
-            'title' => '遠端重啟機台',
-            'description' => '遠端重啟機台系統',
+        return view('admin.remote.index', [
+            'machines' => $machines,
+            'selectedMachine' => $selectedMachine,
+            'history' => $history,
+            'title' => __('Remote Command Center'),
+            'subtitle' => __('Execute maintenance and operational commands remotely')
         ]);
     }
 
-    // 卡機重啟
-    public function restartCardReader()
+    /**
+     * 儲存遠端指令
+     */
+    public function storeCommand(Request $request)
     {
-        return view('admin.placeholder', [
-            'title' => '遠端重啟刷卡機',
-            'description' => '遠端重啟刷卡機設備',
+        $validated = $request->validate([
+            'machine_id' => 'required|exists:machines,id',
+            'command_type' => 'required|string|in:reboot,reboot_card,checkout,lock,unlock,change,dispense',
+            'amount' => 'nullable|integer|min:0',
+            'slot_no' => 'nullable|string',
+            'note' => 'nullable|string|max:255',
+        ]);
+
+        $payload = [];
+        if ($validated['command_type'] === 'change') {
+            $payload['amount'] = $validated['amount'];
+        } elseif ($validated['command_type'] === 'dispense') {
+            $payload['slot_no'] = $validated['slot_no'];
+        }
+
+        // 指令去重：將同機台、同類型的 pending 指令標記為「已取代」
+        RemoteCommand::where('machine_id', $validated['machine_id'])
+            ->where('command_type', $validated['command_type'])
+            ->where('status', 'pending')
+            ->update([
+                'status' => 'superseded',
+                'note' => __('Superseded by new command'),
+                'executed_at' => now(),
+            ]);
+
+        RemoteCommand::create([
+            'machine_id' => $validated['machine_id'],
+            'user_id' => auth()->id(),
+            'command_type' => $validated['command_type'],
+            'payload' => $payload,
+            'status' => 'pending',
+            'note' => $validated['note'] ?? null,
+        ]);
+
+        session()->flash('success', __('Command has been queued successfully.'));
+
+        if ($request->expectsJson()) {
+            return response()->json([
+                'success' => true,
+                'message' => __('Command has been queued successfully.')
             ]);
         }
 
-    // 遠端結帳
-    public function checkout()
-    {
-        return view('admin.placeholder', [
-            'title' => '遠端結帳',
-            'description' => '遠端執行結帳流程',
-        ]);
+        return redirect()->back();
     }
 
-    // 遠端鎖定頁
-    public function lock()
+    /**
+     * 機台庫存管理 (現有功能保留)
+     */
+    public function stock(Request $request)
     {
-        return view('admin.placeholder', [
-            'title' => '遠端鎖定頁',
-            'description' => '遠端鎖定機台頁面',
-        ]);
+        $machines = Machine::withCount([
+            'slots as slots_count',
+            'slots as low_stock_count' => function ($query) {
+                $query->where('stock', '<=', 5); 
+            },
+            'slots as expiring_soon_count' => function ($query) {
+                $query->whereNotNull('expiry_date')
+                      ->where('expiry_date', '<=', now()->addDays(7))
+                      ->where('expiry_date', '>=', now()->startOfDay());
+            }
+        ])->orderBy('last_heartbeat_at', 'desc')->orderBy('id', 'desc')->get();
+        
+        $history = RemoteCommand::where('command_type', 'reload_stock')->with(['machine', 'user'])->latest()->limit(50)->get();
+
+        $selectedMachine = null;
+        if ($request->has('machine_id')) {
+            $selectedMachine = Machine::with(['slots.product', 'commands' => function($query) {
+                $query->where('command_type', 'reload_stock')
+                      ->latest()
+                      ->limit(50);
+            }])->find($request->machine_id);
         }
 
-    // 遠端找零
-    public function change()
-    {
-        return view('admin.placeholder', [
-            'title' => '遠端找零',
-            'description' => '遠端執行找零功能',
-        ]);
-    }
-
-    // 遠端出貨
-    public function dispense()
-    {
-        return view('admin.placeholder', [
-            'title' => '遠端出貨',
-            'description' => '遠端控制商品出貨',
+        return view('admin.remote.stock', [
+            'machines' => $machines,
+            'selectedMachine' => $selectedMachine,
+            'history' => $history,
+            'title' => __('Stock & Expiry Management'),
+            'subtitle' => __('Real-time monitoring and adjustment of cargo lane inventory and expiration dates')
         ]);
     }
 }

app/Http/Controllers/Api/V1/App/MachineAuthController.php

@@ -0,0 +1,119 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\App;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Http\JsonResponse;
+use App\Models\System\User;
+use App\Models\Machine\Machine;
+use Illuminate\Support\Facades\Hash;
+use Illuminate\Support\Facades\Log;
+use App\Jobs\Machine\ProcessStateLog;
+
+class MachineAuthController extends Controller
+{
+    /**
+     * B000: 機台本機管理員/補貨員 離線同步登入驗證
+     * 這個 API 僅用於機台的 Java App 登入畫面驗證帳密。不必進入 Queue。
+     */
+    public function loginB000(Request $request): JsonResponse
+    {
+        // 1. 驗證欄位 (相容舊版 Java App 發送的 JSON 格式)
+        $validated = $request->validate([
+            'machine' => 'required|string',
+            'Su_Account' => 'required|string',
+            'Su_Password' => 'required|string',
+            'ip' => 'nullable|string',
+            'type' => 'nullable|string',
+        ]);
+
+        // 2. 取得機台物件 (需優先於帳密驗證，以便記錄日誌到正確機台)
+        $machine = Machine::withoutGlobalScopes()->where('serial_no', $validated['machine'])->first();
+
+        if (!$machine) {
+            Log::warning("B000 機台登入失敗: 伺服器找不到該機台", [
+                'machine_serial' => $validated['machine']
+            ]);
+            return response()->json(['message' => 'Failed']);
+        }
+
+        // 3. 透過帳號尋找使用者 (允許使用 username 或 email)
+        $user = User::where('username', $validated['Su_Account'])
+            ->orWhere('email', $validated['Su_Account'])
+            ->first();
+
+        // 4. 驗證密碼
+        if (!$user || !Hash::check($validated['Su_Password'], $user->password)) {
+            Log::warning("B000 機台登入失敗: 帳密錯誤", [
+                'account' => $validated['Su_Account'],
+                'machine' => $validated['machine']
+            ]);
+
+            // 寫入機台日誌
+            ProcessStateLog::dispatch(
+                $machine->id,
+                $machine->company_id,
+                __("Login failed: :account", ['account' => $validated['Su_Account']]),
+                'warning',
+                [],
+                'login'
+            );
+
+            return response()->json(['message' => 'Failed']);
+        }
+
+        // 5. RBAC 權限驗證 (遵循多租戶與機台授權規範)
+        $isAuthorized = false;
+        if ($user->isSystemAdmin()) {
+            $isAuthorized = true;
+        } elseif ($user->is_admin) {
+            if ($machine->company_id === $user->company_id) {
+                $isAuthorized = true;
+            }
+        } else {
+            if ($user->machines()->where('machine_id', $machine->id)->exists()) {
+                $isAuthorized = true;
+            }
+        }
+
+        if (!$isAuthorized) {
+            Log::warning("B000 機台登入失敗: 權限不足", [
+                'user_id' => $user->id,
+                'machine_id' => $machine->id
+            ]);
+
+            ProcessStateLog::dispatch(
+                $machine->id,
+                $machine->company_id,
+                __("Unauthorized login attempt: :account", ['account' => $user->username]),
+                'warning',
+                [],
+                'login'
+            );
+
+            return response()->json(['message' => 'Forbidden']);
+        }
+
+        // 6. 驗證完美通過！
+        Log::info("B000 機台登入成功", [
+            'account' => $user->username,
+            'machine' => $machine->serial_no
+        ]);
+
+        // 寫入成功登入日誌
+        ProcessStateLog::dispatch(
+            $machine->id,
+            $machine->company_id,
+            __("User logged in: :name", ['name' => $user->name ?? $user->username]),
+            'info',
+            [],
+            'login'
+        );
+
+        return response()->json([
+            'message' => 'Success',
+            'token' => $user->createToken('technician-setup', ['*'], now()->addHours(8))->plainTextToken
+        ]);
+    }
+}

app/Http/Controllers/Api/V1/App/MachineController.php

@@ -0,0 +1,552 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\App;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use App\Models\Machine\Machine;
+use App\Models\System\User;
+use App\Jobs\Machine\ProcessHeartbeat;
+use App\Jobs\Machine\ProcessTimerStatus;
+use App\Jobs\Machine\ProcessCoinInventory;
+use App\Jobs\Machine\ProcessMachineError;
+use App\Jobs\Machine\ProcessStateLog;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Facades\Validator;
+use Illuminate\Support\Facades\Cache;
+
+class MachineController extends Controller
+{
+    /**
+     * B010: Machine Heartbeat & Status Update (Asynchronous)
+     */
+    public function heartbeat(Request $request)
+    {
+        $machine = $request->get('machine');
+        $data = $request->except(['machine', 'key']); // 排除 Middleware 注入的 Model 物件與認證 key
+
+        // === 狀態異動觸發 (Redis 快取免查 DB) ===
+        $cacheKey = "machine:{$machine->serial_no}:state";
+        $oldState = Cache::get($cacheKey);
+
+        $currentPage = $data['current_page'] ?? null;
+        $doorStatus = $data['door_status'] ?? null;
+        $firmwareVersion = $data['firmware_version'] ?? null;
+        $model = $data['model'] ?? null;
+
+        if ($currentPage !== null || $doorStatus !== null || $firmwareVersion !== null || $model !== null) {
+            // 更新目前狀態到 Redis (保存 1 天)
+            $newState = $oldState ?? [];
+            if ($currentPage !== null) $newState['current_page'] = $currentPage;
+            if ($doorStatus !== null) $newState['door_status'] = $doorStatus;
+            if ($firmwareVersion !== null) $newState['firmware_version'] = $firmwareVersion;
+            if ($model !== null) $newState['model'] = $model;
+
+            Cache::put($cacheKey, $newState, 86400);
+
+            // 若有歷史紀錄才進行比對 (避開 Cache Miss 造成的雪崩)
+            if ($oldState !== null) {
+                // 1. 判斷頁面是否變更
+                if ($currentPage !== null && (string)$currentPage !== (string)($oldState['current_page'] ?? '')) {
+                    // 只記錄「絕對狀態」，配合 lang 中 "Page X" 的翻譯
+                    ProcessStateLog::dispatch($machine->id, $machine->company_id, "Page {$currentPage}", 'info');
+                }
+
+                // 2. 判斷門禁是否變更 (0: 關閉, 1: 開啟)
+                if ($doorStatus !== null && (string)$doorStatus !== (string)($oldState['door_status'] ?? '')) {
+                    $doorMessage = $doorStatus == 1 ? "Door Opened" : "Door Closed";
+                    $doorLevel = 'info'; // 不論開關門皆為 info，避免觸發異常狀態
+                    ProcessStateLog::dispatch($machine->id, $machine->company_id, $doorMessage, $doorLevel);
+                }
+
+                // 3. 判斷韌體版本是否變更
+                if ($firmwareVersion !== null && (string)$firmwareVersion !== (string)($oldState['firmware_version'] ?? '')) {
+                    $oldVersion = $oldState['firmware_version'] ?? 'Unknown';
+                    // 直接在 Controller 進行翻譯並填值，確保儲存到 DB 的是最終正確字串
+                    $versionMessage = __("Firmware updated to :version", ['version' => $firmwareVersion]);
+                    ProcessStateLog::dispatch(
+                        $machine->id, 
+                        $machine->company_id, 
+                        $versionMessage, 
+                        'info',
+                        ['old' => $oldVersion, 'new' => $firmwareVersion]
+                    );
+                }
+
+                // 4. 判斷型號是否變更
+                if ($model !== null && (string)$model !== (string)($oldState['model'] ?? '')) {
+                    $oldModel = $oldState['model'] ?? 'Unknown';
+                    $modelMessage = __("Model changed to :model", ['model' => $model]);
+                    ProcessStateLog::dispatch(
+                        $machine->id, 
+                        $machine->company_id, 
+                        $modelMessage, 
+                        'info',
+                        ['old' => $oldModel, 'new' => $model]
+                    );
+                }
+            }
+        }
+
+        // 異步處理狀態更新
+        ProcessHeartbeat::dispatch($machine->serial_no, $data);
+
+        // 取出待處理指令
+        $command = \App\Models\Machine\RemoteCommand::where('machine_id', $machine->id)
+            ->pending()
+            ->first();
+
+        $status = '49'; // 預設 49 (OK / No Command)
+        $message = 'OK';
+
+        if ($command) {
+            switch ($command->command_type) {
+                case 'reboot':
+                    $status = '51';
+                    $message = 'reboot';
+                    break;
+                case 'reboot_card':
+                    $status = '60';
+                    $message = 'reboot card machine';
+                    break;
+                case 'checkout':
+                    $status = '61';
+                    $message = 'checkout';
+                    break;
+                case 'lock':
+                    $status = '71';
+                    $message = 'lock';
+                    break;
+                case 'unlock':
+                    $status = '70';
+                    $message = 'unlock';
+                    break;
+                case 'change':
+                    $status = '82';
+                    $message = $command->payload['amount'] ?? '0';
+                    break;
+                case 'dispense':
+                    $status = '85';
+                    $message = $command->payload['slot_no'] ?? '';
+                    break;
+                case 'reload_stock':
+                    $status = '49';
+                    $message = 'reload B017';
+                    break;
+            }
+            // 標記為已發送 (sent)
+            $command->update(['status' => 'sent', 'executed_at' => now()]);
+        }
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'message' => $message,
+            'status' => $status
+        ], 202); // 202 Accepted
+    }
+
+    /**
+     * B018: Record Machine Restock/Setup Report (Asynchronous)
+     */
+    public function recordRestock(Request $request)
+    {
+        $machine = $request->get('machine');
+        $data = $request->except(['machine', 'key']); // 排除 Middleware 注入物件
+        $data['serial_no'] = $machine->serial_no;
+
+        \App\Jobs\Machine\ProcessRestockReport::dispatch($data);
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'message' => 'Restock report accepted',
+            'status' => '49'
+        ], 202);
+    }
+
+    /**
+     * B017: Get Slot Info & Stock (Synchronous)
+     */
+    /**
+     * B017: Get Slot Info & Stock (Synchronous - Full Sync)
+     */
+    public function getSlots(Request $request)
+    {
+        $machine = $request->get('machine');
+        
+        // 依貨道編號排序 (Sorted by slot_no as requested)
+        $slots = $machine->slots()->with('product')->orderBy('slot_no')->get();
+
+        // 自動轉 Success: 若機台來撈 B017，代表之前的 reload_stock 指令已成功被機台響應
+        // 同時處理 sent 與 pending 狀態，確保狀態機正確關閉
+        \App\Models\Machine\RemoteCommand::where('machine_id', $machine->id)
+            ->where('command_type', 'reload_stock')
+            ->whereIn('status', ['pending', 'sent'])
+            ->update([
+                'status' => 'success', 
+                'executed_at' => now(),
+                'note' => __('Inventory synced with machine')
+            ]);
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'data' => $slots->map(function ($slot) {
+                return [
+                    'tid' => $slot->slot_no,
+                    'num' => (int)$slot->stock,
+                    'expiry_date' => $slot->expiry_date ? $slot->expiry_date->format('Y-m-d') : null,
+                    'batch_no' => $slot->batch_no,
+                    // 保留原始欄位以供除錯或未來擴充
+                    'product_id' => $slot->product_id,
+                    'capacity' => $slot->max_stock, 
+                    'status' => $slot->is_active ? '1' : '0',
+                ];
+            })
+        ]);
+    }
+
+
+    /**
+     * B710: Sync Timer status (Asynchronous)
+     */
+    public function syncTimer(Request $request)
+    {
+        $machine = $request->get('machine');
+        $data = $request->except(['machine', 'key']); // 排除 Middleware 注入物件
+
+        ProcessTimerStatus::dispatch($machine->serial_no, $data);
+
+        return response()->json(['success' => true], 202);
+    }
+
+    /**
+     * B220: Sync Coin Inventory (Asynchronous)
+     */
+    public function syncCoinInventory(Request $request)
+    {
+        $machine = $request->get('machine');
+        $data = $request->except(['machine', 'key']); // 排除 Middleware 注入物件
+
+        ProcessCoinInventory::dispatch($machine->serial_no, $data);
+
+        return response()->json(['success' => true], 202);
+    }
+
+    /**
+     * B650: Verify Member Code/Barcode (Synchronous)
+     */
+    public function verifyMember(Request $request)
+    {
+        $validator = Validator::make($request->all(), [
+            'code' => 'required|string',
+        ]);
+
+        if ($validator->fails()) {
+            return response()->json(['success' => false, 'message' => 'Invalid code'], 400);
+        }
+
+        $code = $request->input('code');
+
+        // 搜尋會員 (barcode 或特定驗證碼)
+        $member = \App\Models\Member\Member::where('barcode', $code)
+            ->orWhere('id', $code) // 暫時支援 ID
+            ->first();
+
+        if (!$member) {
+            return response()->json([
+                'success' => false,
+                'code' => 404,
+                'message' => 'Member not found'
+            ], 404);
+        }
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'data' => [
+                'member_id' => $member->id,
+                'name' => $member->name,
+                'points' => $member->points,
+                'wallet_balance' => $member->wallet_balance ?? 0,
+            ]
+        ]);
+    }
+
+    /**
+     * B005: Download Machine Advertisements (Synchronous)
+     */
+    public function getAdvertisements(Request $request)
+    {
+        $machine = $request->get('machine');
+
+        $advertisements = \App\Models\Machine\MachineAdvertisement::where('machine_id', $machine->id)
+            ->with([
+                'advertisement' => function ($query) {
+                    $query->playing();
+                }
+            ])
+            ->get()
+            ->filter(fn($ma) => $ma->advertisement !== null)
+            ->map(function ($ma) {
+                // 定義顯示順序權重 (待機 > 購物 > 成功禮)
+                $posWeight = [
+                    'standby' => 1,
+                    'vending' => 2,
+                    'visit_gift' => 3
+                ];
+
+                // 為了相容現有機台 App 邏輯：
+                // App 讀取 t070v03 作為位置標籤 (flag)：
+                // 1. HomeActivity (待機) 讀取 "3"
+                // 2. FontendActivity (販賣頁) 讀取 "1"
+                $posIdMap = [
+                    'standby' => '3',
+                    'vending' => '1',
+                    'visit_gift' => '2'
+                ];
+
+                return [
+                    't070v01' => $ma->advertisement->name,
+                    't070v02' => (string) ($ma->advertisement->duration ?? 15), // 秒數改放這裡
+                    't070v03' => (string) ($posIdMap[$ma->position] ?? '1'),    // 位置數字改放這裡 (App 會讀這欄當 Flag)
+                    't070v04' => $ma->advertisement->url ? (str_starts_with($ma->advertisement->url, 'http') ? $ma->advertisement->url : asset($ma->advertisement->url)) : '',
+                    't070v05' => (string) $ma->sort_order,
+                    'raw_pos_weight' => $posWeight[$ma->position] ?? 99,
+                    'raw_sort' => (int) $ma->sort_order
+                ];
+            })
+            ->sortBy([
+                ['raw_pos_weight', 'asc'],
+                ['raw_sort', 'asc']
+            ])
+            ->values()
+            ->map(function ($item) {
+                unset($item['raw_pos_weight'], $item['raw_sort']);
+                return $item;
+            });
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'data' => $advertisements->values()
+        ]);
+    }
+
+    /**
+     * B009: Report Machine Slot List / Supplementary (Synchronous)
+     */
+    public function reportSlotList(Request $request, \App\Services\Machine\MachineService $machineService)
+    {
+        $machine = $request->get('machine');
+        $payload = $request->all();
+        $account = $payload['account'] ?? null;
+
+        // 1. 驗證帳號是否存在 (驗證執行補貨的人員身分)
+        $user = User::where('username', $account)
+            ->orWhere('email', $account)
+            ->first();
+
+        if (!$user) {
+            return response()->json([
+                'success' => false,
+                'code' => 403,
+                'message' => 'Unauthorized: Account not found',
+                'status' => ''
+            ], 403);
+        }
+
+        // 2. 階層式權限驗證 (遵循 RBAC 多租戶規範)
+        $isAuthorized = false;
+        if ($user->isSystemAdmin()) {
+            // [系統層]：系統管理員可異動所有機台
+            $isAuthorized = true;
+        } elseif ($user->is_admin) {
+            // [公司層]：公司管理員需驗證此機台是否隸屬於該公司
+            $isAuthorized = ($machine->company_id === $user->company_id);
+        } else {
+            // [人員層]：一般人員需檢查 machine_user 授權表
+            $isAuthorized = $user->machines()->where('machine_id', $machine->id)->exists();
+        }
+
+        if (!$isAuthorized) {
+            return response()->json([
+                'success' => false,
+                'code' => 403,
+                'message' => 'Unauthorized: Account not authorized for this machine',
+                'status' => ''
+            ], 403);
+        }
+
+        // 3. 映射舊版機台回傳格式 (Map legacy machine format)
+        // 支持單個物件 data: {} 或 陣列 data: [{}] (Handle both single object and array)
+        $legacyData = $payload['data'] ?? [];
+        if (Arr::isAssoc($legacyData)) {
+            $legacyData = [$legacyData];
+        }
+
+        $mappedSlots = array_map(function ($item) {
+            return [
+                'slot_no' => $item['tid'] ?? null,
+                'product_id' => $item['t060v00'] ?? null,
+                'stock' => $item['num'] ?? 0,
+                'type' => $item['type'] ?? null,
+            ];
+        }, $legacyData);
+
+        // 過濾無效資料 (Filter invalid entries)
+        $mappedSlots = array_filter($mappedSlots, fn($s) => $s['slot_no'] !== null);
+
+        // 同步處理更新庫存 (直接更新不進隊列)
+        $machineService->syncSlots($machine, $mappedSlots);
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'message' => 'Slot report synchronized success',
+            'status' => '49'
+        ]);
+    }
+
+    /**
+     * B012_new: Download Product Catalog (Synchronous)
+     */
+    public function getProducts(Request $request)
+    {
+        $machine = $request->get('machine');
+
+        $products = \App\Models\Product\Product::where('company_id', $machine->company_id)
+            ->with(['translations'])
+            ->active()
+            ->get()
+            ->map(function ($product) {
+                // 提取多語系名稱 (Extract translations)
+                $nameEn = $product->translations->firstWhere('locale', 'en')?->value ?? '';
+                $nameJp = $product->translations->firstWhere('locale', 'ja')?->value ?? '';
+
+                return [
+                    't060v00' => (string) $product->id, // ID 仍建議維持字串，增加未來編號彈性
+                    't060v01' => $product->name,
+                    't060v01_en' => $nameEn,
+                    't060v01_jp' => $nameJp,
+                    't060v03' => $product->spec ?? '',
+                    't060v06' => $product->image_url ? (str_starts_with($product->image_url, 'http') ? $product->image_url : asset($product->image_url)) : '',
+                    't060v09' => (float) $product->price,
+                    't060v11' => (int) ($product->track_limit ?? 10),
+                    't060v30' => (float) ($product->member_price ?? $product->price),
+                    't060v40' => $product->metadata['marketing_plan'] ?? '', // 行銷計畫
+                    't060v41' => $product->metadata['material_code'] ?? $product->barcode ?? '', // 物料編碼 (優先從 metadata 找，回退至條碼)
+                    'spring_limit' => (int) ($product->spring_limit ?? 10),
+                    'track_limit' => (int) ($product->track_limit ?? 10),
+                    't063v03' => (float) $product->price,
+                ];
+            });
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'data' => $products
+        ]);
+    }
+
+    /**
+     * B013: Report Machine Hardware Error/Status (Asynchronous)
+     */
+    public function reportError(Request $request)
+    {
+        $machine = $request->get('machine');
+        $data = $request->only(['tid', 'error_code']);
+
+        // 異步分派處理 (Dispatch to queue)
+        ProcessMachineError::dispatch($machine->serial_no, $data);
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'message' => 'Error report accepted',
+        ], 202); // 202 Accepted
+    }
+
+    /**
+     * B014: Download Machine Settings & Config (Synchronous, Requires User Auth)
+     * 用於機台引導階段，同步金流、發票與機台專屬 API Token。
+     */
+    public function getSettings(Request $request)
+    {
+        $serialNo = $request->input('machine');
+        $user = $request->user();
+
+        // 1. 查找機台 (忽略全局範圍以進行認領)
+        $machine = Machine::withoutGlobalScopes()
+            ->with(['paymentConfig', 'company'])
+            ->where('serial_no', $serialNo)
+            ->first();
+
+        if (!$machine) {
+            return response()->json([
+                'success' => false,
+                'code' => 404,
+                'message' => 'Machine not found'
+            ], 404);
+        }
+
+        // 2. 權限加強驗證 (RBAC)
+        $isAuthorized = false;
+        if ($user->isSystemAdmin()) {
+            $isAuthorized = true;
+        } elseif ($machine->company_id === $user->company_id) {
+            // 公司管理員或已授權員工才能存取
+            if ($user->is_admin || $user->machines()->where('machine_id', $machine->id)->exists()) {
+                $isAuthorized = true;
+            }
+        }
+
+        if (!$isAuthorized) {
+            return response()->json([
+                'success' => false,
+                'code' => 403,
+                'message' => 'Forbidden: You do not have permission to configure this machine'
+            ], 403);
+        }
+
+        // 3. 獲取關聯設定
+        $paymentSettings = $machine->paymentConfig->settings ?? [];
+        $companySettings = $machine->company->settings ?? [];
+
+        // 4. 映射 App 預期欄位 (嚴格遵守 HttpAPI.java 結構)
+        $data = [
+            't050v01' => $machine->serial_no,
+            'api_token' => $machine->api_token, // 向 App 核發正式通訊 Token
+            
+            // 玉山支付
+            't050v41' => $paymentSettings['esun_store_id'] ?? '',
+            't050v42' => $paymentSettings['esun_term_id'] ?? '',
+            't050v43' => $paymentSettings['esun_hash'] ?? '',
+
+            // 電子發票 (綠界)
+            't050v34' => $companySettings['invoice_merchant_id'] ?? '',
+            't050v35' => $companySettings['invoice_hash_key'] ?? '',
+            't050v36' => $companySettings['invoice_hash_iv'] ?? '',
+            't050v38' => $companySettings['invoice_email'] ?? '',
+
+            // 趨勢支付 (TrendPay/Greenpay)
+            'TP_APP_ID' => $paymentSettings['tp_app_id'] ?? '',
+            'TP_APP_KEY' => $paymentSettings['tp_app_key'] ?? '',
+            'TP_PARTNER_KEY' => $paymentSettings['tp_partner_key'] ?? '',
+            
+            // 各類行動支付特店 ID
+            'TP_LINE_MERCHANT_ID' => $paymentSettings['tp_line_merchant_id'] ?? '',
+            'TP_PS_MERCHANT_ID' => $paymentSettings['tp_ps_merchant_id'] ?? '',
+            'TP_EASY_MERCHANT_ID' => $paymentSettings['tp_easy_merchant_id'] ?? '',
+            'TP_PI_MERCHANT_ID' => $paymentSettings['tp_pi_merchant_id'] ?? '',
+            'TP_JKO_MERCHANT_ID' => $paymentSettings['tp_jko_merchant_id'] ?? '',
+        ];
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'data' => [$data] // App 預期的是包含單一物件的陣列
+        ]);
+    }
+}

app/Http/Controllers/Api/V1/App/TransactionController.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace App\Http\Controllers\Api\V1\App;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use App\Jobs\Transaction\ProcessTransaction;
+use App\Jobs\Transaction\ProcessInvoice;
+use App\Jobs\Transaction\ProcessDispenseRecord;
+
+class TransactionController extends Controller
+{
+    /**
+     * B600: Record Transaction (Asynchronous)
+     */
+    public function store(Request $request)
+    {
+        $machine = $request->get('machine');
+        $data = $request->except(['machine', 'key']); // 排除 Middleware 注入物件
+        $data['serial_no'] = $machine->serial_no;
+
+        ProcessTransaction::dispatch($data);
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'message' => 'Accepted'
+        ], 202);
+    }
+
+    /**
+     * B601: Record Invoice (Asynchronous)
+     */
+    public function recordInvoice(Request $request)
+    {
+        $machine = $request->get('machine');
+        $data = $request->except(['machine', 'key']); // 排除 Middleware 注入物件
+        $data['serial_no'] = $machine->serial_no;
+
+        ProcessInvoice::dispatch($data);
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'message' => 'Accepted'
+        ], 202);
+    }
+
+    /**
+     * B602: Record Dispense Result (Asynchronous)
+     */
+    public function recordDispense(Request $request)
+    {
+        $machine = $request->get('machine');
+        $data = $request->all();
+        $data['serial_no'] = $machine->serial_no;
+
+        ProcessDispenseRecord::dispatch($data);
+
+        return response()->json([
+            'success' => true,
+            'code' => 200,
+            'message' => 'Accepted'
+        ], 202);
+    }
+}

app/Http/Controllers/ApiDocsController.php

@@ -0,0 +1,18 @@
+<?php
+
+namespace App\Http\Controllers;
+
+use Illuminate\Http\Request;
+
+class ApiDocsController extends Controller
+{
+    /**
+     * Display the API documentation page.
+     */
+    public function index()
+    {
+        $docs = config('api-docs');
+        
+        return view('docs.api-docs', compact('docs'));
+    }
+}

app/Http/Controllers/Auth/PasswordController.php

@@ -24,6 +24,6 @@ class PasswordController extends Controller
             'password' => Hash::make($validated['password']),
         ]);
 
-        return back()->with('status', 'password-updated');
+        return back()->with('success', __('Password updated successfully.'));
     }
 }

app/Http/Controllers/ProfileController.php

@@ -7,6 +7,7 @@ use Illuminate\Http\RedirectResponse;
 use Illuminate\Http\Request;
 use Illuminate\Support\Facades\Auth;
 use Illuminate\Support\Facades\Redirect;
+use Illuminate\Support\Facades\Storage;
 use Illuminate\View\View;
 
 class ProfileController extends Controller
@@ -16,8 +17,11 @@ class ProfileController extends Controller
      */
     public function edit(Request $request): View
     {
+        $user = $request->user();
+
         return view('profile.edit', [
-            'user' => $request->user(),
+            // 只取最新 10 筆登入紀錄
+            'user' => $user->load(['loginLogs' => fn($q) => $q->latest('login_at')->limit(10)]),
         ]);
     }
 
@@ -26,35 +30,50 @@ class ProfileController extends Controller
      */
     public function update(ProfileUpdateRequest $request): RedirectResponse
     {
-        $request->user()->fill($request->validated());
+        $user = $request->user();
+        $user->fill($request->validated());
 
-        if ($request->user()->isDirty('email')) {
-            $request->user()->email_verified_at = null;
+        if ($user->isDirty('email')) {
+            $user->email_verified_at = null;
         }
 
-        $request->user()->save();
+        $user->save();
 
-        return Redirect::route('profile.edit')->with('status', 'profile-updated');
+        return Redirect::route('profile.edit')->with('success', __('Profile updated successfully.'));
     }
 
     /**
-     * Delete the user's account.
+     * Update the user's avatar via AJAX.
      */
-    public function destroy(Request $request): RedirectResponse
+    public function updateAvatar(Request $request): \Illuminate\Http\JsonResponse
     {
-        $request->validateWithBag('userDeletion', [
-            'password' => ['required', 'current_password'],
+        $request->validate([
+            'avatar' => ['required', 'image', 'mimes:jpeg,png,jpg,gif,webp', 'max:1024'],
         ]);
 
         $user = $request->user();
 
-        Auth::logout();
-
-        $user->delete();
-
-        $request->session()->invalidate();
-        $request->session()->regenerateToken();
-
-        return Redirect::to('/');
+        if ($request->hasFile('avatar')) {
+            // Delete old avatar if exists
+            if ($user->avatar) {
+                Storage::disk('public')->delete($user->avatar);
             }
+
+            $path = $request->file('avatar')->store('avatars', 'public');
+            $user->avatar = $path;
+            $user->save();
+
+            return response()->json([
+                'success' => true,
+                'avatar_url' => $user->avatar_url,
+                'message' => __('Avatar updated successfully.'),
+            ]);
+        }
+
+        return response()->json([
+            'success' => false,
+            'message' => __('No file uploaded.'),
+        ], 400);
+    }
+
 }

app/Http/Controllers/System/LanguageController.php

@@ -0,0 +1,25 @@
+<?php
+
+namespace App\Http\Controllers\System;
+
+use App\Http\Controllers\Controller;
+use Illuminate\Http\Request;
+use Illuminate\Support\Facades\Session;
+
+class LanguageController extends Controller
+{
+    /**
+     * Switch application language.
+     *
+     * @param string $locale
+     * @return \Illuminate\Http\RedirectResponse
+     */
+    public function switch($locale)
+    {
+        if (in_array($locale, ['en', 'zh_TW', 'ja'])) {
+            Session::put('locale', $locale);
+        }
+
+        return redirect()->back();
+    }
+}

app/Http/Kernel.php

@@ -33,6 +33,7 @@ class Kernel extends HttpKernel
             \App\Http\Middleware\EncryptCookies::class,
             \Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse::class,
             \Illuminate\Session\Middleware\StartSession::class,
+            \App\Http\Middleware\SetLocale::class,
             \Illuminate\View\Middleware\ShareErrorsFromSession::class,
             \App\Http\Middleware\VerifyCsrfToken::class,
             \Illuminate\Routing\Middleware\SubstituteBindings::class,
@@ -64,5 +65,10 @@ class Kernel extends HttpKernel
         'signed' => \App\Http\Middleware\ValidateSignature::class,
         'throttle' => \Illuminate\Routing\Middleware\ThrottleRequests::class,
         'verified' => \Illuminate\Auth\Middleware\EnsureEmailIsVerified::class,
+        'tenant.access' => \App\Http\Middleware\EnsureTenantAccess::class,
+        'role' => \Spatie\Permission\Middleware\RoleMiddleware::class,
+        'permission' => \Spatie\Permission\Middleware\PermissionMiddleware::class,
+        'role_or_permission' => \Spatie\Permission\Middleware\RoleOrPermissionMiddleware::class,
+        'iot.auth' => \App\Http\Middleware\IotAuth::class,
     ];
 }

app/Http/Middleware/EnsureTenantAccess.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class EnsureTenantAccess
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        $user = auth()->user();
+
+        // 如果是租戶帳號，檢查公司狀態
+        if ($user && $user->isTenant()) {
+            $company = $user->company;
+
+            if (!$company || $company->status === 0) {
+                auth()->logout();
+                return redirect()->route('login')->with('error', __('Your account is associated with a deactivated company.'));
+            }
+
+            if ($company->end_date && $company->end_date->isPast()) {
+                auth()->logout();
+                return redirect()->route('login')->with('error', __('Your company contract has expired.'));
+            }
+        }
+
+        return $next($request);
+    }
+}

app/Http/Middleware/IotAuth.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use App\Models\Machine\Machine;
+use Symfony\Component\HttpFoundation\Response;
+
+class IotAuth
+{
+    /**
+     * Handle an incoming request.
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        $token = $request->bearerToken();
+        
+        // Phase 1: 暫時也接受 Request Body 中的 key 欄位 (相容模式)
+        if (!$token) {
+            $token = $request->input('key');
+        }
+
+        if (!$token) {
+            return response()->json(['success' => false, 'message' => 'Unauthorized: Missing Token'], 401);
+        }
+
+        $machine = Machine::where('api_token', $token)->first();
+
+        if (!$machine) {
+            return response()->json(['success' => false, 'message' => 'Unauthorized: Invalid Token'], 401);
+        }
+
+        // 將機台物件注入 Request 供後端使用
+        $request->merge(['machine' => $machine]);
+
+        return $next($request);
+    }
+}

app/Http/Middleware/SetLocale.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Http\Middleware;
+
+use Closure;
+use Illuminate\Http\Request;
+use Symfony\Component\HttpFoundation\Response;
+
+class SetLocale
+{
+    /**
+     * Handle an incoming request.
+     *
+     * @param  \Closure(\Illuminate\Http\Request): (\Symfony\Component\HttpFoundation\Response)  $next
+     */
+    public function handle(Request $request, Closure $next): Response
+    {
+        if (session()->has('locale')) {
+            $locale = session()->get('locale');
+            if (in_array($locale, ['zh_TW', 'en', 'ja'])) {
+                app()->setLocale($locale);
+            }
+        }
+
+        return $next($request);
+    }
+}

app/Http/Requests/ProfileUpdateRequest.php

@@ -19,7 +19,7 @@ class ProfileUpdateRequest extends FormRequest
             'name' => ['required', 'string', 'max:255'],
             'email' => ['required', 'string', 'lowercase', 'email', 'max:255', Rule::unique(User::class)->ignore($this->user()->id)],
             'phone' => ['nullable', 'string', 'max:20'],
-            'avatar' => ['nullable', 'string', 'max:255'],
+            'avatar' => ['nullable', 'image', 'mimes:jpeg,png,jpg,gif', 'max:2048'],
         ];
     }
 }

app/Jobs/Machine/ProcessCoinInventory.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace App\Jobs\Machine;
+
+use App\Models\Machine\Machine;
+use App\Models\Machine\CoinInventory;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+class ProcessCoinInventory implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    protected $serialNo;
+    protected $data;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(string $serialNo, array $data)
+    {
+        $this->serialNo = $serialNo;
+        $this->data = $data;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(): void
+    {
+        try {
+            $machine = Machine::where('serial_no', $this->serialNo)->firstOrFail();
+            
+            // Sync inventory: typically the IoT device sends the full state
+            // If it sends partial, logic would differ. For now, we assume simple updateOrCreate per denomination.
+            if (isset($this->data['inventories']) && is_array($this->data['inventories'])) {
+                foreach ($this->data['inventories'] as $inv) {
+                    CoinInventory::updateOrCreate(
+                        [
+                            'machine_id' => $machine->id, 
+                            'denomination' => $inv['denomination'],
+                            'type' => $inv['type'] ?? 'coin'
+                        ],
+                        ['count' => $inv['count']]
+                    );
+                }
+            }
+        } catch (\Exception $e) {
+            Log::error("Failed to process coin inventory for machine {$this->serialNo}: " . $e->getMessage());
+            throw $e;
+        }
+    }
+}

app/Jobs/Machine/ProcessHeartbeat.php

@@ -0,0 +1,41 @@
+<?php
+
+namespace App\Jobs\Machine;
+
+use App\Services\Machine\MachineService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+class ProcessHeartbeat implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    protected $serialNo;
+    protected $data;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(string $serialNo, array $data)
+    {
+        $this->serialNo = $serialNo;
+        $this->data = $data;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(MachineService $machineService): void
+    {
+        try {
+            $machineService->updateHeartbeat($this->serialNo, $this->data);
+        } catch (\Exception $e) {
+            Log::error("Failed to process heartbeat for machine {$this->serialNo}: " . $e->getMessage());
+            throw $e;
+        }
+    }
+}

app/Jobs/Machine/ProcessMachineError.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Jobs\Machine;
+
+use App\Models\Machine\Machine;
+use App\Services\Machine\MachineService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+
+class ProcessMachineError implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    protected $serialNo;
+    protected $data;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(string $serialNo, array $data)
+    {
+        $this->serialNo = $serialNo;
+        $this->data = $data;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(MachineService $service): void
+    {
+        $machine = Machine::where('serial_no', $this->serialNo)->first();
+
+        if ($machine) {
+            $service->recordErrorLog($machine, $this->data);
+        }
+    }
+}

app/Jobs/Machine/ProcessRestockReport.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Jobs\Machine;
+
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Queue\Queueable;
+
+class ProcessRestockReport implements ShouldQueue
+{
+    use Queueable;
+
+    protected $data;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(array $data)
+    {
+        $this->data = $data;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(\App\Services\Machine\MachineService $machineService): void
+    {
+        $serialNo = $this->data['serial_no'] ?? null;
+        $slotsData = $this->data['slots'] ?? [];
+
+        if (!$serialNo) return;
+
+        $machine = \App\Models\Machine\Machine::where('serial_no', $serialNo)->first();
+        if ($machine) {
+            $machineService->syncSlots($machine, $slotsData);
+        }
+    }
+}

app/Jobs/Machine/ProcessStateLog.php

@@ -0,0 +1,56 @@
+<?php
+
+namespace App\Jobs\Machine;
+
+use App\Models\Machine\MachineLog;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+class ProcessStateLog implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    protected $machineId;
+    protected $companyId;
+    protected $message;
+    protected $level;
+    protected $type;
+    protected $context;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(int $machineId, ?int $companyId, string $message, string $level = 'info', array $context = [], string $type = 'status')
+    {
+        $this->machineId = $machineId;
+        $this->companyId = $companyId;
+        $this->message = $message;
+        $this->level = $level;
+        $this->context = $context;
+        $this->type = $type;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(): void
+    {
+        try {
+            MachineLog::create([
+                'machine_id' => $this->machineId,
+                'company_id' => $this->companyId,
+                'type' => $this->type,
+                'level' => $this->level,
+                'message' => $this->message,
+                'context' => $this->context,
+            ]);
+        } catch (\Exception $e) {
+            Log::error("Failed to create state log for machine {$this->machineId}: " . $e->getMessage());
+            throw $e;
+        }
+    }
+}

app/Jobs/Machine/ProcessTimerStatus.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace App\Jobs\Machine;
+
+use App\Models\Machine\Machine;
+use App\Models\Machine\TimerStatus;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+class ProcessTimerStatus implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    protected $serialNo;
+    protected $data;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(string $serialNo, array $data)
+    {
+        $this->serialNo = $serialNo;
+        $this->data = $data;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(): void
+    {
+        try {
+            $machine = Machine::where('serial_no', $this->serialNo)->firstOrFail();
+            
+            TimerStatus::updateOrCreate(
+                ['machine_id' => $machine->id, 'slot_no' => $this->data['slot_no']],
+                [
+                    'status' => $this->data['status'],
+                    'remaining_seconds' => $this->data['remaining_seconds'],
+                    'end_at' => isset($this->data['end_at']) ? \Carbon\Carbon::parse($this->data['end_at']) : null,
+                ]
+            );
+        } catch (\Exception $e) {
+            Log::error("Failed to process timer status for machine {$this->serialNo}: " . $e->getMessage());
+            throw $e;
+        }
+    }
+}

app/Jobs/Transaction/ProcessDispenseRecord.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Jobs\Transaction;
+
+use App\Services\Transaction\TransactionService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+class ProcessDispenseRecord implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    protected $data;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(array $data)
+    {
+        $this->data = $data;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(TransactionService $transactionService): void
+    {
+        try {
+            $transactionService->recordDispense($this->data);
+        } catch (\Exception $e) {
+            Log::error("Failed to record dispense for machine {$this->data['serial_no']}: " . $e->getMessage());
+            throw $e;
+        }
+    }
+}

app/Jobs/Transaction/ProcessInvoice.php

@@ -0,0 +1,42 @@
+<?php
+
+namespace App\Jobs\Transaction;
+
+use App\Services\Transaction\TransactionService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+class ProcessInvoice implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    protected $data;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(array $data)
+    {
+        $this->data = $data;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(TransactionService $transactionService): void
+    {
+        try {
+            $transactionService->recordInvoice($this->data);
+        } catch (\Exception $e) {
+            Log::error('Failed to process invoice: ' . $e->getMessage(), [
+                'data' => $this->data,
+                'exception' => $e
+            ]);
+            throw $e;
+        }
+    }
+}

app/Jobs/Transaction/ProcessTransaction.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Jobs\Transaction;
+
+use App\Services\Transaction\TransactionService;
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Foundation\Bus\Dispatchable;
+use Illuminate\Queue\InteractsWithQueue;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Support\Facades\Log;
+
+class ProcessTransaction implements ShouldQueue
+{
+    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;
+
+    protected $data;
+
+    /**
+     * Create a new job instance.
+     */
+    public function __construct(array $data)
+    {
+        $this->data = $data;
+    }
+
+    /**
+     * Execute the job.
+     */
+    public function handle(TransactionService $transactionService): void
+    {
+        try {
+            $transactionService->processTransaction($this->data);
+        } catch (\Exception $e) {
+            Log::error("Failed to process transaction: " . $e->getMessage());
+            throw $e;
+        }
+    }
+}

app/Listeners/LogSuccessfulLogin.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace App\Listeners;
+
+use App\Models\System\UserLoginLog;
+use Illuminate\Auth\Events\Login;
+use Illuminate\Http\Request;
+
+class LogSuccessfulLogin
+{
+    /**
+     * The request instance.
+     *
+     * @var \Illuminate\Http\Request
+     */
+    protected $request;
+
+    /**
+     * Create the event listener.
+     *
+     * @param  \Illuminate\Http\Request  $request
+     * @return void
+     */
+    public function __construct(Request $request)
+    {
+        $this->request = $request;
+    }
+
+    /**
+     * Handle the event.
+     *
+     * @param  \Illuminate\Auth\Events\Login  $event
+     * @return void
+     */
+    public function handle(Login $event)
+    {
+        $ip = $this->request->ip();
+        $userAgent = $this->request->userAgent();
+
+        // 防重覆機制 (Debouncing): 10 秒內同使用者、同 IP 的記錄視為重複
+        $recentLog = UserLoginLog::where('user_id', $event->user->id)
+            ->where('ip_address', $ip)
+            ->where('login_at', '>=', now()->subSeconds(10))
+            ->first();
+
+        if ($recentLog) {
+            return;
+        }
+
+        $agent = new \Jenssegers\Agent\Agent();
+        $agent->setUserAgent($userAgent);
+
+        $deviceType = 'desktop';
+        if ($agent->isTablet()) {
+            $deviceType = 'tablet';
+        } elseif ($agent->isMobile()) {
+            $deviceType = 'mobile';
+        }
+
+        UserLoginLog::create([
+            'user_id' => $event->user->id,
+            'ip_address' => $ip,
+            'user_agent' => $userAgent,
+            'device_type' => $deviceType,
+            'browser' => $agent->browser(),
+            'platform' => $agent->platform(),
+            'login_at' => now(),
+        ]);
+    }
+}

app/Models/Machine/CoinInventory.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Models\Machine;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+class CoinInventory extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'machine_id',
+        'denomination',
+        'count',
+        'type',
+    ];
+
+    public function machine()
+    {
+        return $this->belongsTo(Machine::class);
+    }
+}

app/Models/Machine/Machine.php

@@ -5,26 +5,245 @@ namespace App\Models\Machine;
 use Illuminate\Database\Eloquent\Factories\HasFactory;
 use Illuminate\Database\Eloquent\Model;
 
+use App\Traits\TenantScoped;
+
 class Machine extends Model
 {
-    use HasFactory;
+    use HasFactory, TenantScoped;
+    use \Illuminate\Database\Eloquent\SoftDeletes;
+
+    protected static function booted()
+    {
+        // 權限隔離：一般帳號登入時只能看到自己被分配的機台
+        static::addGlobalScope('machine_access', function (\Illuminate\Database\Eloquent\Builder $builder) {
+            $user = auth()->user();
+            // 如果是在 Console、或是系統管理員，則不限制 (可看所有機台)
+            if (app()->runningInConsole() || !$user || $user->isSystemAdmin()) {
+                return;
+            }
+
+            // 一般租戶帳號：限制只能看自己擁有的機台
+            $builder->whereExists(function ($query) use ($user) {
+                $query->select(\Illuminate\Support\Facades\DB::raw(1))
+                    ->from('machine_user')
+                    ->whereColumn('machine_user.machine_id', 'machines.id')
+                    ->where('machine_user.user_id', $user->id);
+            });
+        });
+    }
 
     protected $fillable = [
+        'company_id',
         'name',
+        'serial_no',
+        'model',
         'location',
-        'status',
+        'current_page',
+        'door_status',
         'temperature',
         'firmware_version',
+        'api_token',
         'last_heartbeat_at',
+        'card_reader_seconds',
+        'card_reader_checkout_time_1',
+        'card_reader_checkout_time_2',
+        'heating_start_time',
+        'heating_end_time',
+        'payment_buffer_seconds',
+        'card_reader_no',
+        'key_no',
+        'invoice_status',
+        'welcome_gift_enabled',
+        'is_spring_slot_1_10',
+        'is_spring_slot_11_20',
+        'is_spring_slot_21_30',
+        'is_spring_slot_31_40',
+        'is_spring_slot_41_50',
+        'is_spring_slot_51_60',
+        'member_system_enabled',
+        'payment_config_id',
+        'machine_model_id',
+        'images',
+        'creator_id',
+        'updater_id',
     ];
 
+    protected $appends = ['image_urls', 'calculated_status'];
+
+    /**
+     * 動態計算機台當前狀態
+     * 1. 離線 (offline)：超過 30 秒未收到心跳
+     * 2. 異常 (error)：在線但過去 15 分鐘內有錯誤/警告日誌
+     * 3. 在線 (online)：正常在線
+     */
+    public function getCalculatedStatusAttribute(): string
+    {
+        // 判定離線
+        if (!$this->last_heartbeat_at || $this->last_heartbeat_at->diffInSeconds(now()) >= 30) {
+            return 'offline';
+        }
+
+        // 判定異常 (檢查過去 15 分鐘內是否有 error 或 warning 日誌)
+        $hasRecentErrors = $this->logs()
+            ->whereIn('level', ['error', 'warning'])
+            ->where('created_at', '>=', now()->subMinutes(15))
+            ->exists();
+
+        if ($hasRecentErrors) {
+            return 'error';
+        }
+
+        return 'online';
+    }
+
+    /**
+     * Scope: 判定在線 (30 秒內有心跳)
+     */
+    public function scopeOnline($query)
+    {
+        return $query->where('last_heartbeat_at', '>=', now()->subSeconds(30));
+    }
+
+    /**
+     * Scope: 判定離線 (超過 30 秒未收到心跳或從未收到心跳)
+     */
+    public function scopeOffline($query)
+    {
+        return $query->where(function ($q) {
+            $q->whereNull('last_heartbeat_at')
+                ->orWhere('last_heartbeat_at', '<', now()->subSeconds(30));
+        });
+    }
+
+    /**
+     * Scope: 判定異常 (過去 15 分鐘內有錯誤或警告日誌)
+     */
+    public function scopeHasError($query)
+    {
+        return $query->whereExists(function ($q) {
+            $q->select(\Illuminate\Support\Facades\DB::raw(1))
+                ->from('machine_logs')
+                ->whereColumn('machine_logs.machine_id', 'machines.id')
+                ->whereIn('level', ['error', 'warning'])
+                ->where('created_at', '>=', now()->subMinutes(15));
+        });
+    }
+
+    /**
+     * Scope: 判定運行中 (在線且無近期異常)
+     */
+    public function scopeRunning($query)
+    {
+        return $query->online()->whereNotExists(function ($q) {
+            $q->select(\Illuminate\Support\Facades\DB::raw(1))
+                ->from('machine_logs')
+                ->whereColumn('machine_logs.machine_id', 'machines.id')
+                ->whereIn('level', ['error', 'warning'])
+                ->where('created_at', '>=', now()->subMinutes(15));
+        });
+    }
+
+    /**
+     * Scope: 判定異常在線 (在線且有近期異常)
+     */
+    public function scopeErrorOnline($query)
+    {
+        return $query->online()->hasError();
+    }
+
     protected $casts = [
         'last_heartbeat_at' => 'datetime',
+        'welcome_gift_enabled' => 'boolean',
+        'is_spring_slot_1_10' => 'boolean',
+        'is_spring_slot_11_20' => 'boolean',
+        'is_spring_slot_21_30' => 'boolean',
+        'is_spring_slot_31_40' => 'boolean',
+        'is_spring_slot_41_50' => 'boolean',
+        'is_spring_slot_51_60' => 'boolean',
+        'member_system_enabled' => 'boolean',
+        'images' => 'array',
     ];
 
+    /**
+     * Get machine images absolute URLs
+     */
+    public function getImageUrlsAttribute(): array
+    {
+        if (empty($this->images)) {
+            return [];
+        }
+
+        return array_map(fn($path) => \Illuminate\Support\Facades\Storage::disk('public')->url($path), $this->images);
+    }
+
     public function logs()
     {
         return $this->hasMany(MachineLog::class);
     }
 
+    public function slots()
+    {
+        return $this->hasMany(MachineSlot::class);
+    }
+
+    public function commands()
+    {
+        return $this->hasMany(RemoteCommand::class);
+    }
+
+    public function machineModel()
+    {
+        return $this->belongsTo(MachineModel::class);
+    }
+
+    public function paymentConfig()
+    {
+        return $this->belongsTo(\App\Models\System\PaymentConfig::class);
+    }
+
+    public function creator()
+    {
+        return $this->belongsTo(\App\Models\System\User::class, 'creator_id');
+    }
+
+    public function updater()
+    {
+        return $this->belongsTo(\App\Models\System\User::class, 'updater_id');
+    }
+
+    public const PAGE_STATUSES = [
+        '0' => 'Offline',
+        '1' => 'Home Page',
+        '2' => 'Vending Page',
+        '3' => 'Admin Page',
+        '4' => 'Replenishment Page',
+        '5' => 'Tutorial Page',
+        '6' => 'Purchasing',
+        '7' => 'Locked Page',
+        '60' => 'Dispense Success',
+        '61' => 'Slot Test',
+        '62' => 'Payment Selection',
+        '63' => 'Waiting for Payment',
+        '64' => 'Dispensing',
+        '65' => 'Receipt Printing',
+        '66' => 'Pass Code',
+        '67' => 'Pickup Code',
+        '68' => 'Message Display',
+        '69' => 'Cancel Purchase',
+        '610' => 'Purchase Finished',
+        '611' => 'Welcome Gift',
+        '612' => 'Dispense Failed',
+    ];
+
+    public function getCurrentPageLabelAttribute(): string
+    {
+        $code = (string) $this->current_page;
+        $label = self::PAGE_STATUSES[$code] ?? $code;
+        return __($label);
+    }
+
+    public function users()
+    {
+        return $this->belongsToMany(\App\Models\System\User::class);
+    }
 }

app/Models/Machine/MachineAdvertisement.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace App\Models\Machine;
+
+use App\Models\System\Advertisement;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+class MachineAdvertisement extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'machine_id',
+        'advertisement_id',
+        'position',
+        'sort_order',
+        'start_at',
+        'end_at',
+    ];
+
+    protected $casts = [
+        'sort_order' => 'integer',
+        'start_at' => 'datetime',
+        'end_at' => 'datetime',
+    ];
+
+    /**
+     * Get the advertisement associated with this assignment.
+     */
+    public function advertisement()
+    {
+        return $this->belongsTo(Advertisement::class);
+    }
+
+    /**
+     * Get the machine associated with this assignment.
+     */
+    public function machine()
+    {
+        return $this->belongsTo(Machine::class);
+    }
+}

app/Models/Machine/MachineLog.php

@@ -12,8 +12,10 @@ class MachineLog extends Model
     const UPDATED_AT = null;
 
     protected $fillable = [
+        'company_id',
         'machine_id',
         'level',
+        'type',
         'message',
         'context',
     ];
@@ -22,6 +24,33 @@ class MachineLog extends Model
         'context' => 'array',
     ];
 
+    protected $appends = [
+        'translated_message',
+    ];
+
+    /**
+     * 動態重組翻譯後的訊息
+     */
+    public function getTranslatedMessageAttribute(): string
+    {
+        $context = $this->context;
+
+        // 若 context 中已有翻譯標籤 (B013 封裝)，則進行動態重組
+        if (isset($context['translated_label'])) {
+            $label = __($context['translated_label']);
+            $tid = $context['tid'] ?? null;
+            $code = $context['raw_code'] ?? '0000';
+
+            if ($tid) {
+                return __('Slot') . " {$tid}: {$label} (Code: {$code})";
+            }
+            return "{$label} (Code: {$code})";
+        }
+
+        // 預設退回原始 message (支援歷史資料的翻譯判定與佔位符替換)
+        return __($this->message, $context ?? []);
+    }
+
     public function machine()
     {
         return $this->belongsTo(Machine::class);

app/Models/Machine/MachineModel.php

@@ -0,0 +1,37 @@
+<?php
+
+namespace App\Models\Machine;
+
+use Illuminate\Database\Eloquent\Model;
+use App\Traits\TenantScoped;
+
+class MachineModel extends Model
+{
+    use TenantScoped;
+    protected $fillable = [
+        'name',
+        'company_id',
+        'creator_id',
+        'updater_id',
+    ];
+
+    public function machines()
+    {
+        return $this->hasMany(Machine::class);
+    }
+
+    public function company()
+    {
+        return $this->belongsTo(\App\Models\System\Company::class);
+    }
+
+    public function creator()
+    {
+        return $this->belongsTo(\App\Models\System\User::class, 'creator_id');
+    }
+
+    public function updater()
+    {
+        return $this->belongsTo(\App\Models\System\User::class, 'updater_id');
+    }
+}

app/Models/Machine/MachineSlot.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Models\Machine;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use App\Models\Product\Product;
+
+class MachineSlot extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'machine_id',
+        'product_id',
+        'slot_no',
+        'type',
+        'max_stock',
+        'stock',
+        'expiry_date',
+        'batch_no',
+        'is_active',
+    ];
+
+    protected $casts = [
+        'price' => 'decimal:2',
+        'last_restocked_at' => 'datetime',
+        'expiry_date' => 'date:Y-m-d',
+    ];
+
+    public function machine()
+    {
+        return $this->belongsTo(Machine::class);
+    }
+
+    public function product()
+    {
+        return $this->belongsTo(Product::class);
+    }
+}

app/Models/Machine/MaintenanceRecord.php

@@ -0,0 +1,47 @@
+<?php
+
+namespace App\Models\Machine;
+
+use Illuminate\Database\Eloquent\Model;
+
+use App\Traits\TenantScoped;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use App\Models\System\User;
+use App\Models\Machine\Machine;
+
+class MaintenanceRecord extends Model
+{
+    use TenantScoped, SoftDeletes;
+
+    protected $fillable = [
+        'company_id',
+        'machine_id',
+        'user_id',
+        'category',
+        'content',
+        'photos',
+        'maintenance_at',
+        'is_confirmed',
+    ];
+
+    protected $casts = [
+        'photos' => 'array',
+        'maintenance_at' => 'datetime',
+        'is_confirmed' => 'boolean',
+    ];
+
+    public function machine()
+    {
+        return $this->belongsTo(Machine::class);
+    }
+
+    public function user()
+    {
+        return $this->belongsTo(User::class);
+    }
+
+    public function company()
+    {
+        return $this->belongsTo(\App\Models\System\Company::class);
+    }
+}

app/Models/Machine/RemoteCommand.php

@@ -0,0 +1,44 @@
+<?php
+
+namespace App\Models\Machine;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+class RemoteCommand extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'machine_id',
+        'user_id',
+        'command_type',
+        'payload',
+        'status',
+        'ttl',
+        'executed_at',
+    ];
+
+    protected $casts = [
+        'payload' => 'array',
+        'executed_at' => 'datetime',
+    ];
+
+    public function machine()
+    {
+        return $this->belongsTo(Machine::class);
+    }
+
+    public function user()
+    {
+        return $this->belongsTo(\App\Models\System\User::class);
+    }
+
+    /**
+     * Scope for pending commands
+     */
+    public function scopePending($query)
+    {
+        return $query->where('status', 'pending')->orderBy('created_at', 'asc');
+    }
+}

app/Models/Machine/TimerStatus.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace App\Models\Machine;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+class TimerStatus extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'machine_id',
+        'slot_no',
+        'status',
+        'remaining_seconds',
+        'end_at',
+    ];
+
+    protected $casts = [
+        'end_at' => 'datetime',
+    ];
+
+    public function machine()
+    {
+        return $this->belongsTo(Machine::class);
+    }
+}

app/Models/Member/Member.php

@@ -31,6 +31,10 @@ class Member extends Authenticatable
         'avatar',
         'is_active',
         'email_verified_at',
+        'company_id',
+        'barcode',
+        'points',
+        'wallet_balance',
     ];
 
     /**
@@ -49,6 +53,8 @@ class Member extends Authenticatable
         'birthday' => 'date',
         'is_active' => 'boolean',
         'password' => 'hashed',
+        'points' => 'integer',
+        'wallet_balance' => 'decimal:2',
     ];
 
     /**

app/Models/Product/Product.php

@@ -0,0 +1,93 @@
+<?php
+
+namespace App\Models\Product;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use App\Traits\TenantScoped;
+
+class Product extends Model
+{
+    use HasFactory, SoftDeletes, TenantScoped;
+    
+    /**
+     * Scope a query to only include active products.
+     */
+    public function scopeActive($query)
+    {
+        return $query->where('is_active', true);
+    }
+
+    protected $fillable = [
+        'company_id',
+        'category_id',
+        'name',
+        'name_dictionary_key',
+        'barcode',
+        'spec',
+        'manufacturer',
+        'description',
+        'price',
+        'member_price',
+        'cost',
+        'track_limit',
+        'spring_limit',
+        'type',
+        'image_url',
+        'status',
+        'is_active',
+        'metadata',
+    ];
+
+    protected $casts = [
+        'price' => 'decimal:2',
+        'member_price' => 'decimal:2',
+        'cost' => 'decimal:2',
+        'track_limit' => 'integer',
+        'spring_limit' => 'integer',
+        'is_active' => 'boolean',
+        'metadata' => 'array',
+    ];
+
+    public function category()
+    {
+        return $this->belongsTo(ProductCategory::class, 'category_id');
+    }
+
+    /**
+     * 自動附加到 JSON/陣列輸出的屬性（供 Alpine.js 等前端使用）
+     */
+    protected $appends = ['localized_name'];
+
+    /**
+     * 取得當前語系的商品名稱。
+     * 回退順序：當前語系 → zh_TW → name 欄位
+     */
+    public function getLocalizedNameAttribute(): string
+    {
+        if ($this->relationLoaded('translations') && $this->translations->isNotEmpty()) {
+            $locale = app()->getLocale();
+            // 先找當前語系
+            $translation = $this->translations->firstWhere('locale', $locale);
+            if ($translation) {
+                return $translation->value;
+            }
+            // 回退至 zh_TW
+            $fallback = $this->translations->firstWhere('locale', 'zh_TW');
+            if ($fallback) {
+                return $fallback->value;
+            }
+        }
+        return $this->name ?? '';
+    }
+
+    /**
+     * Get the translations for the product name.
+     */
+    public function translations()
+    {
+        return $this->hasMany(\App\Models\System\Translation::class, 'key', 'name_dictionary_key')
+            ->where('group', 'product');
+    }
+}

app/Models/Product/ProductCategory.php

@@ -0,0 +1,60 @@
+<?php
+
+namespace App\Models\Product;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use App\Traits\TenantScoped;
+
+class ProductCategory extends Model
+{
+    use HasFactory, SoftDeletes, TenantScoped;
+
+    protected $fillable = [
+        'company_id',
+        'name',
+        'name_dictionary_key',
+    ];
+
+    /**
+     * 自動附加到 JSON/陣列輸出
+     */
+    protected $appends = ['localized_name'];
+
+    public function products()
+    {
+        return $this->hasMany(Product::class, 'category_id');
+    }
+
+    /**
+     * Get the translations for the category name.
+     */
+    public function translations()
+    {
+        return $this->hasMany(\App\Models\System\Translation::class, 'key', 'name_dictionary_key')
+            ->where('group', 'category');
+    }
+
+    /**
+     * 取得當前語系的商品名稱。
+     * 回退順序：當前語系 → zh_TW → name 欄位
+     */
+    public function getLocalizedNameAttribute(): string
+    {
+        if ($this->relationLoaded('translations') && $this->translations->isNotEmpty()) {
+            $locale = app()->getLocale();
+            // 先找當前語系
+            $translation = $this->translations->firstWhere('locale', $locale);
+            if ($translation) {
+                return $translation->value;
+            }
+            // 回退至 zh_TW
+            $fallback = $this->translations->firstWhere('locale', 'zh_TW');
+            if ($fallback) {
+                return $fallback->value;
+            }
+        }
+        return $this->name ?? '';
+    }
+}

app/Models/System/Advertisement.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace App\Models\System;
+
+use App\Models\Machine\MachineAdvertisement;
+use App\Traits\TenantScoped;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+class Advertisement extends Model
+{
+    use HasFactory, TenantScoped;
+
+    protected $fillable = [
+        'company_id',
+        'name',
+        'type',
+        'duration',
+        'url',
+        'is_active',
+        'start_at',
+        'end_at',
+    ];
+
+    protected $casts = [
+        'duration' => 'integer',
+        'is_active' => 'boolean',
+        'start_at' => 'datetime',
+        'end_at' => 'datetime',
+    ];
+
+    /**
+     * Get the machine assignments for this advertisement.
+     */
+    public function machineAdvertisements()
+    {
+        return $this->hasMany(MachineAdvertisement::class);
+    }
+
+    /**
+     * Get the company that owns the advertisement.
+     */
+    public function company()
+    {
+        return $this->belongsTo(Company::class);
+    }
+
+    /**
+     * Scope a query to only include active advertisements.
+     */
+    public function scopeActive($query)
+    {
+        return $query->where('is_active', true);
+    }
+
+    /**
+     * Scope a query to only include advertisements that should be playing now.
+     */
+    public function scopePlaying($query)
+    {
+        $now = now();
+        return $query->where('is_active', true)
+            ->where(function ($q) use ($now) {
+                $q->whereNull('start_at')
+                    ->orWhere('start_at', '<=', $now);
+            })
+            ->where(function ($q) use ($now) {
+                $q->whereNull('end_at')
+                    ->orWhere('end_at', '>=', $now);
+            });
+    }
+}

app/Models/System/Company.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace App\Models\System;
+
+use App\Models\Machine\Machine;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\HasMany;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Spatie\Permission\Models\Role;
+
+class Company extends Model
+{
+    use HasFactory, SoftDeletes;
+
+    protected $fillable = [
+        'name',
+        'code',
+        'original_type',
+        'current_type',
+        'tax_id',
+        'contact_name',
+        'contact_phone',
+        'contact_email',
+        'status',
+        'start_date',
+        'end_date',
+        'warranty_start_date',
+        'warranty_end_date',
+        'software_start_date',
+        'software_end_date',
+        'note',
+        'settings',
+    ];
+
+    protected $casts = [
+        'start_date' => 'date:Y-m-d',
+        'end_date' => 'date:Y-m-d',
+        'warranty_start_date' => 'date:Y-m-d',
+        'warranty_end_date' => 'date:Y-m-d',
+        'software_start_date' => 'date:Y-m-d',
+        'software_end_date' => 'date:Y-m-d',
+        'status' => 'integer',
+        'settings' => 'array',
+    ];
+
+    /**
+     * Get the contract history for the company.
+     */
+    public function contracts(): HasMany
+    {
+        return $this->hasMany(CompanyContract::class)->latest();
+    }
+
+    /**
+     * Get the users for the company.
+     */
+    public function users(): HasMany
+    {
+        return $this->hasMany(User::class);
+    }
+
+    /**
+     * Get the machines for the company.
+     */
+    public function machines(): HasMany
+    {
+        return $this->hasMany(Machine::class);
+    }
+}

app/Models/System/CompanyContract.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace App\Models\System;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Relations\BelongsTo;
+
+class CompanyContract extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'company_id',
+        'type',
+        'start_date',
+        'end_date',
+        'warranty_start_date',
+        'warranty_end_date',
+        'software_start_date',
+        'software_end_date',
+        'note',
+        'creator_id',
+    ];
+
+    protected $casts = [
+        'start_date' => 'date:Y-m-d',
+        'end_date' => 'date:Y-m-d',
+        'warranty_start_date' => 'date:Y-m-d',
+        'warranty_end_date' => 'date:Y-m-d',
+        'software_start_date' => 'date:Y-m-d',
+        'software_end_date' => 'date:Y-m-d',
+    ];
+
+    /**
+     * Get the company that owns the contract.
+     */
+    public function company(): BelongsTo
+    {
+        return $this->belongsTo(Company::class);
+    }
+
+    /**
+     * Get the user who created the record.
+     */
+    public function creator(): BelongsTo
+    {
+        return $this->belongsTo(User::class, 'creator_id');
+    }
+}

app/Models/System/PaymentConfig.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace App\Models\System;
+
+use Illuminate\Database\Eloquent\Model;
+
+class PaymentConfig extends Model
+{
+    protected $fillable = [
+        'company_id',
+        'name',
+        'settings',
+        'creator_id',
+        'updater_id',
+    ];
+
+    protected $casts = [
+        'settings' => 'array',
+    ];
+
+    public function machines()
+    {
+        return $this->hasMany(\App\Models\Machine\Machine::class);
+    }
+
+    public function company()
+    {
+        return $this->belongsTo(\App\Models\System\Company::class);
+    }
+
+    public function creator()
+    {
+        return $this->belongsTo(User::class, 'creator_id');
+    }
+
+    public function updater()
+    {
+        return $this->belongsTo(User::class, 'updater_id');
+    }
+}

app/Models/System/Role.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace App\Models\System;
+
+use Spatie\Permission\Models\Role as SpatieRole;
+
+class Role extends SpatieRole
+{
+    protected $fillable = [
+        'name',
+        'guard_name',
+        'company_id',
+        'is_system',
+    ];
+
+    protected $casts = [
+        'is_system' => 'boolean',
+    ];
+
+    /**
+     * Get the company that owns the role.
+     */
+    public function company()
+    {
+        return $this->belongsTo(Company::class);
+    }
+
+    /**
+     * Scope a query to only include roles for a specific company or system roles.
+     */
+    public function scopeForCompany($query, $company_id)
+    {
+        return $query->where(function($q) use ($company_id) {
+            $q->where('company_id', $company_id)
+              ->orWhereNull('company_id');
+        });
+    }
+}

app/Models/System/Translation.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace App\Models\System;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+
+class Translation extends Model
+{
+    use HasFactory, \App\Traits\TenantScoped;
+
+    protected $fillable = [
+        'company_id',
+        'group',
+        'key',
+        'locale',
+        'value',
+    ];
+}

app/Models/System/User.php

@@ -8,9 +8,13 @@ use Illuminate\Foundation\Auth\User as Authenticatable;
 use Illuminate\Notifications\Notifiable;
 use Laravel\Sanctum\HasApiTokens;
 
+use App\Traits\TenantScoped;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use Spatie\Permission\Traits\HasRoles;
+
 class User extends Authenticatable
 {
-    use HasApiTokens, HasFactory, Notifiable;
+    use HasApiTokens, HasFactory, Notifiable, HasRoles, TenantScoped, SoftDeletes;
 
     /**
      * The attributes that are mass assignable.
@@ -18,6 +22,7 @@ class User extends Authenticatable
      * @var array<int, string>
      */
     protected $fillable = [
+        'company_id',
         'username',
         'name',
         'email',
@@ -25,6 +30,8 @@ class User extends Authenticatable
         'phone',
         'avatar',
         'role',
+        'status',
+        'is_admin',
     ];
 
     /**
@@ -45,5 +52,59 @@ class User extends Authenticatable
     protected $casts = [
         'email_verified_at' => 'datetime',
         'password' => 'hashed',
+        'is_admin' => 'boolean',
     ];
+
+    /**
+     * Get the login logs for the user.
+     */
+    public function loginLogs()
+    {
+        return $this->hasMany(UserLoginLog::class);
+    }
+
+    /**
+     * Get the company that owns the user.
+     */
+    public function company()
+    {
+        return $this->belongsTo(Company::class);
+    }
+
+    /**
+     * Get the machines assigned to the user.
+     */
+    public function machines()
+    {
+        return $this->belongsToMany(\App\Models\Machine\Machine::class);
+    }
+
+    /**
+     * Check if the user is a system administrator.
+     */
+    public function isSystemAdmin(): bool
+    {
+        return is_null($this->company_id);
+    }
+
+    /**
+     * Check if the user belongs to a tenant.
+     */
+    public function isTenant(): bool
+    {
+        return !is_null($this->company_id);
+    }
+
+    /**
+     * Get the URL for the user's avatar.
+     */
+    public function getAvatarUrlAttribute(): string
+    {
+        if ($this->avatar) {
+            return \Illuminate\Support\Facades\Storage::disk('public')->url($this->avatar);
+        }
+
+        // Return a default UI Avatar if no avatar is set
+        return "https://ui-avatars.com/api/?name=" . urlencode($this->name) . "&color=7F9CF5&background=EBF4FF";
+    }
 }

app/Models/System/UserLoginLog.php

@@ -0,0 +1,30 @@
+<?php
+
+namespace App\Models\System;
+
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+
+class UserLoginLog extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'user_id',
+        'ip_address',
+        'user_agent',
+        'device_type',
+        'browser',
+        'platform',
+        'login_at',
+    ];
+
+    protected $casts = [
+        'login_at' => 'datetime',
+    ];
+
+    public function user()
+    {
+        return $this->belongsTo(User::class);
+    }
+}

app/Models/Transaction/DispenseRecord.php

@@ -0,0 +1,50 @@
+<?php
+
+namespace App\Models\Transaction;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use App\Models\Machine\Machine;
+use App\Models\Product\Product;
+
+class DispenseRecord extends Model
+{
+    use HasFactory, SoftDeletes;
+
+    protected $fillable = [
+        'company_id',
+        'order_id',
+        'flow_id',
+        'machine_id',
+        'product_id',
+        'slot_no',
+        'amount',
+        'remaining_stock',
+        'dispense_status',
+        'member_barcode',
+        'machine_time',
+        'points_used',
+    ];
+
+    protected $casts = [
+        'amount' => 'decimal:2',
+        'machine_time' => 'datetime',
+        'dispense_status' => 'integer',
+    ];
+
+    public function order()
+    {
+        return $this->belongsTo(Order::class);
+    }
+
+    public function machine()
+    {
+        return $this->belongsTo(Machine::class);
+    }
+
+    public function product()
+    {
+        return $this->belongsTo(Product::class);
+    }
+}

app/Models/Transaction/Invoice.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Models\Transaction;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+class Invoice extends Model
+{
+    use HasFactory, SoftDeletes;
+
+    protected $fillable = [
+        'company_id',
+        'order_id',
+        'machine_id',
+        'flow_id',
+        'invoice_no',
+        'amount',
+        'carrier_id',
+        'invoice_date',
+        'random_number',
+        'love_code',
+        'rtn_code',
+        'rtn_msg',
+        'metadata',
+    ];
+
+    protected $casts = [
+        'total_amount' => 'decimal:2',
+        'tax_amount' => 'decimal:2',
+        'metadata' => 'array',
+    ];
+
+    public function order()
+    {
+        return $this->belongsTo(Order::class);
+    }
+}

app/Models/Transaction/Order.php

@@ -0,0 +1,64 @@
+<?php
+
+namespace App\Models\Transaction;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\SoftDeletes;
+use App\Traits\TenantScoped;
+use App\Models\Machine\Machine;
+use App\Models\Member\Member;
+
+class Order extends Model
+{
+    use HasFactory, SoftDeletes, TenantScoped;
+
+    protected $fillable = [
+        'company_id',
+        'flow_id',
+        'order_no',
+        'machine_id',
+        'member_id',
+        'total_amount',
+        'discount_amount',
+        'pay_amount',
+        'payment_type',
+        'payment_status',
+        'payment_at',
+        'status',
+        'metadata',
+    ];
+
+    protected $casts = [
+        'total_amount' => 'decimal:2',
+        'discount_amount' => 'decimal:2',
+        'pay_amount' => 'decimal:2',
+        'payment_at' => 'datetime',
+        'metadata' => 'array',
+    ];
+
+    public function machine()
+    {
+        return $this->belongsTo(Machine::class);
+    }
+
+    public function member()
+    {
+        return $this->belongsTo(Member::class);
+    }
+
+    public function items()
+    {
+        return $this->hasMany(OrderItem::class);
+    }
+
+    public function invoice()
+    {
+        return $this->hasOne(Invoice::class);
+    }
+
+    public function dispenseRecords()
+    {
+        return $this->hasMany(DispenseRecord::class);
+    }
+}

app/Models/Transaction/OrderItem.php

@@ -0,0 +1,39 @@
+<?php
+
+namespace App\Models\Transaction;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use App\Models\Product\Product;
+
+class OrderItem extends Model
+{
+    use HasFactory;
+
+    protected $fillable = [
+        'order_id',
+        'product_id',
+        'product_name',
+        'barcode',
+        'price',
+        'quantity',
+        'subtotal',
+        'metadata',
+    ];
+
+    protected $casts = [
+        'price' => 'decimal:2',
+        'subtotal' => 'decimal:2',
+        'metadata' => 'array',
+    ];
+
+    public function order()
+    {
+        return $this->belongsTo(Order::class);
+    }
+
+    public function product()
+    {
+        return $this->belongsTo(Product::class);
+    }
+}

app/Models/Transaction/PaymentType.php

@@ -0,0 +1,23 @@
+<?php
+
+namespace App\Models\Transaction;
+
+use Illuminate\Database\Eloquent\Factories\HasFactory;
+use Illuminate\Database\Eloquent\Model;
+use Illuminate\Database\Eloquent\SoftDeletes;
+
+class PaymentType extends Model
+{
+    use HasFactory, SoftDeletes;
+
+    protected $fillable = [
+        'name',
+        'code',
+        'config',
+        'status',
+    ];
+
+    protected $casts = [
+        'config' => 'array',
+    ];
+}

app/Policies/Machine/MaintenanceRecordPolicy.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace App\Policies\Machine;
+
+use App\Models\Machine\MaintenanceRecord;
+use App\Models\System\User;
+use Illuminate\Auth\Access\Response;
+
+class MaintenanceRecordPolicy
+{
+    /**
+     * Determine whether the user can view any models.
+     */
+    public function viewAny(User $user): bool
+    {
+        return $user->can('menu.machines.maintenance');
+    }
+
+    /**
+     * Determine whether the user can view the model.
+     */
+    public function view(User $user, MaintenanceRecord $maintenanceRecord): bool
+    {
+        return $user->can('menu.machines.maintenance');
+    }
+
+    /**
+     * Determine whether the user can create models.
+     */
+    public function create(User $user): bool
+    {
+        return $user->can('menu.machines.maintenance');
+    }
+
+    /**
+     * Determine whether the user can update the model.
+     */
+    public function update(User $user, MaintenanceRecord $maintenanceRecord): bool
+    {
+        return $user->can('menu.machines.maintenance');
+    }
+
+    /**
+     * Determine whether the user can delete the model.
+     */
+    public function delete(User $user, MaintenanceRecord $maintenanceRecord): bool
+    {
+        return $user->isSystemAdmin() && $user->can('menu.machines.maintenance');
+    }
+
+    /**
+     * Determine whether the user can restore the model.
+     */
+    public function restore(User $user, MaintenanceRecord $maintenanceRecord): bool
+    {
+        return false;
+    }
+
+    /**
+     * Determine whether the user can permanently delete the model.
+     */
+    public function forceDelete(User $user, MaintenanceRecord $maintenanceRecord): bool
+    {
+        return false;
+    }
+}

app/Providers/AppServiceProvider.php

@@ -2,6 +2,9 @@
 
 namespace App\Providers;
 
+use App\Listeners\LogSuccessfulLogin;
+use Illuminate\Auth\Events\Login;
+use Illuminate\Support\Facades\Event;
 use Illuminate\Support\ServiceProvider;
 
 class AppServiceProvider extends ServiceProvider
@@ -19,8 +22,9 @@ class AppServiceProvider extends ServiceProvider
      */
     public function boot(): void
     {
-        if (!$this->app->isLocal()) {
+        if (str_starts_with(config('app.url'), 'https://')) {
             \Illuminate\Support\Facades\URL::forceScheme('https');
         }
     }
 }
+

app/Providers/AuthServiceProvider.php

@@ -13,7 +13,7 @@ class AuthServiceProvider extends ServiceProvider
      * @var array<class-string, class-string>
      */
     protected $policies = [
-        //
+        \App\Models\Machine\MaintenanceRecord::class => \App\Policies\Machine\MaintenanceRecordPolicy::class,
     ];
 
     /**

app/Providers/EventServiceProvider.php

@@ -2,6 +2,8 @@
 
 namespace App\Providers;
 
+use App\Listeners\LogSuccessfulLogin;
+use Illuminate\Auth\Events\Login;
 use Illuminate\Auth\Events\Registered;
 use Illuminate\Auth\Listeners\SendEmailVerificationNotification;
 use Illuminate\Foundation\Support\Providers\EventServiceProvider as ServiceProvider;
@@ -18,6 +20,9 @@ class EventServiceProvider extends ServiceProvider
         Registered::class => [
             SendEmailVerificationNotification::class,
         ],
+        Login::class => [
+            LogSuccessfulLogin::class,
+        ],
     ];
 
     /**

app/Services/Machine/MachineService.php

@@ -4,42 +4,439 @@ namespace App\Services\Machine;
 
 use App\Models\Machine\Machine;
 use App\Models\Machine\MachineLog;
-use Illuminate\Support\Facades\Log;
+use App\Models\Machine\RemoteCommand;
+use Illuminate\Support\Facades\DB;
+use Carbon\Carbon;
 
 class MachineService
 {
     /**
-     * 處理機台日誌寫入與狀態更新
+     * B013: 硬體狀態代碼對照表 (Hardware Status Code Mapping)
+     */
+    public const ERROR_CODE_MAP = [
+        // 出貨狀態類 (Prefix: 04 - BUY_STATUS)
+        '0401' => ['label' => 'Dispensing in progress', 'level' => 'info'],
+        '0402' => ['label' => 'Dispense successful', 'level' => 'info'],
+        '0403' => ['label' => 'Slot jammed', 'level' => 'error'],
+        '0404' => ['label' => 'Motor not stopped', 'level' => 'warning'],
+        '0406' => ['label' => 'Slot not found', 'level' => 'error'],
+        '0407' => ['label' => 'Dispense error (0407)', 'level' => 'error'],
+        '0408' => ['label' => 'Dispense error (0408)', 'level' => 'error'],
+        '0409' => ['label' => 'Dispense error (0409)', 'level' => 'error'],
+        '040A' => ['label' => 'Dispense error (040A)', 'level' => 'error'],
+        '0410' => ['label' => 'Elevator rising', 'level' => 'info'],
+        '0411' => ['label' => 'Elevator descending', 'level' => 'info'],
+        '0412' => ['label' => 'Elevator rise error', 'level' => 'error'],
+        '0413' => ['label' => 'Elevator descent error', 'level' => 'error'],
+        '0414' => ['label' => 'Pickup door closed', 'level' => 'info'],
+        '0415' => ['label' => 'Pickup door error', 'level' => 'error'],
+        '0416' => ['label' => 'Delivery door opened', 'level' => 'info'],
+        '0417' => ['label' => 'Delivery door open error', 'level' => 'error'],
+        '0418' => ['label' => 'Delivering product', 'level' => 'info'],
+        '0419' => ['label' => 'Delivery door closed', 'level' => 'info'],
+        '0420' => ['label' => 'Delivery door close error', 'level' => 'error'],
+        '0421' => ['label' => 'Hopper empty', 'level' => 'warning'],
+        '0422' => ['label' => 'Hopper overheated', 'level' => 'warning'],
+        '0423' => ['label' => 'Hopper heating timeout', 'level' => 'error'],
+        '0424' => ['label' => 'Hopper error (0424)', 'level' => 'error'],
+        '0426' => ['label' => 'Microwave door opened', 'level' => 'info'],
+        '0427' => ['label' => 'Microwave door error', 'level' => 'error'],
+        '04FF' => ['label' => 'Dispense stopped', 'level' => 'info'],
+
+        // 貨道狀態類 (Prefix: 02 - SLOT_STATUS)
+        '0201' => ['label' => 'Slot normal', 'level' => 'info'],
+        '0202' => ['label' => 'Product empty', 'level' => 'warning'],
+        '0203' => ['label' => 'Slot empty', 'level' => 'warning'],
+        '0206' => ['label' => 'Slot not closed', 'level' => 'warning'],
+        '0207' => ['label' => 'Slot motor error (0207)', 'level' => 'error'],
+        '0208' => ['label' => 'Slot motor error (0208)', 'level' => 'error'],
+        '0209' => ['label' => 'Slot motor error (0209)', 'level' => 'error'],
+        '0212' => ['label' => 'Hopper empty (0212)', 'level' => 'warning'],
+
+        // 機台整體狀態類 (Prefix: 54 - MACHINE_STATUS)
+        '5400' => ['label' => 'Machine normal', 'level' => 'info'],
+        '5401' => ['label' => 'Elevator sensor error', 'level' => 'error'],
+        '5402' => ['label' => 'Pickup door not closed', 'level' => 'warning'],
+        '5403' => ['label' => 'Elevator failure', 'level' => 'error'],
+    ];
+
+    /**
+     * Update machine heartbeat and status.
+     * 
+     * @param string $serialNo
+     * @param array $data
+     * @return Machine
+     */
+    public function updateHeartbeat(string $serialNo, array $data): Machine
+    {
+        return DB::transaction(function () use ($serialNo, $data) {
+            $machine = Machine::where('serial_no', $serialNo)->firstOrFail();
+
+            // 採用現代化語意命名 (Modern semantic naming)
+            $temperature = $data['temperature'] ?? $machine->temperature;
+            $currentPage = $data['current_page'] ?? $machine->current_page;
+            $doorStatus = $data['door_status'] ?? $machine->door_status;
+            $firmwareVersion = $data['firmware_version'] ?? $machine->firmware_version;
+            $model = $data['model'] ?? $machine->model;
+
+            $updateData = [
+                'temperature' => $temperature,
+                'current_page' => $currentPage,
+                'door_status' => $doorStatus,
+                'firmware_version' => $firmwareVersion,
+                'model' => $model,
+                'last_heartbeat_at' => now(),
+            ];
+
+            $machine->update($updateData);
+
+            // Record log if provided
+            if (!empty($data['log'])) {
+                $machine->logs()->create([
+                    'company_id' => $machine->company_id,
+                    'type' => 'status',
+                    'level' => $data['log_level'] ?? 'info',
+                    'message' => $data['log'],
+                    'context' => $data['log_payload'] ?? null,
+                ]);
+            }
+
+            return $machine;
+        });
+    }
+
+    /**
+     * Sync machine slots based on replenishment report.
+     * 
+     * @param Machine $machine
+     * @param array $slotsData
+     */
+    public function syncSlots(Machine $machine, array $slotsData): void
+    {
+        DB::transaction(function () use ($machine, $slotsData) {
+            // 蒐集所有傳入的商品 ID (可能是 SKU 或 實際 ID)
+            $productCodes = collect($slotsData)->pluck('product_id')->filter()->unique()->toArray();
+            
+            // 優先以 ID 查詢商品，若 ID 不存在則嘗試 Barcode (Prioritize ID lookup, fallback to Barcode)
+            $products = \App\Models\Product\Product::whereIn('id', $productCodes)
+                ->orWhereIn('barcode', $productCodes)
+                ->get();
+
+            foreach ($slotsData as $slotData) {
+                $slotNo = $slotData['slot_no'] ?? null;
+                if (!$slotNo) continue;
+
+                $existingSlot = $machine->slots()->where('slot_no', $slotNo)->first();
+                
+                // 查找對應的實體 ID (支援 ID 與 Barcode 比對)
+                $productCode = $slotData['product_id'] ?? null;
+                $actualProductId = null;
+                if ($productCode) {
+                    $actualProductId = $products->first(function ($p) use ($productCode) {
+                        return (string)$p->id === (string)$productCode || $p->barcode === (string)$productCode;
+                    })?->id;
+                }
+
+                // 根據貨道類型自動決定上限 (Auto-calculate max_stock based on slot type)
+                // 若未提供 type，預設為 '1' (履帶/Track)
+                $slotType = $slotData['type'] ?? $existingSlot->type ?? '1';
+                if ($actualProductId) {
+                    $product = $products->find($actualProductId);
+                    if ($product) {
+                        // 1: 履帶, 2: 彈簧
+                        $calculatedMaxStock = ($slotType == '1') ? $product->track_limit : $product->spring_limit;
+                        $slotData['capacity'] = $calculatedMaxStock ?? $slotData['capacity'] ?? null;
+                    }
+                }
+
+                $updateData = [
+                    'product_id' => $actualProductId,
+                    'type' => $slotType,
+                    'stock' => $slotData['stock'] ?? 0,
+                    'max_stock' => $slotData['capacity'] ?? ($existingSlot->max_stock ?? 10),
+                    'is_active' => true,
+                ];
+
+                // 如果這是一次明確的補貨回報，建議更新時間並記錄
+                if ($existingSlot) {
+                    $existingSlot->update($updateData);
+                } else {
+                    $machine->slots()->create(array_merge($updateData, ['slot_no' => $slotNo]));
+                }
+            }
+        });
+    }
+
+    /**
+     * Update machine slot stock, expiry, and batch.
+     * 
+     * @param Machine $machine
+     * @param array $data
+     * @param int|null $userId
+     * @return void
+     */
+    public function updateSlot(Machine $machine, array $data, ?int $userId = null): void
+    {
+        DB::transaction(function () use ($machine, $data, $userId) {
+            $slotNo = $data['slot_no'];
+            $stock = $data['stock'] ?? null;
+            $expiryDate = $data['expiry_date'] ?? null;
+            $batchNo = $data['batch_no'] ?? null;
+            $slot = $machine->slots()->where('slot_no', $slotNo)->firstOrFail();
+
+            // 紀錄舊數據以供 Payload 使用
+            $oldData = [
+                'stock' => $slot->stock,
+                'expiry_date' => $slot->expiry_date ? Carbon::parse($slot->expiry_date)->toDateString() : null,
+                'batch_no' => $slot->batch_no,
+            ];
+
+            $updateData = [
+                'expiry_date' => $expiryDate,
+                'batch_no' => $batchNo,
+            ];
+            if ($stock !== null) $updateData['stock'] = (int)$stock;
+            
+            $slot->update($updateData);
+
+            // 指令去重：將該機台所有尚未領取的舊庫存同步指令標記為「已取代」
+            RemoteCommand::where('machine_id', $machine->id)
+                ->where('command_type', 'reload_stock')
+                ->where('status', 'pending')
+                ->update([
+                    'status' => 'superseded',
+                    'note' => __('Superseded by new adjustment'),
+                    'executed_at' => now(),
+                ]);
+
+            // 建立遠端指令紀錄 (Unified Command Concept)
+            RemoteCommand::create([
+                'machine_id' => $machine->id,
+                'user_id' => $userId,
+                'command_type' => 'reload_stock',
+                'status' => 'pending',
+                'payload' => [
+                    'slot_no' => $slotNo,
+                    'old' => $oldData,
+                    'new' => [
+                        'stock' => $stock !== null ? (int)$stock : $oldData['stock'],
+                        'expiry_date' => $expiryDate ?: null,
+                        'batch_no' => $batchNo ?: null,
+                    ]
+                ]
+            ]);
+        });
+    }
+
+    /**
+     * B013: Record machine hardware error/status log with auto-translation.
+     * 
+     * @param Machine $machine
+     * @param array $data
+     * @return MachineLog
+     */
+    public function recordErrorLog(Machine $machine, array $data): MachineLog
+    {
+        $errorCode = $data['error_code'] ?? '0000';
+        $mapping = self::ERROR_CODE_MAP[$errorCode] ?? ['label' => 'Unknown Status', 'level' => 'error'];
+        
+        $slotNo = $data['tid'] ?? null;
+        $label = $mapping['label'];
+        
+        // 儲存原始英文格式作為 DB 備用，前端顯示會優先使用 model accessor 的動態翻譯內容
+        $message = $slotNo ? "Slot {$slotNo}: {$label} (Code: {$errorCode})" : "{$label} (Code: {$errorCode})";
+
+        return $machine->logs()->create([
+            'company_id' => $machine->company_id,
+            'type' => 'submachine',
+            'level' => $mapping['level'],
+            'message' => $message,
+            'context' => array_merge($data, [
+                'translated_label' => $label,
+                'raw_code' => $errorCode
+            ]),
+        ]);
+    }
+
+    /**
+     * Update machine slot stock (single slot).
+     * Legacy support for recordLog (Existing code).
      */
     public function recordLog(int $machineId, array $data): MachineLog
     {
         $machine = Machine::findOrFail($machineId);
 
-        // 建立日誌紀錄
-        $log = $machine->logs()->create([
+        return $machine->logs()->create([
             'level' => $data['level'] ?? 'info',
             'message' => $data['message'],
             'context' => $data['context'] ?? null,
         ]);
-
-        // 同步更新機台最後活耀時間與狀態
-        $machine->update([
-            'last_heartbeat_at' => now(),
-            'status' => $this->resolveStatus($data),
-        ]);
-
-        return $log;
     }
 
     /**
-     * 根據日誌內容判斷機台是否應標記成錯誤
+     * Get machine utilization and OEE statistics for entire fleet.
      */
-    protected function resolveStatus(array $data): string
+    public function getFleetStats(string $date): array
     {
-        if (isset($data['level']) && $data['level'] === 'error') {
-            return 'error';
+        $start = Carbon::parse($date)->startOfDay();
+        $end = Carbon::parse($date)->endOfDay();
+
+        // 1. Online Count (Base on new heartbeat logic)
+        $machines = Machine::all(); // This is filtered by TenantScoped
+        $totalMachines = $machines->count();
+        $onlineCount = Machine::online()->count();
+
+        $machineIds = $machines->pluck('id')->toArray();
+
+        // 2. Total Daily Sales (Sum of B600 logs across all authorized machines)
+        $totalSales = MachineLog::whereIn('machine_id', $machineIds)
+            ->where('message', 'like', '%B600%')
+            ->whereBetween('created_at', [$start, $end])
+            ->count();
+
+        // 3. Average OEE (Simulated based on individual machine stats for performance)
+        $totalOee = 0;
+        $count = 0;
+        
+        foreach ($machines as $machine) {
+            $stats = $this->getUtilizationStats($machine, $date);
+            $totalOee += $stats['overview']['oee'];
+            $count++;
         }
 
-        return 'online';
+        $avgOee = ($count > 0) ? ($totalOee / $count) : 0;
+
+        return [
+            'avgOee' => round($avgOee, 2),
+            'onlineCount' => $onlineCount,
+            'totalMachines' => $totalMachines,
+            'totalSales' => $totalSales,
+            'alertCount' => MachineLog::whereIn('machine_id', $machineIds)
+                ->where('level', 'error')
+                ->whereBetween('created_at', [$start, $end])
+                ->count()
+        ];
+    }
+
+    /**
+     * Get machine utilization and OEE statistics.
+     */
+    public function getUtilizationStats(Machine $machine, string $date): array
+    {
+        $start = Carbon::parse($date)->startOfDay();
+        $end = Carbon::parse($date)->endOfDay();
+
+        // 1. Availability: Based on heartbeat logs (status type)
+        // Assume online if heartbeat within 6 minutes
+        $logs = $machine->logs()
+            ->where('type', 'status')
+            ->whereBetween('created_at', [$start, $end])
+            ->orderBy('created_at')
+            ->get();
+
+        $onlineMinutes = 0;
+        $lastLogTime = null;
+
+        foreach ($logs as $log) {
+            $currentTime = Carbon::parse($log->created_at);
+            if ($lastLogTime) {
+                $diff = $currentTime->diffInMinutes($lastLogTime);
+                if ($diff <= 6) {
+                    $onlineMinutes += $diff;
+                }
+            }
+            $lastLogTime = $currentTime;
+        }
+
+        $totalMinutes = 24 * 60;
+        $availability = ($totalMinutes > 0) ? min(100, ($onlineMinutes / $totalMinutes) * 100) : 0;
+
+        // 2. Performance: Sales Count (B600)
+        // Target: 2 sales per hour (48/day)
+        $salesCount = $machine->logs()
+            ->where('message', 'like', '%B600%')
+            ->whereBetween('created_at', [$start, $end])
+            ->count();
+        
+        $targetSales = 48;
+        $performance = ($targetSales > 0) ? min(100, ($salesCount / $targetSales) * 100) : 0;
+
+        // 3. Quality: Success Rate
+        // Exclude failed dispense (B130)
+        $errorCount = $machine->logs()
+            ->where('message', 'like', '%B130%')
+            ->whereBetween('created_at', [$start, $end])
+            ->count();
+        
+        $totalAttempts = $salesCount + $errorCount;
+        $quality = ($totalAttempts > 0) ? (($salesCount / $totalAttempts) * 100) : 100;
+
+        // Combined OEE
+        $oee = ($availability / 100) * ($performance / 100) * ($quality / 100) * 100;
+
+        return [
+            'overview' => [
+                'availability' => round($availability, 2),
+                'performance' => round($performance, 2),
+                'quality' => round($quality, 2),
+                'oee' => round($oee, 2),
+                'onlineHours' => round($onlineMinutes / 60, 2),
+                'salesCount' => $salesCount,
+                'errorCount' => $errorCount,
+            ],
+            'chart' => [
+                'uptime' => $this->formatUptimeTimeline($logs, $start, $end),
+                'sales' => $this->formatSalesTimeline($machine, $start, $end)
+            ]
+        ];
+    }
+
+    private function formatUptimeTimeline($logs, $start, $end)
+    {
+        $data = [];
+        if ($logs->isEmpty()) return $data;
+
+        $lastLog = null;
+        $currentRangeStart = null;
+
+        foreach ($logs as $log) {
+            $logTime = Carbon::parse($log->created_at);
+            if (!$currentRangeStart) {
+                $currentRangeStart = $logTime;
+            } else {
+                $diff = $logTime->diffInMinutes(Carbon::parse($lastLog->created_at));
+                if ($diff > 10) { // Interruption > 10 mins
+                    $data[] = [
+                        'x' => 'Uptime',
+                        'y' => [$currentRangeStart->getTimestamp() * 1000, Carbon::parse($lastLog->created_at)->getTimestamp() * 1000],
+                        'fillColor' => '#06b6d4'
+                    ];
+                    $currentRangeStart = $logTime;
+                }
+            }
+            $lastLog = $log;
+        }
+
+        if ($currentRangeStart && $lastLog) {
+            $data[] = [
+                'x' => 'Uptime',
+                'y' => [$currentRangeStart->getTimestamp() * 1000, Carbon::parse($lastLog->created_at)->getTimestamp() * 1000],
+                'fillColor' => '#06b6d4'
+            ];
+        }
+
+        return $data;
+    }
+
+    private function formatSalesTimeline($machine, $start, $end)
+    {
+        return $machine->logs()
+            ->where('message', 'like', '%B600%')
+            ->whereBetween('created_at', [$start, $end])
+            ->get()
+            ->map(function($log) {
+                return [Carbon::parse($log->created_at)->getTimestamp() * 1000, 1];
+            })
+            ->toArray();
     }
 }

app/Services/Transaction/TransactionService.php

@@ -0,0 +1,120 @@
+<?php
+
+namespace App\Services\Transaction;
+
+use App\Models\Transaction\Order;
+use App\Models\Transaction\OrderItem;
+use App\Models\Transaction\Invoice;
+use App\Models\Transaction\DispenseRecord;
+use Illuminate\Support\Facades\DB;
+use App\Models\Machine\Machine;
+
+class TransactionService
+{
+    /**
+     * Process a new transaction (B600).
+     */
+    public function processTransaction(array $data): Order
+    {
+        return DB::transaction(function () use ($data) {
+            $machine = Machine::where('serial_no', $data['serial_no'])->firstOrFail();
+            
+            // Create Order
+            $order = Order::create([
+                'company_id' => $machine->company_id,
+                'flow_id' => $data['flow_id'] ?? null,
+                'order_no' => $data['order_no'] ?? $this->generateOrderNo(),
+                'machine_id' => $machine->id,
+                'member_id' => $data['member_id'] ?? null,
+                'total_amount' => $data['total_amount'],
+                'discount_amount' => $data['discount_amount'] ?? 0,
+                'pay_amount' => $data['pay_amount'],
+                'payment_type' => $data['payment_type'] ?? 0,
+                'payment_status' => $data['payment_status'] ?? 1,
+                'payment_at' => now(),
+                'status' => 'completed',
+                'metadata' => $data['metadata'] ?? null,
+            ]);
+
+            // Create Order Items
+            if (!empty($data['items'])) {
+                foreach ($data['items'] as $item) {
+                    $order->items()->create([
+                        'product_id' => $item['product_id'],
+                        'product_name' => $item['product_name'] ?? 'Unknown',
+                        'barcode' => $item['barcode'] ?? null,
+                        'price' => $item['price'],
+                        'quantity' => $item['quantity'],
+                        'subtotal' => $item['price'] * $item['quantity'],
+                    ]);
+                }
+            }
+
+            return $order;
+        });
+    }
+
+    /**
+     * Generate a unique order number.
+     */
+    protected function generateOrderNo(): string
+    {
+        return 'ORD-' . now()->format('YmdHis') . '-' . strtoupper(bin2hex(random_bytes(3)));
+    }
+
+    /**
+     * Record Invoice (B601).
+     */
+    public function recordInvoice(array $data): Invoice
+    {
+        return DB::transaction(function () use ($data) {
+            $machine = Machine::where('serial_no', $data['serial_no'])->firstOrFail();
+            
+            $order = null;
+            if (!empty($data['flow_id'])) {
+                $order = Order::where('flow_id', $data['flow_id'])->first();
+            }
+
+            return Invoice::create([
+                'company_id' => $machine->company_id,
+                'order_id' => $order?->id ?? ($data['order_id'] ?? null),
+                'machine_id' => $machine->id,
+                'flow_id' => $data['flow_id'] ?? null,
+                'invoice_no' => $data['invoice_no'] ?? null,
+                'amount' => $data['amount'] ?? 0,
+                'carrier_id' => $data['carrier_id'] ?? null,
+                'invoice_date' => $data['invoice_date'] ?? null,
+                'random_number' => $data['random_no'] ?? null,
+                'love_code' => $data['love_code'] ?? null,
+                'metadata' => $data['metadata'] ?? null,
+            ]);
+        });
+    }
+
+    /**
+     * Record dispense result (B602).
+     */
+    public function recordDispense(array $data): DispenseRecord
+    {
+        return DB::transaction(function () use ($data) {
+            $machine = Machine::where('serial_no', $data['serial_no'])->firstOrFail();
+            
+            $order = null;
+            if (!empty($data['flow_id'])) {
+                $order = Order::where('flow_id', $data['flow_id'])->first();
+            }
+
+            return DispenseRecord::create([
+                'company_id' => $machine->company_id,
+                'order_id' => $order?->id ?? ($data['order_id'] ?? null),
+                'flow_id' => $data['flow_id'] ?? null,
+                'machine_id' => $machine->id,
+                'slot_no' => $data['slot_no'] ?? 'unknown',
+                'product_id' => $data['product_id'] ?? null,
+                'amount' => $data['amount'] ?? 0,
+                'dispense_status' => $data['dispense_status'] ?? 0,
+                'machine_time' => $data['machine_time'] ?? now(),
+            ]);
+        });
+    }
+}

app/Traits/ImageHandler.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace App\Traits;
+
+use Illuminate\Http\UploadedFile;
+use Illuminate\Support\Facades\Storage;
+use Illuminate\Support\Str;
+
+trait ImageHandler
+{
+    /**
+     * 將圖片轉換為 WebP 並儲存
+     *
+     * @param UploadedFile $file 原始檔案
+     * @param string $directory 儲存目錄 (不含 disk 名稱)
+     * @param int $quality 壓縮品質 (0-100)
+     * @return string 儲存的路徑
+     */
+    protected function storeAsWebp(UploadedFile $file, string $directory, int $quality = 80): string
+    {
+        $filename = Str::random(40) . '.webp';
+        $path = "{$directory}/{$filename}";
+
+        // 讀取原始圖片資訊
+        $imageInfo = getimagesize($file->getRealPath());
+        if (!$imageInfo) {
+            return $file->store($directory, 'public');
+        }
+
+        $mime = $imageInfo['mime'];
+        $source = null;
+
+        switch ($mime) {
+            case 'image/jpeg':
+                $source = imagecreatefromjpeg($file->getRealPath());
+                break;
+            case 'image/png':
+                $source = imagecreatefrompng($file->getRealPath());
+                break;
+            case 'image/gif':
+                $source = imagecreatefromgif($file->getRealPath());
+                break;
+            case 'image/webp':
+                $source = imagecreatefromwebp($file->getRealPath());
+                break;
+            default:
+                // 不支援的格式直接存
+                return $file->store($directory, 'public');
+        }
+
+        if (!$source) {
+            return $file->store($directory, 'public');
+        }
+
+        // 確保支援真彩色 (解決 palette image 問題)
+        if (!imageistruecolor($source)) {
+            imagepalettetotruecolor($source);
+        }
+
+        // 確保目錄存在
+        Storage::disk('public')->makeDirectory($directory);
+        $fullPath = Storage::disk('public')->path($path);
+
+        // 轉換並儲存
+        imagewebp($source, $fullPath, $quality);
+        imagedestroy($source);
+
+        return $path;
+    }
+}

app/Traits/TenantScoped.php

@@ -0,0 +1,51 @@
+<?php
+
+namespace App\Traits;
+
+use Illuminate\Database\Eloquent\Builder;
+
+trait TenantScoped
+{
+    /**
+     * Boot the trait.
+     */
+    public static function bootTenantScoped(): void
+    {
+        static::addGlobalScope('tenant', function (Builder $query) {
+            // 避免在 User Model 本身套用此 Scope，否則在 auth()->user() 讀取 User 時會產生循環引用
+            if (static::class === \App\Models\System\User::class) {
+                return;
+            }
+
+            // check if running in console/migration
+            if (app()->runningInConsole()) {
+                return;
+            }
+
+            $user = auth()->user();
+            
+            // 如果使用者已登入且有綁定公司，則自動注入過濾條件
+            if ($user && $user->company_id) {
+                $query->where((new static)->getTable() . '.company_id', $user->company_id);
+            }
+        });
+
+        // 建立資料時，自動填入當前使用者的 company_id
+        static::creating(function ($model) {
+            if (!$model->company_id) {
+                $user = auth()->user();
+                if ($user && $user->company_id) {
+                    $model->company_id = $user->company_id;
+                }
+            }
+        });
+    }
+
+    /**
+     * Define the company relationship.
+     */
+    public function company()
+    {
+        return $this->belongsTo(\App\Models\System\Company::class);
+    }
+}

compose.yaml

@@ -19,6 +19,7 @@ services:
             XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
             XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
             IGNITION_LOCAL_SITES_PATH: '${PWD}'
+            TZ: 'Asia/Taipei'
         volumes:
             - '.:/var/www/html'
         networks:
@@ -27,6 +28,24 @@ services:
             - mysql
             - redis
 
+    laravel.queue:
+        image: 'sail-8.5/app'
+        container_name: star-cloud-queue
+        hostname: star-cloud-queue
+        command: php artisan queue:work --tries=3 --timeout=90
+        environment:
+            WWWUSER: '${WWWUSER}'
+            LARAVEL_SAIL: 1
+            TZ: 'Asia/Taipei'
+        volumes:
+            - '.:/var/www/html'
+        networks:
+            - sail
+        depends_on:
+            - mysql
+            - redis
+        restart: always
+
     mysql:
         image: 'mysql/mysql-server:8.0'
         container_name: star-cloud-mysql
@@ -41,6 +60,7 @@ services:
             MYSQL_PASSWORD: '${DB_PASSWORD}'
             MYSQL_ALLOW_EMPTY_PASSWORD: 1
             MYSQL_EXTRA_OPTIONS: '${MYSQL_EXTRA_OPTIONS:-}'
+            TZ: 'Asia/Taipei'
         volumes:
             - 'sail-mysql:/var/lib/mysql'
             - './vendor/laravel/sail/database/mysql/create-testing-database.sh:/docker-entrypoint-initdb.d/10-create-testing-database.sh'

composer.json

@@ -10,9 +10,12 @@
     "require": {
         "php": "^8.2",
         "guzzlehttp/guzzle": "^7.8",
+        "jenssegers/agent": "^2.6",
         "laravel/framework": "^12.0",
         "laravel/sanctum": "^4.3",
-        "laravel/tinker": "^2.10.1"
+        "laravel/tinker": "^2.10.1",
+        "simplesoftwareio/simple-qrcode": "^4.2",
+        "spatie/laravel-permission": "^7.2"
     },
     "require-dev": {
         "fakerphp/faker": "^1.23",

composer.lock

@@ -4,8 +4,62 @@
         "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies",
         "This file is @generated automatically"
     ],
-    "content-hash": "dc689fd91200cf19e401759d009094a3",
+    "content-hash": "2889e194212440faeb9f8f3dd7513795",
     "packages": [
+        {
+            "name": "bacon/bacon-qr-code",
+            "version": "2.0.8",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/Bacon/BaconQrCode.git",
+                "reference": "8674e51bb65af933a5ffaf1c308a660387c35c22"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/Bacon/BaconQrCode/zipball/8674e51bb65af933a5ffaf1c308a660387c35c22",
+                "reference": "8674e51bb65af933a5ffaf1c308a660387c35c22",
+                "shasum": ""
+            },
+            "require": {
+                "dasprid/enum": "^1.0.3",
+                "ext-iconv": "*",
+                "php": "^7.1 || ^8.0"
+            },
+            "require-dev": {
+                "phly/keep-a-changelog": "^2.1",
+                "phpunit/phpunit": "^7 | ^8 | ^9",
+                "spatie/phpunit-snapshot-assertions": "^4.2.9",
+                "squizlabs/php_codesniffer": "^3.4"
+            },
+            "suggest": {
+                "ext-imagick": "to generate QR code images"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "BaconQrCode\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-2-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Ben Scholzen 'DASPRiD'",
+                    "email": "mail@dasprids.de",
+                    "homepage": "https://dasprids.de/",
+                    "role": "Developer"
+                }
+            ],
+            "description": "BaconQrCode is a QR code generator for PHP.",
+            "homepage": "https://github.com/Bacon/BaconQrCode",
+            "support": {
+                "issues": "https://github.com/Bacon/BaconQrCode/issues",
+                "source": "https://github.com/Bacon/BaconQrCode/tree/2.0.8"
+            },
+            "time": "2022-12-07T17:46:57+00:00"
+        },
         {
             "name": "brick/math",
             "version": "0.14.8",
@@ -135,6 +189,56 @@
             ],
             "time": "2024-02-09T16:56:22+00:00"
         },
+        {
+            "name": "dasprid/enum",
+            "version": "1.0.7",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/DASPRiD/Enum.git",
+                "reference": "b5874fa9ed0043116c72162ec7f4fb50e02e7cce"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/DASPRiD/Enum/zipball/b5874fa9ed0043116c72162ec7f4fb50e02e7cce",
+                "reference": "b5874fa9ed0043116c72162ec7f4fb50e02e7cce",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=7.1 <9.0"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^7 || ^8 || ^9 || ^10 || ^11",
+                "squizlabs/php_codesniffer": "*"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "DASPRiD\\Enum\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "BSD-2-Clause"
+            ],
+            "authors": [
+                {
+                    "name": "Ben Scholzen 'DASPRiD'",
+                    "email": "mail@dasprids.de",
+                    "homepage": "https://dasprids.de/",
+                    "role": "Developer"
+                }
+            ],
+            "description": "PHP 7.1 enum implementation",
+            "keywords": [
+                "enum",
+                "map"
+            ],
+            "support": {
+                "issues": "https://github.com/DASPRiD/Enum/issues",
+                "source": "https://github.com/DASPRiD/Enum/tree/1.0.7"
+            },
+            "time": "2025-09-16T12:23:56+00:00"
+        },
         {
             "name": "dflydev/dot-access-data",
             "version": "v3.0.3",
@@ -1052,6 +1156,141 @@
             ],
             "time": "2025-08-22T14:27:06+00:00"
         },
+        {
+            "name": "jaybizzle/crawler-detect",
+            "version": "v1.3.7",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/JayBizzle/Crawler-Detect.git",
+                "reference": "7f7a45b5d5df9c95ba6b2008544e6cf8e66de6f5"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/JayBizzle/Crawler-Detect/zipball/7f7a45b5d5df9c95ba6b2008544e6cf8e66de6f5",
+                "reference": "7f7a45b5d5df9c95ba6b2008544e6cf8e66de6f5",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=7.1.0"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "^4.8|^5.5|^6.5|^7.5|^8.5|^9.4"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Jaybizzle\\CrawlerDetect\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Mark Beech",
+                    "email": "m@rkbee.ch",
+                    "role": "Developer"
+                }
+            ],
+            "description": "CrawlerDetect is a PHP class for detecting bots/crawlers/spiders via the user agent",
+            "homepage": "https://github.com/JayBizzle/Crawler-Detect/",
+            "keywords": [
+                "crawler",
+                "crawler detect",
+                "crawler detector",
+                "crawlerdetect",
+                "php crawler detect"
+            ],
+            "support": {
+                "issues": "https://github.com/JayBizzle/Crawler-Detect/issues",
+                "source": "https://github.com/JayBizzle/Crawler-Detect/tree/v1.3.7"
+            },
+            "time": "2026-02-02T19:15:54+00:00"
+        },
+        {
+            "name": "jenssegers/agent",
+            "version": "v2.6.4",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/jenssegers/agent.git",
+                "reference": "daa11c43729510b3700bc34d414664966b03bffe"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/jenssegers/agent/zipball/daa11c43729510b3700bc34d414664966b03bffe",
+                "reference": "daa11c43729510b3700bc34d414664966b03bffe",
+                "shasum": ""
+            },
+            "require": {
+                "jaybizzle/crawler-detect": "^1.2",
+                "mobiledetect/mobiledetectlib": "^2.7.6",
+                "php": ">=5.6"
+            },
+            "require-dev": {
+                "php-coveralls/php-coveralls": "^2.1",
+                "phpunit/phpunit": "^5.0|^6.0|^7.0"
+            },
+            "suggest": {
+                "illuminate/support": "Required for laravel service providers"
+            },
+            "type": "library",
+            "extra": {
+                "laravel": {
+                    "aliases": {
+                        "Agent": "Jenssegers\\Agent\\Facades\\Agent"
+                    },
+                    "providers": [
+                        "Jenssegers\\Agent\\AgentServiceProvider"
+                    ]
+                },
+                "branch-alias": {
+                    "dev-master": "3.0-dev"
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "Jenssegers\\Agent\\": "src/"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Jens Segers",
+                    "homepage": "https://jenssegers.com"
+                }
+            ],
+            "description": "Desktop/mobile user agent parser with support for Laravel, based on Mobiledetect",
+            "homepage": "https://github.com/jenssegers/agent",
+            "keywords": [
+                "Agent",
+                "browser",
+                "desktop",
+                "laravel",
+                "mobile",
+                "platform",
+                "user agent",
+                "useragent"
+            ],
+            "support": {
+                "issues": "https://github.com/jenssegers/agent/issues",
+                "source": "https://github.com/jenssegers/agent/tree/v2.6.4"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/jenssegers",
+                    "type": "github"
+                },
+                {
+                    "url": "https://tidelift.com/funding/github/packagist/jenssegers/agent",
+                    "type": "tidelift"
+                }
+            ],
+            "time": "2020-06-13T08:05:20+00:00"
+        },
         {
             "name": "laravel/framework",
             "version": "v12.53.0",
@@ -2082,6 +2321,68 @@
             ],
             "time": "2026-01-15T06:54:53+00:00"
         },
+        {
+            "name": "mobiledetect/mobiledetectlib",
+            "version": "2.8.45",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/serbanghita/Mobile-Detect.git",
+                "reference": "96aaebcf4f50d3d2692ab81d2c5132e425bca266"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/serbanghita/Mobile-Detect/zipball/96aaebcf4f50d3d2692ab81d2c5132e425bca266",
+                "reference": "96aaebcf4f50d3d2692ab81d2c5132e425bca266",
+                "shasum": ""
+            },
+            "require": {
+                "php": ">=5.0.0"
+            },
+            "require-dev": {
+                "phpunit/phpunit": "~4.8.36"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-0": {
+                    "Detection": "namespaced/"
+                },
+                "classmap": [
+                    "Mobile_Detect.php"
+                ]
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Serban Ghita",
+                    "email": "serbanghita@gmail.com",
+                    "homepage": "http://mobiledetect.net",
+                    "role": "Developer"
+                }
+            ],
+            "description": "Mobile_Detect is a lightweight PHP class for detecting mobile devices. It uses the User-Agent string combined with specific HTTP headers to detect the mobile environment.",
+            "homepage": "https://github.com/serbanghita/Mobile-Detect",
+            "keywords": [
+                "detect mobile devices",
+                "mobile",
+                "mobile detect",
+                "mobile detector",
+                "php mobile detect"
+            ],
+            "support": {
+                "issues": "https://github.com/serbanghita/Mobile-Detect/issues",
+                "source": "https://github.com/serbanghita/Mobile-Detect/tree/2.8.45"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/serbanghita",
+                    "type": "github"
+                }
+            ],
+            "time": "2023-11-07T21:57:25+00:00"
+        },
         {
             "name": "monolog/monolog",
             "version": "3.10.0",
@@ -3357,6 +3658,222 @@
             },
             "time": "2025-12-14T04:43:48+00:00"
         },
+        {
+            "name": "simplesoftwareio/simple-qrcode",
+            "version": "4.2.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/SimpleSoftwareIO/simple-qrcode.git",
+                "reference": "916db7948ca6772d54bb617259c768c9cdc8d537"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/SimpleSoftwareIO/simple-qrcode/zipball/916db7948ca6772d54bb617259c768c9cdc8d537",
+                "reference": "916db7948ca6772d54bb617259c768c9cdc8d537",
+                "shasum": ""
+            },
+            "require": {
+                "bacon/bacon-qr-code": "^2.0",
+                "ext-gd": "*",
+                "php": ">=7.2|^8.0"
+            },
+            "require-dev": {
+                "mockery/mockery": "~1",
+                "phpunit/phpunit": "~9"
+            },
+            "suggest": {
+                "ext-imagick": "Allows the generation of PNG QrCodes.",
+                "illuminate/support": "Allows for use within Laravel."
+            },
+            "type": "library",
+            "extra": {
+                "laravel": {
+                    "aliases": {
+                        "QrCode": "SimpleSoftwareIO\\QrCode\\Facades\\QrCode"
+                    },
+                    "providers": [
+                        "SimpleSoftwareIO\\QrCode\\QrCodeServiceProvider"
+                    ]
+                }
+            },
+            "autoload": {
+                "psr-4": {
+                    "SimpleSoftwareIO\\QrCode\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Simple Software LLC",
+                    "email": "support@simplesoftware.io"
+                }
+            ],
+            "description": "Simple QrCode is a QR code generator made for Laravel.",
+            "homepage": "https://www.simplesoftware.io/#/docs/simple-qrcode",
+            "keywords": [
+                "Simple",
+                "generator",
+                "laravel",
+                "qrcode",
+                "wrapper"
+            ],
+            "support": {
+                "issues": "https://github.com/SimpleSoftwareIO/simple-qrcode/issues",
+                "source": "https://github.com/SimpleSoftwareIO/simple-qrcode/tree/4.2.0"
+            },
+            "time": "2021-02-08T20:43:55+00:00"
+        },
+        {
+            "name": "spatie/laravel-package-tools",
+            "version": "1.93.0",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/spatie/laravel-package-tools.git",
+                "reference": "0d097bce95b2bf6802fb1d83e1e753b0f5a948e7"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/spatie/laravel-package-tools/zipball/0d097bce95b2bf6802fb1d83e1e753b0f5a948e7",
+                "reference": "0d097bce95b2bf6802fb1d83e1e753b0f5a948e7",
+                "shasum": ""
+            },
+            "require": {
+                "illuminate/contracts": "^10.0|^11.0|^12.0|^13.0",
+                "php": "^8.1"
+            },
+            "require-dev": {
+                "mockery/mockery": "^1.5",
+                "orchestra/testbench": "^8.0|^9.2|^10.0|^11.0",
+                "pestphp/pest": "^2.1|^3.1|^4.0",
+                "phpunit/php-code-coverage": "^10.0|^11.0|^12.0",
+                "phpunit/phpunit": "^10.5|^11.5|^12.5",
+                "spatie/pest-plugin-test-time": "^2.2|^3.0"
+            },
+            "type": "library",
+            "autoload": {
+                "psr-4": {
+                    "Spatie\\LaravelPackageTools\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Freek Van der Herten",
+                    "email": "freek@spatie.be",
+                    "role": "Developer"
+                }
+            ],
+            "description": "Tools for creating Laravel packages",
+            "homepage": "https://github.com/spatie/laravel-package-tools",
+            "keywords": [
+                "laravel-package-tools",
+                "spatie"
+            ],
+            "support": {
+                "issues": "https://github.com/spatie/laravel-package-tools/issues",
+                "source": "https://github.com/spatie/laravel-package-tools/tree/1.93.0"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/spatie",
+                    "type": "github"
+                }
+            ],
+            "time": "2026-02-21T12:49:54+00:00"
+        },
+        {
+            "name": "spatie/laravel-permission",
+            "version": "7.2.3",
+            "source": {
+                "type": "git",
+                "url": "https://github.com/spatie/laravel-permission.git",
+                "reference": "062b0cd8e3a1753fa7a53e468b918710004aa06b"
+            },
+            "dist": {
+                "type": "zip",
+                "url": "https://api.github.com/repos/spatie/laravel-permission/zipball/062b0cd8e3a1753fa7a53e468b918710004aa06b",
+                "reference": "062b0cd8e3a1753fa7a53e468b918710004aa06b",
+                "shasum": ""
+            },
+            "require": {
+                "illuminate/auth": "^12.0|^13.0",
+                "illuminate/container": "^12.0|^13.0",
+                "illuminate/contracts": "^12.0|^13.0",
+                "illuminate/database": "^12.0|^13.0",
+                "php": "^8.4",
+                "spatie/laravel-package-tools": "^1.0"
+            },
+            "require-dev": {
+                "larastan/larastan": "^3.9",
+                "laravel/passport": "^13.0",
+                "laravel/pint": "^1.0",
+                "orchestra/testbench": "^10.0|^11.0",
+                "pestphp/pest": "^3.0|^4.0",
+                "pestphp/pest-plugin-laravel": "^3.0|^4.1",
+                "phpstan/phpstan": "^2.1"
+            },
+            "type": "library",
+            "extra": {
+                "laravel": {
+                    "providers": [
+                        "Spatie\\Permission\\PermissionServiceProvider"
+                    ]
+                },
+                "branch-alias": {
+                    "dev-main": "7.x-dev",
+                    "dev-master": "7.x-dev"
+                }
+            },
+            "autoload": {
+                "files": [
+                    "src/helpers.php"
+                ],
+                "psr-4": {
+                    "Spatie\\Permission\\": "src"
+                }
+            },
+            "notification-url": "https://packagist.org/downloads/",
+            "license": [
+                "MIT"
+            ],
+            "authors": [
+                {
+                    "name": "Freek Van der Herten",
+                    "email": "freek@spatie.be",
+                    "homepage": "https://spatie.be",
+                    "role": "Developer"
+                }
+            ],
+            "description": "Permission handling for Laravel 12 and up",
+            "homepage": "https://github.com/spatie/laravel-permission",
+            "keywords": [
+                "acl",
+                "laravel",
+                "permission",
+                "permissions",
+                "rbac",
+                "roles",
+                "security",
+                "spatie"
+            ],
+            "support": {
+                "issues": "https://github.com/spatie/laravel-permission/issues",
+                "source": "https://github.com/spatie/laravel-permission/tree/7.2.3"
+            },
+            "funding": [
+                {
+                    "url": "https://github.com/spatie",
+                    "type": "github"
+                }
+            ],
+            "time": "2026-02-23T20:30:07+00:00"
+        },
         {
             "name": "symfony/clock",
             "version": "v8.0.0",

config/api-docs.php

@@ -0,0 +1,599 @@
+<?php
+
+return [
+    'title' => 'Star Cloud IoT API 說明文件',
+    'version' => 'v1.0.0',
+    'description' => '此文件提供 Star Cloud 智能販賣機 IoT 端點通訊協議說明，供硬體端與前端開發者調研與串接使用。',
+    'categories' => [
+        [
+            'name' => '機台核心通訊 (IoT Core)',
+            'apis' => [
+                [
+                    'name' => 'B000: 維運人員登入認證 (Technician Login)',
+                    'slug' => 'b000-tech-login',
+                    'method' => 'POST',
+                    'path' => '/api/v1/app/admin/login/B000',
+                    'description' => '機台啟動引導的第一步。維運人員輸入個人帳密與機台編號進行認證，成功後核發臨時 Sanctum Token 供後續 B014 下載敏感設定使用。',
+                    'headers' => [
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [
+                        'username' => [
+                            'type' => 'string',
+                            'required' => true,
+                            'description' => '維運人員帳號',
+                            'example' => 'admin_test'
+                        ],
+                        'password' => [
+                            'type' => 'string',
+                            'required' => true,
+                            'description' => '維運人員密碼',
+                            'example' => 'password123'
+                        ],
+                        'machine' => [
+                            'type' => 'string',
+                            'required' => true,
+                            'description' => '機台序號 (Serial No)',
+                            'example' => 'SN202604130001'
+                        ],
+                    ],
+                    'response_parameters' => [
+                        'message' => [
+                            'type' => 'string',
+                            'description' => '回應訊息',
+                            'example' => 'Success'
+                        ],
+                        'token' => [
+                            'type' => 'string',
+                            'description' => '臨時身份認證 Token (Sanctum)',
+                            'example' => '1|abcdefg...'
+                        ],
+                    ],
+                    'request' => [
+                        'username' => 'admin_test',
+                        'password' => 'password123',
+                        'machine' => 'SN202604130001'
+                    ],
+                    'response' => [
+                        'message' => 'Success',
+                        'token' => '1|abcdefg...'
+                    ],
+                ],
+                [
+                    'name' => 'B014: 機台參數與金鑰下載 (Config Download)',
+                    'slug' => 'b014-config-download',
+                    'method' => 'GET',
+                    'path' => '/api/v1/app/machine/setting/B014',
+                    'description' => '機台引導階段的第二步。在人員登入後，透過此介面下載金流金鑰、電子發票設定與機台專屬通訊 Token。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <user_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [
+                        'machine' => [
+                            'type' => 'string',
+                            'required' => true,
+                            'description' => '機台序號',
+                            'example' => 'SN202604130001'
+                        ],
+                    ],
+                    'response_parameters' => [
+                        'success' => [
+                            'type' => 'boolean',
+                            'description' => '是否成功',
+                            'example' => true
+                        ],
+                        'data' => [
+                            'type' => 'array',
+                            'description' => '配置物件陣列。包含：t050v01 (序號), api_token (通訊 Token), t050v41~43 (玉山設定), t050v34~38 (發票設定), TP_... (趨勢/手機支付設定)',
+                            'example' => [
+                                [
+                                    't050v01' => 'SN202604130001',
+                                    'api_token' => 'mac_token_...',
+                                    't050v41' => '80812345',
+                                    't050v34' => '2000132',
+                                    'TP_APP_ID' => 'GP_001'
+                                ]
+                            ]
+                        ],
+                    ],
+                    'request' => [],
+                    'response' => [
+                        'success' => true,
+                        'code' => 200,
+                        'data' => [
+                            [
+                                't050v01' => 'SN202604130001',
+                                'api_token' => 'mac_token_...',
+                                't050v41' => '80812345',
+                                't050v42' => '9001',
+                                't050v43' => 'hash_key',
+                                't050v34' => '2000132',
+                                'TP_APP_ID' => 'GP_001'
+                            ]
+                        ]
+                    ],
+                    'notes' => '此 API 受 auth:sanctum 保護，必須在 Header 帶上從 B000 取得的 Token。'
+                ],
+                [
+                    'name' => 'B005: 廣告清單同步 (Ad Sync)',
+                    'slug' => 'b005-ad-sync',
+                    'method' => 'GET',
+                    'path' => '/api/v1/app/machine/ad/B005',
+                    'description' => '用於機台端獲取目前應播放的廣告檔案 URL 清單。此介面無需 Request Body。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <api_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [],
+                    'response_parameters' => [
+                        'success' => [
+                            'type' => 'boolean',
+                            'description' => '請求是否成功',
+                            'example' => true
+                        ],
+                        'code' => [
+                            'type' => 'integer',
+                            'description' => '內部業務狀態碼',
+                            'example' => 200
+                        ],
+                        'data' => [
+                            'type' => 'array',
+                            'description' => '廣告物件陣列。內部欄位包含：t070v01 (名稱), t070v02 (秒數), t070v03 (位置：1:販賣頁, 2:來店禮, 3:待機廣告), t070v04 (URL), t070v05 (順位)',
+                            'example' => [
+                                [
+                                    't070v01' => '測試機台廣告',
+                                    't070v02' => 15,
+                                    't070v03' => 3,
+                                    't070v04' => 'https://example.com/ad1.mp4',
+                                    't070v05' => 1
+                                ]
+                            ]
+                        ],
+                    ],
+                    'request' => [],
+                    'response' => [
+                        'success' => true,
+                        'code' => 200,
+                        'message' => 'OK',
+                        'data' => [
+                            [
+                                't070v01' => '測試機台廣告',
+                                't070v02' => 15,
+                                't070v03' => 3,
+                                't070v04' => 'https://example.com/ad1.mp4',
+                                't070v05' => 1
+                            ]
+                        ]
+                    ],
+                ],
+                [
+                    'name' => 'B009: 貨道庫存即時回報 (Inventory Report)',
+                    'slug' => 'b009-inventory-report',
+                    'method' => 'PUT',
+                    'path' => '/api/v1/app/products/supplementary/B009',
+                    'description' => '當人員在機台端完成操作後，將目前的貨道實體狀態同步回雲端。需進行 RBAC 權限核查。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <api_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [
+                        'account' => [
+                            'type' => 'string',
+                            'required' => true,
+                            'description' => '操作人員帳號',
+                            'example' => '0999123456'
+                        ],
+                        'data' => [
+                            'type' => 'array',
+                            'required' => true,
+                            'description' => '貨道數據陣列。tid: 貨道號, t060v00: 商品 ID, num: 庫存量',
+                            'example' => [
+                                ['tid' => '1', 't060v00' => '1', 'num' => '10']
+                            ]
+                        ],
+                    ],
+                    'response_parameters' => [
+                        'success' => [
+                            'type' => 'boolean',
+                            'description' => '同步是否成功',
+                            'example' => true
+                        ],
+                        'code' => [
+                            'type' => 'integer',
+                            'description' => '內部業務狀態碼',
+                            'example' => 200
+                        ],
+                        'message' => [
+                            'type' => 'string',
+                            'description' => '回應訊息',
+                            'example' => 'Slot report synchronized success'
+                        ],
+                        'status' => [
+                            'type' => 'string',
+                            'description' => '固定回傳 49 代表同步完成',
+                            'example' => '49'
+                        ],
+                    ],
+                    'request' => [
+                        'account' => '0999123456',
+                        'data' => [
+                            ['tid' => '1', 't060v00' => '1', 'num' => '10']
+                        ]
+                    ],
+                    'response' => [
+                        'success' => true,
+                        'code' => 200,
+                        'message' => 'Slot report synchronized success',
+                        'status' => '49'
+                    ],
+                ],
+                [
+                    'name' => 'B010: 心跳上報與狀態同步 (Heartbeat)',
+                    'slug' => 'b010-heartbeat',
+                    'method' => 'POST',
+                    'path' => '/api/v1/app/machine/status/B010',
+                    'description' => '機台定期向雲端回報當前頁面、版本、溫度及門禁狀態。身份由 Bearer Token 識別。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <api_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [
+                        'current_page' => [
+                            'type' => 'integer',
+                            'required' => true,
+                            'description' => '當前頁面編號。對照表：
+0: 離線, 1: 主頁面, 2: 販賣頁, 3: 管理頁, 4: 補貨頁, 5: 教學頁
+6: 購買中, 7: 鎖定頁, 60: 出貨成功, 61: 貨道測試, 62: 付款選擇
+63: 等待付款, 64: 出貨, 65: 收據簽單, 66: 通行碼, 67: 取貨碼
+68: 訊息顯示, 69: 取消購買, 610: 購買結束, 611: 來店禮, 612: 出貨失敗',
+                            'example' => 1
+                        ],
+                        'firmware_version' => [
+                            'type' => 'string',
+                            'required' => true,
+                            'description' => '軟體或韌體版本號',
+                            'example' => '1.0.5'
+                        ],
+                        'model' => [
+                            'type' => 'string',
+                            'required' => false,
+                            'description' => '機台型號',
+                            'example' => 'STAR-V1'
+                        ],
+                        'temperature' => [
+                            'type' => 'float',
+                            'required' => false,
+                            'description' => '感測環境溫度',
+                            'example' => 25.5
+                        ],
+                        'door_status' => [
+                            'type' => 'integer',
+                            'required' => false,
+                            'description' => '門禁狀態 (0: 關閉, 1: 開啟)',
+                            'example' => 0
+                        ],
+                        'log' => [
+                            'type' => 'string',
+                            'required' => false,
+                            'description' => '事件日誌主訊息',
+                            'example' => 'Door opened'
+                        ],
+                        'log_level' => [
+                            'type' => 'string',
+                            'required' => false,
+                            'description' => '日誌等級 (info, warning, error)',
+                            'example' => 'info'
+                        ],
+                        'log_payload' => [
+                            'type' => 'object',
+                            'required' => false,
+                            'description' => '詳細上下文 (JSON 對象)',
+                            'example' => ['error_code' => 500, 'component' => 'door_sensor']
+                        ],
+                    ],
+                    'response_parameters' => [
+                        'success' => [
+                            'type' => 'boolean',
+                            'description' => '請求是否處理成功',
+                            'example' => true
+                        ],
+                        'code' => [
+                            'type' => 'integer',
+                            'description' => '內部業務狀態碼',
+                            'example' => 200
+                        ],
+                        'message' => [
+                            'type' => 'string',
+                            'description' => '回應訊息說明',
+                            'example' => 'OK'
+                        ],
+                        'status' => [
+                            'type' => 'string',
+                            'description' => '雲端指令代碼。對照表：
+49: reload B017 (貨道同步), 51: reboot (重啟系統)
+60: reboot card machine (刷卡機重啟), 61: checkout (觸發結帳)
+70: unlock (解鎖), 71: lock (鎖定), 85: reload B0552 (遠端出貨)
+待定義: change (遠端找零 - 目前 Java App 尚無對接)',
+                            'example' => '49'
+                        ],
+                    ],
+                    'request' => [
+                        'current_page' => 1,
+                        'firmware_version' => '1.0.5',
+                        'model' => 'STAR-V1',
+                        'temperature' => 25.5,
+                        'door_status' => 0,
+                        'log' => 'Door opened',
+                        'log_level' => 'info',
+                        'log_payload' => [
+                            'error_code' => 500,
+                            'component' => 'door_sensor'
+                        ],
+                    ],
+                    'response' => [
+                        'success' => true,
+                        'code' => 200,
+                        'message' => 'OK',
+                        'status' => '49'
+                    ],
+                    'notes' => '機台收到 B010 回應中的特定 `status` 代碼後，應根據對照表執行對應的指令動作或 API 呼叫 (如 B017)。若為空則代表無指令。'
+                ],
+                [
+                    'name' => 'B012: 商品配置與商品主檔同步 (Unified Sync)',
+                    'slug' => 'b012-unified-sync',
+                    'method' => 'GET/PATCH',
+                    'path' => '/api/v1/app/machine/products/B012',
+                    'description' => '用於機台端獲取目前所有可販售商品的詳細配置。GET 為全量同步，PATCH 為增量更新。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <api_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [],
+                    'response_parameters' => [
+                        'success' => [
+                            'type' => 'boolean',
+                            'description' => '請求是否處理成功',
+                            'example' => true
+                        ],
+                        'code' => [
+                            'type' => 'integer',
+                            'description' => '內部業務狀態碼',
+                            'example' => 200
+                        ],
+                        'data' => [
+                            'type' => 'array',
+                            'description' => '商品明細物件陣列',
+                            'example' => [
+                                [
+                                    't060v00' => '1',
+                                    't060v01' => '可口可樂 330ml',
+                                    't060v01_en' => 'Coca Cola',
+                                    't060v01_jp' => 'コカコーラ',
+                                    't060v03' => 'Cold Drink',
+                                    't060v06' => 'https://.../coke.png',
+                                    't060v09' => 25.0,
+                                    't060v11' => 10,
+                                    't060v30' => 20.0,
+                                    't063v03' => 25.0,
+                                    't060v40' => 'Buy 1 Get 1',
+                                    't060v41' => 'SKU-001',
+                                    'spring_limit' => 10,
+                                    'track_limit' => 15
+                                ]
+                            ]
+                        ]
+                    ],
+                    'request' => [],
+                    'response' => [
+                        'success' => true,
+                        'code' => 200,
+                        'message' => 'OK',
+                        'data' => [
+                            [
+                                't060v00' => '1',
+                                't060v01' => '可口可樂 330ml',
+                                't060v01_en' => 'Coca Cola',
+                                't060v01_jp' => 'コカコーラ',
+                                't060v03' => 'Cold Drink',
+                                't060v06' => 'https://.../coke.png',
+                                't060v09' => 25.0,
+                                't060v11' => 10,
+                                't060v30' => 20.0,
+                                't063v03' => 25.0,
+                                't060v40' => 'Buy 1 Get 1',
+                                't060v41' => 'SKU-001',
+                                'spring_limit' => 10,
+                                'track_limit' => 15
+                            ]
+                        ]
+                    ],
+                    'notes' => '運作邏輯 (Client-side Logic): GET 執行全量同步，App 應於收到成功回應後，先執行 deleteAll() 再進行 insertAll()。PATCH 執行增量更新，App 僅對記憶體中的既存商品進行欄位值覆蓋 (Patching)。'
+                ],
+                [
+                    'name' => 'B013: 機台故障與異常狀態上報 (Error/Status Report)',
+                    'slug' => 'b013-error-report',
+                    'method' => 'POST',
+                    'path' => '/api/v1/app/machine/error/B013',
+                    'description' => '用於接收機台發出的即時硬體狀態代碼（如卡貨、門未關）。身份由 Bearer Token 識別，回傳成功代表伺服器已將任務列入異步隊列處理。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <api_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [
+                        'tid' => [
+                            'type' => 'integer',
+                            'required' => false,
+                            'description' => '涉及到之具體貨道編號 (Slot No)',
+                            'example' => 12
+                        ],
+                        'error_code' => [
+                            'type' => 'string',
+                            'required' => true,
+                            'description' => '硬體狀態代碼 (4 位 16 進位字串)',
+                            'example' => '0403'
+                        ],
+                    ],
+                    'response_parameters' => [
+                        'success' => [
+                            'type' => 'boolean',
+                            'description' => '請求是否已成功接收',
+                            'example' => true
+                        ],
+                        'code' => [
+                            'type' => 'integer',
+                            'description' => '內部業務狀態碼',
+                            'example' => 200
+                        ],
+                    ],
+                    'request' => [
+                        'tid' => 12,
+                        'error_code' => '0403',
+                    ],
+                    'response' => [
+                        'success' => true,
+                        'code' => 200,
+                        'message' => 'Error report accepted'
+                    ],
+                    'notes' => '硬體代碼對照表見後端 MachineService::ERROR_CODE_MAP 定義。
+0402: 出貨成功, 0403: 貨道卡貨, 0202: 貨道缺貨, 0415: 取貨門異常...等。'
+                ],
+                [
+                    'name' => 'B017: 貨道庫存同步 (Slot Synchronization)',
+                    'slug' => 'b017-slot-sync',
+                    'method' => 'GET',
+                    'path' => '/api/v1/app/machine/reload_msg/B017',
+                    'description' => '用於機台端獲獲取所有貨道的最新庫存、效期與狀態。通常由 B010 回傳 status: 49 時觸發。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <api_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [],
+                    'response_parameters' => [
+                        'success' => [
+                            'type' => 'boolean',
+                            'description' => '是否成功',
+                            'example' => true
+                        ],
+                        'data' => [
+                            'type' => 'array',
+                            'description' => '貨道數據陣列。',
+                            'example' => [
+                                [
+                                    'tid' => '1',
+                                    'num' => 10,
+                                    'expiry_date' => '2026-12-31',
+                                    'batch_no' => 'B2026',
+                                    'status' => '1'
+                                ]
+                            ]
+                        ],
+                    ],
+                    'request' => [],
+                    'response' => [
+                        'success' => true,
+                        'code' => 200,
+                        'data' => [
+                            [
+                                'tid' => '1',
+                                'num' => 10,
+                                'expiry_date' => '2026-12-31',
+                                'batch_no' => 'B2026',
+                                'product_id' => 1,
+                                'capacity' => 15,
+                                'status' => '1'
+                            ]
+                        ]
+                    ],
+                    'notes' => 'B017 為全量同步。實作上後端會依據 slot_no 進行排序，並將相關指令狀態更新為已完成。'
+                ],
+                [
+                    'name' => 'B024: 取貨碼/通行碼驗證與消耗回報',
+                    'slug' => 'b024-access-code',
+                    'method' => 'POST/PUT',
+                    'path' => '/api/v1/app/sell/access-code/B024',
+                    'description' => '處理代碼取貨流程。POST 用於驗證碼有效性，PUT 用於回報出貨成功並消耗代碼。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <api_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [
+                        'passCode' => [
+                            'type' => 'string',
+                            'description' => '取貨碼 (POST)',
+                        ],
+                        'accessCodeId' => [
+                            'type' => 'string',
+                            'description' => '代碼 ID (PUT)',
+                        ],
+                        'status' => [
+                            'type' => 'string',
+                            'description' => '出貨狀態 (PUT: 1:成功, 0:失敗)',
+                        ],
+                    ],
+                    'response_parameters' => [
+                        'res1' => ['type' => 'string', 'description' => '雲端關聯 ID'],
+                        'res3' => ['type' => 'string', 'description' => '預計出貨商品 ID'],
+                    ],
+                    'request' => [
+                        'passCode' => '12345678'
+                    ],
+                    'response' => [
+                        'success' => true,
+                        'res1' => '99',
+                        'res3' => '5'
+                    ],
+                ],
+                [
+                    'name' => 'B027: 贈品碼/優惠券驗證與消耗回報',
+                    'slug' => 'b027-freebie-code',
+                    'method' => 'POST/PUT',
+                    'path' => '/api/v1/app/sell/free-gift/B027',
+                    'description' => '處理贈品券與 0 元購活動。邏輯與 B024 相似但對象為行銷贈品。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <api_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [
+                        'passCode' => [
+                            'type' => 'string',
+                            'description' => '贈品碼 (POST)',
+                        ],
+                    ],
+                    'response_parameters' => [
+                        'success' => ['type' => 'boolean', 'description' => '驗證結果'],
+                    ],
+                    'request' => [
+                        'passCode' => 'FREE888'
+                    ],
+                    'response' => [
+                        'success' => true,
+                        'message' => 'Free gift verified'
+                    ],
+                ],
+                [
+                    'name' => 'B055: 遠端指令出貨控制 (Remote Dispense)',
+                    'slug' => 'b055-remote-dispense',
+                    'method' => 'POST/PUT',
+                    'path' => '/api/v1/app/machine/dispense/B055',
+                    'description' => '遠端手動驅動機台出貨。POST 用於獲取待處理指令，PUT 用於回報出貨完成。',
+                    'headers' => [
+                        'Authorization' => 'Bearer <api_token>',
+                        'Content-Type' => 'application/json',
+                    ],
+                    'parameters' => [
+                        'id' => ['type' => 'string', 'description' => '指令 ID (PUT)'],
+                        'stock' => ['type' => 'string', 'description' => '剩餘庫存 (PUT)'],
+                    ],
+                    'request' => [],
+                    'response' => [
+                        'success' => true,
+                        'data' => [
+                            ['slot_no' => '1', 'order_id' => 'RE-123']
+                        ]
+                    ],
+                ]
+            ]
+        ]
+    ]
+];

config/app.php

@@ -70,7 +70,7 @@ return [
     |
     */
 
-    'timezone' => 'UTC',
+    'timezone' => env('APP_TIMEZONE', 'Asia/Taipei'),
 
     /*
     |--------------------------------------------------------------------------
@@ -83,7 +83,7 @@ return [
     |
     */
 
-    'locale' => 'en',
+    'locale' => env('APP_LOCALE', 'zh_TW'),
 
     /*
     |--------------------------------------------------------------------------

config/database.php

@@ -57,6 +57,7 @@ return [
             'prefix' => '',
             'prefix_indexes' => true,
             'strict' => true,
+            'timezone' => env('DB_TIMEZONE', '+08:00'),
             'engine' => null,
             'options' => extension_loaded('pdo_mysql') ? array_filter([
                 PDO::MYSQL_ATTR_SSL_CA => env('MYSQL_ATTR_SSL_CA'),

config/permission.php

@@ -0,0 +1,202 @@
+<?php
+
+return [
+
+    'models' => [
+
+        /*
+         * When using the "HasPermissions" trait from this package, we need to know which
+         * Eloquent model should be used to retrieve your permissions. Of course, it
+         * is often just the "Permission" model but you may use whatever you like.
+         *
+         * The model you want to use as a Permission model needs to implement the
+         * `Spatie\Permission\Contracts\Permission` contract.
+         */
+
+        'permission' => Spatie\Permission\Models\Permission::class,
+
+        /*
+         * When using the "HasRoles" trait from this package, we need to know which
+         * Eloquent model should be used to retrieve your roles. Of course, it
+         * is often just the "Role" model but you may use whatever you like.
+         *
+         * The model you want to use as a Role model needs to implement the
+         * `Spatie\Permission\Contracts\Role` contract.
+         */
+
+        'role' => \App\Models\System\Role::class,
+
+    ],
+
+    'table_names' => [
+
+        /*
+         * When using the "HasRoles" trait from this package, we need to know which
+         * table should be used to retrieve your roles. We have chosen a basic
+         * default value but you may easily change it to any table you like.
+         */
+
+        'roles' => 'roles',
+
+        /*
+         * When using the "HasPermissions" trait from this package, we need to know which
+         * table should be used to retrieve your permissions. We have chosen a basic
+         * default value but you may easily change it to any table you like.
+         */
+
+        'permissions' => 'permissions',
+
+        /*
+         * When using the "HasPermissions" trait from this package, we need to know which
+         * table should be used to retrieve your models permissions. We have chosen a
+         * basic default value but you may easily change it to any table you like.
+         */
+
+        'model_has_permissions' => 'model_has_permissions',
+
+        /*
+         * When using the "HasRoles" trait from this package, we need to know which
+         * table should be used to retrieve your models roles. We have chosen a
+         * basic default value but you may easily change it to any table you like.
+         */
+
+        'model_has_roles' => 'model_has_roles',
+
+        /*
+         * When using the "HasRoles" trait from this package, we need to know which
+         * table should be used to retrieve your roles permissions. We have chosen a
+         * basic default value but you may easily change it to any table you like.
+         */
+
+        'role_has_permissions' => 'role_has_permissions',
+    ],
+
+    'column_names' => [
+        /*
+         * Change this if you want to name the related pivots other than defaults
+         */
+        'role_pivot_key' => null, // default 'role_id',
+        'permission_pivot_key' => null, // default 'permission_id',
+
+        /*
+         * Change this if you want to name the related model primary key other than
+         * `model_id`.
+         *
+         * For example, this would be nice if your primary keys are all UUIDs. In
+         * that case, name this `model_uuid`.
+         */
+
+        'model_morph_key' => 'model_id',
+
+        /*
+         * Change this if you want to use the teams feature and your related model's
+         * foreign key is other than `team_id`.
+         */
+
+        'team_foreign_key' => 'team_id',
+    ],
+
+    /*
+     * When set to true, the method for checking permissions will be registered on the gate.
+     * Set this to false if you want to implement custom logic for checking permissions.
+     */
+
+    'register_permission_check_method' => true,
+
+    /*
+     * When set to true, Laravel\Octane\Events\OperationTerminated event listener will be registered
+     * this will refresh permissions on every TickTerminated, TaskTerminated and RequestTerminated
+     * NOTE: This should not be needed in most cases, but an Octane/Vapor combination benefited from it.
+     */
+    'register_octane_reset_listener' => false,
+
+    /*
+     * Events will fire when a role or permission is assigned/unassigned:
+     * \Spatie\Permission\Events\RoleAttachedEvent
+     * \Spatie\Permission\Events\RoleDetachedEvent
+     * \Spatie\Permission\Events\PermissionAttachedEvent
+     * \Spatie\Permission\Events\PermissionDetachedEvent
+     *
+     * To enable, set to true, and then create listeners to watch these events.
+     */
+    'events_enabled' => false,
+
+    /*
+     * Teams Feature.
+     * When set to true the package implements teams using the 'team_foreign_key'.
+     * If you want the migrations to register the 'team_foreign_key', you must
+     * set this to true before doing the migration.
+     * If you already did the migration then you must make a new migration to also
+     * add 'team_foreign_key' to 'roles', 'model_has_roles', and 'model_has_permissions'
+     * (view the latest version of this package's migration file)
+     */
+
+    'teams' => false,
+
+    /*
+     * The class to use to resolve the permissions team id
+     */
+    'team_resolver' => \Spatie\Permission\DefaultTeamResolver::class,
+
+    /*
+     * Passport Client Credentials Grant
+     * When set to true the package will use Passports Client to check permissions
+     */
+
+    'use_passport_client_credentials' => false,
+
+    /*
+     * When set to true, the required permission names are added to exception messages.
+     * This could be considered an information leak in some contexts, so the default
+     * setting is false here for optimum safety.
+     */
+
+    'display_permission_in_exception' => false,
+
+    /*
+     * When set to true, the required role names are added to exception messages.
+     * This could be considered an information leak in some contexts, so the default
+     * setting is false here for optimum safety.
+     */
+
+    'display_role_in_exception' => false,
+
+    /*
+     * By default wildcard permission lookups are disabled.
+     * See documentation to understand supported syntax.
+     */
+
+    'enable_wildcard_permission' => false,
+
+    /*
+     * The class to use for interpreting wildcard permissions.
+     * If you need to modify delimiters, override the class and specify its name here.
+     */
+    // 'wildcard_permission' => Spatie\Permission\WildcardPermission::class,
+
+    /* Cache-specific settings */
+
+    'cache' => [
+
+        /*
+         * By default all permissions are cached for 24 hours to speed up performance.
+         * When permissions or roles are updated the cache is flushed automatically.
+         */
+
+        'expiration_time' => \DateInterval::createFromDateString('24 hours'),
+
+        /*
+         * The cache key used to store all permissions.
+         */
+
+        'key' => 'spatie.permission.cache',
+
+        /*
+         * You may optionally indicate a specific cache driver to use for permission and
+         * role caching using any of the `store` drivers listed in the cache.php config
+         * file. Using 'default' here means to use the `default` set in cache.php.
+         */
+
+        'store' => 'default',
+    ],
+];

database/factories/Machine/MachineFactory.php

@@ -14,9 +14,9 @@ class MachineFactory extends Factory
         return [
             'name' => 'Machine-' . fake()->unique()->numberBetween(101, 999),
             'location' => fake()->address(),
-            'status' => fake()->randomElement(['online', 'offline', 'error']),
             'temperature' => fake()->randomFloat(2, 2, 10),
             'firmware_version' => 'v' . fake()->randomElement(['1.0.0', '1.1.2', '2.0.1']),
+            'serial_no' => 'SN-' . strtoupper(fake()->unique()->bothify('??###?')),
             'last_heartbeat_at' => fake()->dateTimeBetween('-1 day', 'now'),
         ];
     }

database/factories/System/CompanyFactory.php

@@ -0,0 +1,24 @@
+<?php
+
+namespace Database\Factories\System;
+
+use App\Models\System\Company;
+use Illuminate\Database\Eloquent\Factories\Factory;
+
+class CompanyFactory extends Factory
+{
+    protected $model = Company::class;
+
+    public function definition(): array
+    {
+        return [
+            'name' => $this->faker->company,
+            'code' => $this->faker->unique()->bothify('COMP###'),
+            'status' => 1,
+            'settings' => [
+                'enable_material_code' => false,
+                'enable_points' => false,
+            ],
+        ];
+    }
+}

database/factories/System/UserFactory.php

@@ -1,6 +1,6 @@
 <?php
 
-namespace Database\Factories;
+namespace Database\Factories\System;
 
 use Illuminate\Database\Eloquent\Factories\Factory;
 use Illuminate\Support\Facades\Hash;

database/migrations/2026_03_12_085534_create_user_login_logs_table.php

@@ -0,0 +1,31 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('user_login_logs', function (Blueprint $table) {
+            $table->id();
+            $table->foreignId('user_id')->constrained()->onDelete('cascade');
+            $table->string('ip_address', 45)->nullable();
+            $table->text('user_agent')->nullable();
+            $table->timestamp('login_at')->useCurrent();
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('user_login_logs');
+    }
+};

database/migrations/2026_03_13_022045_add_device_info_to_user_login_logs_table.php

@@ -0,0 +1,30 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('user_login_logs', function (Blueprint $table) {
+            $table->string('device_type')->nullable()->after('user_agent'); // desktop, mobile, tablet
+            $table->string('browser')->nullable()->after('device_type');
+            $table->string('platform')->nullable()->after('browser');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('user_login_logs', function (Blueprint $table) {
+            $table->dropColumn(['device_type', 'browser', 'platform']);
+        });
+    }
+};

database/migrations/2026_03_13_111434_create_permission_tables.php

@@ -0,0 +1,137 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        $teams = config('permission.teams');
+        $tableNames = config('permission.table_names');
+        $columnNames = config('permission.column_names');
+        $pivotRole = $columnNames['role_pivot_key'] ?? 'role_id';
+        $pivotPermission = $columnNames['permission_pivot_key'] ?? 'permission_id';
+
+        throw_if(empty($tableNames), 'Error: config/permission.php not loaded. Run [php artisan config:clear] and try again.');
+        throw_if($teams && empty($columnNames['team_foreign_key'] ?? null), 'Error: team_foreign_key on config/permission.php not loaded. Run [php artisan config:clear] and try again.');
+
+        /**
+         * See `docs/prerequisites.md` for suggested lengths on 'name' and 'guard_name' if "1071 Specified key was too long" errors are encountered.
+         */
+        Schema::create($tableNames['permissions'], static function (Blueprint $table) {
+            $table->id(); // permission id
+            $table->string('name');
+            $table->string('guard_name');
+            $table->timestamps();
+
+            $table->unique(['name', 'guard_name']);
+        });
+
+        /**
+         * See `docs/prerequisites.md` for suggested lengths on 'name' and 'guard_name' if "1071 Specified key was too long" errors are encountered.
+         */
+        Schema::create($tableNames['roles'], static function (Blueprint $table) use ($teams, $columnNames) {
+            $table->id(); // role id
+            if ($teams || config('permission.testing')) { // permission.testing is a fix for sqlite testing
+                $table->unsignedBigInteger($columnNames['team_foreign_key'])->nullable();
+                $table->index($columnNames['team_foreign_key'], 'roles_team_foreign_key_index');
+            }
+            $table->string('name');
+            $table->string('guard_name');
+            $table->timestamps();
+            if ($teams || config('permission.testing')) {
+                $table->unique([$columnNames['team_foreign_key'], 'name', 'guard_name']);
+            } else {
+                $table->unique(['name', 'guard_name']);
+            }
+        });
+
+        Schema::create($tableNames['model_has_permissions'], static function (Blueprint $table) use ($tableNames, $columnNames, $pivotPermission, $teams) {
+            $table->unsignedBigInteger($pivotPermission);
+
+            $table->string('model_type');
+            $table->unsignedBigInteger($columnNames['model_morph_key']);
+            $table->index([$columnNames['model_morph_key'], 'model_type'], 'model_has_permissions_model_id_model_type_index');
+
+            $table->foreign($pivotPermission)
+                ->references('id') // permission id
+                ->on($tableNames['permissions'])
+                ->cascadeOnDelete();
+            if ($teams) {
+                $table->unsignedBigInteger($columnNames['team_foreign_key']);
+                $table->index($columnNames['team_foreign_key'], 'model_has_permissions_team_foreign_key_index');
+
+                $table->primary([$columnNames['team_foreign_key'], $pivotPermission, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_permissions_permission_model_type_primary');
+            } else {
+                $table->primary([$pivotPermission, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_permissions_permission_model_type_primary');
+            }
+        });
+
+        Schema::create($tableNames['model_has_roles'], static function (Blueprint $table) use ($tableNames, $columnNames, $pivotRole, $teams) {
+            $table->unsignedBigInteger($pivotRole);
+
+            $table->string('model_type');
+            $table->unsignedBigInteger($columnNames['model_morph_key']);
+            $table->index([$columnNames['model_morph_key'], 'model_type'], 'model_has_roles_model_id_model_type_index');
+
+            $table->foreign($pivotRole)
+                ->references('id') // role id
+                ->on($tableNames['roles'])
+                ->cascadeOnDelete();
+            if ($teams) {
+                $table->unsignedBigInteger($columnNames['team_foreign_key']);
+                $table->index($columnNames['team_foreign_key'], 'model_has_roles_team_foreign_key_index');
+
+                $table->primary([$columnNames['team_foreign_key'], $pivotRole, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_roles_role_model_type_primary');
+            } else {
+                $table->primary([$pivotRole, $columnNames['model_morph_key'], 'model_type'],
+                    'model_has_roles_role_model_type_primary');
+            }
+        });
+
+        Schema::create($tableNames['role_has_permissions'], static function (Blueprint $table) use ($tableNames, $pivotRole, $pivotPermission) {
+            $table->unsignedBigInteger($pivotPermission);
+            $table->unsignedBigInteger($pivotRole);
+
+            $table->foreign($pivotPermission)
+                ->references('id') // permission id
+                ->on($tableNames['permissions'])
+                ->cascadeOnDelete();
+
+            $table->foreign($pivotRole)
+                ->references('id') // role id
+                ->on($tableNames['roles'])
+                ->cascadeOnDelete();
+
+            $table->primary([$pivotPermission, $pivotRole], 'role_has_permissions_permission_id_role_id_primary');
+        });
+
+        app('cache')
+            ->store(config('permission.cache.store') != 'default' ? config('permission.cache.store') : null)
+            ->forget(config('permission.cache.key'));
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        $tableNames = config('permission.table_names');
+
+        throw_if(empty($tableNames), 'Error: config/permission.php not found and defaults could not be merged. Please publish the package configuration before proceeding, or drop the tables manually.');
+
+        Schema::dropIfExists($tableNames['role_has_permissions']);
+        Schema::dropIfExists($tableNames['model_has_roles']);
+        Schema::dropIfExists($tableNames['model_has_permissions']);
+        Schema::dropIfExists($tableNames['roles']);
+        Schema::dropIfExists($tableNames['permissions']);
+    }
+};

database/migrations/2026_03_13_111435_create_companies_table.php

@@ -0,0 +1,37 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('companies', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');                          // 公司名稱
+            $table->string('code', 20)->unique();            // 公司代碼（簡碼）
+            $table->string('tax_id', 20)->nullable();        // 統一編號
+            $table->string('contact_name', 100)->nullable(); // 聯絡人
+            $table->string('contact_phone', 50)->nullable(); // 聯絡電話
+            $table->string('contact_email')->nullable();     // 聯絡信箱
+            $table->tinyInteger('status')->default(1);       // 1:啟用, 0:停用
+            $table->date('valid_until')->nullable();          // 合約期限
+            $table->text('note')->nullable();                // 備註
+            $table->timestamps();
+            $table->softDeletes();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('companies');
+    }
+};

database/migrations/2026_03_13_111437_add_company_id_to_machines_table.php

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('machines', function (Blueprint $table) {
+            $table->foreignId('company_id')->nullable()->after('id')
+                  ->constrained('companies')->nullOnDelete();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('machines', function (Blueprint $table) {
+            $table->dropConstrainedForeignId('company_id');
+        });
+    }
+};

database/migrations/2026_03_13_111437_add_company_id_to_users_table.php

@@ -0,0 +1,32 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            $table->foreignId('company_id')->nullable()->after('id')
+                  ->constrained('companies')->nullOnDelete();
+            $table->tinyInteger('status')->default(1)->after('role'); // 1:啟用, 0:停用
+            $table->softDeletes();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('users', function (Blueprint $table) {
+            $table->dropConstrainedForeignId('company_id');
+            $table->dropColumn(['status', 'deleted_at']);
+        });
+    }
+};

database/migrations/2026_03_13_134237_add_is_system_to_roles_table.php

@@ -0,0 +1,28 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class extends Migration
+{
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::table('roles', function (Blueprint $table) {
+            $table->boolean('is_system')->default(false)->after('guard_name');
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::table('roles', function (Blueprint $table) {
+            $table->dropColumn('is_system');
+        });
+    }
+};