Files

DrMesta103 9c30295b4b io

2026-05-03 17:01:46 +03:30

6.4 KiB

Raw Blame History

📋 Daily Quiz & Golden Card Lottery

🎯 Overview

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

چرا این فیچر؟

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

⚡ Quick Start

Windows:

RUN_QUIZ_FEATURE.bat

Linux/Mac:

chmod +x RUN_QUIZ_FEATURE.sh
./RUN_QUIZ_FEATURE.sh

Manual:

npm run db:generate
npm run db:push
npm run seed:quiz
npm run dev

📸 Screenshots

User Flow:

Daily Quiz (/quiz) - کوییز با countdown timer
Quiz History (/quiz/history) - تاریخچه شرکت
Golden Cards (/golden-cards) - کارت‌های دریافتی
Unboxing - انیمیشن باز کردن کارت

Admin Flow:

Quiz List (/admin/quiz) - لیست کوییزها
Create Quiz (/admin/quiz/new) - ایجاد کوییز
Results (/admin/quiz/[id]/results) - نتایج و برندگان
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

- id, date, windowStart, windowEnd
- winnersCount, isProcessed
- questions[], submissions[]

QuizQuestion

- id, quizId, questionText
- options[], correctAnswer, order

QuizSubmission

- id, userId, quizId
- answers[], score, submittedAt
- Unique: [userId, quizId]

GoldenCard

- id, userId, playerId
- status (SEALED/OPENED)
- acquiredDate, openedAt

🧪 Testing

Test Scenario:

✅ Create quiz as admin
✅ Submit 100% as user
✅ Run lottery as admin
✅ Receive sealed card
✅ Open card as user
✅ View revealed player

Edge Cases:

✅ Outside time window
✅ Duplicate submission
✅ No eligible players
✅ No perfect scores
✅ Already opened card

🚀 Deployment

Environment Variables

DATABASE_URL="postgresql://..."
NEXTAUTH_SECRET="..."
NEXTAUTH_URL="http://localhost:3000"

Build

npm run build
npm start

Vercel

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:

Check documentation files
Review IMPLEMENTATION_SUMMARY.md
Open Prisma Studio: npm run db:studio
Check browser console
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

6.4 KiB Raw Blame History Unescape Escape