# 📋 Daily Quiz & Golden Card Lottery - راهنمای پیاده‌سازی

این فیچر شامل **کوییز روزانه** و **قرعه‌کشی Golden Card** برای بازی فانتزی فوتبال است.

---

## 🗂️ ساختار فایل‌ها

### Database Schema
- `prisma/schema.prisma` - مدل‌های جدید:
  - `DailyQuiz` - کوییز روزانه
  - `QuizQuestion` - سوالات کوییز
  - `QuizSubmission` - پاسخ‌های کاربران
  - `GoldenCard` - کارت‌های طلایی
  - `Player.isGoldenCardEligible` - فیلد جدید

### API Routes
**Admin:**
- `app/api/admin/quiz/route.ts` - لیست و ایجاد کوییز
- `app/api/admin/quiz/[id]/lottery/route.ts` - اجرای قرعه‌کشی
- `app/api/admin/players/[id]/golden-toggle/route.ts` - فعال/غیرفعال کردن Golden Card

**User:**
- `app/api/quiz/route.ts` - دریافت کوییز امروز
- `app/api/quiz/submit/route.ts` - ارسال پاسخ‌ها
- `app/api/quiz/my-results/route.ts` - تاریخچه نتایج
- `app/api/golden-cards/route.ts` - لیست کارت‌های کاربر
- `app/api/golden-cards/[id]/reveal/route.ts` - باز کردن کارت

### Admin Panel
- `app/(admin)/admin/quiz/page.tsx` - لیست کوییزها
- `app/(admin)/admin/quiz/new/page.tsx` - ایجاد کوییز جدید
- `app/(admin)/admin/quiz/QuizForm.tsx` - فرم ایجاد کوییز
- `app/(admin)/admin/quiz/LotteryButton.tsx` - دکمه قرعه‌کشی
- `app/(admin)/admin/quiz/[id]/results/page.tsx` - نتایج و برندگان
- `app/(admin)/admin/players/GoldenToggle.tsx` - تاگل Golden Card

### User Pages
- `app/(user)/quiz/page.tsx` - صفحه کوییز روزانه
- `app/(user)/quiz/DailyQuizClient.tsx` - UI کوییز با countdown
- `app/(user)/quiz/history/page.tsx` - تاریخچه شرکت در کوییزها
- `app/(user)/golden-cards/page.tsx` - صفحه Golden Cards
- `app/(user)/golden-cards/GoldenCardsClient.tsx` - UI باز کردن کارت‌ها

---

## 🚀 مراحل راه‌اندازی

### 1. Database Migration
```bash
# Generate Prisma Client
npm run db:generate

# Push schema to database
npm run db:push
```

### 2. تنظیم بازیکنان Golden Card
1. به پنل ادمین برو: `/admin/players`
2. برای بازیکنان برتر، تاگل **Golden Card** رو فعال کن
3. حداقل 5-10 بازیکن رو فعال کن

### 3. ایجاد کوییز روزانه
1. برو به `/admin/quiz`
2. کلیک روی **+ کوییز جدید**
3. تاریخ، بازه زمانی (مثلاً 18:00 تا 21:00)، و تعداد برندگان رو وارد کن
4. سوالات رو اضافه کن (حداقل 5 سوال)
5. گزینه صحیح رو با دایره انتخاب کن
6. ذخیره کن

### 4. شرکت کاربران
- کاربران به `/quiz` می‌رن
- در بازه زمانی مشخص شده، به سوالات پاسخ می‌دن
- countdown timer نمایش داده می‌شه
- بعد از ارسال، نمره نمایش داده می‌شه

### 5. اجرای قرعه‌کشی
1. برو به `/admin/quiz`
2. روی دکمه **قرعه‌کشی** کلیک کن
3. سیستم:
   - همه کاربران با نمره 100% رو پیدا می‌کنه
   - به صورت تصادفی تعداد مشخص شده رو انتخاب می‌کنه
   - به هر برنده یک **Sealed Golden Card** می‌ده
4. نتایج در `/admin/quiz/[id]/results` نمایش داده می‌شه

### 6. باز کردن کارت‌ها
- کاربران به `/golden-cards` می‌رن
- روی کارت مهر شده کلیک می‌کنن
- انیمیشن unboxing نمایش داده می‌شه
- بازیکن تصادفی reveal می‌شه

---

## 🎨 UI Features

### Dark Mode + Glassmorphism
- پس‌زمینه: `bg-gray-950`
- کارت‌ها: `bg-white/5 backdrop-blur border border-white/10`
- Gradient buttons: `bg-gradient-to-r from-yellow-500 to-amber-500`
- Neon accents برای Golden Cards

### Countdown Timer
- نمایش ساعت، دقیقه، ثانیه
- استایل glassmorphism
- Auto-refresh هر ثانیه

### Unboxing Animation
- کارت مهر شده با icon 🎴
- Pulse animation
- Modal reveal با bounce effect
- Gradient border بر اساس پست بازیکن

---

## 📊 Business Logic

### امتیازدهی
- هر سوال: 1 امتیاز
- نمره نهایی: درصد (0-100)
- فقط نمره 100% واجد شرایط قرعه‌کشی

### قرعه‌کشی
- فیلتر: `score = 100`
- انتخاب تصادفی: `winnersCount` نفر
- هر برنده: 1 Golden Card (بازیکن تصادفی از لیست eligible)

### Golden Card Status
- `SEALED`: مهر شده، بازیکن مخفی
- `OPENED`: باز شده، بازیکن نمایش داده می‌شه

---

## 🔐 Security

### Authorization
- Admin routes: `requireAdmin()` middleware
- User routes: `requireAuth()` middleware
- API routes: `getServerSession()` check

### Validation
- Time window check در submit
- Duplicate submission prevention
- Correct answer محافظت شده (فقط server-side)

---

## 🧪 Testing Checklist

- [ ] ایجاد کوییز توسط ادمین
- [ ] نمایش کوییز در بازه زمانی
- [ ] countdown timer صحیح کار می‌کنه
- [ ] ارسال پاسخ‌ها
- [ ] محاسبه نمره صحیح
- [ ] جلوگیری از ارسال مجدد
- [ ] اجرای قرعه‌کشی
- [ ] دریافت Golden Card
- [ ] باز کردن کارت
- [ ] نمایش تاریخچه
- [ ] toggle Golden Card در admin

---

## 🎯 Next Steps (Optional Enhancements)

1. **Cron Job**: قرعه‌کشی خودکار هر شب
2. **Notifications**: اطلاع‌رسانی به برندگان
3. **Leaderboard**: جدول برترین شرکت‌کنندگان
4. **Streak System**: پاداش برای شرکت مداوم
5. **Lottie Animations**: انیمیشن‌های پیشرفته‌تر
6. **Sound Effects**: صدا برای unboxing
7. **Social Share**: اشتراک‌گذاری نتایج
8. **Quiz Categories**: دسته‌بندی سوالات

---

## 📞 Support

در صورت بروز مشکل:
1. لاگ‌های console رو چک کن
2. Prisma Studio رو باز کن: `npm run db:studio`
3. دیتابیس رو بررسی کن
4. API routes رو با Postman تست کن

---

**✅ فیچر آماده استفاده است!**