[REFACTOR] 實作側邊欄與儀表板多語系化，修復 UI 位移與樣式優化

.agents/rules/api-rules.md

@@ -2,208 +2,82 @@
 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>` 識別。
+    2.  **Request Body**: 透過 `machine` 或 `serial_no` 等欄位識別具體機台。
+*   **主要 Endpoint 範例**:
+    *   **心跳上報 (B010)**: `POST /api/app/machine/status/B010`
+    *   **交易回傳 (B600)**: `POST /api/app/B600` (Body 欄位 `req2` 為機台編號)
+    *   **貨道庫存 (B017)**: `POST /api/app/machine/reload_msg/B017`
+    *   **遠端出貨 (B055)**: `POST /api/app/machine/dispense/B055`
 
 ---
 
-## 主要 Endpoints 範例
+## ⚡ 5. 高併發處理與隊列
 
-### 1) Auth
+為了系統穩定性，以下 API **嚴禁直寫資料庫**，必須進入 **Redis Queue** 異步處理：
+1.  **B010**: 心跳上傳（每 5-10 秒一次）。
+2.  **B600 / B602**: 交易與出貨紀錄。
+3.  **B220**: 零錢機庫存變動。
+4.  **B710**: 計時器狀態同步。
 
-* POST /api/v1/auth/login
-
-  * request:
-
-  ```json
-  {"email":"user@example.com","password":"pa55"}
-  ```
-
-  * response:
-
-  ```json
-  {"success":true,"code":200,"data":{"token":"...","user":{"id":1,"name":"..."}}}
-  ```
-
-* POST /api/v1/auth/logout
-
-  * header: Authorization: Bearer <token>
-  * response: 200
-
-* POST /api/v1/auth/refresh
+後端應立即回傳 `202 Accepted` 或業務定義的成功碼，由 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。