# 婚禮賓客管理系統 (Wedding Guest Management System)

基於 Laravel 11 + Filament 3 + Inertia.js + React 打造的婚禮賓客管理系統。

## 技術棧

- **後端**: Laravel 11, PHP 8.2
- **後台管理**: Laravel Filament 3.0
- **前端表單**: Inertia.js + React
- **資料庫**: MySQL 8.0
- **樣式**: Tailwind CSS
- **佇列**: Laravel Queue (Database Driver)
- **語系**: 繁體中文 (zh_TW)
- **時區**: Asia/Taipei

## 專案結構

本專案已建立以下檔案結構：

### 資料庫層 (Database Layer)
```
database/
├── migrations/
│   ├── 2026_02_01_000001_create_guests_table.php
│   ├── 2026_02_01_000002_create_accompanying_guests_table.php
│   ├── 2026_02_01_000003_create_tables_table.php (Phase 2)
│   └── 2026_02_01_000004_create_gift_records_table.php (Phase 2)
├── factories/
│   └── GuestFactory.php
└── seeders/
    └── GuestSeeder.php
```

### 模型層 (Models)
```
app/Models/
├── Guest.php (主賓客模型，含 SoftDeletes)
├── AccompanyingGuest.php (同行賓客)
├── Table.php (桌次安排 - Phase 2)
└── GiftRecord.php (禮金記錄 - Phase 2)
```

### 控制器與驗證 (Controllers & Requests)
```
app/Http/
├── Controllers/
│   └── RsvpController.php (RSVP 表單 CRUD)
└── Requests/
    ├── RsvpStoreRequest.php (新增驗證)
    └── RsvpUpdateRequest.php (更新驗證)
```

### 前端 React 組件 (Frontend)
```
resources/js/Pages/Rsvp/
├── Create.jsx (多步驟表單主頁)
├── Edit.jsx (修改表單)
├── Success.jsx (成功頁面)
└── Components/
    ├── StepOne.jsx (基本資訊)
    ├── StepTwo.jsx (出席意願)
    ├── StepThree.jsx (出席詳情)
    ├── StepFour.jsx (同行賓客)
    └── StepFive.jsx (其他資訊)
```

### Filament 後台 (Admin Panel)
```
app/Filament/
├── Resources/
│   ├── GuestResource.php (賓客資源管理)
│   └── GuestResource/Pages/
│       ├── ListGuests.php (列表頁)
│       ├── CreateGuest.php (新增頁)
│       └── EditGuest.php (編輯頁)
└── Widgets/
    └── StatsOverview.php (儀表板統計)
```

### 路由 (Routes)
```
routes/
└── web.php (包含所有 RSVP 路由)
```

## 功能特色

### Phase 1 (MVP - 已完成檔案結構)

✅ **賓客回函表單**
- 多步驟表單設計 (5 步驟)
- 手機號碼作為唯一識別
- 自動產生 edit_token 供後續修改
- 支援同行賓客管理
- 飲食需求與特殊需求記錄
- 手機優先響應式設計
- 繁體中文介面

✅ **後台管理系統**
- Filament 3 管理面板
- 賓客 CRUD 完整功能
- 出席狀態篩選
- VIP 賓客標記
- 搜尋與排序功能
- 統計儀表板

✅ **資料庫設計**
- 主賓客表 (guests)
- 同行賓客表 (accompanying_guests)
- 軟刪除支援
- 完整索引優化

### Phase 2 (規劃中)
- 桌次安排系統
- 禮金記錄管理
- 簽到系統
- QR Code 生成
- Email / SMS 通知
- Excel / PDF 匯出

## 安裝步驟

### 前置需求
- PHP >= 8.2
- Composer
- Node.js >= 18
- MySQL >= 8.0

### 方式一：使用 Docker (推薦)

```bash
# 1. 啟動 Docker 容器
docker compose up -d

# 2. 進入容器執行設定
docker compose exec app bash

# 3. 安裝依賴
composer install
npm install

# 4. 設定環境變數
cp .env.example .env
php artisan key:generate

# 5. 執行 Migration 與 Seeder
php artisan migrate --seed

# 6. 建立 Filament 管理員
php artisan make:filament-user

# 7. 編譯前端資源
npm run build

# 8. 訪問應用
# 前台: http://localhost:8000/rsvp
# 後台: http://localhost:8000/admin
# phpMyAdmin: http://localhost:8080
```

### 方式二：傳統安裝

```bash
# 1. 安裝後端依賴
composer create-project laravel/laravel wedding-guest-management
cd wedding-guest-management

# 2. 安裝必要套件
composer require filament/filament:"^3.0"
composer require maatwebsite/excel
composer require barryvdh/laravel-dompdf
composer require spatie/laravel-permission

# 3. 安裝 Laravel Breeze with Inertia React
composer require laravel/breeze --dev
php artisan breeze:install react

# 4. 安裝前端依賴
npm install
npm run build

# 5. 初始化 Filament
php artisan filament:install --panels
php artisan make:filament-user

# 6. 設定環境變數
cp .env.example .env
php artisan key:generate

# 編輯 .env 設定資料庫連線
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=wedding_guest_management
DB_USERNAME=root
DB_PASSWORD=

# 7. 執行 Migration 與 Seeder
php artisan migrate --seed

# 8. 啟動開發伺服器
php artisan serve
npm run dev
```

## 資料庫結構

### guests (主賓客表)
| 欄位 | 類型 | 說明 |
|------|------|------|
| id | bigint | 主鍵 |
| invitation_code | string | 邀請碼 (選填) |
| name | string | 姓名 |
| phone | string | 電話 (唯一) |
| email | string | Email (選填) |
| invited_by | enum | 邀請方 (groom/bride/both) |
| guest_type | enum | 賓客類別 (family/colleague/friend/elder/classmate/other) |
| attendance_status | enum | 出席狀態 (attending/pending/not_attending) |
| adult_count | integer | 成人人數 |
| child_count | integer | 兒童人數 |
| infant_count | integer | 嬰幼兒人數 |
| dietary_requirement | enum | 飲食需求 (regular/vegan/ovo_lacto/special) |
| dietary_notes | text | 飲食備註 |
| special_needs | text | 特殊需求 |
| wish_message | text | 祝福留言 |
| preferred_table_mates | text | 希望同桌 |
| table_id | bigint | 桌次 ID (外鍵) |
| edit_token | string | 修改 Token (唯一) |
| is_vip | boolean | VIP 賓客 |
| tags | json | 標籤 |
| notes | text | 內部備註 |
| created_at | timestamp | 建立時間 |
| updated_at | timestamp | 更新時間 |
| deleted_at | timestamp | 軟刪除時間 |

### accompanying_guests (同行賓客表)
| 欄位 | 類型 | 說明 |
|------|------|------|
| id | bigint | 主鍵 |
| guest_id | bigint | 主賓客 ID (外鍵) |
| name | string | 姓名 |
| relationship | string | 關係 |
| age_group | enum | 年齡層 (adult/child/infant) |
| dietary_requirement | enum | 飲食需求 |
| created_at | timestamp | 建立時間 |
| updated_at | timestamp | 更新時間 |

## 使用方式

### 前台 RSVP 表單
1. 訪問 `/rsvp` 填寫回函表單
2. 完成填寫後取得專屬修改連結
3. 使用修改連結更新資料

### 後台管理
1. 訪問 `/admin` 登入管理後台
2. 查看賓客列表與統計資訊
3. 管理賓客資料、篩選、匯出

## Google Sheet 同步

請在 `.env` 設定：

```dotenv
GOOGLE_SHEETS_SPREADSHEET_ID=
GOOGLE_SHEETS_SHEET_NAME=guests
GOOGLE_SHEETS_SERVICE_ACCOUNT_CREDENTIALS_JSON=
```

手動同步指令：

```bash
docker compose exec app php artisan guests:sync-google-sheet --full
docker compose exec app php artisan guests:sync-google-sheet --guest-id=123
```

## 幸福海洋神寵功能

賓客填完 RSVP 後，系統會在成功頁面揭曉一隻以 Gemini AI 生成的專屬幸福海洋神寵，並可透過 LINE 收到神寵圖片。

### 環境變數設定

在 `.env` 中加入下列設定：

```env
# Gemini API（生成神寵圖片）
GEMINI_API_KEY=your_gemini_api_key
GEMINI_IMAGE_MODEL=gemini-2.0-flash-preview-image-generation

# LINE Messaging API（推送通知）
LINE_CHANNEL_ACCESS_TOKEN=your_line_channel_access_token
LINE_CHANNEL_SECRET=your_line_channel_secret

# 神寵池大小（選填，預設 5）
CREATURE_POOL_SIZE=5
```

### 初始化神寵池

部署後或需要補充預備神寵時執行：

```bash
# 補足池子至預設大小（讀取 CREATURE_POOL_SIZE，預設 5）
docker compose exec app php artisan creature:init-pool

# 指定數量（補足至 10 隻）
docker compose exec app php artisan creature:init-pool 10
```

此指令會計算目前池中數量，只補發不足的部分（不重複）。

### 啟動 Queue Worker

神寵圖片由 Queue Job 在背景生成，須啟動 Worker：

```bash
docker compose exec app php artisan queue:work
```

生產環境建議使用 Supervisor 管理 Worker 持續運行。

### 運作流程

1. 系統預先在池子中生成數隻神寵（`creature:init-pool`）
2. 賓客送出 RSVP → 系統自動認領最舊的池子神寵
3. 成功頁面顯示 2 秒 loading 後揭曉神寵名字與圖片
4. 賓客加 LINE 好友並傳送手機號碼或短碼完成綁定
5. 綁定成功時，LINE 自動推送神寵圖片給賓客

## 開發資訊

### LSP 錯誤說明
目前檔案中的 LSP 錯誤是因為 Laravel 套件尚未安裝。執行 `composer install` 後這些錯誤會自動消失。

### 測試資料

載入預設賓客群組（新郎／新娘方各類別，共 13 組）：

```bash
docker compose exec app php artisan db:seed --class=GuestGroupSeeder
```

載入測試賓客資料（30 筆隨機賓客）：

```bash
docker compose exec app php artisan db:seed --class=GuestSeeder
```

一次重置資料庫並執行所有 Seeder（包含 GuestGroupSeeder → GuestSeeder）：

```bash
docker compose exec app php artisan migrate:fresh --seed
```

### 開發模式
```bash
# 啟動後端伺服器
php artisan serve

# 啟動前端熱重載
npm run dev

# 佇列處理 (如需使用)
php artisan queue:work
```

## 注意事項

1. **edit_token 安全性**: edit_token 為 32 字元隨機字串，請妥善保管修改連結
2. **手機號碼唯一性**: 同一手機號碼僅能填寫一次表單
3. **資料備份**: 使用軟刪除機制，刪除的資料可復原
4. **生產環境**: 部署前請設定 `APP_ENV=production` 並執行 `php artisan optimize`

## 授權

此專案為婚禮專用系統，遵循 MIT 授權條款。

## 聯絡方式

如有任何問題，請聯繫開發團隊。

---

**專案版本**: v1.0 (Phase 1 MVP)  
**最後更新**: 2026-02-01  
**維護者**: OpenCode Team