187 lines
6.3 KiB
Markdown
187 lines
6.3 KiB
Markdown
# 📋 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 تست کن
|
|
|
|
---
|
|
|
|
**✅ فیچر آماده استفاده است!**
|