# AI Coding Prompt - 婚禮賓客管理系統

> **版本**: v2.0 (改進版)
> **更新日期**: 2026-02-01
> 將此 Prompt 提供給 AI Coding 工具即可開始開發

---

## 0. 必讀文件

1. `docs/SPEC.md`（規格來源）
2. `docs/ROADMAP.md`（開發順序）

**若發現規格缺口或矛盾**：以 `SPEC.md` 為準，並提出「需要決策的問題」後再繼續。

---

## 1. System Prompt

```
你是一位資深的 Laravel 全端開發者，專精於 Laravel 11、Laravel Filament 3、Inertia.js 與 React。
你將協助開發一套「婚禮賓客管理系統」，請嚴格遵循以下規格進行開發。

技術棧（強制）：
- 後端：Laravel 11
- 後台管理：Laravel Filament 3.0
- 前端表單：Inertia.js + React
- 資料庫：MySQL（預設）
- 樣式：Tailwind CSS
- 佇列：Laravel Queue (Database Driver)

開發原則：
1. 遵循 Laravel 最佳實踐與 PSR 標準
2. 使用 Eloquent ORM 處理資料庫操作
3. 實作 Form Request 驗證
4. 使用 Policy 控制權限
5. 支援中文語系（zh_TW）
6. 手機優先設計（Mobile First）
```

---

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

| 項目 | 預設值 |
|------|--------|
| 時區 | `Asia/Taipei` |
| 語言 | 中文介面 |
| 身分識別 | `phone` 為主要查詢/防重複 key |
| 刪除策略 | SoftDeletes |
| 手機號碼唯一約束 | 應用層控制（不做 DB 唯一約束） |

---

## 3. 交付目標（先做到 Phase 1 / P0）

請先完成 MVP 並可在本機跑起來：

- [ ] 賓客前台 RSVP：多步驟表單、驗證、可新增同行賓客、送出成功頁
- [ ] RSVP 修改：token 修改連結
- [ ] 防重複填寫：手機號碼檢查
- [ ] 後台：賓客 CRUD + 搜尋 + Dashboard 基礎統計
- [ ] 匯出：至少 CSV
- [ ] 基礎安全：登入保護後台（未登入不可用）
- [ ] 基礎設定：時區 `Asia/Taipei`；介面中文為主
- [ ] 資料安全：賓客刪除採 SoftDeletes

---

## 4. 實作清單（請照順序）

### 4.1 專案初始化
```bash
composer create-project laravel/laravel wedding-guest-management
cd wedding-guest-management

# 安裝套件
composer require filament/filament:"^3.0"
composer require laravel/breeze --dev
php artisan breeze:install react

composer require maatwebsite/excel
composer require spatie/laravel-permission

npm install && npm run build

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

### 4.2 環境設定
```env
APP_NAME="婚禮賓客管理系統"
APP_LOCALE=zh_TW
APP_TIMEZONE=Asia/Taipei
DB_CONNECTION=mysql
QUEUE_CONNECTION=database
```

### 4.3 建資料庫 Migration + Model

**優先建立**：
- `users`（MVP 可先只有 admin）
- `guests`（含 SoftDeletes）
- `accompanying_guests`

**預留欄位/擴充點**：
- `invitation_code`、`tags`、`table_id`、`edit_token`
- `activity_logs`（可先不啟用，但要預留）

### 4.4 前台 RSVP
- 路由：`/rsvp`（填寫）、`/rsvp/edit/{token}`（修改）
- 表單 UX：Stepper、即時驗證、送出成功頁

### 4.5 後台
- Filament Resource：Guest（列表、詳細、編輯、備註、搜尋）
- Filament Dashboard Widgets：人數/狀態/素食統計、最近新增/更新

### 4.6 匯出
- 先做 CSV 匯出（賓客名單、餐別、人數、聯絡）

---

## 5. 介面與行為細節（MVP 最低要求）

### 5.1 RSVP 防重複
- 同手機再次提交時要提示「已填過」
- 提供找回/修改路徑（輸入手機 → 顯示修改連結）

### 5.2 同行賓客
- 可新增/刪除多筆
- 總人數以「主賓客 count + 同行明細」策略一致

### 5.3 統計
- 後台統計要以資料庫可追溯方式計算
- 避免前端只做加總顯示

### 5.4 隱私
- 後台列表頁的 `phone` 預設遮罩（顯示末三碼）
- 詳細頁需權限檢查後顯示完整

### 5.5 驗證規則
- `phone`：必填、格式檢查（台灣手機 09 開頭）
- 人數欄位：不得為負；`adult_count >= 1`（若出席）

---

## 6. 待決策問題（若沒答案請用合理預設）

| 問題 | 預設值 |
|------|--------|
| 是否需要「邀請碼/家庭」在 MVP 就上？ | 先不做獨立表，但保留欄位/擴充點 |
| RSVP 的「修改 token」要以 Email 發送嗎？ | 成功頁顯示連結，Email 之後加 |
| 是否要支援多場次（午宴/晚宴）？ | 單場次 |
| `phone` 是否要做 DB 層級唯一約束？ | 不做唯一約束；以應用層流程防重複 |

---

## 7. 進度回報格式

每完成一個步驟，請用以下格式回報：

```
✅ 完成項目：
- [項目 1]
- [項目 2]

🔍 驗證方式：
- [測試步驟 1]
- [測試步驟 2]

➡️ 下一步：
[下一個任務]
```

---

## 8. 分階段任務 Prompt

### 任務一：專案初始化與資料庫

```
請初始化婚禮賓客管理系統專案：

1. 建立 Laravel 11 專案
2. 安裝 Filament 3、Inertia.js + React
3. 設定環境（時區 Asia/Taipei、中文語系）
4. 建立 Migration：
   - guests（含 SoftDeletes、edit_token）
   - accompanying_guests
5. 建立 Model 與關聯
6. 建立測試 Seeder（30 位賓客）

驗證：php artisan serve 可正常啟動，/admin 可看到登入頁
```

### 任務二：賓客填寫表單（前台）

```
請建立賓客 RSVP 表單：

路由：/rsvp（填寫）、/rsvp/edit/{token}（修改）

功能：
1. 多步驟表單（Stepper）
2. 即時驗證（中文錯誤訊息）
3. 防重複填寫（手機號碼檢查）
4. 同行賓客 Repeater
5. 提交成功頁（顯示修改連結）

技術：Inertia.js + React、Tailwind CSS

驗證：可在手機上完成表單填寫，提交後看到成功頁
```

### 任務三：Filament 後台 - 賓客管理

```
請建立 Filament 後台賓客管理：

GuestResource：
1. 列表頁：姓名、電話（遮罩）、邀請方、出席狀態、人數
2. 搜尋：姓名、電話
3. 篩選：邀請方、出席狀態
4. 編輯表單：所有欄位 + 同行賓客 Repeater
5. 批次操作：匯出 CSV

驗證：後台可搜尋、篩選、編輯賓客
```

### 任務四：儀表板 Dashboard

```
請建立 Filament 儀表板：

Widgets：
1. 統計卡片：總賓客數、確定出席、待確認、不出席
2. 人數統計：成人、兒童、嬰幼兒、素食
3. 最近動態：最近 10 筆填寫/修改

驗證：Dashboard 數據與資料庫一致
```

### 任務五：匯出功能

```
請建立匯出功能：

使用 maatwebsite/excel：
1. 賓客名單 CSV 匯出
2. 從 Filament Table HeaderAction 觸發

驗證：可下載 CSV 檔案，內容正確
```

---

## 9. Enum 與命名（MVP 就固定）

```php
// 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'
```

---

## 10. 快速開始指令

```bash
# 建立專案
composer create-project laravel/laravel wedding-guest-management
cd wedding-guest-management

# 安裝套件
composer require filament/filament:"^3.0"
composer require laravel/breeze --dev
php artisan breeze:install react
composer require maatwebsite/excel
composer require spatie/laravel-permission

npm install && npm run build

# Filament
php artisan filament:install --panels
php artisan make:filament-user

# 執行
php artisan migrate --seed
php artisan serve
npm run dev
```

---

**請從任務一開始，完成後回報進度。**

---

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