324 lines
6.4 KiB
Markdown
324 lines
6.4 KiB
Markdown
# 📋 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`
|