# 婚禮賓客管理系統 - 開發 Roadmap

> 基於 CLAUDE.md 的優先順序規劃
> **版本**: v2.0 (改進版)
> **更新日期**: 2026-02-01

---

## 開發階段總覽

```
Phase 1: MVP 基礎功能 (2週 / P0)
    ↓
Phase 2: 核心管理功能 (2週 / P1)
    ↓
Phase 3: 進階功能與整合 (1-2週 / P2)
    ↓
Phase 4: 優化與擴展 (持續 / P3)
```

---

## Phase 1: MVP 最小可行產品（2週 / P0）

### 目標
完成核心資料收集與基礎管理功能，讓新人可以開始發送連結收集名單。

### 1.1 專案初始化
- [ ] Laravel 11 專案建置
- [ ] 資料庫設計與 Migration（guests, accompanying_guests）
- [ ] Laravel Filament 後台安裝
- [ ] Inertia.js + React 安裝
- [ ] 基礎認證系統（登入/登出）
- [ ] 環境設定（時區 `Asia/Taipei`、中文語系）

### 1.2 賓客填寫表單（前台）
- [ ] 表單頁面 UI（RWD、手機優先）
- [ ] 多步驟表單（Stepper）：
  - Step 1: 基本資訊（姓名、電話、Email、邀請方、賓客類別）
  - Step 2: 出席意願（三選一）
  - Step 3: 出席詳情（動態顯示）
  - Step 4: 同行賓客
  - Step 5: 其他（希望同桌、祝福留言）
- [ ] 即時表單驗證
- [ ] 防重複填寫（手機號碼檢查）
- [ ] 提交成功頁面（顯示婚禮資訊、修改連結）
- [ ] 修改機制（token 修改連結）

### 1.3 後台基本 CRUD
- [ ] Filament 賓客 Resource（CRUD）
- [ ] 賓客列表（分頁、搜尋、篩選）
- [ ] 賓客詳情查看/編輯
- [ ] 備註欄位
- [ ] 批次操作（匯出 CSV、刪除）
- [ ] 軟刪除（SoftDeletes）

### 1.4 基本統計儀表板
- [ ] 總賓客數（確定出席/待確認/不出席）
- [ ] 總人數統計（成人/兒童/嬰幼兒）
- [ ] 素食統計
- [ ] 最近動態（新填寫、修改）

### 1.5 系統設定（基礎）
- [ ] 婚禮基本資訊設定
- [ ] 表單開關控制

### Phase 1 驗收標準
- [ ] 賓客可透過手機完成表單填寫（5 分鐘內）
- [ ] 賓客可用 token 修改已填寫資料
- [ ] 管理者可登入後台查看賓客名單
- [ ] 儀表板統計數據與資料庫一致
- [ ] 可匯出 CSV 格式賓客名單

---

## Phase 2: 核心管理功能（2週 / P1）

### 目標
完成分桌管理、禮金管理等婚禮核心功能。

### 2.1 桌次管理
- [ ] 桌次 CRUD（桌號、桌名、區域、最大人數）
- [ ] 桌次列表與排序
- [ ] 每桌人數即時統計

### 2.2 分桌功能
- [ ] 視覺化拖曳分桌介面
- [ ] 未分配賓客清單
- [ ] 超額警告提示
- [ ] 希望同桌需求標示
- [ ] 批次分桌（按邀請方/類別）

### 2.3 LINE ID 綁定功能
- [ ] 賓客表單新增 LINE ID 欄位（選填）
- [ ] LINE ID 與賓客資料綁定
- [ ] 後台顯示 LINE ID 欄位與篩選
- [ ] LINE ID 格式驗證
- [ ] 透過 LINE ID 查詢賓客

### 2.4 匯出功能
- [ ] 賓客名單 Excel 匯出
- [ ] 素食統計表匯出（給廠商）
- [ ] 座位表匯出（Excel/PDF）

### 2.5 通知功能
- [ ] Email 模板管理
- [ ] 填寫確認信自動發送
- [ ] 發送記錄

### 2.6 權限與稽核
- [ ] 角色定義（admin/checkin_staff/gift_staff）
- [ ] 權限分配
- [ ] 啟用 `activity_logs`（關鍵操作記錄）

### Phase 2 驗收標準
- [ ] 可完成全部賓客分桌（有超額提示）
- [ ] LINE ID 綁定與查詢功能正常
- [ ] 可匯出 Excel/PDF 報表
- [ ] Email 通知可正常發送

---

## Phase 3: 進階功能與整合（1-2週 / P2）

### 目標
加入禮金管理、婚宴當日功能、LINE 進階整合、智能建議。

### 3.1 禮金管理
- [ ] 禮金記錄 CRUD
- [ ] 關聯賓客功能
- [ ] 禮金統計（總額、分類統計）
- [ ] 收禮狀態標記
- [ ] 金額快速按鈕（1200/1600/2000...）
- [ ] 金額欄位權限遮罩
- [ ] 禮金清單匯出

### 3.3 報到系統
- [ ] 報到介面（Mobile Friendly）
- [ ] 快速搜尋（姓名/手機末三碼）
- [ ] 一鍵報到功能
- [ ] 桌號大字體顯示
- [ ] 即時報到統計
- [ ] 報到記錄 Log

### 3.4 QR Code 功能
- [ ] 賓客專屬 QR Code 生成
- [ ] QR Code 報到掃描
- [ ] 座位查詢 QR Code

### 3.5 現場查詢螢幕
- [ ] 賓客自助查詢介面
- [ ] 大螢幕顯示模式

### 3.6 LINE 進階整合（選配）
- [ ] LINE Notify 通知
- [ ] LINE Bot 桌次查詢

### 3.7 智能分桌建議（選配）
- [ ] AI 分桌演算法
- [ ] 衝突檢測與建議

### Phase 3 驗收標準
- [ ] 禮金登記與統計功能正常
- [ ] 金額權限遮罩生效
- [ ] 現場報到流程順暢（5 秒內完成單筆）
- [ ] QR Code 報到功能正常
- [ ] 現場查詢介面運作正常

---

## Phase 4: 優化與擴展（持續 / P3）

### 目標
效能優化、UX 提升、額外功能。

### 4.1 效能優化
- [ ] 資料庫索引優化
- [ ] 快取策略（報到查詢）
- [ ] API 效能調校

### 4.2 UI/UX 調整
- [ ] 使用者回饋收集與優化
- [ ] 動畫與過場效果
- [ ] Loading 狀態優化

### 4.3 行動裝置優化
- [ ] PWA 支援（離線功能）
- [ ] 觸控操作優化

### 4.4 進階功能（選配）
- [ ] 喜餅發放管理
- [ ] 回禮管理
- [ ] 多場次支援（午宴/晚宴）

### 4.5 稽核與安全
- [ ] 完整操作日誌
- [ ] MFA 雙因素認證
- [ ] 資料加密強化

### 4.6 備份與匯出
- [ ] 自動備份機制
- [ ] 一鍵完整資料匯出

### Phase 4 驗收標準
- [ ] 頁面載入時間 < 2 秒
- [ ] 手機操作體驗流暢
- [ ] 無重大安全漏洞
- [ ] 資料備份機制正常運作

---

## 風險項目

### 提早識別以免婚禮當天翻車

| 風險 | 說明 | 建議處理方式 |
|------|------|-------------|
| 拖曳分桌複雜度高 | 前端實作難度較大 | 先做下拉選單版，再升級拖曳 |
| 現場網路不穩 | 報到查詢可能卡住 | 加入快取/索引；PWA 離線列為 P3 |
| 權限沒先規劃 | 後期重構成本高 | Phase 1 就預留欄位/Policy |
| LINE API 申請 | 可能需要時間 | 提早申請官方帳號 |
| PDF 中文字體 | 匯出可能亂碼 | 測試中文字體支援 |

---

## 技術債注意事項

1. **資料結構**：Phase 1 就要確定，後期修改成本高
2. **Enum 命名**：MVP 就固定，避免後期 migration 地獄
3. **權限設計**：Phase 1 就預留，避免後續重構
4. **測試覆蓋**：每個 Phase 完成需有基本測試
5. **文件維護**：API 文件與使用說明同步更新

---

## 里程碑時程

| 階段 | 內容 | 建議時程 |
|------|------|----------|
| Phase 1 | MVP 基礎功能 | 第 1-2 週 |
| Phase 2 | 核心管理功能 | 第 3-4 週 |
| Phase 3 | 進階功能與整合 | 第 5-6 週 |
| Phase 4 | 優化與擴展 | 持續迭代 |

---

**文件版本**: v2.0
**最後更新**: 2026-02-01
**維護者**: ClaudeCode Team