حيرة | HAYRA 🎯

منصة أسئلة جماعية بين فريقين بأجواء برامج المسابقات: شاشة عرض على التلفزيون + لوحة تحكم للمضيف على الجوال + لوحة إدارة + بنك أسئلة دائم مع مركز استيراد.

• لوحة فئات (3–8 أعمدة) وقيم 100 إلى 600، والـ 600 أسئلة عميقة فعلًا
• إجابة صحيحة، خطأ، تحويل/سرقة بوقت مستقل، إظهار الإجابة، تخطي، إعادة فتح، وتراجع Undo
• وسائل مساعدة: مضاعفة، وقت إضافي، بدون سرقة، 50/50 (مرة لكل فريق)
• سلسلة الإجابات 🔥، خانات غامضة (هدية / دبل / ذهبي ×3 / تحدٍّ)، وسؤال نهائي برهان سري
• فقرة ملك الثواني 👑: عداد يظهر لحظة ثم يختفي ويتوقف بعد مدة سرية، والفريق يقدّر المدة (هامش ±0.30 / ±0.20 / ±0.10 ثانية حسب الصعوبة)
• تحديات QR: مثّلها، ارسم، وصف بدون الكلمة، كلمة سرية، مين أنا… برمز مؤقت يُفتح على جهاز واحد ويتعطل بعد انتهاء السؤال
• تعليقات عربية مضحكة مع إيموجي وقصاصات بعد كل إجابة صحيحة، ومؤثرات صوتية مع زر كتم
• وضع متفرج للقراءة فقط، ووضع عائلي، وتقييم المضيف للأسئلة، وإحصائيات نهاية اللعبة
• مزامنة لحظية عبر Supabase Realtime مع استطلاع احتياطي، وطابور أوفلاين لجوال المضيف
• حذف الجلسة عند انتهاء اللعبة، وحذف الجلسات المهجورة تلقائيًا بعد 12 ساعة

التقنيات: Next.js 15 (App Router) + React 19 + TypeScript + Tailwind CSS + Supabase (Postgres / Auth / Realtime / Storage).

---

1) هيكل المشروع

hayra/
├── supabase/
│   ├── migrations/
│   │   ├── 001_schema.sql          الجداول
│   │   ├── 002_security.sql        RLS + Storage + Realtime
│   │   ├── 003_functions.sql       الدوال + بيانات الدخول الافتراضية
│   │   ├── 004_seed_taxonomy.sql   11 فئة + الفئات الفرعية + 8 باقات
│   │   └── 005_seed_questions.sql  362 سؤال مبدئي
│   └── seed/hayra-questions.json   نفس الأسئلة بصيغة الاستيراد (مثال للصيغة)
├── scripts/engine-selftest.ts      اختبار محرك اللعبة
└── src/
    ├── app/
    │   ├── page.tsx                الرئيسية
    │   ├── login/                  الدخول المشترك
    │   ├── packs/  how-to-play/
    │   ├── play/new/               الفرق → الإعدادات → الفئات
    │   ├── game/[id]/host|tv|watch المضيف / التلفزيون / المتفرج
    │   ├── qr/[token]/             صفحة تحدي QR
    │   ├── admin/                  لوحة الإدارة
    │   └── api/                    كل منطق السيرفر
    ├── components/                 الواجهات (game / admin / ui / site)
    └── lib/
        ├── game/                   المحرك، اختيار الأسئلة، الحالة العامة، التعليقات
        ├── importers/              OpenTDB, Quran, Wikidata, TMDB, football-data, JSON/CSV
        ├── client/                 Realtime، المؤقت، الصوت، طابور الأوفلاين
        └── supabase/               عملاء Supabase

---

2) إعداد Supabase (خطوة بخطوة)

1. أنشئ مشروعًا جديدًا على https://supabase.com
2. افتح SQL Editor وشغّل الملفات بالترتيب، كل ملف بشكل منفصل: 001_schema.sql ← 002_security.sql ← 003_functions.sql ← 004_seed_taxonomy.sql ← 005_seed_questions.sql ← 006_question_modes.sql ← 007_grants.sql
3. إنشاء حساب المشرف: من Authentication → Users → Add user، أضف بريدك وكلمة مرور وفعّل Auto Confirm.
4. ثم شغّل في SQL Editor (غيّر البريد):

   insert into public.admins (user_id)
   select id from auth.users where email = '[email protected]';
   

5. من Project Settings → API انسخ:
   • Project URL
   • anon public key
   • service_role key (سري)
6. (اختياري) الحذف التلقائي كل ساعة: فعّل pg_cron من Database → Extensions ثم شغّل:

   select cron.schedule('hayra-cleanup', '0 * * * *', $$select public.cleanup_expired()$$);
   

   بدون هذه الخطوة، السيرفر ينظّف الجلسات المنتهية تلقائيًا عند إنشاء كل لعبة جديدة.

ملاحظة: الـ Realtime وbucket الصور media يُفعَّلان تلقائيًا من 002_security.sql.

---

3) التشغيل على جهازك

npm install
cp .env.example .env.local      # ثم عبّئ القيم
npm run dev                     # http://localhost:3000

لتوليد ACCESS_JWT_SECRET:

node -e "console.log(require('crypto').randomBytes(48).toString('base64url'))"

المتغير	الوصف
NEXT_PUBLIC_SUPABASE_URL	رابط مشروع Supabase
NEXT_PUBLIC_SUPABASE_ANON_KEY	المفتاح العام
SUPABASE_SERVICE_ROLE_KEY	سري — للسيرفر فقط، لا تضعه في متغير يبدأ بـ NEXT_PUBLIC
ACCESS_JWT_SECRET	32 حرفًا أو أكثر لتوقيع كوكي الدخول
NEXT_PUBLIC_SITE_URL	رابط الموقع بعد النشر
TMDB_API_TOKEN	اختياري — لاستيراد TMDB
FOOTBALL_DATA_API_KEY	اختياري — لاستيراد football-data.org

الفحوصات:

npm run typecheck
npm run test:engine
npm run build

---

4) ⚠️ أول شيء بعد التشغيل

بيانات الدخول الافتراضية للعب:

• Access Code: HAYRA
• Password: hayra2026

غيّرها فورًا من /admin → بيانات الدخول. التغيير يسجّل خروج كل الأجهزة.

---

5) النشر على Vercel

المشروع يحتاج Node API Routes، لذلك يُنشر على Vercel (وليس Cloudflare Pages static).

1. ارفع المشروع على GitHub (القسم التالي).
2. من https://vercel.com اختر Add New → Project واختر المستودع.
3. أضف متغيرات البيئة من الجدول السابق في Environment Variables.
4. اضغط Deploy.
5. في Supabase افتح Authentication → URL Configuration وضع رابط Vercel في Site URL.

استيراد القرآن يحمّل ملفًا حجمه ~19MB. خطة Vercel المجانية تسمح بـ 60 ثانية، والمسار مضبوط على maxDuration = 60. إذا انتهت المهلة، قلّل «عدد الأسئلة لكل نوع».

---

6) الرفع على GitHub

cd hayra
git init
git add .
git commit -m "Hayra trivia platform"
git branch -M main
git remote add origin https://github.com/USERNAME/hayra.git
git push -u origin main

ملف .gitignore يستثني .env.local وnode_modules و.next. تأكد أنك لا ترفع أي مفاتيح.

---

7) كيف تلعب

1. سجّل الدخول من الجوال، ثم ابدأ لعبة أو باقات جاهزة.
2. أسماء الفرق ← الإعدادات ← الفئات ← ابدأ اللعبة.
3. تفتح لوحة المضيف ونافذة ربط الشاشات. امسح رمز «📺 التلفزيون» من جهاز العرض (لا يحتاج تسجيل دخول) واضغط «اضغط للبدء» لتفعيل الصوت.
4. المضيف يختار الخانة، ويرى الإجابة على جواله فقط، ثم يحكم: صح / خطأ / تحويل / إظهار.
5. عند تحديث صفحة المضيف تكمل اللعبة من مكانها، ويظهر زر «استئناف» في الرئيسية.
6. في النهاية: «لعبة جديدة» أو «العودة للرئيسية»، وكلاهما يحذف الجلسة نهائيًا.

---

8) بنك الأسئلة ومركز الاستيراد

• مصدر اللعب هو قاعدة بيانات حيرة فقط. المصادر الخارجية للاستيراد وليست للعرض المباشر.
• كل ما يُستورد من API خارجي يدخل غير مفعّل وغير موثّق. راجعه من بنك الأسئلة، مع فلتر «دفعة الاستيراد» أو وسم «يحتاج ترجمة»، ثم فعّله أو وثّقه دفعة واحدة.
• المصادر المتاحة:

المصدر	ماذا يولّد	مفتاح؟
JSON / CSV	أسئلتك أو باقات إسلامية مراجعة	لا
Quran Core Dataset (mjmirza)	في أي سورة، أكمل الآية، عدد الآيات، السورة التالية، الجزء، مكية/مدنية	لا
Wikidata SPARQL	عواصم، أعلام (صور)، عملات بأسماء عربية	لا
Open Trivia DB	أسئلة إنجليزية تحتاج ترجمة	لا
TMDB	بوسترات وسنوات المسلسلات والأفلام العربية	نعم
football-data.org	ملاعب، سنة التأسيس، شعارات، أبطال المواسم	نعم

• صيغة JSON: انظر supabase/seed/hayra-questions.json. الحقول الأساسية: category (slug أو الاسم العربي)، subcategory، type، question_text، answer، difficulty (1–6)، إضافة لحقول اختيارية مثل choices، clues، extra، image_url، source، reference، tags، family_safe، verified.
• صيغة CSV: حمّل القالب من مركز الاستيراد. القوائم تُفصل بـ |.
• الاستيراد المكرر لا يُنشئ نسخًا مكررة، بفضل القيد unique(import_source, external_id).
• لوحة الإدارة → الرئيسية تعرض مصفوفة تغطية لكل فئة × مستوى، لتعرف أين تنقص الأسئلة.

⚠️ مراجعة الأسئلة المبدئية

• الأسئلة المكتوبة يدويًا (hayra-seed) محفوظة غير موثّقة. راجعها، خصوصًا الإسلاميات، ثم وثّقها.
• أسئلة القرآن البنيوية المولّدة من البيانات موثّقة، ما عدا «مكية/مدنية» لأن فيها خلافًا في بعض السور.
• خيار «الموثّق فقط» في إعدادات اللعبة يمنع ظهور أي سؤال غير موثّق.

---

9) الأمان

• كلمة المرور المشتركة محفوظة كـ bcrypt hash داخل Postgres (pgcrypto)، والتحقق يتم في السيرفر فقط، مع تأخير عند الفشل.
• كوكي الدخول httpOnly موقّع (JWT)، ويُبطَل عند تغيير البيانات من لوحة الإدارة.
• RLS مفعّل على كل الجداول. جداول الجلسات والرموز لا يصلها إلا السيرفر، بينما التلفزيون يقرأ نسخة عامة بدون إجابات حتى تُكشف.
• التحكم باللعبة يتطلب مفتاح مضيف عشوائيًا (يُخزَّن كـ SHA-256)، ويُرسل في الهيدر x-host-key.
• رمز QR لا يحتوي الإجابة، ويُربط بالجلسة والسؤال وبجهاز واحد، ويتعطل بانتهاء السؤال.
• لوحة الإدارة: Supabase Auth + جدول admins، والتحقق يتم في الـ middleware وفي الصفحة وعبر RLS.
• مفتاح service_role لا يُستخدم إلا داخل API Routes.

---

10) حل المشاكل

المشكلة	الحل
«لا توجد أسئلة كافية»	اختر فئات أخرى، أو ألغِ «الموثّق فقط»، أو فعّل أسئلة من البنك
التلفزيون لا يتحدث لحظيًا	تأكد أن 002_security.sql نُفّذ. يوجد تحديث احتياطي كل 4 ثوانٍ
لا يوجد صوت على التلفزيون	اضغط «اضغط للبدء» مرة واحدة، لأن المتصفح يمنع الصوت قبل أول تفاعل
«هذا الحساب ليس مشرفًا»	نفّذ أمر insert into public.admins من الخطوة 2
رمز QR فُتح على جهاز خطأ	من لوحة المضيف اضغط «📱 إعادة ضبط QR»