[DOCS] 新增並更新 Phase 1 核心機台通訊 API 技術規範文件 (B010~B710)

docs/api_analysis.md

@@ -0,0 +1,474 @@
+# Star Cloud API 分析與資料庫結構整理
+
+> 基於 `docs/API/` 中 12 個 PDF 文件的完整分析，整理出 API 端點清單、資料流向及推導出的資料庫結構。
+
+---
+
+## 一、API 端點總覽
+
+| 代碼 | 名稱 | URL | Method | 說明 |
+|------|------|-----|--------|------|
+| B010 | 機台狀態上傳 & 指令撈回 | `/api/app/machine/status/{workid}` | POST | 機台定期心跳上報（狀態、溫度、門禁、版本），並撈回遠端指令。詳見 [b010_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b010_technical_spec.md) |
+| B017 | 遠端改庫存 | `/api/app/machine/reload_msg/{workid}` | POST | 機台撈取最新貨道庫存數量。詳見 [b017_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b017_technical_spec.md) |
+| B055 | 遠端出貨（取得指令） | `/api/app/machine/dispense/{workid}` | POST | 機台撈取遠端出貨指令列表。詳見 [b055_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b055_technical_spec.md) |
+| B055 | 遠端出貨（狀態回傳） | `/api/app/machine/dispense/{workid}` | PUT | 機台回報出貨結果（成功/失敗）及剩餘庫存。詳見 [b055_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b055_technical_spec.md) |
+| B220 | 零錢機庫存變動回傳 | `/api/app/coin/inventory/B220` | POST | 零錢機各面額庫存回傳（1/5/10/50/100/500/1000 元）。詳見 [b220_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b220_technical_spec.md) |
+| B600 | 消費金流回傳 | `/api/app/B600` | POST | 消費交易核心 API — 記錄金流類型、金額、商品、發票、會員等。詳見 [b600_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b600_technical_spec.md) |
+| B601 | 發票資訊回傳 | `/api/app/B601` | POST | 開立發票後回傳發票號碼、日期、隨機碼等。詳見 [b601_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b601_technical_spec.md) |
+| B602 | 出貨回傳 | `/api/app/B602` | POST | 出貨結果回傳（商品、貨道、金額、庫存、會員條碼等）。詳見 [b602_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b602_technical_spec.md) |
+| B650 | 驗證會員 | `/api/app/B650` | POST | 會員驗證（點數折抵、優惠券、取貨碼、線上訂單線下取貨等）。詳見 [b650_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b650_technical_spec.md) |
+| B710 | 計時器狀態回傳 | `/api/app/B710` | POST | 計時型機台的貨道使用狀態與倒數秒數回傳。詳見 [b710_technical_spec.md](file:///home/mama/projects/star-cloud/docs/b710_technical_spec.md) |
+
+---
+
+## 二、API 詳細分析
+
+### 2.1 B010 — 機台狀態上傳 & 指令撈回
+
+**用途**：機台定期向 Cloud 回報自身狀態，Cloud 透過 response 中的 `status` 碼下發遠端指令。
+
+**Request 欄位**：
+
+| 欄位 | 說明 |
+|------|------|
+| `key` | API 金鑰 (`KahnEwjhfDBHUYS7`) |
+| `machine` | 機台序號 |
+| `door` | 門禁狀態（非必填） |
+| `temperature` | 溫度 |
+| `M_Stus` | 機台型號（非必填） |
+| `M_Stus2` | 當前頁面狀態碼 |
+| `M_Ver` | 當前軟體版本 |
+
+**頁面狀態碼 (M_Stus2)**：
+- `0`: 離線, `1`: 主頁面, `2`: 販賣頁, `3`: 管理頁, `4`: 補貨頁, `5`: 教學頁
+- `6`: 購買中, `7`: 鎖定頁, `60`: 出貨成功, `61`: 貨道測試, `62`: 付款選擇
+- `63`: 等待付款, `64`: 出貨, `65`: 收據簽單, `66`: 通行碼, `67`: 取貨碼
+- `68`: 訊息顯示, `69`: 取消購買, `610`: 購買結束, `611`: 來店禮, `612`: 出貨失敗
+
+**遠端指令碼 (Response status)**：
+- `49`: reload B017 (重新載入庫存), `50`: reload B005, `51`: reboot (重啟)
+- `60`: reboot card machine, `61`: checkout, `70`: unlock, `71`: lock
+- `72`: sellCode reload B023, `75`: exp reload B026, `79`: read B050
+- `81`: sync timer status (B710), `85`: reload B055 (遠端出貨)
+
+---
+
+### 2.2 B600 — 消費金流回傳（核心交易 API）
+
+**用途**：記錄每筆消費交易的完整資訊，為最核心的銷售數據 API。
+
+**Request 欄位**：
+
+| 欄位 | 參數名 | 說明 | 類型 |
+|------|--------|------|------|
+| req1 | key | API 金鑰 | String |
+| req2 | machine | 機台編號 | String |
+| req3 | payment_type | 金流類型代碼 | String |
+| req4 | payment_request | 金流送出 data | String |
+| req5 | payment_response | 金流回傳 data | String |
+| req6 | product_id | 商品 ID | String |
+| req7 | amount | 消費金額 | String |
+| req8 | invoice_info | 發票歸戶資訊（統編-電話） | String |
+| req9 | order_no | APP 定義訂單編號 | String |
+| req10 | member_barcode | 掃會員得到的條碼 | String |
+| req11 | machine_time | 機台時間 | String |
+| req12 | status | 金流狀態 (0: 失敗, 1: 成功, 2: 50 結帳) | String |
+| req13 | change_amount | 找零金額 | String |
+| req14 | points_used | 使用的點數 | String |
+| req15 | reserved | 系統保留 | String |
+| req16 | items | 商品明細 `[{pid, amount, num}]` | JsonArray |
+
+**金流類型 (req3) 完整對照**：
+
+| 代碼 | 說明 |
+|------|------|
+| 1 | 信用卡 |
+| 2 | 悠遊卡/一卡通 |
+| 3 | 掃碼支付 |
+| 4 | 手機支付 |
+| 5 | 通行碼 |
+| 6 | 取貨碼 |
+| 7 | 來店禮 |
+| 8 | 問卷 |
+| 9 | 零錢 |
+| 21-25 | 線下付款 + (1/2/3/4/9) |
+| 30-34 | TapPay (Line/街口/悠遊付/Pi/全盈+) |
+| 40 | 會員驗證取貨商品 |
+| 41 | 線上訂單線下結帳 |
+| 50-54 | 線下付款 + TapPay 系列 |
+| 60 | 點數/優惠券全額折抵 |
+| 61-64, 69 | 會員 + (1/2/3/4/9) |
+| 70 | 官方 LinePay |
+| 90-94 | 會員 + TapPay 系列 |
+| 101-109 | 大豐環保點數 + 消費 |
+| 110-114, 120 | 大豐環保 + TapPay/LinePay |
+
+---
+
+### 2.3 B650 — 驗證會員
+
+**驗證類型 (req6)**：
+
+| req6 | 說明 | Response 特殊欄位 |
+|------|------|--------------------|
+| 0 | 有點擊商品的驗證 | `userToken`, `amount`, `point`, `respondMSG` |
+| 1 | 會員純驗證 | 基本驗證回應 |
+| 2 | 會員兌換商品列表 | `productList[{pId, pName, token, validityPeriod, num}]` |
+| 3 | 線上訂單線下結帳 | `orderUrl`, `orderNumber`, `orderAmount` |
+| 4 | 會員贈品 | — |
+
+**Response 狀態碼**：
+- `100`: 成功 — 無可用點數
+- `101`: 成功 — 全額折抵（點數或優惠券）
+- `102`: 成功 — 部分折抵
+- `103`: 取貨碼驗證成功
+- `104`: 線上訂單驗證成功
+- `21`: Key Error, `22`: Time Error, `23`: User Token Error
+- `25`: 會員平台錯誤, `30`: 會員正在其他機台使用中
+- `35`: 無效優惠券, `40`: 已兌換過, `41`: 無效訂單, `42`: 取貨碼錯誤
+
+---
+
+## 三、資料庫結構推導
+
+根據以上 API 的欄位分析，以下是系統需要的**完整資料庫結構**：
+
+### 🟢 已存在的資料表（比對現有 migration）
+
+| 資料表 | 說明 | 對應 API |
+|--------|------|----------|
+| `users` | 後台管理員 | — |
+| `machines` | 機台基本資料 | B010, B017, B055, B220, B600, B602 |
+| `machine_logs` | 機台日誌 | B010 |
+| `app_configs` | APP 設定 | — |
+| `members` | 會員資料 | B650 |
+| `social_accounts` | 社群帳號 | B650 |
+| `member_wallets` | 會員錢包 | B650 |
+| `wallet_transactions` | 錢包交易 | B600, B650 |
+| `member_points` | 點數帳戶 | B650 |
+| `point_transactions` | 點數異動 | B650, B600 |
+| `point_rules` | 點數規則 | B650 |
+| `membership_tiers` | 會員等級 | — |
+| `member_memberships` | 會員等級紀錄 | — |
+| `gift_definitions` | 禮品定義 | — |
+| `member_gifts` | 禮品發放 | — |
+| `deposit_bonus_rules` | 儲值回饋規則 | — |
+
+### 🔴 需新增的資料表
+
+以下是從 API 欄位推導出**目前資料庫中缺少**，但系統運作所必需的資料表：
+
+---
+
+#### 1. `products` — 商品資料
+
+> 來源：B600 (req6, req16), B602 (req5), B650 (productList), B710 (pid)
+
+```
+products
+├── id                  BIGINT PK
+├── name                VARCHAR         商品名稱
+├── price               DECIMAL(10,2)   售價
+├── cost                DECIMAL(10,2)   成本（選填）
+├── category_id         BIGINT FK       分類（選填）
+├── image               VARCHAR         商品圖片 URL
+├── barcode             VARCHAR         商品條碼
+├── description         TEXT            商品描述
+├── is_active           BOOLEAN         是否上架
+├── created_at          TIMESTAMP
+└── updated_at          TIMESTAMP
+```
+
+---
+
+#### 2. `machine_slots` — 機台貨道
+
+> 來源：B017 (tid, num), B055 (res2), B602 (req6, req9), B710 (cid)
+
+```
+machine_slots
+├── id                  BIGINT PK
+├── machine_id          BIGINT FK       → machines
+├── slot_no             VARCHAR         貨道編號 (tid/cid)
+├── product_id          BIGINT FK       → products（可空）
+├── stock               INT             當前庫存數量
+├── max_stock           INT             最大容量
+├── is_active           BOOLEAN         是否啟用
+├── created_at          TIMESTAMP
+└── updated_at          TIMESTAMP
+```
+
+---
+
+#### 3. `orders` — 訂單（消費紀錄主表）
+
+> 來源：B600 (核心), B601, B602
+
+```
+orders
+├── id                  BIGINT PK
+├── order_no            VARCHAR UNIQUE  APP 定義訂單編號 (req9)
+├── machine_id          BIGINT FK       → machines (req2)
+├── member_id           BIGINT FK       → members（可空）
+├── payment_type        TINYINT         金流類型代碼 (req3)
+├── total_amount        DECIMAL(10,2)   消費金額 (req7)
+├── change_amount       DECIMAL(10,2)   找零金額 (req13)
+├── points_used         INT             使用的點數 (req14)
+├── discount_amount     DECIMAL(10,2)   折扣前金額 (req15)
+├── payment_status      TINYINT         金流狀態 (req12: 0失敗/1成功/2:50結帳)
+├── payment_request     TEXT            金流送出 data (req4)
+├── payment_response    TEXT            金流回傳 data (req5)
+├── member_barcode      VARCHAR         會員條碼 (req10)
+├── invoice_info        VARCHAR         發票歸戶資訊 (req8)
+├── machine_time        DATETIME        機台時間 (req11)
+├── flow_id             VARCHAR         Cloud 回傳的金流 ID (B600 response message)
+├── created_at          TIMESTAMP
+└── updated_at          TIMESTAMP
+```
+
+---
+
+#### 4. `order_items` — 訂單明細
+
+> 來源：B600 (req16: `[{pid, amount, num}]`)
+
+```
+order_items
+├── id                  BIGINT PK
+├── order_id            BIGINT FK       → orders
+├── product_id          BIGINT FK       → products (pid)
+├── quantity            INT             數量 (num)
+├── unit_price          DECIMAL(10,2)   單價 (amount)
+├── subtotal            DECIMAL(10,2)   小計
+├── created_at          TIMESTAMP
+└── updated_at          TIMESTAMP
+```
+
+---
+
+#### 5. `invoices` — 發票紀錄
+
+> 來源：B601
+
+```
+invoices
+├── id                  BIGINT PK
+├── order_id            BIGINT FK       → orders（透過 flow_id 關聯）
+├── flow_id             VARCHAR         B600 回傳的金流 ID (req3)
+├── machine_id          BIGINT FK       → machines (req2)
+├── rtn_code            VARCHAR         發票回傳碼 (req4)
+├── rtn_msg             VARCHAR         發票回傳訊息 (req5)
+├── invoice_no          VARCHAR         發票號碼 (req6)
+├── invoice_date        DATE            發票日期 (req7)
+├── random_number       VARCHAR         隨機碼 (req8)
+├── love_code           VARCHAR         愛心碼 (req9)
+├── business_tax_id     VARCHAR         公司統編 (新增)
+├── carrier_id          VARCHAR         載具編號 (新增)
+├── carrier_type        VARCHAR         載具類型 (新增)
+├── status              TINYINT         發票狀態 (1:有效, 0:作廢)
+├── created_at          TIMESTAMP
+└── updated_at          TIMESTAMP
+```
+
+---
+
+#### 6. `dispense_records` — 出貨紀錄
+
+> 來源：B602, B055
+
+```
+dispense_records
+├── id                  BIGINT PK
+├── order_id            BIGINT FK       → orders（透過 flow_id 關聯）
+├── flow_id             VARCHAR         金流 ID (req3)
+├── machine_id          BIGINT FK       → machines (req2)
+├── product_id          BIGINT FK       → products (req5)
+├── slot_no             VARCHAR         貨道編號 (req6)
+├── amount              DECIMAL(10,2)   消費金額 (req7)
+├── remaining_stock     INT             貨道剩餘庫存 (req9)
+├── member_barcode      VARCHAR         會員條碼 (req10)
+├── machine_time        DATETIME        機台時間 (req11)
+├── coupon_order_no     VARCHAR         商品券訂單編號 (req12)
+├── dispense_status     TINYINT         出貨狀態 (req13: 0成功/1失敗)
+├── original_price      DECIMAL(10,2)   折扣前金額 (req15)
+├── points_used         INT             使用的點數 (req16)
+├── created_at          TIMESTAMP
+└── updated_at          TIMESTAMP
+```
+
+---
+
+#### 7. `remote_dispense_commands` — 遠端出貨指令
+
+> 來源：B055
+
+```
+remote_dispense_commands
+├── id                  BIGINT PK
+├── machine_id          BIGINT FK       → machines
+├── command_id          VARCHAR         執行命令 ID (res1)
+├── slot_no             VARCHAR         貨道 ID (res2)
+├── status              TINYINT         狀態 (0: 待執行, 1: 出貨成功, 2: 出貨失敗)
+├── remaining_stock     INT             出貨後剩餘庫存
+├── created_at          TIMESTAMP
+└── updated_at          TIMESTAMP
+```
+
+---
+
+#### 8. `coin_inventory_logs` — 零錢機庫存紀錄
+
+> 來源：B220
+
+```
+coin_inventory_logs
+├── id                  BIGINT PK
+├── machine_id          BIGINT FK       → machines
+├── value_1             INT             1 元庫存
+├── value_5             INT             5 元庫存
+├── value_10            INT             10 元庫存
+├── value_50            INT             50 元庫存
+├── value_100           INT             100 元庫存
+├── value_500           INT             500 元庫存
+├── value_1000          INT             1000 元庫存
+├── account             VARCHAR         操作人帳號 (0=消費者)
+├── created_at          TIMESTAMP
+└── updated_at          TIMESTAMP
+```
+
+---
+
+#### 9. `timer_statuses` — 計時器狀態
+
+> 來源：B710
+
+```
+timer_statuses
+├── id                  BIGINT PK
+├── machine_id          BIGINT FK       → machines
+├── slot_no             VARCHAR         貨道 ID (cid)
+├── product_id          BIGINT FK       → products (pid, 0=未設定)
+├── status              TINYINT         狀態 (0: 未啟用, 1: 使用中, 2: 異常)
+├── remaining_seconds   INT             剩餘秒數 (num)
+├── created_at          TIMESTAMP
+└── updated_at          TIMESTAMP
+```
+
+---
+
+#### 10. `payment_types` — 金流類型參照表（建議）
+
+> 來源：B600 req3 的龐大對照表
+
+```
+payment_types
+├── id                  BIGINT PK
+├── code                INT UNIQUE      金流類型代碼
+├── name                VARCHAR         名稱（中文）
+├── category            VARCHAR         分類（信用卡/電子票證/行動支付/TapPay/會員/環保點數...）
+├── is_active           BOOLEAN         是否啟用
+├── created_at          TIMESTAMP
+└── updated_at          TIMESTAMP
+```
+
+---
+
+## 四、ER 關係圖
+
+```mermaid
+erDiagram
+    machines ||--o{ machine_slots : "擁有"
+    machines ||--o{ machine_logs : "產生"
+    machines ||--o{ orders : "交易於"
+    machines ||--o{ coin_inventory_logs : "零錢記錄"
+    machines ||--o{ timer_statuses : "計時器"
+    machines ||--o{ remote_dispense_commands : "遠端指令"
+    
+    products ||--o{ machine_slots : "放置於"
+    products ||--o{ order_items : "被購買"
+    products ||--o{ timer_statuses : "計時商品"
+    
+    orders ||--o{ order_items : "包含"
+    orders ||--o| invoices : "開立"
+    orders ||--o{ dispense_records : "出貨"
+    orders }o--o| members : "消費者"
+    orders }o--|| payment_types : "付款方式"
+    
+    members ||--o{ social_accounts : "社群綁定"
+    members ||--o| member_wallets : "錢包"
+    members ||--o| member_points : "點數"
+    members ||--o{ member_memberships : "會員等級"
+    members ||--o{ member_gifts : "禮品"
+    
+    member_wallets ||--o{ wallet_transactions : "異動"
+    member_points ||--o{ point_transactions : "異動"
+    membership_tiers ||--o{ member_memberships : "對應等級"
+    gift_definitions ||--o{ member_gifts : "對應禮品"
+```
+
+---
+
+## 五、API 資料流向圖
+
+```
+┌─────────────┐
+│  機台 (APP)  │
+└──────┬──────┘
+       │
+       ├── B010 ──► 心跳上報 ──► machine_logs（狀態/溫度/版本）
+       │              ◄── 返回遠端指令碼
+       │
+       ├── B017 ──► 撈取庫存 ──► machine_slots（最新貨道數量）
+       │
+       ├── B055 ──► 撈取出貨指令 ──► remote_dispense_commands
+       │     PUT ──► 回報出貨結果 ──► 更新 command status + 庫存
+       │
+       ├── B220 ──► 零錢機庫存 ──► coin_inventory_logs
+       │
+       ├── B600 ──► 消費金流 ──► orders + order_items（核心交易）
+       │              ◄── 返回金流 ID (flow_id)
+       │
+       ├── B601 ──► 發票回傳 ──► invoices（關聯 flow_id）
+       │
+       ├── B602 ──► 出貨回傳 ──► dispense_records（關聯 flow_id）
+       │
+       ├── B650 ──► 驗證會員 ──► members + member_points
+       │              ◄── 點數折抵/優惠券/取貨碼/線上訂單
+       │
+       └── B710 ──► 計時器狀態 ──► timer_statuses
+```
+
+---
+
+## 六、重要觀察與建議
+
+### 6.1 API 金鑰
+- 所有 API 使用同一把硬編碼金鑰 `KahnEwjhfDBHUYS7`
+- **建議**：遷移到 Star Cloud 後改為每台機台獨立的 API Token，使用 Laravel Sanctum 管理
+
+### 6.2 資料一致性
+- B600（金流）→ B601（發票）→ B602（出貨）三支 API 透過 `flow_id` 串聯
+- 建議資料庫設計中以 `orders.flow_id` 作為三者的關聯基準
+
+### 6.3 高頻 API
+- **B010** 為最高頻率 API（每台機台數秒呼叫一次），必須走 **Redis Queue 異步寫入**
+- B220（零錢機庫存）與 B710（計時器）也屬於高頻回報，建議異步處理
+
+### 6.4 新舊版差異
+- B220 和 B600/B602 各有兩個版本的 PDF（新舊版），新版增加了更多面額（500/1000 元）和 TapPay 金流類型
+- 建議以**較新版本 (帶日期後綴的)** 為準進行開發
+
+### 6.5 `machines` 表建議補充欄位
+
+根據 B010 API，`machines` 表應包含：
+
+| 欄位 | 說明 | 來源 |
+|------|------|------|
+| `serial_no` | 機台序號 | B010 machine |
+| `model` | 機台型號 | B010 M_Stus |
+| `current_status` | 當前頁面狀態碼 | B010 M_Stus2 |
+| `current_version` | 當前軟體版本 | B010 M_Ver |
+| `temperature` | 最新溫度 | B010 temperature |
+| `door_status` | 門禁狀態 | B010 door |
+| `last_heartbeat_at` | 最後心跳時間 | B010 呼叫時間 |
+| `is_online` | 是否在線 | 由心跳超時判斷 |

docs/architecture_plan.md

@@ -0,0 +1,627 @@
+# Star Cloud — 智能販賣機管理平台技術架構規劃
+
+> **目標**：為上千至上萬台智能販賣機建構集中式管理後台，承接所有機台透過 API 回寫的資料，並提供完整的營運管理介面。
+
+---
+
+## 一、系統架構全景
+
+```
+                        ┌──────────────────────────────────────────────┐
+                        │            Star Cloud 管理後台                │
+                        │     (Laravel 12 + Blade + Tailwind)          │
+                        │  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
+                        │  │ 儀表板    │  │ 機台管理  │  │ 銷售分析   │  │
+                        │  │ Dashboard │  │ Machines  │  │ Analytics  │  │
+                        │  └──────────┘  └──────────┘  └───────────┘  │
+                        │  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
+                        │  │ 倉庫管理  │  │ 會員系統  │  │ 遠端操控   │  │
+                        │  │Warehouses │  │ Members   │  │  Remote    │  │
+                        │  └──────────┘  └──────────┘  └───────────┘  │
+                        └──────────┬───────────────┬───────────────────┘
+                                   │  Web Routes   │
+                                   │  (Blade SSR)  │
+                        ┌──────────┴───────────────┴───────────────────┐
+                        │              Laravel Application              │
+                        │                                               │
+                        │  Controllers → Services → Models → MySQL     │
+                        │                                               │
+                        └──────┬────────────────────┬──────────────────┘
+                               │                    │
+                    ┌──────────┴────┐       ┌───────┴───────┐
+                    │  API Routes   │       │  Redis Queue  │
+                    │  /api/v1/app  │       │  (異步處理)    │
+                    └──────┬────────┘       └───────┬───────┘
+                           │                        │
+                    ┌──────┴────────┐       ┌───────┴───────┐
+                    │ API Controller│──────►│   Jobs        │
+                    │ (驗證 + 分派) │ dispatch│ (Worker 執行) │
+                    └───────────────┘       └───────┬───────┘
+                           ▲                        │
+          ┌────────────────┤                        ▼
+          │                │                 ┌──────────────┐
+    ┌─────┴─────┐    ┌────┴─────┐           │   Services   │
+    │ 販賣機 #1  │    │販賣機 #N │           │  (業務邏輯)   │
+    │  B010      │    │  B600    │           └──────┬───────┘
+    │  B600      │    │  B602    │                  │
+    │  B602      │    │  ...     │                  ▼
+    └────────────┘    └──────────┘           ┌──────────────┐
+                                             │    MySQL     │
+                                             │  (持久化)    │
+                                             └──────────────┘
+```
+
+---
+
+## 二、技術棧確認
+
+| 層級 | 技術 | 說明 |
+|------|------|------|
+| **後端框架** | PHP 8.5 / Laravel 12 | 單體架構，Blade SSR |
+| **資料庫** | MySQL 8.0 | 資料持久化 |
+| **快取/隊列** | Redis | B010 心跳、B600 金流等高頻 API 必須異步 |
+| **前端視圖** | Blade + Tailwind CSS + Preline UI | 極簡奢華風 |
+| **前端互動** | Alpine.js | 輕量 DOM 互動 |
+| **建置工具** | Vite | 前端資源編譯 |
+| **開發環境** | Laravel Sail (Docker) | 本地開發 |
+| **IoT 通訊** | Redis Queue + Jobs | 異步寫入，避免 API 直連 DB |
+| **認證** | Laravel Sanctum | 後台用 Session，API 用 Token |
+
+---
+
+## 三、多租戶與權限架構 (Multi-Tenant RBAC)
+
+為支援系統管理員（內部營運）與租戶（客戶公司及子帳號）的雙層管理模式，平台採用以下三層級權限隔離架構：
+
+### 3.1 租戶隔離層 (Tenant Isolation)
+*   **核心機制**：導入 `companies` 資料表作為租戶實體，所有歸屬於客戶的資源（`users`, `machines` 等）均需綁定 `company_id`。
+*   **身份判定**：
+    *   **系統管理員 (內部)**：`company_id = null`，具備跨租戶檢視與管理機台、設定全局參數的最高權限。
+    *   **客戶端帳號 (租戶)**：`company_id` 有值，所有查詢（透過 Eloquent Global Scopes 或 Middleware）自動注入 `where('company_id', $user->company_id)`，達成資料物理隔離。
+
+### 3.2 角色與權限層 (Roles & Permissions)
+*   採用 `spatie/laravel-permission` 套件並進行多租戶改造。
+*   **多租戶角色 (Tenant-Aware Roles)**：擴充 `roles` 表，加入 `company_id` 欄位。
+    *   **系統預設角色** (`company_id = null`)：如 Super Admin, System Support。
+    *   **客戶自建角色** (`company_id = N`)：如客戶建立的「分區維修員」、「會計」，確保客戶只能看見與分配屬於自己公司的角色給員工。
+*   **權限 (Permissions)**：定義系統最小操作單位（如 `machine.view`, `user.create`），供角色綁定。
+
+### 3.3 流程控制與防禦 (Flow Control)
+*   **介面隔離**：依據身份動態隱藏/顯示系統級選單（例如「全站設定」、「合約管理」等多租戶不可見的功能）。
+*   **越權防禦**：客戶創建子帳號時，後端必定強制攔截並覆寫 `user->company_id = Auth::user()->company_id`，確保子帳號牢牢綁在自己的公司名下。同時限制其只能撈與分配自己公司名下的 Role。
+
+---
+
+## 四、資料庫完整設計
+
+### 4.1 資料表總覽
+
+分為 **6 大領域**，共 **28 張表**：
+
+```mermaid
+graph LR
+    subgraph 系統管理
+        A1[users] --> A2[sessions]
+        A1 --> A3[personal_access_tokens]
+        A4[failed_jobs]
+    end
+    
+    subgraph 機台領域
+        B1[machines] --> B2[machine_slots]
+        B1 --> B3[machine_logs]
+        B1 --> B4[coin_inventories]
+        B1 --> B5[timer_statuses]
+        B1 --> B6[remote_commands]
+        B1 --> B7[machine_heartbeats]
+    end
+    
+    subgraph 商品領域
+        C1[products]
+        C2[product_categories]
+    end
+    
+    subgraph 交易領域
+        D1[orders] --> D2[order_items]
+        D1 --> D3[invoices]
+        D1 --> D4[dispense_records]
+        D5[payment_types]
+    end
+    
+    subgraph 會員領域
+        E1[members] --> E2[social_accounts]
+        E1 --> E3[member_wallets]
+        E3 --> E4[wallet_transactions]
+        E1 --> E5[member_points]
+        E5 --> E6[point_transactions]
+        E7[point_rules]
+        E8[deposit_bonus_rules]
+        E1 --> E9[membership_tiers]
+        E1 --> E10[member_memberships]
+        E1 --> E11[gift_definitions]
+        E1 --> E12[member_gifts]
+    end
+    
+    subgraph APP設定
+        F1[app_configs]
+    end
+```
+
+### 4.2 需新增的資料表（Migration 設計）
+
+> 以下為 API 分析後推導出的缺失表，搭配各 API 欄位產生對應。
+
+---
+
+#### 👑 多租戶與權限基礎表 (RBAC & Tenant)
+
+##### 🆕 `companies` — 租戶/客戶主表
+所有客戶端的資料邊界，用來實現資料物理隔離。
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `id` | BIGINT PK | — |
+| `name` | VARCHAR(255) | 公司/組織名稱 |
+| `tax_id` | VARCHAR(20) NULL | 統一編號 |
+| `contact_name` | VARCHAR(100) NULL | 聯絡人姓名 |
+| `contact_phone` | VARCHAR(50) NULL | 聯絡電話 |
+| `status` | TINYINT DEFAULT 1 | 狀態 (1:啟用, 0:停用) |
+| `valid_until` | DATE NULL | 合約使用期限 |
+| `timestamps` | — | — |
+| `deleted_at` | TIMESTAMP NULL | 軟刪除 (SoftDeletes) |
+
+##### 🟡 `users` 表 — 需擴充欄位
+將 Laravel 預設的使用者表與租戶綁定。
+
+| 新增欄位 | 類型 | 說明 |
+|----------|------|------|
+| `company_id` | BIGINT FK NULL | → `companies` (NULL 代表系統管理員) |
+| `status` | TINYINT DEFAULT 1 | 帳號狀態 (1:啟用, 0:停用) |
+
+##### 🟡 `roles` 表 (Spatie 權限擴充)
+Spatie 預設的 roles 表必須加上多租戶設計，確保留戶只能管理自己的角色。
+
+| 新增/調整欄位 | 類型 | 說明 |
+|----------|------|------|
+| `company_id` | BIGINT FK NULL | → `companies` (NULL 代表系統全域角色) |
+| **UNIQUE** | `(name, guard_name, company_id)` | 原套件無 `company_id`，需修改為複合唯一鍵 |
+
+---
+
+#### 🟡 `machines` 表 — 需擴充欄位
+
+現有 `machines` 表僅有基礎欄位，需為 B010 API 補充：
+
+| 新增欄位 | 類型 | 說明 | 來源 API |
+|----------|------|------|----------|
+| `serial_no` | `VARCHAR UNIQUE` | 機台序號（API 用此識別） | B010 `machine` |
+| `model` | `VARCHAR` | 機台型號 | B010 `M_Stus` |
+| `current_page` | `TINYINT` | 當前頁面狀態碼 | B010 `M_Stus2` |
+| `door_status` | `VARCHAR` | 門禁狀態 | B010 `door` |
+| `is_online` | `BOOLEAN` | 是否在線（心跳超時判斷） | 計算欄位 |
+| `api_token` | `VARCHAR` | 機台專屬 API Token | 取代硬編碼 key |
+
+---
+
+#### 🆕 `products` — 商品資料
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `id` | BIGINT PK | — |
+| `name` | VARCHAR(255) | 商品名稱 (預設語系) |
+| `name_dictionary_key` | VARCHAR(100) NULL | 多語系字典鍵值 (對應 translations 表) |
+| `sku` | VARCHAR(100) UNIQUE | 商品編號 |
+| `price` | DECIMAL(10,2) | 售價 |
+| `cost` | DECIMAL(10,2) NULL | 成本 |
+| `category_id` | BIGINT FK NULL | → product_categories |
+| `image` | VARCHAR NULL | 圖片 URL |
+| `barcode` | VARCHAR NULL | 條碼 |
+| `is_timer_product` | BOOLEAN | 是否為計時型商品 |
+| `is_active` | BOOLEAN | 是否上架 |
+| `timestamps` | — | — |
+
+---
+
+#### 🌐 多語系支援表 (i18n)
+
+為了支援後台介面與 APP 端顯示的多語系內容（如商品名稱、分類名稱、系統提示），統一採用字典表架構。
+
+##### 🆕 `translations` — 多語系字典表
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `id` | BIGINT PK | — |
+| `group` | VARCHAR(50) | 分組 (例如: `product`, `category`, `system`) |
+| `key` | VARCHAR(100) | 字典鍵值 (例如: `prod_name_001`) |
+| `locale` | VARCHAR(10) | 語系代碼 (例如: `zh_TW`, `en_US`, `ja_JP`) |
+| `value` | TEXT | 翻譯內容 |
+| `timestamps` | — | — |
+| **UNIQUE** | `(group, key, locale)` | 確保同一組鍵值在同一語系下唯一 |
+
+> **多語系實作策略**：
+> 1. **靜態文案**：後台介面的靜態文字直接使用 Laravel 內建的 `lang/` 目錄 (JSON 或 PHP 陣列)。
+> 2. **動態資料**：資料庫內容（如商品名稱 `products.name`）保留預設語系供後台快速搜尋。同時新增 `name_dictionary_key`。當對接外部 APP 或前台需要多語系時，透過 API 關聯 `translations` 表，回傳當前語系對應的 `value`。
+
+---
+
+#### 🆕 `machine_slots` — 機台貨道
+
+| 欄位 | 類型 | 說明 | 來源 |
+|------|------|------|------|
+| `id` | BIGINT PK | — | — |
+| `machine_id` | BIGINT FK | → machines | B017, B055, B710 |
+| `slot_no` | VARCHAR(20) | 貨道編號 | B017 `tid`, B710 `cid` |
+| `product_id` | BIGINT FK NULL | → products | B710 `pid` |
+| `stock` | INT DEFAULT 0 | 當前庫存 | B017 `num` |
+| `max_stock` | INT DEFAULT 0 | 最大容量 | — |
+| `is_active` | BOOLEAN | 是否啟用 | — |
+| `timestamps` | — | — | — |
+| **UNIQUE** | `(machine_id, slot_no)` | 複合唯一鍵 | — |
+
+---
+
+#### 🆕 `orders` — 訂單主表
+
+| 欄位 | 類型 | 說明 | 來源 |
+|------|------|------|------|
+| `id` | BIGINT PK | — | — |
+| `flow_id` | VARCHAR UNIQUE | Cloud 金流 ID | B600 response |
+| `order_no` | VARCHAR | APP 訂單號 | B600 `req9` |
+| `machine_id` | BIGINT FK | → machines | B600 `req2` |
+| `member_id` | BIGINT FK NULL | → members | B650 關聯 |
+| `payment_type` | SMALLINT | 金流類型碼 | B600 `req3` |
+| `total_amount` | DECIMAL(10,2) | 消費金額 | B600 `req7` |
+| `change_amount` | DECIMAL(10,2) | 找零 | B600 `req13` |
+| `points_used` | INT DEFAULT 0 | 使用點數 | B600 `req14` |
+| `original_amount` | DECIMAL(10,2) NULL | 折扣前金額 | B602 `req15` |
+| `payment_status` | TINYINT | 0:失敗/1:成功 | B600 `req12` |
+| `payment_request` | TEXT NULL | 金流送出 data | B600 `req4` |
+| `payment_response` | TEXT NULL | 金流回傳 data | B600 `req5` |
+| `member_barcode` | VARCHAR NULL | 會員條碼 | B600 `req10` |
+| `invoice_info` | VARCHAR NULL | 發票歸戶 | B600 `req8` |
+| `machine_time` | DATETIME NULL | 機台時間 | B600 `req11` |
+| `timestamps` | — | — | — |
+| **INDEX** | `(machine_id, created_at)` | 查詢最佳化 | — |
+| **INDEX** | `(payment_type)` | 金流類型篩選 | — |
+
+---
+
+#### 🆕 `order_items` — 訂單明細
+
+| 欄位 | 類型 | 說明 | 來源 |
+|------|------|------|------|
+| `id` | BIGINT PK | — | — |
+| `order_id` | BIGINT FK | → orders | — |
+| `product_id` | BIGINT FK | → products | B600 `req16.pid` |
+| `quantity` | INT | 數量 | B600 `req16.num` |
+| `unit_price` | DECIMAL(10,2) | 單價 | B600 `req16.amount` |
+| `subtotal` | DECIMAL(10,2) | 小計 | 計算 |
+| `timestamps` | — | — | — |
+
+---
+
+#### 🆕 `invoices` — 發票紀錄
+
+| 欄位 | 類型 | 說明 | 來源 |
+|------|------|------|------|
+| `id` | BIGINT PK | — | — |
+| `order_id` | BIGINT FK | → orders（via flow_id） | — |
+| `flow_id` | VARCHAR | 金流 ID | B601 `req3` |
+| `machine_id` | BIGINT FK | → machines | B601 `req2` |
+| `rtn_code` | VARCHAR NULL | 回傳碼 | B601 `req4` |
+| `rtn_msg` | VARCHAR NULL | 回傳訊息 | B601 `req5` |
+| `invoice_no` | VARCHAR NULL | 發票號碼 | B601 `req6` |
+| `invoice_date` | DATE NULL | 發票日期 | B601 `req7` |
+| `random_number` | VARCHAR NULL | 隨機碼 | B601 `req8` |
+| `love_code` | VARCHAR NULL | 愛心碼 | B601 `req9` |
+| `timestamps` | — | — | — |
+
+---
+
+#### 🆕 `dispense_records` — 出貨紀錄
+
+| 欄位 | 類型 | 說明 | 來源 |
+|------|------|------|------|
+| `id` | BIGINT PK | — | — |
+| `order_id` | BIGINT FK NULL | → orders | — |
+| `flow_id` | VARCHAR NULL | 金流 ID | B602 `req3` |
+| `machine_id` | BIGINT FK | → machines | B602 `req2` |
+| `product_id` | VARCHAR | 商品 ID | B602 `req5` |
+| `slot_no` | VARCHAR | 貨道編號 | B602 `req6` |
+| `amount` | DECIMAL(10,2) | 消費金額 | B602 `req7` |
+| `remaining_stock` | INT NULL | 剩餘庫存 | B602 `req9` |
+| `dispense_status` | TINYINT | 0:成功/1:失敗 | B602 `req13` |
+| `member_barcode` | VARCHAR NULL | 會員條碼 | B602 `req10` |
+| `machine_time` | DATETIME NULL | 機台時間 | B602 `req11` |
+| `points_used` | INT DEFAULT 0 | 使用點數 | B602 `req16` |
+| `timestamps` | — | — | — |
+
+---
+
+#### 🆕 `remote_commands` — 遠端指令佇列
+
+| 欄位 | 類型 | 說明 | 來源 |
+|------|------|------|------|
+| `id` | BIGINT PK | — | — |
+| `machine_id` | BIGINT FK | → machines | — |
+| `command_type` | VARCHAR(20) | 指令類型 | B010 response status |
+| `status` | ENUM | pending/sent/success/failed | — |
+| `payload` | JSON NULL | 指令附加資料 | — |
+| `executed_at` | TIMESTAMP NULL | 執行時間 | — |
+| `timestamps` | — | — | — |
+
+> 對應 B010 遠端指令（reboot, lock, unlock, checkout, dispense 等）以及 B055 遠端出貨。
+
+---
+
+#### 🆕 `coin_inventories` — 零錢機庫存
+
+| 欄位 | 類型 | 說明 | 來源 |
+|------|------|------|------|
+| `id` | BIGINT PK | — | — |
+| `machine_id` | BIGINT FK | → machines | B220 `machine` |
+| `value_1` | INT DEFAULT 0 | 1 元 | B220 |
+| `value_5` | INT DEFAULT 0 | 5 元 | B220 |
+| `value_10` | INT DEFAULT 0 | 10 元 | B220 |
+| `value_50` | INT DEFAULT 0 | 50 元 | B220 |
+| `value_100` | INT DEFAULT 0 | 100 元 | B220 |
+| `value_500` | INT DEFAULT 0 | 500 元 | B220 |
+| `value_1000` | INT DEFAULT 0 | 1000 元 | B220 |
+| `operator` | VARCHAR NULL | 操作人 (0=消費者) | B220 `account` |
+| `timestamps` | — | — | — |
+
+---
+
+#### 🆕 `timer_statuses` — 計時器狀態
+
+| 欄位 | 類型 | 說明 | 來源 |
+|------|------|------|------|
+| `id` | BIGINT PK | — | — |
+| `machine_id` | BIGINT FK | → machines | B710 `req2` |
+| `slot_no` | VARCHAR | 貨道 ID | B710 `cid` |
+| `product_id` | BIGINT FK NULL | → products (0=未設定) | B710 `pid` |
+| `status` | TINYINT | 0:未啟用/1:使用中/2:異常 | B710 `status` |
+| `remaining_seconds` | INT | 剩餘秒數 | B710 `num` |
+| `timestamps` | — | — | — |
+
+---
+
+#### 🆕 `payment_types` — 金流類型參照
+
+| 欄位 | 類型 | 說明 |
+|------|------|------|
+| `id` | BIGINT PK | — |
+| `code` | SMALLINT UNIQUE | 金流代碼 (1,2,3...120) |
+| `name` | VARCHAR | 中文名稱 |
+| `category` | VARCHAR | 大分類 |
+| `is_active` | BOOLEAN | 是否啟用 |
+| `timestamps` | — | — |
+
+---
+
+## 五、IoT API 路由設計
+
+### 5.1 路由結構
+
+```php
+// routes/api.php
+Route::prefix('v1/app')->middleware(['throttle:iot'])->group(function () {
+    
+    // B010 - 機台狀態上傳 & 指令撈回
+    Route::post('/machine/status', [MachineStatusController::class, 'heartbeat']);
+    
+    // B017 - 遠端撈庫存
+    Route::post('/machine/reload', [MachineStockController::class, 'reload']);
+    
+    // B055 - 遠端出貨
+    Route::post('/machine/dispense', [DispenseController::class, 'getCommands']);
+    Route::put('/machine/dispense', [DispenseController::class, 'updateStatus']);
+    
+    // B220 - 零錢機庫存
+    Route::post('/coin/inventory', [CoinInventoryController::class, 'store']);
+    
+    // B600 - 消費金流
+    Route::post('/transaction', [TransactionController::class, 'store']);
+    
+    // B601 - 發票回傳
+    Route::post('/invoice', [InvoiceController::class, 'store']);
+    
+    // B602 - 出貨回傳
+    Route::post('/dispense-record', [DispenseRecordController::class, 'store']);
+    
+    // B650 - 驗證會員
+    Route::post('/member/verify', [MemberVerifyController::class, 'verify']);
+    
+    // B710 - 計時器狀態
+    Route::post('/timer/status', [TimerStatusController::class, 'sync']);
+});
+```
+
+### 5.2 處理管線
+
+> [!IMPORTANT]
+> 遵循 IoT 通訊技能規範：**嚴禁** API Controller 直接寫入 DB。
+
+| API | 處理方式 | 原因 |
+|-----|----------|------|
+| B010 | **異步** (Redis Queue) | 最高頻，每台數秒一次 |
+| B017 | **同步** (直接回應) | 低頻，需即時回傳庫存數據 |
+| B055 GET | **同步** | 需即時回傳指令列表 |
+| B055 PUT | **異步** | 出貨結果可背景處理 |
+| B220 | **異步** | 庫存變動日誌可背景寫入 |
+| B600 | **異步** | 高頻交易，核心數據 |
+| B601 | **異步** | 發票資訊可背景寫入 |
+| B602 | **異步** | 出貨紀錄可背景寫入 |
+| B650 | **同步** | 需即時回傳驗證結果與折抵金額 |
+| B710 | **異步** | 計時器狀態批量更新 |
+
+---
+
+## 六、後台模組 ↔ 資料表對應
+
+| 後台模組（web.php） | 對應資料表 | 資料來源 API |
+|---------------------|-----------|-------------|
+| 1. 儀表板 Dashboard | orders, machines, dispense_records | 統計彙整 |
+| 2. 會員管理 Members | members, social_accounts, member_wallets... | B650 |
+| 3. 機台管理 Machines | machines, machine_logs, machine_slots | B010, B017 |
+| 4. APP 管理 App | app_configs, timer_statuses | B710 |
+| 5. 倉庫管理 Warehouses | products, machine_slots | B017, B602 |
+| 6. 銷售管理 Sales | orders, order_items, dispense_records | B600, B602 |
+| 7. 分析管理 Analysis | orders, dispense_records, coin_inventories | 全部 |
+| 8. 稽核管理 Audit | orders, dispense_records | B600, B602 |
+| 9. 資料設定 DataConfig | products, payment_types, users | — |
+| 10. 遠端管理 Remote | remote_commands | B010, B055 |
+| 11. Line 管理 | members (Line 綁定) | — |
+| 12. 預約系統 Reservation | （未來擴充） | — |
+| 13. 特殊權限 SpecialPerm | machines, app_configs | — |
+| 14. 權限設定 Permission | users, roles | — |
+
+---
+
+## 七、效能預估與應對
+
+### 10,000 台機台的流量預估
+
+| API | 頻率 | 每秒請求量 (QPS) | 每日資料量 |
+|-----|------|-----------------|-----------|
+| B010 心跳 | 每 5 秒/台 | **~2,000** | ~173M 筆 |
+| B600 金流 | 每筆交易 | ~10-50 | ~50K-200K 筆 |
+| B602 出貨 | 每筆交易 | ~10-50 | ~50K-200K 筆 |
+| B710 計時器 | 每 10 秒/台 | ~1,000 | ~86M 筆 |
+
+### 應對策略
+
+| 策略 | 實作方式 |
+|------|----------|
+| **Redis Queue 異步寫入** | 所有高頻 API 進 Queue，Worker 批量寫入 |
+| **心跳資料瘦身** | B010 不逐筆寫 DB，僅更新 `machines` 表的即時欄位 + 異常時寫 log |
+| **資料分區** | `orders` 和 `dispense_records` 按月份分區 |
+| **索引策略** | 所有查詢欄位建立適當 INDEX（machine_id + created_at 複合索引） |
+| **速率限制** | 單台機台 60 req/min，全站 100,000 req/min |
+| **快取** | 機台列表、商品列表等低變動資料用 Redis Cache |
+
+---
+
+## 八、實作路線圖與預估時程
+
+> **總結報告**：為確保開發品質與應對突發狀況，本專案預計總開發時程擴展為 **16 - 18 週**。以 1 人天 = 8 小時純開發時間計算，預估總投入約 **80 - 90 個工作天**。
+
+### 🗓️ 專案開發甘特圖 (自動排除週末)
+
+```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 動態設定
+
+
+---
+
+## 九、目錄結構建議
+
+```
+app/
+├── Http/Controllers/
+│   ├── Admin/              ← 後台管理（已存在 14 模組）
+│   └── Api/V1/
+│       ├── App/            ← 機台 IoT API（新增）
+│       │   ├── MachineStatusController.php   (B010)
+│       │   ├── MachineStockController.php    (B017)
+│       │   ├── DispenseController.php        (B055)
+│       │   ├── CoinInventoryController.php   (B220)
+│       │   ├── TransactionController.php     (B600)
+│       │   ├── InvoiceController.php         (B601)
+│       │   ├── DispenseRecordController.php  (B602)
+│       │   ├── MemberVerifyController.php    (B650)
+│       │   └── TimerStatusController.php     (B710)
+│       ├── MemberController.php              ← 會員 API（已存在）
+│       └── MachineController.php             ← 機台日誌（已存在）
+├── Jobs/
+│   └── Machine/            ← IoT 異步任務（新增）
+│       ├── ProcessHeartbeat.php
+│       ├── ProcessTransaction.php
+│       ├── ProcessDispenseRecord.php
+│       ├── ProcessInvoice.php
+│       ├── ProcessCoinInventory.php
+│       └── ProcessTimerStatus.php
+├── Services/
+│   └── Machine/            ← 業務邏輯（新增）
+│       ├── HeartbeatService.php
+│       ├── TransactionService.php
+│       ├── DispenseService.php
+│       └── MemberVerifyService.php
+└── Models/
+    ├── Machine/            ← 已存在
+    │   ├── Machine.php
+    │   └── MachineLog.php
+    ├── Transaction/        ← 新增
+    │   ├── Order.php
+    │   ├── OrderItem.php
+    │   ├── Invoice.php
+    │   ├── DispenseRecord.php
+    │   └── PaymentType.php
+    ├── Product/            ← 新增
+    │   ├── Product.php
+    │   └── ProductCategory.php
+    └── Member/             ← 已存在
+```

docs/b010_technical_spec.md

@@ -0,0 +1,89 @@
+# B010 API (機台心跳與指令) 技術規範與執行指南
+
+本文件整合了 B010 API 的業務邏輯討論與技術執行分析，作為 Star Cloud 實作機台通訊核心的指導準則。
+
+---
+
+## 1. 業務邏輯與指令下發 (Command Flow)
+
+### 1.1 指令下發機制
+B010 是 Cloud 向機台下達遠端指令（如：開鎖、重啟、改庫存）的唯一通道。
+*   **指令隊列**：指令需先寫入 `remote_commands` 表，狀態標記為 `pending`。
+*   **撈取邏輯**：當機台定期呼叫 B010 時，後端 Service 會查詢該機台是否有等待執行的指令。
+*   **回應處理**：若有指令，則在 Response 的 `status` 欄位回傳對應的指令碼（如 51:重啟, 70:開鎖）。
+*   **優先順序**：當同時有多個指令待執行時，需按緊急程度（如：重啟 > 開鎖 > 載入配置）定義優先順序回傳。
+
+### 1.2 執行回饋 (Feedback Loop)
+*   **確認機制**：機台收到指令後，必須確保執行結果能回報至雲端。
+*   **判定方案**：
+    *   **被動判定**：若機台在其後的 B010 心跳中回報狀態正常（如：軟體版本更新成功、頁面碼正確），即視為成功。
+    *   **主動判定**：對於關鍵指令（如遠端出貨），機台需另外呼叫狀態更新 API (如 B055 PUT) 回報結果。
+
+---
+
+## 2. 執行面挑戰：高併發與效能 (Performance)
+
+### 2.1 寫入瓶頸分析
+*   **數據規模**：10,000 台機台，每 5 秒一個心跳，全站 QPS 約 2,000。
+*   **DB 壓力**：直接同步寫入 MySQL `machines` 與 `machine_logs` 將導致磁碟 I/O 鎖定。
+
+### 2.2 解決策略 (Redis 緩衝)
+*   **即時狀態流動**：
+    *   **最後在線時間**、**溫度**、**門禁狀態**、**頁面碼** 等動態數據優先存入 **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)
+
+*   **API Key 遷移**：從目前全系統硬編碼的共用 Key，逐步遷移至每台機台專屬的 `api_token`。
+*   **實裝方式**：
+    *   後台管理介面新增「核發機台 Token」功能。
+    *   建立專屬 `IotAuthMiddleware`，驗證請求中的 Token 與 `machines` 表是否匹配。
+
+---
+
+## 5. 離線與告警機制 (Heartbeat Logic)
+
+*   **在線判定**：心跳超時（建議超過 60 秒）即在 UI 將機台顯示為「離線」。
+*   **自動維護**：排程 Job 定期掃描 `machines.last_heartbeat_at`，對長期失聯的機台發出系統告警。
+
+---
+
+## 6. 待確認事項 (To-be-confirmed)
+
+### 6.1 指令下發與回應 (Command Flow)
+1.  **指令優先順序**：當後台同時有多個指令待執行 (如：改庫存 + 重啟) 時，應如何定義優先權？
+2.  **執行狀態回饋**：機台收到心跳指令後的執行結果確認，應採「被動判定」(機台下次心跳狀態正確則視為成功) 還是「主動回報」(機台另呼叫 API)？
+
+### 6.2 效能與日誌策略 (Performance & Logs)
+3.  **Redis 更新頻率**：即時狀態從 Redis 批量同步至 MySQL 的建議時間間隔 (目前暫估 1~5 分鐘)。
+4.  **心跳日誌級別**：是否確認「正常心跳」不寫入資料庫日誌，僅記錄「異常/變更」事件？
+
+### 6.3 在線/離線判定 (Presence)
+5.  **離線超時定義**：預計多久未收心跳判定為離線？(建議 30~60 秒)。
+6.  **斷線告警機制**：機台斷線時，是否需即時產出系統警示或推播給相關人員？
+
+### 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 多種頁面狀態碼中，哪些特定的錯誤代碼需要在管理後台觸發即時紅字警示？

docs/b017_technical_spec.md

@@ -0,0 +1,65 @@
+# B017 API (遠端改庫存) 技術規範與執行指南
+
+本文件記錄 B017 API 的業務邏輯與技術執行細節，用於指導後端管理系統遠端調整機台庫存的實作。
+
+---
+
+## 1. 業務情境與觸發機制 (Trigger)
+
+### 1.1 觸發流程
+1.  **管理行為**：管理員在後台管理介面手動修改特定機台的貨道庫存數量。
+2.  **指令預備**：後端系統記錄異動請求，並在該機台的 B010 (心跳) 回應中，將 `status` 設為 `49` (reload B017)。
+3.  **機台拉取**：機台收到心跳回應中的 `49` 代碼後，主動呼叫 B017 API (`/api/app/machine/reload_msg/{workid}`)。
+4.  **數據同步**：機台獲取最新庫存數據並更新本地狀態。
+
+### 1.2 更新範圍
+*   **全量更新 (Full Sync)**：B017 API 回傳該機台**所有貨道**的最新庫存數量，而非僅回傳變動部分。這有助於機台軟體進行「最終狀態一致性」的自我校正。
+
+---
+
+## 2. 資料一致性與日誌 (Consistency & Audit)
+
+### 2.1 更新確認機制
+*   **隱式成功 (Implicit Success)**：機台更新本地庫存後不需要回傳明確的 B017 確認 API。
+*   **驗證方式**：系統將以機台下次呼叫 B010 回報的狀態或機台後續的正常銷售紀錄，視為前次更新成功。
+
+### 2.2 管理員異動日誌 (Audit Log)
+*   **強制要求**：每次後台發起遠端改庫存操作，必須記錄於 `activity_logs` 或特定的 `stock_adjustment_logs`。
+*   *紀錄內容*：管理者 ID、執行時間、機台 ID、調整前後的貨道庫存對照。
+
+### 2.3 庫存衝突處理
+*   *情境*：若雲端下發庫存更新時，機台現場同時發生實體銷售。
+*   *處理原則*：**詳見下方待確認事項**。
+
+---
+
+## 3. 執行面優化 (Execution Strategy)
+
+### 3.1 Redis 緩衝與效能
+*   **快取策略**：機台的貨道結構與庫存數據應快取於 Redis 中。當管理員調整庫存時，同步更新 Redis 與 MySQL。
+*   **讀取優化**：B017 API 應直接從 Redis 讀取數據回傳給機台，以降低 MySQL 的查詢壓力。
+
+---
+
+## 4. 欄位定義與對照
+
+| 欄位名稱 | 資料庫對應 | 說明 |
+|----------|------------|------|
+| `workid` | `machines.serial_no` | 機台識別序號 |
+| `channelid` | `machine_slots.slot_no` | 貨道編號 |
+| `stock` | `machine_slots.stock` | 該貨道的當前可用庫存 |
+
+---
+
+## 5. 開發建議
+*   建立一個專屬的 `StockService` 來處理 Redis 與 DB 的同步，以及異動日誌的寫入。
+*   在 `B010` 的回應邏輯中，檢查 `remote_commands` 是否有 pending 的庫存異動指令，以動態切換 `status: 49`。
+
+---
+
+## 6. 待確認事項 (To-be-confirmed)
+
+1.  **庫存衝突優先權**：當「雲端改庫存」與「現場實體銷售」同時發生時，最終庫存應以何者為準？(待主管確認)。
+2.  **API 欄位對照**：
+    *   `workid` 是否嚴格對應 `serial_no`？
+    *   `channelid` 是否對標 `slot_no`？

docs/b055_technical_spec.md

@@ -0,0 +1,55 @@
+# B055 API (遠端出貨) 技術規範與執行指南
+
+本文件定義 B055 API 的技術實作規範，用於處理從雲端發起的機台遠端出貨指令及其結果回饋。
+
+---
+
+## 1. 業務流程與通訊機制
+
+### 1.1 指令下發流程
+1.  **指令生成**：Cloud 後端（管理者或系統觸發）在 `remote_dispense_commands` 表中建立一筆狀態為 `0` (待執行) 的指令。
+2.  **心跳通知**：在該機台的 B010 回應中，將 `status` 設為 `85` (reload B055)。
+3.  **機台撈取 (POST)**：機台呼叫 B055 POST API (`/api/app/machine/dispense/{workid}`) 取得詳細出貨參數（貨道 ID、指令 ID）。
+4.  **執行與回報 (PUT)**：機台嘗試出貨後，呼叫 B055 PUT API 回報出貨結果及剩餘庫存。
+
+### 1.2 數據關聯 (Data Linking)
+*   **出貨紀錄整合**：遠端出貨成功後，系統必須在 `dispense_records` 表中同步存入一筆紀錄，並將 `source` 標記為 `remote`（或對應識別），確保後台報表包含所有實體出貨數據。
+
+---
+
+## 2. 資料庫結構：`remote_dispense_commands`
+
+| 欄位 | 說明 | 備註 |
+|------|------|------|
+| `command_id` | 執行命令 ID | 用於追蹤單次指令 |
+| `slot_no` | 貨道 ID | 指派機台出貨的通道 |
+| `status` | 執行狀態 | 0:待執行, 1:成功, 2:失敗 |
+| `remaining_stock` | 剩餘庫存 | 由機台回報 |
+
+---
+
+## 3. 執行面優化 (Execution Strategy)
+
+*   **Redis 隊列**：由於遠端出貨屬於高優先權操作，待執行指令應快取於 Redis 中，以確保機台呼叫 POST 時能即時回應。
+*   **異步處理**：機台 PUT 回報結果後，系統透過隊列更新 DB 狀態，並根據結果觸發後續邏輯（如扣除庫存、異動日誌）。
+
+---
+
+## 4. 待確認事項 (To-be-confirmed)
+
+### 4.1 業務情境 (Scenario)
+1.  **指令發起來源**：確認指令是由後台管理員手動測試發起，還是串接外部線上購買系統產出的取貨指令？
+
+### 4.2 失敗處理機制 (Failure Handling)
+2.  **自動退款/告警**：若機台 PUT 回報出貨失敗，雲端是否需要自動發起退款（針對線上訂單）或發送維修告警通知？
+
+### 4.3 指令效期與防重 (TTL & Idempotency)
+3.  **指令效期**：如果指令發出後機台失聯，該指令應在多久後失效 (TTL)？
+4.  **防重複機制**：如何嚴格確保同一個 `command_id` 不會被重複執行兩次？
+
+### 4.4 安全性與權限 (Security)
+5.  **指令簽名**：除了 `api_token`，發送出貨指令是否需要額外的加密簽名驗證以防偽造？
+6.  **權限限制**：是否限制僅特定高級管理員可發起此類高風險指令？
+
+### 4.5 欄位定義
+7.  **URL {workid}**：確認是否對標 `serial_no`。

docs/b220_technical_spec.md

@@ -0,0 +1,51 @@
+# B220 API (零錢機庫存變動) 技術規範與執行指南
+
+本文件定義 B220 API 的技術實作規範，用於監控機台內的硬幣與鈔票庫存數量，並提供補幣紀錄與找零水位告警功能。
+
+---
+
+## 1. 業務情境與數據特性
+
+### 1.1 數據採集
+*   **回報內容**：機台定期回報各面額（1, 5, 10, 50, 100, 500, 1000 元）的**當前累積總量 (Total Amount)**。
+*   **操作識別**：
+    *   `account = 0`：消費者交易引起的庫存變動。
+    *   `account != 0`：管理員或補貨員進行手動補幣或清空錢箱的操作。
+
+### 1.2 報表與對帳
+*   **零錢庫存分析**：系統必須保留所有變動紀錄，以提供後台「分析報表 > 零錢庫存分析」選單顯示歷史庫存走勢與補幣紀錄。
+
+---
+
+## 2. 執行面優化與告警 (Execution & Alerts)
+
+### 2.1 高頻數據處理 (待確認頻率)
+*   **快取策略**：機台各面額的最新總量應快取於 Redis 或更新至 `machines` 表的擴充欄位，供後台儀表板即時監看。
+*   **寫入過濾**：為節省儲存空間，建議僅在資料數值有實際變動時才寫入 `coin_inventory_logs`。
+
+### 2.2 找零不足告警 (Low Inventory Warning)
+*   **機制**：當特定面額（如 5 元、10 元硬幣）低於預設的水位閾值時，系統應：
+    *   在管理後台儀表板顯示紅字告警。
+    *   （選配）發送推播或系統通知給補貨人員。
+
+---
+
+## 3. 資料庫結構：`coin_inventory_logs`
+
+| 欄位 | 說明 | 備註 |
+|------|------|------|
+| `machine_id` | 機台關聯 ID | |
+| `value_x` | 各面額數量 | 包含 1, 5, 10, 50, 100, 500, 1000 |
+| `account` | 操作人識別 | 0 為消費者，其餘為管理員 |
+| `created_at` | 紀錄時間 | |
+
+---
+
+## 4. 待確認事項 (To-be-confirmed)
+
+### 4.1 系統效能與頻率
+1.  **回報頻率**：確認機台呼叫 B220 的頻率（是每次交易後即時回報，還是定時回報？）。
+
+### 4.2 告警配置
+2.  **水位閾值**：各面額的最低告警水位數值（如 5 元低於多少枚觸發告警）。
+3.  **通知方式**：觸發告警時的具體通知管道。

docs/b600_technical_spec.md

@@ -0,0 +1,52 @@
+# B600 API (消費金流回傳) 技術規範與執行指南
+
+本文件定義 B600 API 的技術實作規範，這是系統處理金流交易、訂單生成與跨 API 關聯的核心。
+
+---
+
+## 1. 交易生命週期與 `flow_id` 串聯
+
+為確保一筆交易數據的完整性，系統採用 `flow_id` 串聯三個連續上報的 API：
+
+1.  **B600 (金流上報)**：
+    *   機台於支付成功後即時呼叫。
+    *   雲端收到後產出專屬的 `flow_id` 並回傳給機台。
+2.  **B601 (發票上報)**：
+    *   機台開立發票後，攜帶 B600 取得的 `flow_id` 呼叫。
+    *   系統根據 `flow_id` 將發票資訊與 `orders` 表關聯。
+3.  **B602 (出貨上報)**：
+    *   機台實體出貨後，攜帶 `flow_id` 呼叫。
+    *   系統根據 `flow_id` 更新訂單的出貨狀態。
+
+---
+
+## 2. 金流類型與標準化
+
+### 2.1 類型定義
+根據 B600 PDF 文件規範 (Req3)，系統優先採用以下預定義類型進行處理與對帳。
+
+### 2.2 防重複上報 (Idempotency)
+為防止網路不穩導致機台重複呼叫 B600，系統必須使用機台產生的 `order_no (tid)` 結合 `machine_id` 作為唯一鍵值校驗。
+
+---
+
+## 3. 執行面優化：異步隊列 (Async Queue)
+
+在高併發環境下，為確保機台端不因等待資料庫寫入而時耗，B600 採以下流程：
+
+1.  **即時回應**：API 接收請求後，將原始 JSON 派發至 **Redis Queue**。
+2.  **背景處理**：由 `ProcessTransaction` 任務異步執行：
+    *   建立 `orders` 與 `order_items`。
+    *   計算並異動會員點數/優惠券。
+    *   同步更新儀表板統計數據。
+3.  **異步回傳**：機台呼叫 API 後會收到 `202 Accepted`，`flow_id` 則透過回應檔同步回傳。
+
+---
+
+## 4. 待確認事項 (To-be-confirmed)
+
+### 4.1 數據完整性稽核
+1.  **自動對帳**：是否需要定期自動比對「B600 收取金額」與「B602 實際出貨金額」，並將差異標記為異常訂單？
+
+### 4.2 失敗補償邏輯
+2.  **出貨失敗處理**：若 B602 回報「出貨失敗」，系統是否需觸發自動退款程序（限線上支付）或發送補發通知？

docs/b601_technical_spec.md

@@ -0,0 +1,49 @@
+# B601 API (發票資訊回傳) 技術規範與執行指南
+
+本文件定義 B601 API 的技術實作規範，用於紀錄每筆訂單對應的電子發票資訊。
+
+---
+
+## 1. 業務流程與角色定義
+
+### 1.1 系統角色
+*   **機台端**：負責與電子發票系統對接、開立發票，並於取得發票號碼後將資訊回傳至雲端。
+*   **雲端 (Star Cloud)**：僅負責**紀錄 (Logging)** 發票資訊，不涉及上傳傳財政部平台或寄送中獎通知。
+
+### 1.2 串聯機制
+*   **關聯 ID**：必須攜帶 B600 取得的 `flow_id`，以便將發票資訊正確掛載至對應的 `orders`。
+
+---
+
+## 2. 資料庫結構：`invoices`
+
+為符合台灣發票規範，除了原始 PDF 欄位外，本系統將擴充相關稅務欄位：
+
+| 欄位 | 說明 | 備註 |
+|------|------|------|
+| `order_id` | 訂單關聯 ID | 透過 `flow_id` 對應 |
+| `invoice_no` | 發票號碼 | 例：AB-12345678 |
+| `invoice_date` | 發票日期 | |
+| `random_number` | 隨機碼 | 4 位數 |
+| `love_code` | 愛心碼 | 捐贈碼 |
+| `business_tax_id` | **公司統編** | 8 位數 |
+| `carrier_id` | **載具編號** | 手機條碼或自然人憑證 |
+| `carrier_type` | **載具類型** | |
+| `status` | **發票狀態** | 1:有效, 0:作廢 |
+
+---
+
+## 3. 發票作廢機制 (Invoice Voiding)
+
+*   **需求確認**：當交易發生退款或特定失敗情境時，機台端需具備回報「發票作廢」的能力。
+*   **API 實作**：
+    *   **方法一**：呼叫 B601 POST 時帶入 `status = 0`。
+    *   **方法二**：新增 `/api/app/B601/void` 專屬端點（待後續細化）。
+
+---
+
+## 4. 待確認事項 (To-be-confirmed)
+
+### 4.1 邏輯關聯與超時
+1.  **發票缺失標記**：若收到 B600 (金流) 但在預設時間內（如 5 分鐘）未收到 B601，後台是否應將該訂單標記為「發票缺失」以供巡檢。
+2.  **重試機制**：機台端在 B601 呼叫失敗時的緩存與重傳策略。

docs/b602_technical_spec.md

@@ -0,0 +1,50 @@
+# B602 API (出貨回傳) 技術規範與執行指南
+
+本文件定義 B602 API 的技術實作規範，用於紀錄機台實體出貨結果，並作為訂單完結與庫存校準的依據。
+
+---
+
+## 1. 業務邏輯與交易完結
+
+### 1.1 串聯機制
+*   **關聯 ID**：必須攜帶 B600 取得的 `flow_id`，以確保出貨紀錄正確鏈結至對應的 `orders`。
+
+### 1.2 多品項交易處理 (Multi-item Orders)
+*   **一對多關係**：系統支持一筆訂單（同一個 `flow_id`）對應多筆 `dispense_records`。
+*   **上報方式**：機台每完成一個貨道之出貨即呼叫一次 B602。雲端後端將自動彙整所有關聯之出貨紀錄以計算該訂單之總體狀態。
+
+---
+
+## 2. 庫存一致性機制 (Stock Consistency)
+
+為確保雲端與機台端的物理庫存同步，系統採以下策略：
+
+1.  **強制信任機制**：系統將「強制信任」機台在 B602 中回報的 `remaining_stock` (絕對值)，並直接更新資料庫中的貨道庫存。
+2.  **異常監控**：若機台回報的庫存與系統計算的預期值（原值 - 1）不符時，系統應於後台標記該次出貨為「庫存異動異常」，供管理員檢查是否發生卡貨或漏貨。
+
+---
+
+## 3. 資料庫結構：`dispense_records`
+
+| 欄位 | 說明 | 備註 |
+|------|------|------|
+| `order_id` | 訂單 ID | 透過 `flow_id` 關聯 |
+| `product_id` | 商品 ID | 出貨之商品 |
+| `slot_no` | 貨道編號 | 出貨之貨道 |
+| `dispense_status` | 出貨狀態 | 0: 成功, 1: 失敗 |
+| `remaining_stock` | 剩餘庫存 | 機台回報之絕對值 |
+| `source` | 來源標記 | `local` (B602), `remote` (B055) |
+
+---
+
+## 4. 待確認事項 (To-be-confirmed)
+
+### 4.1 訂單完結判斷
+1.  **超時標記**：若雲端收到 B600 但遲遲未收到 B602，預設在多久後應將訂單標記為「出貨超時」？
+2.  **狀態遷移**：出貨失敗 (`status=1`) 時，訂單的最終顯示文字與處理流程。
+
+### 4.2 營收與點數處理
+3.  **出貨失敗補償**：若 B602 回報失敗：
+    *   行動支付是否自動觸發退款？
+    *   是否自動退回該次交易所扣除之會員點數與優惠券？
+4.  **現金交易失敗**：出貨失敗且為現金交易時，是否應產出待維護工單或通知補貨員。

docs/b650_technical_spec.md

@@ -0,0 +1,46 @@
+# B650 API (會員/點數/取貨碼驗證) 技術規範與執行指南
+
+本文件定義 B650 API 的技術實作規範，用於處理會員驗證、點數折抵、優惠券兌換、取貨碼驗證以及線上訂單線下結帳等多元功能。
+
+---
+
+## 1. 業務功能與驗證類型 (req6)
+
+根據 API 請求中的 `req6` 欄位，B650 提供以下驗證模式：
+
+| req6 | 說明 | 核心流程 |
+|------|------|----------|
+| `0` | 點擊商品驗證 | 驗證會員資格與點數餘額 |
+| `1` | 會員純驗證 | 僅確認會員身份是否有效 |
+| `2` | 會員兌換商品清單 | 撈取該會員可使用的兌換券或贈品清單 |
+| `3` | 線上訂單線下結帳 | 驗證取貨碼或訂單編號 |
+| `4` | 會員贈品 | 處理行銷活動贈品領取 |
+
+---
+
+## 2. 執行面機制 (Execution Strategy)
+
+*   **高可用性請求**：由於會員驗證通常發生在交易前夕，API 必須具備極速響應能力，建議與第三方系統（若有）採用高效能通訊協議。
+*   **Response 狀態碼校驗**：系統必須嚴格遵守 PDF 定義的狀態碼（如 `101` 全額折抵, `104` 線上訂單驗證成功, `30` 會員使用中等）進行前端反饋。
+
+---
+
+## 3. 待確認事項 (To-be-confirmed)
+
+以下議題目前皆列為**待確認**，將於 Phase 2 或後續討論中釐清：
+
+### 3.1 會員系統架構 (Architecture)
+1.  **資料主體**：Star Cloud 是直接管理會員資料庫，還是僅作為轉發請求至第三方 CRM 的代理伺服器？
+
+### 3.2 安全與防雙重消費 (Security)
+2.  **鎖定機制**：是否需要在 Redis 實作「會員操作 Session」，防止同一帳號在多台機台同時扣點 (狀態碼 30)？
+3.  **Token 時效**：回傳之 `userToken` 的有效期與刷新機制。
+
+### 3.3 線上/線下整合流程
+4.  **訂單轉換**：驗證取貨碼成功後，雲端是否應自動產出對應的銷售紀錄單？
+
+### 3.4 扣點邏輯
+5.  **預扣 vs 實扣**：點數與優惠券應於 B650 驗證時預先鎖定，還是待 B602 出貨成功後才正式扣除？
+
+### 3.5 界面展示需求
+6.  **商品資訊**：當 `req6 = 2` 時，回傳的產品清單是否需要包含圖片或詳細描述供機台屏幕顯示？

docs/b710_technical_spec.md

@@ -0,0 +1,49 @@
+# B710 API (計時器狀態回傳) 技術規範與執行指南
+
+本文件定義 B710 API 的技術實作規範，用於處理計時型設備（如洗衣服務、按摩服務）的剩餘時間監測與狀態回報。
+
+---
+
+## 1. 業務流程與資料流
+
+### 1.1 狀態回報
+*   **回報內容**：機台定期回報特定貨道 (product/timer) 的 `remaining_seconds` (剩餘秒數) 與目前狀態。
+*   **資料用途**：
+    *   **即時監控**：供管理後台儀表板顯示設備的使用進度。
+    *   **稼動分析**：紀錄設備的總租用時數與閒置率。
+
+---
+
+## 2. 執行面機制 (Execution Strategy)
+
+*   **異步處理**：由於計時狀態可能高頻回報，系統應優先將數據更新至 **Redis 快取**，以確保前端查詢的高效能與資料庫的負擔平衡。
+
+---
+
+## 3. 資料庫結構：`timer_statuses`
+
+| 欄位 | 說明 | 備註 |
+|------|------|------|
+| `machine_id` | 機台 ID | |
+| `product_id` | 產品/服務 ID | |
+| `remaining_seconds` | 剩餘秒數 | |
+| `status` | 運行狀態 | 1:運行中, 0:停止 |
+
+---
+
+## 4. 待確認事項 (To-be-confirmed)
+
+以下議題目前皆列為**待確認**，將於後續開發階段釐清：
+
+### 4.1 回報頻率與快取
+1.  **更新頻率**：確認機台呼叫 B710 的精確頻率，以及資料庫寫入的節流策略（例如：僅在關鍵變動或每分鐘寫入一次）。
+
+### 4.2 遠端通知與異常
+2.  **結束通知**：倒數結束時，雲端是否需主動對對消費者發送推播或系統訊息？
+3.  **斷線判定**：針對長期未回報的計時器，雲端應自動判定為結束還是異常？
+
+### 4.3 復歸機制
+4.  **斷電補償**：機台意外斷電重啟後，是否需向雲端 B010 撈回最後的剩餘秒數以恢復服務？
+
+### 4.4 報表需求
+5.  **稼動分析**：後台是否需要針對此數據計算「設備利用率」等績效指標。

docs/rbac_architecture.md

@@ -0,0 +1,55 @@
+# Star Cloud 多租戶與權限架構 (Multi-Tenant RBAC) 實作規劃
+
+## 1. 架構目標
+為了支援 Star Cloud 系統具備 B2B SaaS 的多租戶特性，讓「系統管理員（內部營運）」與「租戶（客戶公司）」能在同一套後台中共存。各租戶能自行建立子帳號並分配權限，且資料彼此絕對隔離。
+
+將導入基於 `companies` 的租戶隔離，並結合 `spatie/laravel-permission` 實作多租戶的角色權限控制。
+
+---
+
+## 2. 核心實作架構
+
+### 2.1 租戶隔離層 (Tenant Isolation)
+建立實體的租戶邊界，確保每個客戶在物理與邏輯上只能存取自己的資料。
+*   **變更**：新增 `companies` 表（公司名稱、統編、狀態等）。
+*   **綁定**：在 `users`, `machines`, 等核心資源表中加上 `company_id`。
+*   **身份判定**：
+    *   `company_id = null`：系統預設管理員（內部工程師 / 營運人員），具備跨公司存取能力。
+    *   `company_id = N`：客戶端帳號（租戶）。
+
+### 2.2 角色與權限層 (Roles & Permissions)
+利用 `spatie/laravel-permission` 結合多租戶。
+*   **全域權限 (Permissions)**：定義系統所有的最小操作單位（如 `machine.view`, `user.create`），所有租戶共用權限定義。
+*   **多租戶角色 (Tenant-Aware Roles)**：原本套件的 `roles` 表必須擴充加上 `company_id` 欄位。
+    *   系統預設角色 (`company_id = null`)：如 Super Admin。
+    *   客戶自建角色 (`company_id = N`)：如客戶自定義的「台北區維修員」，只能分配給統一個 `company_id` 的使用者。
+
+### 2.3 流程控制與防禦 (Flow Control)
+*   **自動過濾 (Global Scopes)**：寫一個 Trait `TenantScoped`，當非內部人員登入時，自動幫 Eloquent Model 的所有查詢加上 `where('company_id', auth()->user()->company_id)`。
+*   **越權防禦 (Create User)**：租戶在後台建立「新子帳號」時，API Controller 必須在背景強制 `NewUser->company_id = Auth::user()->company_id`。
+*   **角色分配防禦**：客戶分配角色給員工時，只能撈取並指定 `company_id` 與自己相同的 Role。
+
+---
+
+## 3. 實作步驟 (對應 Phase 1 與 Phase 3)
+
+### 步驟 1：資料庫結構 (Migrations)
+1. 建立 `create_companies_table` migration。
+2. 建立 `add_company_id_to_users_table` migration。
+3. 調整 `machines` 及其他資源表，加入 `company_id` 欄位與外鍵。
+4. 安裝並發布 `spatie/laravel-permission` migrations，並接續寫一個 migration 為 `roles` 和 `permissions` 調整結構 (加入 `company_id` 至 `roles`)。
+
+### 步驟 2：Eloquent Models 與 Scopes 修改
+1. 建立 `Company` Model (`App\Models\System\Company`)。
+2. 修改 `User` Model (`App\Models\Member\User`)，加入 `company()` 關聯與 Helper methods (`isSystemAdmin()`, `isTenant()`)。
+3. 建立 `TenantScoped` Trait，包含 Laravel Global Scope 邏輯。套用至 `Machine` 等需要隔離的 Model。
+
+### 步驟 3：後端流程與介面防禦 (Middleware & Controllers)
+1. 建立 `CheckTenantAccess` Middleware 進行基礎的路由存取權限卡控。
+2. 在後台的「帳號與權限」模組中，實作過濾邏輯：
+    *   撈取使用者、角色列表時帶入 `company_id`。
+    *   創建或修改時強制綁定 `Auth::user()->company_id`。
+
+### 步驟 4：前端 Blade 呈現切換
+1. 使用 Blade 的 `@if(auth()->user()->isSystemAdmin())` 在 Sidebar 中隱藏或顯示「全站管理」、「合約設定」等專屬區塊。
+2. 確保一般租戶登入時，左側選單僅顯示其有權限存取的「機台管理」、「我的專屬會員」、「所屬帳號設定」等區塊。