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

2026-03-12 17:42:57 +08:00
parent 8ee14eaa29
commit 773396fc90
43 changed files with 1928 additions and 650 deletions
--- a/docs/architecture_plan.md
+++ b/docs/architecture_plan.md
@@ -343,9 +343,10 @@ Spatie 預設的 roles 表必須加上多租戶設計，確保留戶只能管理
 |------|------|------|------|
 | `id` | BIGINT PK | — | — |
 | `machine_id` | BIGINT FK | → machines | — |
-| `command_type` | VARCHAR(20) | 指令類型 | B010 response status |
+| `command_type` | VARCHAR(50) | 指令類型 (reboot, lock, stock_update, dispense...) | B010, B017, B055 |
 | `status` | ENUM | pending/sent/success/failed | — |
-| `payload` | JSON NULL | 指令附加資料 | — |
+| `payload` | JSON NULL | 指令參數 (如: `{"slot_no": "A01", "num": 50}`) | — |
+| `ttl` | INT DEFAULT 60 | 指令失效秒數 (尤其針對遠端出貨) | — |
 | `executed_at` | TIMESTAMP NULL | 執行時間 | — |
 | `timestamps` | — | — | — |

@@ -503,76 +504,15 @@ Route::prefix('v1/app')->middleware(['throttle:iot'])->group(function () {

 ## 八、實作路線圖與預估時程

-> **總結報告**：為確保開發品質與應對突發狀況，本專案預計總開發時程擴展為 **16 - 18 週**。以 1 人天 = 8 小時純開發時間計算，預估總投入約 **80 - 90 個工作天**。
+> [!NOTE]
+> 為了保持規劃書的簡潔，詳細的開發時程、甘特圖、子選單拆解與 Phase 任務清單已獨立至專屬文件。

-### 🗓️ 專案開發甘特圖 (自動排除週末)
+👉 **[查看詳細開發時程規劃 (development_schedule.md)](file:///home/mama/projects/star-cloud/docs/development_schedule.md)**

-```mermaid
-gantt
-    title Star Cloud 實作時程規劃
-    dateFormat  YYYY-MM-DD
-    excludes weekends
-    
-    section 第一階段 MVP
-    Phase 1 基礎設施與資料表      :active, p1, 2026-03-11, 14d
-    Phase 2 IoT API 與異步管線    :p2, after p1, 24d
-    Phase 3 後台 MVP 頁面整合     :p3, after p2, 18d
-    
-    section 第二階段 進階
-    Phase 4 進階功能與報表分析    :p4, after p3, 30d
-```
-
-### 📅 詳細時程對照表
-
-| 階段 (Phase) | 關鍵任務摘要 | 預估天數 | 預計工作日期 | 狀態 |
-| :--- | :--- | :---: | :---: | :---: |
-| **Phase 1** | 基礎架構、28張表設計、資料遷移基礎 | 14 工作天 | 03/11 ~ 03/30 | 準備啟動 |
-| **Phase 2** | B010~B710 核心 API、Redis 異步 Job、Service | 24 工作天 | 03/31 ~ 05/01 | 規劃中 |
-| **Phase 3** | 儀表板、機台/銷售/遠端管理 MVP 介面 | 18 工作天 | 05/04 ~ 05/27 | 規劃中 |
-| **Phase 4** | 數據分析統計圖表、補貨演算法、自動對帳模組 | 30 工作天 | 05/28 ~ 07/08 | 規劃中 |
-
---
-
-### 🔵 第一階段：MVP 營運核心 (最優先上線)
-**目標**：確保機台金流與指令能穩定連通，完成基礎營運管理功能。
-
-#### Phase 1：基礎設施與核心資料表 (預計: 14 工作天)
- [ ] 擴充 `machines` 表（serial_no, model 等欄位）
- [ ] 建立 多租戶與權限基礎表 (`companies`, `spatie/laravel-permission` 相關表)
- [ ] 將 `company_id` 欄位加入 `users`, `machines`, `roles` 等核心表
- [ ] 建立 `translations` 多語系字典表，並擴充 `products` 語系關聯
- [ ] 新增 `products` + `product_categories` 表
- [ ] 新增 `machine_slots` 表
- [ ] 新增 `orders` + `order_items` 表
- [ ] 新增 `invoices` + `dispense_records` 表
- [ ] 新增 `remote_commands` 表 (遠端管理與對接用)
- [ ] 新增 `payment_types` 表 + Seeder
-
-#### Phase 2：核心營運 IoT API 與異步管線 (預計: 24 工作天)
- [ ] 實作 **B010** API (心跳上報 + 狀態更新 + 遠端管理)
- [ ] 實作 **B017 / B055** API (遠端改庫存/出貨)
- [ ] 實作 **B600 / B601 / B602** API (金流/發票/出貨紀錄)
- [ ] 實作 **B650** API (會員驗證 + 點數折抵)
- [ ] 建立上述對應的 **Redis Queue Job + Service** 異步處理邏輯
-
-#### Phase 3：後台 MVP 頁面整合 (預計: 18 工作天)
- [ ] **多租戶權限與身份切換機制 (Middleware & Views)**
- [ ] 儀表板 Dashboard：即時數據看板 (營收、機台數，依據租戶隔離資料)
- [ ] 機台管理 Machines：連線狀態、貨道庫存、指令操作 UI
- [ ] 銷售管理 Sales：訂單列表、出貨/發票追蹤
- [ ] 系統基礎設定：帳號與權限設定 (RBAC UI)、商品建檔、金流代碼設定、**多語系字典維護介面**
-
---
-
-### 🟢 第二階段：進階營運與智慧分析 (持續優化)
-**目標**：強化報表分析能力與自動化稽核。
-
-#### Phase 4：進階功能與報表分析模組 (預計: 30 工作天)
- [ ] **分析管理 Analysis**：趨勢圖、商品熱銷分析、機台產能報表
- [ ] **倉庫管理 Warehouses**：補貨建議、入/出庫流程優化
- [ ] **擴充支持**：B220 (零錢機) + B710 (計時器) 支援
- [ ] **自動化稽核 Audit**：對帳機制、異常提醒
- [ ] **行銷模組**：Line 聯動、預約系統、UI 動態設定
+本專案預計總開發時程為 **17 ~ 18 週** (約 85 個工作天)，分為三個主要階段：
+1. **Phase 1 (5天)**：基礎建設與 IoT API 串接。
+2. **Phase 2 (50天)**：後台核心營運管理介面 (含遠端與倉庫管理)。
+3. **Phase 3 (30天)**：進階分析報表與垂直功能模組。


 ---
--- a/docs/b010_technical_spec.md
+++ b/docs/b010_technical_spec.md
@@ -24,7 +24,7 @@ B010 是 Cloud 向機台下達遠端指令（如：開鎖、重啟、改庫存
 ## 2. 執行面挑戰：高併發與效能 (Performance)

 ### 2.1 寫入瓶頸分析
-*   **數據規模**：10,000 台機台，每 5 秒一個心跳，全站 QPS 約 2,000。
+*   **數據規模**：10,000 台機台，每 10 秒一個心跳，全站 QPS 約 1,000。
 *   **DB 壓力**：直接同步寫入 MySQL `machines` 與 `machine_logs` 將導致磁碟 I/O 鎖定。

 ### 2.2 解決策略 (Redis 緩衝)
@@ -32,58 +32,34 @@ B010 是 Cloud 向機台下達遠端指令（如：開鎖、重啟、改庫存
    *   **最後在線時間**、**溫度**、**門禁狀態**、**頁面碼** 等動態數據優先存入 **Redis**。
    *   **批量更新 (Lazy Update)**：每 1~5 分鐘由後台任務將 Redis 數據批量寫回 MySQL `machines` 表。
 *   **日誌優化**：
-    *   正常的心跳資料不逐筆寫入 `machine_logs`。
-    *   僅在**狀態變更**（如：門被打開、溫度過高、軟體報錯）時，才觸發資料庫日誌記錄。
+    *   **正常心跳不寫入資料庫日誌**，僅在**狀態變更**（如：門被打開、溫度過高、軟體報錯）時，才觸發資料庫日誌記錄。

 ---

-## 3. 資料庫結構擴充 (Schema Gap)
-
-必須對原有的 `machines` 表進行欄位擴充，以承載 B010 的回傳值：
-
-| 新增欄位 | 類型 | 說明 |
-|----------|------|------|
-| `serial_no` | VARCHAR(50) UNIQUE | 機台序號 (API `machine`) |
-| `model` | VARCHAR(50) | 機台型號 (API `M_Stus`) |
-| `current_page` | TINYINT | 當前頁面代碼 (API `M_Stus2`) |
-| `door_status` | VARCHAR(10) | 門禁狀態 (`open`/`closed`) |
-| `api_token` | VARCHAR(100) | 獨立安全憑證 (取代共用 Key) |
-
---
-
-## 4. 安全性與驗證策略 (Security)
+## 5. 安全性與驗證策略 (Security)

 *   **API Key 遷移**：從目前全系統硬編碼的共用 Key，逐步遷移至每台機台專屬的 `api_token`。
+*   **驗證方式**：機台端需在 Header 帶入 `Authorization: Bearer <api_token>` 進行身份驗證。
 *   **實裝方式**：
    *   後台管理介面新增「核發機台 Token」功能。
    *   建立專屬 `IotAuthMiddleware`，驗證請求中的 Token 與 `machines` 表是否匹配。

 ---

-## 5. 離線與告警機制 (Heartbeat Logic)
+## 6. 離線與告警機制 (Heartbeat Logic)

-*   **在線判定**：心跳超時（建議超過 60 秒）即在 UI 將機台顯示為「離線」。
-*   **自動維護**：排程 Job 定期掃描 `machines.last_heartbeat_at`，對長期失聯的機台發出系統告警。
+*   **在線判定**：心跳超時超過 **30 秒** 即在 UI 將機台顯示為「離線」。
+*   **告警機制**：機台斷線時，系統需即時產出**警示或推播通知**給相關人員。
+*   **自動維護**：排程 Job 定期掃描 `machines.last_heartbeat_at`，處理長期失聯機台。

 ---

-## 6. 待確認事項 (To-be-confirmed)
+## 7. 業務邏輯細節 (Fine-grained Logic)

-### 6.1 指令下發與回應 (Command Flow)
-1.  **指令優先順序**：當後台同時有多個指令待執行 (如：改庫存 + 重啟) 時，應如何定義優先權？
-2.  **執行狀態回饋**：機台收到心跳指令後的執行結果確認，應採「被動判定」(機台下次心跳狀態正確則視為成功) 還是「主動回報」(機台另呼叫 API)？
+*   **指令成功判定**：採「**被動判定**」。機台收到指令後，若在其後的 B010 心跳中回報狀態正確（如：頁面碼已變更），即視為指令執行成功。

-### 6.2 效能與日誌策略 (Performance & Logs)
-3.  **Redis 更新頻率**：即時狀態從 Redis 批量同步至 MySQL 的建議時間間隔 (目前暫估 1~5 分鐘)。
-4.  **心跳日誌級別**：是否確認「正常心跳」不寫入資料庫日誌，僅記錄「異常/變更」事件？
+---

-### 6.3 在線/離線判定 (Presence)
-5.  **離線超時定義**：預計多久未收心跳判定為離線？(建議 30~60 秒)。
-6.  **斷線告警機制**：機台斷線時，是否需即時產出系統警示或推播給相關人員？
+## 8. 待確認事項 (已結案)

-### 6.4 安全性驗證 (Auth)
-7.  **Token 傳遞方式**：將 API Key 遷移至專屬 Token 時，機台端是否能配合在 Header (`Authorization: Bearer <token>`) 帶入，或必須保留在 JSON Payload 中？
-
-### 6.5 欄位細節 (Field Details)
-8.  **URL {workid} 定義**：URL 中的 `{workid}` 應對應為 `serial_no` (機台序號) 還是資料庫自增 `id`？
-9.  **M_Stus2 告警觸發**：20 多種頁面狀態碼中，哪些特定的錯誤代碼需要在管理後台觸發即時紅字警示？
+目前已根據 2026-03-12 的討論完成所有關鍵決策。
--- a/docs/b017_technical_spec.md
+++ b/docs/b017_technical_spec.md
@@ -8,7 +8,7 @@

 ### 1.1 觸發流程
 1.  **管理行為**：管理員在後台管理介面手動修改特定機台的貨道庫存數量。
-2.  **指令預備**：後端系統記錄異動請求，並在該機台的 B010 (心跳) 回應中，將 `status` 設為 `49` (reload B017)。
+2.  **指令預備**：後端系統將異動請求寫入 `remote_commands` 表 (type: `stock_update`, payload 含貨道編號與數量)，並在該機台的 B010 (心跳) 回應中將 `status` 設為 `49` (reload B017)。
 3.  **機台拉取**：機台收到心跳回應中的 `49` 代碼後，主動呼叫 B017 API (`/api/app/machine/reload_msg/{workid}`)。
 4.  **數據同步**：機台獲取最新庫存數據並更新本地狀態。

@@ -43,11 +43,10 @@

 ## 4. 欄位定義與對照

-| 欄位名稱 | 資料庫對應 | 說明 |
+| B017 欄位 | 資料庫對應 | 說明 |
 |----------|------------|------|
-| `workid` | `machines.serial_no` | 機台識別序號 |
 | `channelid` | `machine_slots.slot_no` | 貨道編號 |
-| `stock` | `machine_slots.stock` | 該貨道的當前可用庫存 |
+| `stock` | `machine_slots.stock` | 該貨道的最新庫存數量 |

 ---

@@ -57,9 +56,16 @@

 ---

-## 6. 待確認事項 (To-be-confirmed)
+## 6. 庫存衝突處理原則

-1.  **庫存衝突優先權**：當「雲端改庫存」與「現場實體銷售」同時發生時，最終庫存應以何者為準？(待主管確認)。
-2.  **API 欄位對照**：
-    *   `workid` 是否嚴格對應 `serial_no`？
-    *   `channelid` 是否對標 `slot_no`？
+**以機台實際出貨為最終依據（最終一致性策略）**。
+
+*   **情境**：雲端下發庫存更新（如設為 50），同時機台現場發生實體銷售（賣出 2 個）。
+*   **處理原則**：機台在本地執行 `50 - 已出貨量 = 48`，並透過後續的 B602 出貨紀錄上報給雲端，雲端以此為最終庫存數字。
+*   **理由**：機台掌握實際出貨資訊，強制以雲端覆蓋將導致帳面庫存與實際庫存不符，引發空貨道但系統顯示有庫存的嚴重問題。
+
+---
+
+## 7. 待確認事項 (已結案)
+
+所有關鍵決策已於 2026-03-12 完成確認。
--- a/docs/b055_technical_spec.md
+++ b/docs/b055_technical_spec.md
@@ -7,7 +7,7 @@
 ## 1. 業務流程與通訊機制

 ### 1.1 指令下發流程
-1.  **指令生成**：Cloud 後端（管理者或系統觸發）在 `remote_dispense_commands` 表中建立一筆狀態為 `0` (待執行) 的指令。
+1.  **指令生成**：Cloud 後端（管理者）在 `remote_commands` 表中建立一筆類型為 `dispense`、狀態為 `pending` 的指令。
 2.  **心跳通知**：在該機台的 B010 回應中，將 `status` 設為 `85` (reload B055)。
 3.  **機台撈取 (POST)**：機台呼叫 B055 POST API (`/api/app/machine/dispense/{workid}`) 取得詳細出貨參數（貨道 ID、指令 ID）。
 4.  **執行與回報 (PUT)**：機台嘗試出貨後，呼叫 B055 PUT API 回報出貨結果及剩餘庫存。
@@ -17,14 +17,16 @@

 ---

-## 2. 資料庫結構：`remote_dispense_commands`
+## 2. 指令資料定義：使用全域 `remote_commands`

-| 欄位 | 說明 | 備註 |
-|------|------|------|
-| `command_id` | 執行命令 ID | 用於追蹤單次指令 |
-| `slot_no` | 貨道 ID | 指派機台出貨的通道 |
-| `status` | 執行狀態 | 0:待執行, 1:成功, 2:失敗 |
-| `remaining_stock` | 剩餘庫存 | 由機台回報 |
+遠端出貨指令統一存放在 `remote_commands` 表中，B055 的特定參數將存放於 `payload` (JSON) 欄位。
+
+| 欄位 | B055 對應說明 | 備註 |
+|------|--------------|------|
+| `id` | 執行命令 ID | 用於追蹤單次指令 (POST 回傳) |
+| `payload->slot_no` | 貨道 ID | 指派機台出貨的通道 |
+| `status` | 執行狀態 | pending/sent/success/failed |
+| `ttl` | 指令效期 | 預設 60 秒 |

 ---

@@ -35,21 +37,31 @@

 ---

-## 4. 待確認事項 (To-be-confirmed)
+## 4. 欄位定義與對照

-### 4.1 業務情境 (Scenario)
-1.  **指令發起來源**：確認指令是由後台管理員手動測試發起，還是串接外部線上購買系統產出的取貨指令？
+| B055 欄位 | 資料庫對應 | 說明 |
+|----------|------------|------|
+| `command_id` | `remote_dispense_commands.id` | 指令唯一識別碼 |
+| `slot_no` | `machine_slots.slot_no` | 目標貨道編號 |

-### 4.2 失敗處理機制 (Failure Handling)
-2.  **自動退款/告警**：若機台 PUT 回報出貨失敗，雲端是否需要自動發起退款（針對線上訂單）或發送維修告警通知？
+---

-### 4.3 指令效期與防重 (TTL & Idempotency)
-3.  **指令效期**：如果指令發出後機台失聯，該指令應在多久後失效 (TTL)？
-4.  **防重複機制**：如何嚴格確保同一個 `command_id` 不會被重複執行兩次？
+## 5. 業務邏輯細節建議

-### 4.4 安全性與權限 (Security)
-5.  **指令簽名**：除了 `api_token`，發送出貨指令是否需要額外的加密簽名驗證以防偽造？
-6.  **權限限制**：是否限制僅特定高級管理員可發起此類高風險指令？
+### 5.1 指令效期 (TTL)
+*   **建議設定**：**60 秒 (1 分鐘)**。
+*   **理由**：由於遠端出貨指令由管理員手動發起（通常用於現場故障排除或客訴處理），若機台因網路問題超過一分鐘未拉取指令，該次操作的情境通常已失效，應自動失效以防止後續無預警出貨。

-### 4.5 欄位定義
-7.  **URL {workid}**：確認是否對標 `serial_no`。
+### 5.2 失敗處理
+*   **機制**：機台回報出貨失敗時，系統僅需記錄結果並在後台顯示異常狀態。
+*   **處理原則**：考量目前僅供管理員手動發起，**不需執行自動退款**，由管理員依據日誌進行後續手動處理即可。
+
+### 5.3 安全與權限
+*   **驗證機制**：維持 `api_token` 驗證，不需額外的加密簽名。
+*   **權限控制**：建議在 RBAC 權限系統中，限制僅「高級管理員」或「維修主管」具備發起遠端出貨的權限。
+
+---
+
+## 6. 待確認事項 (已結案)
+
+所有關鍵決策已於 2026-03-12 完成確認。
--- a/docs/b220_technical_spec.md
+++ b/docs/b220_technical_spec.md
@@ -19,14 +19,27 @@

 ## 2. 執行面優化與告警 (Execution & Alerts)

-### 2.1 高頻數據處理 (待確認頻率)
+### 2.1 數據處理頻率
+*   **回報時機**：機台在**每次交易完成後**（包含消費者找零或管理員補幣）即時呼叫 B220 API 回報最新庫存。
 *   **快取策略**：機台各面額的最新總量應快取於 Redis 或更新至 `machines` 表的擴充欄位，供後台儀表板即時監看。
-*   **寫入過濾**：為節省儲存空間，建議僅在資料數值有實際變動時才寫入 `coin_inventory_logs`。
+*   **寫入過濾**：為節省儲存空間，僅在資料數值有實際變動時才寫入 `coin_inventory_logs`。

 ### 2.2 找零不足告警 (Low Inventory Warning)
-*   **機制**：當特定面額（如 5 元、10 元硬幣）低於預設的水位閾值時，系統應：
-    *   在管理後台儀表板顯示紅字告警。
-    *   （選配）發送推播或系統通知給補貨人員。
+
+當特定面額低於預設的水位閾值時，系統將觸發告警。
+
+#### **建議水位告警計畫 (Threshold Plan)**
+| 面額 | 告警閾值 (枚數) | 說明 |
+|------|----------------|------|
+| 1 元 | < 50 | 找零頻率高，需預留較快補幣空間 |
+| 5 元 | < 40 | |
+| 10 元| < 40 | 主要找零面額，需重點監控 |
+| 50 元| < 20 | |
+| 100 元以上 | — | 通常不作為找零面額，僅供庫存監控 |
+
+*   **通知管道**：
+    1.  **後台儀表板**：在機台管理介面顯示顯眼的「紅字告警」。
+    2.  **系統推播**：即時發送通知給相關營運或補貨人員。

 ---

@@ -41,11 +54,7 @@

 ---

-## 4. 待確認事項 (To-be-confirmed)
+## 4. 待確認事項 (已結案)

-### 4.1 系統效能與頻率
-1.  **回報頻率**：確認機台呼叫 B220 的頻率（是每次交易後即時回報，還是定時回報？）。
+所有關鍵決策已於 2026-03-12 完成確認並由系統規劃水位計畫。

-### 4.2 告警配置
-2.  **水位閾值**：各面額的最低告警水位數值（如 5 元低於多少枚觸發告警）。
-3.  **通知方式**：觸發告警時的具體通知管道。
--- a/docs/b600_technical_spec.md
+++ b/docs/b600_technical_spec.md
@@ -43,10 +43,20 @@

 ---

-## 4. 待確認事項 (To-be-confirmed)
+## 4. 數據完整性與異常處理 (Integrity & Exceptions)

-### 4.1 數據完整性稽核
-1.  **自動對帳**：是否需要定期自動比對「B600 收取金額」與「B602 實際出貨金額」，並將差異標記為異常訂單？
+### 4.1 自動對帳機制 (Auto-Reconciliation)
+*   **機制**：系統後台需建立定期定時任務（Scheduled Task），比對同一 `flow_id` 下的以下數據：
+    - **B600 (收取金額)**：訂單總計金額。
+    - **B602 (出貨總價值)**：機台實際出貨商品之總價值。
+*   **異常標記**：若兩者金額不符（例如：付了 $50 但僅出貨 $0 或 $30），系統應自動將該訂單標記為 **「金額異常」**，並同步產出警示通知供營運人員手動稽核。

-### 4.2 失敗補償邏輯
-2.  **出貨失敗處理**：若 B602 回報「出貨失敗」，系統是否需觸發自動退款程序（限線上支付）或發送補發通知？
+### 4.2 出貨失敗處理 (Dispense Failure)
+*   **原則**：若 B602 回報「出貨失敗」，系統**不觸發自動退款**程序。
+*   **處理流程**：系統僅記錄失敗狀態並維持訂單為「待處理/異常」，後續由客服或管理員介入，根據實際情況進行人工退款、補發指令或現場處理。
+
+---
+
+## 5. 待確認事項 (已結案)
+
+所有關鍵決策已於 2026-03-12 完成確認。
--- a/docs/b601_technical_spec.md
+++ b/docs/b601_technical_spec.md
@@ -42,8 +42,8 @@

 ---

-## 4. 待確認事項 (To-be-confirmed)
+## 4. 待確認事項 (已結案)

-### 4.1 邏輯關聯與超時
-1.  **發票缺失標記**：若收到 B600 (金流) 但在預設時間內（如 5 分鐘）未收到 B601，後台是否應將該訂單標記為「發票缺失」以供巡檢。
-2.  **重試機制**：機台端在 B601 呼叫失敗時的緩存與重傳策略。
+所有關於發票關聯邏輯與重試機制的技術決策已於 2026-03-12 完成確認：
+1. **發票缺失標記**：系統不需針對 B600 與 B601 的到達時差進行「發票缺失」自動標記。
+2. **重試機制**：機台端呼叫失敗時不需額外的緩存與重傳策略（維持基本回報邏輯）。
--- a/docs/b602_technical_spec.md
+++ b/docs/b602_technical_spec.md
@@ -37,14 +37,21 @@

 ---

-## 4. 待確認事項 (To-be-confirmed)
+## 4. 數據完整性與異常處理 (Integrity & Exceptions)

-### 4.1 訂單完結判斷
-1.  **超時標記**：若雲端收到 B600 但遲遲未收到 B602，預設在多久後應將訂單標記為「出貨超時」？
-2.  **狀態遷移**：出貨失敗 (`status=1`) 時，訂單的最終顯示文字與處理流程。
+### 4.1 出貨超時監控 (Dispense Timeout)
+*   **閾值建議**：若系統收到 B600 (金流) 超過 **5 分鐘** 仍未收到任何對應之 B602 (出貨回報)，雲端後台應自動將該訂單標記為 **「出貨超時」**。
+*   **用途**：此狀態主要用於輔助對帳，標記可能發生網路中斷或機台異常卡死之交易，需由管理員介入核實。

-### 4.2 營收與點數處理
-3.  **出貨失敗補償**：若 B602 回報失敗：
-    *   行動支付是否自動觸發退款？
-    *   是否自動退回該次交易所扣除之會員點數與優惠券？
-4.  **現金交易失敗**：出貨失敗且為現金交易時，是否應產出待維護工單或通知補貨員。
+### 4.2 出貨失敗處理 (Dispense Failure)
+*   **狀態遷移**：當 B602 回報 `dispense_status = 1` (失敗) 時，訂單狀態應更新為 **「出貨失敗」**。
+*   **即時通知**：系統應立即產出 **「後台警示通知」** 並推播給營運人員，以便快速處理現場排礙或後續補償。
+*   **補償與維護策略 (現階段)**：
+    - **點數/優惠券**：目前不採自動退回機制，維持異常狀態由管理員人工處理。
+    - **營運維護**：目前暫不自動產出維護工單或推播給補貨員，僅紀錄於異常日誌並顯示於後台通知區。
+
+---
+
+## 5. 待確認事項 (已結案)
+
+所有關於出貨流程與超時判定之技術決策已於 2026-03-12 完成確認。
--- a/docs/b650_technical_spec.md
+++ b/docs/b650_technical_spec.md
@@ -1,4 +1,4 @@
-# B650 API (會員/點數/取貨碼驗證) 技術規範與執行指南
+# [暫緩執行] B650 API (會員/點數/取貨碼驗證) 技術規範與執行指南

 本文件定義 B650 API 的技術實作規範，用於處理會員驗證、點數折抵、優惠券兌換、取貨碼驗證以及線上訂單線下結帳等多元功能。

--- a/docs/b710_technical_spec.md
+++ b/docs/b710_technical_spec.md
@@ -1,4 +1,4 @@
-# B710 API (計時器狀態回傳) 技術規範與執行指南
+# [暫緩執行] B710 API (計時器狀態回傳) 技術規範與執行指南

 本文件定義 B710 API 的技術實作規範，用於處理計時型設備（如洗衣服務、按摩服務）的剩餘時間監測與狀態回報。

--- a/docs/development_schedule.md
+++ b/docs/development_schedule.md
@@ -0,0 +1,250 @@
+# Star Cloud 開發時程規劃書
+
+> [!NOTE]
+> 本文件由 `architecture_plan.md` 分離，專門記錄專案的開發週期、階段目標與詳細子選單實作時程。
+> **總結報告**：本專案預計總開發時程為 **17 ~ 18 週**。以 1 人天 = 8 小時純開發時間計算，預估總投入約 **85 個工作天**。
+
+---
+
+## 一、專案開發甘特圖 (自動排除週末)
+
+```mermaid
+gantt
+    title Star Cloud 實作時程規劃
+    dateFormat  YYYY-MM-DD
+    excludes weekends
+    
+    section Phase 1 基礎建設
+    資料表 + IoT API + 異步管線   :active, p1, 2026-03-16, 5d
+    
+    section Phase 2 核心營運
+    後台核心營運頁面整合           :p2, after p1, 50d
+    
+    section Phase 3 進階模組
+    進階分析與垂直模組             :p3, after p2, 30d
+```
+
+## 二、詳細時程對照表
+
+| 階段 (Phase) | 關鍵任務摘要 | 預估天數 | 預計工作日期 | 狀態 |
+| :--- | :--- | :---: | :---: | :---: |
+| **Phase 1** | 28 張資料表 Migration + B010~B710 核心 API + Redis 異步 Job | **5 工作天** | 03/16 ~ 03/20 | 進行中 |
+| **Phase 2** | **後台核心營運頁面** (帳號權限、資料設定、機台、銷售、遠端、倉庫、儀表板) | **50 工作天** | 03/23 ~ 05/29 | 規劃中 |
+| **Phase 3** | **進階垂直模組** (分析、稽核、會員、APP、Line、預約、特殊權限) | **30 工作天** | 06/01 ~ 07/10 | 規劃中 |
+
+---
+
+## 三、後台子菜單開發細節 (Module & Sub-menu Breakdown)
+
+> [!IMPORTANT]
+> 開發順序依**功能相依性**排列：先建帳號與權限基礎 → 再建商品等主檔資料 → 然後是依賴主檔的機台與銷售 → 接著是營運急需的遠端管理與倉庫管理 → 最後是匯總數據的儀表板。Phase 3 則從分析報表開始，逐步擴展至行銷與第三方聯動。
+
+### ⚡ Phase 1：基礎建設 (03/16 ~ 03/20)
+
+| 任務類別 | 內容 | 日期 |
+| :--- | :--- | :---: |
+| 資料庫 Migration | 28 張資料表建立、Seeder、多租戶欄位擴充 | 03/16 - 03/17 |
+| IoT API 端點 | B010 心跳、B017 庫存、B055 出貨、B600/B601/B602 金流 | 03/18 - 03/19 |
+| 異步管線 | Redis Queue Job + Service 層、B650 會員驗證 | 03/20 |
+
+### 🏛️ Phase 2：核心營運子選單 (03/23 ~ 05/29)
+共 51 項子選單，依功能相依性分為七個開發階段。
+
+#### 📌 A. 帳號與權限基礎 (03/23 ~ 04/03)
+> 為何優先：帳號、角色、權限是所有後台模組的存取控管基礎，必須最先到位。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 1 | **資料設定** | 帳號管理 | 03/23 - 03/24 | 租戶主帳號 CRUD，為所有管理功能打底 |
+| 2 | | 子帳號 | 03/25 | 租戶內部員工帳號新增與停用 |
+| 3 | | 子帳號角色 | 03/26 | 租戶內部角色定義與權限範圍 |
+| 4 | **個人設定** | 個人檔案 | 03/27 | 登入使用者個人資訊修改（已有基礎） |
+| 5 | **權限設定** | 角色設定 | 03/30 - 03/31 | `spatie` RBAC 角色定義與分配核心 UI |
+| 6 | | APP功能 | 04/01 | APP 模組的功能權限開關 |
+| 7 | | 資料設定 | 04/01 | 資料設定模組的權限開關 |
+| 8 | | 銷售管理 | 04/01 | 銷售管理模組的權限開關 |
+| 9 | | 機台管理 | 04/01 | 機台管理模組的權限開關 |
+| 10 | | 倉庫管理 | 04/02 | 倉庫管理模組的權限開關 |
+| 11 | | 分析管理 | 04/02 | 分析管理模組的權限開關 |
+| 12 | | 稽核管理 | 04/02 | 稽核管理模組的權限開關 |
+| 13 | | 遠端管理 | 04/02 | 遠端管理模組的權限開關 |
+| 14 | | Line管理 | 04/03 | Line 管理模組的權限開關 |
+| 15 | | 其他功能 | 04/03 | 其餘未分類功能之權限控管 |
+| 16 | | AI智能預測 | 04/03 | AI 預測功能的存取權限設定 |
+
+#### 📌 B. 基礎資料主檔 (04/06 ~ 04/10)
+> 為何第二：商品主檔是機台貨道、倉庫、銷售等後續模組的共同基礎資料。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 17 | **資料設定** | 商品管理 | 04/06 - 04/08 | 商品主檔 CRUD、條碼、售價、圖片上傳 |
+| 18 | | 廣告管理 | 04/09 | 機台螢幕廣告素材上傳與排程 |
+| 19 | | 管理者可賣 | 04/09 | 管理者可直接販售之商品清單設定 |
+| 20 | | 點數設定 | 04/10 | 點數發放規則與兌換比例設定 |
+| 21 | | 識別證 | 04/10 | 員工/維修人員識別證管理 |
+
+#### 📌 C. 機台管理 (04/13 ~ 04/23)
+> 為何第三：機台是核心營運實體，須在商品主檔建好後才能綁定貨道。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 22 | **機台管理** | 機台列表 | 04/13 - 04/15 | 設備清單、在線狀態、基礎參數設定（核心） |
+| 23 | | 機台日誌 | 04/16 - 04/17 | B010 心跳日誌查詢、異常事件追蹤 |
+| 24 | | 機台權限 | 04/20 | 機台指派給租戶/帳號的控管介面 |
+| 25 | | 機台稼動率 | 04/21 | 設備運作效率統計與視覺化 |
+| 26 | | 效期管理 | 04/22 | 各貨道商品到期日監控與預警 |
+| 27 | | 維修管理單 | 04/23 | 機台報修工單建立、追蹤與結案流程 |
+
+#### 📌 D. 銷售管理 (04/24 ~ 04/29)
+> 為何第四：交易數據依賴機台與商品，兩者就緒後再開發銷售查詢。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 28 | **銷售管理** | 銷售紀錄 | 04/24 - 04/27 | 交易明細查詢、金流狀態回溯 |
+| 29 | | 取貨碼 | 04/28 | 取貨碼生成與核銷管理 |
+| 30 | | 購買單 | 04/28 | 訂單管理與出貨追蹤 |
+| 31 | | 促銷時段 | 04/29 | 時段折扣規則設定與排程管理 |
+| 32 | | 通行碼 | 04/29 | 通行碼發放與使用紀錄 |
+| 33 | | 來店禮 | 04/29 | 到店即贈的禮品活動設定 |
+
+#### 📌 E. 遠端管理 (04/30 ~ 05/11)
+> 為何第五：營運最迫切需要的即時控制能力，直接串接 Phase 1 的 B010/B055 API。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 34 | **遠端管理** | 機台庫存 | 04/30 - 05/01 | 遠端查閱/修改機台貨道庫存 (B017) |
+| 35 | | 機台重啟 | 05/04 | 遠端重啟機台指令下發 |
+| 36 | | 卡機重啟 | 05/04 | 遠端重啟讀卡機指令 |
+| 37 | | 遠端結帳 | 05/05 | 遠端觸發機台結帳清算 |
+| 38 | | 遠端鎖定 | 05/06 | 遠端鎖定/解鎖機台操作 |
+| 39 | | 遠端找零 | 05/07 | 遠端觸發找零機退幣 |
+| 40 | | 遠端出貨 | 05/08 - 05/11 | B055 遠端出貨指令下發與結果追蹤 |
+
+#### 📌 F. 倉庫管理 (05/12 ~ 05/27)
+> 為何第六：供應鏈管理依賴商品主檔與機台數據，且補貨流程為日常營運核心。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 41 | **倉庫管理** | 倉庫列表(全) | 05/12 | 全公司倉庫總覽與基礎資料管理 |
+| 42 | | 倉庫列表(個) | 05/13 | 個人/分區倉庫檢視 |
+| 43 | | 庫存管理單 | 05/14 - 05/15 | 庫存異動單建立與審核流程 |
+| 44 | | 調撥單 | 05/18 - 05/19 | 跨倉庫商品調撥申請與執行 |
+| 45 | | 採購單 | 05/20 - 05/21 | 採購單建立、審批與到貨入庫 |
+| 46 | | 機台補貨單 | 05/22 - 05/25 | 機台補貨任務派發與執行 |
+| 47 | | 機台補貨紀錄 | 05/26 | 歷史補貨紀錄查詢與統計 |
+| 48 | | 機台庫存 | 05/26 | 各機台即時庫存總覽 (B017 資料) |
+| 49 | | 人員庫存 | 05/27 | 補貨人員攜帶庫存管理 |
+| 50 | | 回庫單 | 05/27 | 退回倉庫的商品登記與核銷 |
+
+#### 📌 G. 儀表板 (05/28 ~ 05/29)
+> 為何最後：儀表板匯總機台、銷售、遠端指令、倉庫等全部數據，必須等上游模組完成才有意義。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 51 | **儀表板** | 儀表板 | 05/28 - 05/29 | 即時營收、在線機台數、今日訂單、庫存水位看板 |
+
+### 🚀 Phase 3：進階分析與垂直模組子選單 (06/01 ~ 07/10)
+共 33 項子選單，依功能相依性分為七個開發階段。
+
+#### 📌 A. 分析管理 (06/01 ~ 06/10)
+> 為何優先：报表分析依賴 Phase 2 已累積的銷售、機台與倉庫運管數據。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 52 | **分析管理** | 零錢庫存 | 06/01 - 06/02 | B220 零錢機各面額庫存呈現與趨勢 |
+| 53 | | 機台報表 | 06/03 - 06/05 | 機台營收、稼動率、故障率綜合報表 |
+| 54 | | 商品報表 | 06/08 - 06/09 | 熱銷排行、區域分析、坪效矩陣 |
+| 55 | | 問卷分析 | 06/10 | 問卷結果統計圖表與資料匯出 |
+
+#### 📌 B. 稽核管理 (06/11 ~ 06/17)
+> 為何第二：稽核對帳需要倉庫（採購/調撥/補貨）數據作為比對來源。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 56 | **稽核管理** | 採購單 | 06/11 - 06/12 | 採購單據稽核、金額核對 |
+| 57 | | 調撥單 | 06/15 | 調撥單據稽核、數量差異追蹤 |
+| 58 | | 補貨單 | 06/16 - 06/17 | 補貨前後庫存比對、異常標記 |
+
+#### 📌 C. 會員管理 (06/18 ~ 06/26)
+> 為何第三：會員模組相對獨立，但其錢包/點數系統需在行銷模組（Line、APP）之前就位。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 59 | **會員管理** | 會員列表 | 06/18 - 06/19 | 會員資料 CRUD、錢包/點數明細 |
+| 60 | | 會員等級 | 06/22 | 等級定義與升降級條件設定 |
+| 61 | | 儲值回饋 | 06/23 | 儲值金額對應加碼回饋規則 |
+| 62 | | 點數規則 | 06/24 | 消費累點比例與到期規則設定 |
+| 63 | | 禮品設定 | 06/25 - 06/26 | 點數兌換禮品項目與庫存管理 |
+
+#### 📌 D. APP 管理 (06/29 ~ 07/01)
+> 為何第四：APP 功能（問卷、遊戲）可複用會員數據；計時器依賴 B710 API。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 64 | **APP 管理** | UI元素 | 06/29 | APP Banner、主題色、首頁佈局設定 |
+| 65 | | 小幫手 | 06/29 | APP 內嵌引導助手內容管理 |
+| 66 | | 問卷 | 06/30 | 問卷題目建立與發布排程 |
+| 67 | | 互動遊戲 | 07/01 | APP 內互動遊戲設定與獎品規則 |
+| 68 | | 計時器 | 07/01 | B710 計時器狀態監控與設定介面 |
+
+#### 📌 E. Line 管理 (07/02 ~ 07/06)
+> 為何第五：Line 綁定依賴會員系統，商品型錄依賴商品主檔。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 69 | **Line 管理** | Line會員 | 07/02 | Line 綁定會員清單與資料同步 |
+| 70 | | Line機台 | 07/02 | Line 關聯機台推播設定 |
+| 71 | | Line商品 | 07/03 | Line 商品型錄同步管理 |
+| 72 | | Line生活圈 | 07/03 | Line OA 官方帳號設定與群發 |
+| 73 | | Line訂單 | 07/06 | Line 渠道訂單查詢與追蹤 |
+| 74 | | Line優惠券 | 07/06 | Line 專屬優惠券發放與核銷 |
+
+#### 📌 F. 預約系統 (07/07 ~ 07/09)
+> 為何第六：獨立子系統，為未來擴充計時型設備預約的基礎。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 75 | **預約系統** | 預約會員 | 07/07 | 預約系統會員資料管理 |
+| 76 | | 店家管理 | 07/07 | 店家資訊維護與營業時間設定 |
+| 77 | | 時段組合 | 07/08 | 可預約時段模板建立與排程 |
+| 78 | | 場地管理 | 07/08 | 場地/設備資源定義與狀態管理 |
+| 79 | | 優惠券 | 07/09 | 預約專用優惠券發放規則 |
+| 80 | | 預約管理 | 07/09 | 預約紀錄查詢、取消與改期操作 |
+| 81 | | 訂單管理 | 07/09 | 預約產生之訂單明細與付款追蹤 |
+
+#### 📌 G. 特殊權限 (07/10)
+> 為何最後：高風險工程操作，須在所有系統穩定後才開放。
+
+| # | 模組名稱 | 子菜單項目 | 日期 | 功能重點 |
+| :---: | :--- | :--- | :---: | :--- |
+| 82 | **特殊權限** | 庫存清空 | 07/10 | 工程級一鍵清空指定機台庫存 |
+| 83 | | APK版本 | 07/10 | 機台 APK 版本發布與 OTA 控管 |
+| 84 | | Discord通知 | 07/10 | Discord Webhook 告警通知設定 |
+
+---
+
+## 四、開發階段任務清單 (Phase Checklist)
+
+### ⚡ Phase 1：基礎建設 + IoT API (5 工作天)
+- [ ] 擴充 `machines` 表（serial_no, model 等欄位）
+- [ ] 建立多租戶權限基礎表 (`companies`, `spatie/laravel-permission`)
+- [ ] 核心模型與關聯建立 (Products, Orders, Payments)
+- [ ] 實作 B010~B710 核心 IoT API 與 Redis Queue
+- [ ] 會員驗證 B650 串接
+
+### 🏛️ Phase 2：後台核心營運頁面 (50 工作天)
+- [ ] 帳號/角色/權限設定核
+- [ ] 商品、廣告、點數主檔管理
+- [ ] 機台列表、日誌、維修單、效期監控
+- [ ] 銷售紀錄、促銷時段、通行碼管理
+- [ ] 遠端控制 (庫存、重啟、找零、出貨) 7 項
+- [ ] 倉庫供應鏈 (採購、調撥、補貨、回庫) 10 項
+- [ ] 核心數據儀表板
+
+### 🚀 Phase 3：進階分析與垂直模組 (30 工作天)
+- [ ] 零錢機、機台、商品大數據分析報表
+- [ ] 供應鏈稽核對帳系統
+- [ ] 會員等級、儲值回饋、禮品兌換系統
+- [ ] APP/Line 行銷工具整合
+- [ ] 預約子系統 (場地、店家、訂單管理)
+- [ ] 特殊工程權限 (APK 下發, Discord 通知)