football-next/QUIZ_FEATURE_GUIDE.md

📋 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

# 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 تست کن

---

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