# 📋 Daily Quiz & Golden Card Lottery

## 🎯 Overview

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

### چرا این فیچر؟
- 🎮 **Engagement**: کاربران قبل از شروع تورنمنت فعال می‌مونن
- 🏆 **Gamification**: سیستم پاداش و قرعه‌کشی
- 💎 **Exclusive Rewards**: کارت‌های طلایی بازیکنان برتر
- 📊 **Data Collection**: اطلاعات از علاقه‌مندی کاربران

---

## ⚡ Quick Start

### Windows:
```bash
RUN_QUIZ_FEATURE.bat
```

### Linux/Mac:
```bash
chmod +x RUN_QUIZ_FEATURE.sh
./RUN_QUIZ_FEATURE.sh
```

### Manual:
```bash
npm run db:generate
npm run db:push
npm run seed:quiz
npm run dev
```

---

## 📸 Screenshots

### User Flow:
1. **Daily Quiz** (`/quiz`) - کوییز با countdown timer
2. **Quiz History** (`/quiz/history`) - تاریخچه شرکت
3. **Golden Cards** (`/golden-cards`) - کارت‌های دریافتی
4. **Unboxing** - انیمیشن باز کردن کارت

### Admin Flow:
1. **Quiz List** (`/admin/quiz`) - لیست کوییزها
2. **Create Quiz** (`/admin/quiz/new`) - ایجاد کوییز
3. **Results** (`/admin/quiz/[id]/results`) - نتایج و برندگان
4. **Players** (`/admin/players`) - تنظیم Golden Card

---

## 🎨 Features

### ✅ User Features
- کوییز روزانه با بازه زمانی
- Countdown timer real-time
- سوالات چند گزینه‌ای
- نمایش نتیجه فوری
- تاریخچه شرکت
- کارت‌های طلایی
- Unboxing animation

### ✅ Admin Features
- ایجاد کوییز روزانه
- افزودن سوالات نامحدود
- تنظیم بازه زمانی
- اجرای قرعه‌کشی
- مشاهده برندگان
- تنظیم Golden Card eligible

### ✅ UI/UX
- Dark mode
- Glassmorphism effects
- Gradient buttons
- Neon glow
- Smooth animations
- Responsive design

---

## 📚 Documentation

| File | Description |
|------|-------------|
| `QUIZ_QUICKSTART.md` | راهنمای شروع سریع |
| `QUIZ_FEATURE_GUIDE.md` | مستندات کامل فیچر |
| `IMPLEMENTATION_SUMMARY.md` | جزئیات فنی پیاده‌سازی |
| `FEATURES.md` | لیست کامل فیچرها |

---

## 🗂️ File Structure

```
📁 Database
  └── prisma/schema.prisma (4 new models)

📁 API Routes (8 endpoints)
  ├── /api/quiz
  ├── /api/quiz/submit
  ├── /api/quiz/my-results
  ├── /api/golden-cards
  ├── /api/golden-cards/[id]/reveal
  ├── /api/admin/quiz
  ├── /api/admin/quiz/[id]/lottery
  └── /api/admin/players/[id]/golden-toggle

📁 Admin Panel (7 components)
  ├── /admin/quiz
  ├── /admin/quiz/new
  ├── /admin/quiz/[id]/results
  └── Components: QuizForm, LotteryButton, GoldenToggle

📁 User Pages (5 components)
  ├── /quiz
  ├── /quiz/history
  ├── /golden-cards
  └── Components: DailyQuizClient, GoldenCardsClient

📁 Scripts
  └── scripts/seed-quiz-sample.ts
```

---

## 🔧 Tech Stack

- **Framework**: Next.js 16 (App Router)
- **Database**: PostgreSQL + Prisma
- **Auth**: NextAuth v4
- **Styling**: Tailwind CSS v4
- **Language**: TypeScript

---

## 🎯 How It Works

### 1️⃣ Admin Creates Quiz
```
Admin → /admin/quiz/new
  ├── Set date & time window
  ├── Add questions (unlimited)
  ├── Mark correct answers
  └── Set winners count
```

### 2️⃣ Users Participate
```
User → /quiz
  ├── See countdown timer
  ├── Answer questions
  ├── Submit answers
  └── Get score (0-100%)
```

### 3️⃣ Lottery Execution
```
Admin → /admin/quiz → Run Lottery
  ├── Filter 100% scores
  ├── Random selection
  ├── Assign sealed cards
  └── View winners
```

### 4️⃣ Card Reveal
```
User → /golden-cards
  ├── See sealed cards
  ├── Click to open
  ├── Animation plays
  └── Player revealed
```

---

## 🔒 Security

- ✅ Admin-only routes
- ✅ User authentication
- ✅ Time window validation
- ✅ Duplicate prevention
- ✅ Server-side scoring
- ✅ Ownership validation

---

## 📊 Database Models

### DailyQuiz
```prisma
- id, date, windowStart, windowEnd
- winnersCount, isProcessed
- questions[], submissions[]
```

### QuizQuestion
```prisma
- id, quizId, questionText
- options[], correctAnswer, order
```

### QuizSubmission
```prisma
- id, userId, quizId
- answers[], score, submittedAt
- Unique: [userId, quizId]
```

### GoldenCard
```prisma
- id, userId, playerId
- status (SEALED/OPENED)
- acquiredDate, openedAt
```

---

## 🧪 Testing

### Test Scenario:
1. ✅ Create quiz as admin
2. ✅ Submit 100% as user
3. ✅ Run lottery as admin
4. ✅ Receive sealed card
5. ✅ Open card as user
6. ✅ View revealed player

### Edge Cases:
- ✅ Outside time window
- ✅ Duplicate submission
- ✅ No eligible players
- ✅ No perfect scores
- ✅ Already opened card

---

## 🚀 Deployment

### Environment Variables
```env
DATABASE_URL="postgresql://..."
NEXTAUTH_SECRET="..."
NEXTAUTH_URL="http://localhost:3000"
```

### Build
```bash
npm run build
npm start
```

### Vercel
```bash
vercel deploy
```

---

## 📈 Future Enhancements

- [ ] Cron job for auto-lottery
- [ ] Email notifications
- [ ] Push notifications
- [ ] Quiz categories
- [ ] Difficulty levels
- [ ] Streak rewards
- [ ] Social sharing
- [ ] Lottie animations
- [ ] Sound effects
- [ ] Analytics dashboard

---

## 🐛 Troubleshooting

### Quiz not showing?
- Check time window
- Verify date is today
- Check database connection

### Lottery not working?
- Ensure eligible players exist
- Check for 100% submissions
- Verify admin permissions

### Card not opening?
- Check user authentication
- Verify card status is SEALED
- Check player data exists

---

## 📞 Support

For issues or questions:
1. Check documentation files
2. Review `IMPLEMENTATION_SUMMARY.md`
3. Open Prisma Studio: `npm run db:studio`
4. Check browser console
5. Review API logs

---

## ✨ Credits

**Implemented by**: Kiro AI Assistant
**Date**: 2026
**Version**: 1.0.0
**Status**: ✅ Production Ready

---

## 📝 License

Part of Fantasy Football Web Application

---

**🎉 Enjoy the feature!**

For detailed documentation, see `QUIZ_FEATURE_GUIDE.md`