# 婚禮賓客管理系統 - 應用程式規格書

> 本規格統整自 CLAUDE.md、CHATGPT.md、GEMINI.md 三份計劃書
> **版本**: v2.0 (改進版)
> **更新日期**: 2026-02-01

---

## 0. 產品目標與重要預設

### 0.1 產品目標
- 讓賓客用手機快速填寫 RSVP（含攜伴、飲食、特殊需求），並支援後續修改
- 讓新人/工作人員以後台管理名單、統計人數、安排桌次、登記禮金、婚宴當日快速查詢與報到

### 0.2 重要預設（若未特別決策，一律採用）

| 項目 | 預設值 | 說明 |
|------|--------|------|
| 語言 | 中文 | 介面與通知文案以中文為主 |
| 時區 | `Asia/Taipei` | config/app.php 設定 |
| 身分識別 | `phone` | 以手機號碼作為主要查詢/防重複 key |
| 刪除策略 | SoftDeletes | 後台刪除採軟刪除，避免資料遺失 |
| 手機號碼唯一約束 | 應用層控制 | 不做 DB 層級唯一約束，允許 admin 合併 |

### 0.3 優先級定義

| 優先級 | 說明 | 對應階段 |
|--------|------|----------|
| **P0** | MVP 最小可行產品 | Phase 1 |
| **P1** | 核心功能 | Phase 2 |
| **P2** | 進階功能 | Phase 3 |
| **P3** | 優化與擴展 | Phase 4 |

---

## 1. 角色與權限 (RBAC)

### 1.1 角色定義

| 角色 | 英文代號 | 權限範圍 | 優先級 |
|------|---------|---------|--------|
| 系統管理者 | `admin` | 全功能（設定、刪除、匯出、權限管理） | P0 |
| 新人/主辦 | `organizer` | 管理賓客、座位、桌次、禮金、通知 | P1 |
| 接待組 | `checkin_staff` | 報到、賓客查詢、座位指引（禮金金額遮罩） | P1 |
| 收禮組 | `gift_staff` | 登記禮金/對帳（可見禮金金額） | P2 |
| 協辦/僅查看 | `viewer` | 僅查看（不可編輯） | P2 |

### 1.2 欄位級權限（最低要求）【P1】

| 欄位 | 遮罩規則 |
|------|----------|
| 禮金金額 | 預設僅 `admin` / `gift_staff` 可見【P2】 |
| 電話號碼 | 列表顯示末三碼，詳細頁依權限解鎖 |
| 地址 | 列表遮罩，詳細頁依權限解鎖 |

### 1.3 稽核要求【P1】
- 後台關鍵操作需有操作記錄（`activity_logs`）
- 至少記錄：賓客修改、桌次調整、禮金登記/修改、報到

---

## 2. 功能需求（按優先級分層）

### 2.1 賓客填寫表單（前台）

#### 2.1.1 表單入口與狀態【P0】
- **入口方式**：短網址 / QR Code
- **可設定**：男方/女方不同入口或同入口分流【P1】
- **表單狀態控制**【P1】：
  - `開放填寫`：任何人都可以填寫
  - `暫停`：暫時關閉表單
  - `截止`：不再接受新填寫
  - `僅允許修改`：已填寫者可用 token 修改

#### 2.1.2 必填欄位（核心）【P0】

| 欄位 | 類型 | 說明 |
|------|------|------|
| 賓客姓名 | 必填 | |
| 聯絡電話 | 必填 | 做為唯一識別與查詢 Key |
| 電子郵件 | 選填 | 用於寄送確認信 |
| LINE ID | 選填 | 用於 LINE 綁定與通知 |
| 邀請方 | 必填 | 新郎方/新娘方/共同友人（單選） |
| 賓客類別 | 必填 | 親屬/同事/朋友/長輩/同學（單選） |
| 參加意願 | 必填 | 確定出席/不確定/無法出席（單選） |

#### 2.1.3 出席資訊（動態邏輯）【P0】

**若選「確定出席」**：
- 成人人數（含自己，預設 1，最小值 1）
- 兒童人數（12歲以下，預設 0）
- 嬰幼兒人數（需要兒童座椅，預設 0）
- 素食需求（葷食/全素/蛋奶素/特殊飲食備註）
- 特殊需求（輪椅通道/嬰兒車停放）

**若選「不確定」**：
- 僅收集基本資訊，可後續修改

**若選「無法出席」**【P1】：
- 「不出席，但想收帖」→ 顯示地址欄位
- 「禮到人不到」→ 顯示電子支付資訊

#### 2.1.4 同行賓客【P0】
可新增多筆同行賓客資料：
- 姓名（必填）
- 關係（配偶/子女/朋友）
- 年齡層（成人/兒童/嬰幼兒）
- 素食需求

#### 2.1.5 其他功能【P0】
- 希望同桌的賓客（可填寫姓名）
- 祝福留言（選填）
- 填寫時間戳記（自動記錄）
- 修改連結（填寫後提供專屬 token 可再次編輯）

#### 2.1.6 表單設計要求【P0】
- RWD 響應式設計（手機優先）
- 多步驟表單（Stepper）+ 進度指示
- 即時表單驗證
- 提交後確認畫面（含婚禮資訊、導航連結）
- LINE/Email 通知新人有新填寫【P1】

#### 2.1.7 防重複策略【P0】
- 以 `phone`（或 `email`）檢查是否已存在回覆
- 已存在：提示「已填過」並引導進入「找回/修改」流程
- 不存在：允許建立新回覆
- 後台需提供「合併/標記重複」的擴充點【P1】

#### 2.1.8 驗證規則【P0】
- `phone`：必填、格式檢查（台灣手機 09 開頭）
- 人數欄位：不得為負；`adult_count >= 1`（若出席）
- `attendance_status` 為「不出席」時：出席相關欄位可清空

---

### 2.2 後台：儀表板 Dashboard【P0】

| 統計項目 | 說明 | 優先級 |
|----------|------|--------|
| 總賓客數 | 確定出席/待確認/不出席 | P0 |
| 總人數統計 | 成人/兒童/嬰幼兒分開計 | P0 |
| 素食統計 | 各類型素食人數 | P0 |
| 最近動態 | 新填寫、新修改的賓客 | P0 |
| 分桌進度 | 已分配/未分配人數 | P1 |
| 總禮金統計 | 已收/未收（權限控管） | P2 |
| 報到率 | 即時到場率 | P2 |

---

### 2.3 後台：賓客管理 (CRM)

#### 2.3.1 列表功能【P0】
- 分頁顯示所有賓客
- 搜尋（姓名/電話）
- 篩選（邀請方/出席狀態/是否已分桌/是否有 LINE ID）
- 排序（填寫時間/姓名/桌次）
- 批次操作（匯出 CSV/刪除）

#### 2.3.2 賓客詳細資料【P0】
- 查看完整填寫內容
- 編輯功能
- 備註欄位（內部使用）
- 操作記錄（建立/修改歷程）【P1】
- 重新發送修改連結【P1】

#### 2.3.3 標籤系統【P1】
- 自訂標籤（VIP/長輩/需特別照顧/大學幫/工作人員）
- 批次加標籤

---

### 2.4 後台：分桌管理【P1】

#### 2.4.1 桌次設定【P1】
- 建立桌次（桌號、桌名、區域）
- 設定每桌人數上限（預設 10 人）
- 區域分類（內場/外場/主桌/長輩區）
- 桌次排序與顏色標記

#### 2.4.2 分桌方式【P1】

1. **手動拖曳分配**
   - 視覺化拖拽介面
   - 即時顯示每桌人數、素食數
   - 超額警告提示

2. **快速分配規則**
   - 按邀請方自動分組
   - 按賓客類別分組
   - 參考「希望同桌」備註

3. **智能建議（AI）**【P2】
   - 根據關係、年齡層建議分桌
   - 衝突檢測

#### 2.4.3 匯出【P1】
- 匯出座位表（Excel/CSV）
- PDF 匯出【P2】

---

### 2.5 後台：LINE ID 綁定管理【P1】

#### 2.5.1 LINE ID 欄位【P1】
- 賓客填寫表單時可選填 LINE ID
- 後台可手動為賓客新增/修改 LINE ID
- LINE ID 格式驗證（英數字、底線、句點，4-20 字元）

#### 2.5.2 LINE ID 查詢與管理【P1】
- 透過 LINE ID 搜尋賓客
- 後台列表顯示 LINE ID 綁定狀態
- 批次篩選已綁定/未綁定 LINE ID 的賓客

#### 2.5.3 LINE ID 應用【P1】
- 為後續 LINE 通知/LINE Bot 整合預留基礎
- LINE ID 欄位可用於匯出報表

---

### 2.6 後台：禮金管理【P2】

#### 2.6.1 禮金記錄欄位

| 欄位 | 說明 | 優先級 |
|------|------|--------|
| 賓客姓名 | 自動帶入/手動新增 | P2 |
| 禮金金額 | 可設定遮罩顯示 | P2 |
| 收禮時間 | 預設當天 | P2 |
| 收禮方式 | 現金/轉帳/禮券 | P2 |
| 禮金袋編號 | 方便對帳 | P2 |
| 收禮人 | 經手人員帳號 | P2 |
| 備註 | 金飾、禮物、代包等 | P2 |

#### 2.6.2 禮金統計【P2】
- 總禮金額
- 已收/未收禮金人數
- 按邀請方統計（新郎方/新娘方）
- 按賓客類別統計

#### 2.6.3 快速輸入【P2】
- 金額快速按鈕（1200/1600/2000/2600/3600/6000）

---

### 2.7 婚宴當日：報到系統【P2】

#### 2.6.1 報到介面（Mobile Friendly）
- 快速搜尋：姓名/手機末三碼
- QR Code 報到（選配）

#### 2.6.2 資訊顯示
- 桌號（超大字體）
- 飲食需求
- 特殊備註（輪椅等）
- 一鍵「已報到」

#### 2.6.3 即時統計
- 已報到 / 總人數
- 報到率百分比

---

### 2.8 通知功能【P1】

#### 2.7.1 Email 通知
- 填寫確認信（賓客填寫後自動發送）
- 邀請函（手動發送）
- 桌次確認信（婚禮前一週）
- 感謝信（婚禮後）

#### 2.7.2 發送管理
- 範本管理
- 發送記錄（時間、對象、成功/失敗）

#### 2.7.3 LINE 整合【P2】（選配）
- LINE Notify 通知
- LINE Bot 桌次查詢

---

### 2.9 報表與匯出【P1】

| 報表 | 格式 | 優先級 |
|------|------|--------|
| 賓客名單總表 | Excel/CSV | P0 |
| 素食統計表（給廠商） | Excel/CSV | P1 |
| 座位表 | Excel/PDF | P1 |
| 禮金清單 | Excel/CSV | P2 |

---

### 2.10 系統設定【P1】

#### 2.9.1 基本設定
- 婚禮基本資訊（新人姓名、日期、時間、地點、導航連結）
- 表單開放/關閉時間
- 預設桌次人數

#### 2.9.2 權限管理
- 角色定義與權限分配
- 欄位級權限控制（禮金遮罩）

---

## 3. 核心使用流程 (User Journeys)

### 3.1 賓客填寫與修改流程【P0】
```
1. 賓客開啟短網址/掃 QR → 填寫多步驟表單
2. 系統驗證必填/格式 → 建立回覆 → 顯示成功頁
3. 系統產生修改 token → 提供修改連結
4. 賓客用修改連結更新資料 → 後台可看到更新紀錄【P1】
```

### 3.2 分桌與輸出流程【P1】
```
1. 管理者建立桌次與人數上限
2. 以拖曳方式將「確定出席」賓客分配到桌次
3. 匯出每桌名單給現場/廠商
```

### 3.3 現場報到流程【P2】
```
1. 工作人員登入「報到模式」→ 搜尋賓客（姓名/手機末三碼）
2. 顯示桌號與備註 → 點擊「已報到」
3. 後台統計即時更新
```

---

## 4. 資料模型

### 4.1 實體（Entities）

| 資料表 | 說明 | 優先級 |
|--------|------|--------|
| `users` | 後台使用者（含角色/權限） | P0 |
| `guests` | 賓客主檔（含 RSVP 回覆） | P0 |
| `accompanying_guests` | 同行賓客明細 | P0 |
| `tables` | 桌次 | P1 |
| `gift_records` | 禮金記錄 | P1 |
| `check_in_logs` | 報到記錄 | P2 |
| `activity_logs` | 操作記錄/稽核 | P1 |
| `notifications` | 通知紀錄 | P1 |
| `settings` | 系統設定 | P1 |

### 4.2 Enum 與命名（MVP 就固定）

| 欄位 | 選項 |
|------|------|
| `invited_by` | `groom` / `bride` / `both` |
| `attendance_status` | `attending` / `pending` / `not_attending` |
| `guest_type` | `family` / `colleague` / `friend` / `elder` / `classmate` / `other` |
| `dietary_requirement` | `regular` / `vegan` / `ovo_lacto` / `special` |
| `age_group` | `adult` / `child` / `infant` |
| `payment_method` | `cash` / `transfer` / `voucher` / `gift` |

### 4.3 關鍵欄位

```
guests:
  - invitation_code?, name, phone, email?, line_id?
  - invited_by, guest_type, attendance_status
  - adult_count, child_count, infant_count
  - dietary_requirement, dietary_notes?, special_needs?
  - wish_message?, preferred_table_mates?
  - table_id?, edit_token, is_vip, tags?, notes?
  - deleted_at?

accompanying_guests:
  - guest_id, name, relationship?
  - age_group, dietary_requirement?

tables:
  - table_number, table_name?, area?
  - max_seats, sort_order?, color?

gift_records:
  - guest_id?, guest_name, amount?
  - payment_method, envelope_number?
  - received_at, received_by?, notes?
```

### 4.4 統計口徑（重要）
- 後台「人數統計」以 `guests.adult_count/child_count/infant_count` 為準
- `accompanying_guests` 用於名單明細/桌卡資訊
- 可做一致性檢查提醒【P1】

### 4.5 索引建議（P0 就做）
- `guests.phone`、`guests.name`、`guests.line_id`
- `guests.table_id`
- `gift_records.guest_id`
- `check_in_logs.guest_id`

---

## 5. 非功能性需求

### 5.1 安全性【P1】
- HTTPS 強制使用【P0】
- 資料加密（特別是禮金）
- 敏感欄位遮罩（手機、金額）
- 登入 MFA（至少管理者）【P2】

### 5.2 效能【P1】
- 現場報到秒開（快取/索引）
- 資料庫索引優化

### 5.3 可用性【P0】
- RWD 響應式設計（手機優先）
- 手機後台支援【P2】

### 5.4 稽核【P1】
- 操作紀錄完整
- 修改歷程版本控管

### 5.5 備份【P1】
- 定時自動備份
- 一鍵匯出整包資料

---

## 6. 技術架構

### 6.1 技術棧
- **後端**：Laravel 11
- **後台管理**：Laravel Filament 3.0
- **前端表單**：Inertia.js + React
- **資料庫**：MySQL / PostgreSQL
- **佇列**：Laravel Queue（通知發送）

### 6.2 套件建議

| 功能 | 套件 | 優先級 |
|------|------|--------|
| PDF 匯出 | barryvdh/laravel-dompdf | P1 |
| Excel 匯出 | maatwebsite/excel | P1 |
| 拖曳分桌 | React DnD / SortableJS | P1 |
| 權限管理 | spatie/laravel-permission | P1 |
| QR Code | simplesoftwareio/simple-qrcode | P2 |

---

## 7. MVP 完成定義（Phase 1 / P0）

### 7.1 完成條件
- [ ] 賓客可透過手機完成 RSVP 表單（含同行賓客）
- [ ] 賓客可用 token 修改已填寫資料
- [ ] 防重複填寫機制運作正常（手機號碼檢查）
- [ ] 管理者可登入後台查看賓客名單
- [ ] 後台可搜尋/篩選/編輯賓客資料
- [ ] 儀表板顯示正確統計數據
- [ ] 可匯出賓客名單（至少 CSV 格式）
- [ ] 基本權限：未登入不可進入後台

### 7.2 基礎設定
- [ ] 時區設定為 `Asia/Taipei`
- [ ] 介面以中文為主
- [ ] 賓客刪除採 SoftDeletes

---

## 8. 附錄

### 8.1 賓客類別選項
- 親屬 (family)
- 同事 (colleague)
- 朋友 (friend)
- 長輩 (elder)
- 同學 (classmate)
- 其他 (other)

### 8.2 素食選項
- 葷食 (regular)
- 全素 (vegan)
- 蛋奶素 (ovo_lacto)
- 特殊飲食 (special)

### 8.3 出席狀態
- 確定出席 (attending)
- 不確定 (pending)
- 無法出席 (not_attending)

---

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