# AGENTS.md

本檔案提供協作代理在此專案的快速上手資訊與標準操作。

## 專案摘要
- **專案名稱**: 婚禮賓客管理系統 (Wedding Guest Management System)
- **用途**: 賓客 RSVP 回函與後台管理
- **主要技術**: Laravel 11 + Filament 3 + Inertia.js + React
- **語系/時區**: 繁體中文 (zh_TW) / Asia/Taipei

## 技術棧
- 後端: PHP 8.2, Laravel 11
- 後台: Filament 3
- 前端: Inertia.js + React, Tailwind CSS
- 資料庫: MySQL 8.0
- 佇列: Laravel Queue (Database)
- 容器: Docker + Nginx + phpMyAdmin

## 重要目錄
- `app/`: Laravel 應用程式碼 (Models, Controllers, Filament)
- `database/`: Migrations, Seeders, Factories
- `resources/js/`: React 頁面與元件
- `routes/`: 路由定義
- `docker/`: Docker 與 Nginx 設定、初始化腳本
- `docs/`: 專案文件

## 快速啟動 (Docker 推薦)
```bash
docker compose up -d
docker compose exec app bash /var/www/html/docker/setup.sh
docker compose exec app php artisan make:filament-user
docker compose exec app npm run build
```

### 服務位址
- 前台: http://localhost:8000/rsvp
- 後台: http://localhost:8000/admin
- phpMyAdmin: http://localhost:8080

### 測試環境
- 前台 (RSVP 填單): https://csh-wedding-test.test7362.aiacademy.tw/rsvp
- 可在此環境進行功能測試，無需本機啟動服務

### 資料庫連線 (Docker)
- Host: `db` (容器內) / `localhost` (本機)
- Port: `3306`
- Database: `wedding_guest_management`
- Username: `wedding_user`
- Password: `password`
- Root Password: `root`

## 傳統安裝 (非 Docker)
```bash
composer install
npm install
cp .env.example .env
php artisan key:generate
php artisan migrate --seed
php artisan make:filament-user
npm run build
```

## 常用指令
```bash
# 進入容器
docker compose exec app bash

# Artisan 指令
docker compose exec app php artisan <command>

# 前端開發 (熱重載)
docker compose exec app npm run dev

# 清快取
docker compose exec app php artisan cache:clear
docker compose exec app php artisan config:clear
docker compose exec app php artisan view:clear
```

## 開發注意事項
- `edit_token` 為 32 字元修改 Token，請勿外洩。
- 手機號碼為唯一識別，重複手機不可再次填單。
- LSP 錯誤通常因未安裝套件，執行 `composer install` 後會消失。
- **Artisan 指令務必透過 Docker 執行**: `docker compose exec app php artisan <command>`，勿直接執行 `php artisan`。

## 功能索引

### 幸福海洋神寵（Ocean Pet）

賓客填完 RSVP 後，系統會在成功頁面揭曉一隻專屬的幸福海洋神寵。

**架構概述（Pool 預生成）**
- 系統預先在背景 Queue 生成神寵圖片存入 `guest_creatures` 池（`guest_id = null`）
- 賓客送出 RSVP 時，以悲觀鎖 (`lockForUpdate`) 認領最舊的一隻池子神寵
- 每認領一隻，自動補發一個 Queue Job 補充池子
- 成功頁面顯示 2 秒 spinner 後 reveal 神寵圖片（client-side，無 polling）
- LINE 綁定成功時，若該賓客已有 done 神寵，會一併推送圖片

**關鍵程式位置**
- `app/Models/GuestCreature.php` — 神寵 Model（`guest_id` 可為 null）
- `app/Services/CreatureGeneratorService.php` — 生成名字／屬性邏輯
- `app/Services/GeminiImageHelper.php` — 呼叫 Gemini API 產圖
- `app/Jobs/GenerateCreatureJob.php` — Queue Job，`guestId=null` 為 pool mode
- `app/Console/Commands/InitCreaturePool.php` — `creature:init-pool` 指令
- `app/Http/Controllers/RsvpController.php` — `claimPoolCreature()` 池子認領
- `app/Http/Controllers/Api/LineWebhookController.php` — `replyAfterBinding()` 神寵推送
- `resources/js/Pages/Rsvp/Success.jsx` — CreatureSection 揭曉動畫
- `database/migrations/..._create_guest_creatures_table.php` — 建表
- `database/migrations/..._make_guest_id_nullable_in_guest_creatures.php` — 允許 null guest_id
- `database/seeders/CreatureItemSeeder.php` — 神寵素材資料（A 類 11 項）
- `config/services.php` — `creature_pool.size`（環境變數 `CREATURE_POOL_SIZE`，預設 5）

**測試**
- `tests/Feature/GenerateCreatureJobTest.php`
- `tests/Feature/RsvpCreatureIntegrationTest.php`
- `tests/Feature/LineWebhookCreaturePushTest.php`

### RSVP URL Query 參數預填

- **功能**: RSVP 表單所有欄位可透過 URL query 參數預填，例如 `/rsvp?name=王小明&phone=0912345678&invited_by=groom`
- **後端**: `app/Http/Controllers/RsvpController.php` — `create()` 方法讀取並清理 query 參數，以 `defaults` prop 傳給 Inertia
- **前端**: `resources/js/Pages/Rsvp/Create.jsx` — 接收 `defaults` prop，初始化 `useForm()` 預設值
- **支援欄位**: `name`, `nickname`, `phone`, `email`, `invited_by`, `guest_type`, `attendance_status`, `adult_count`, `child_count`, `infant_count`, `dietary_requirement`, `dietary_notes`, `special_needs`, `wish_message`, `preferred_table_mates`