# 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 通知)