Discord Bot Master Template

بوت ديسكورد احترافي متكامل — إدارة، تذاكر دعم، موسيقى، بناء Embeds، نظام لوقز شامل (30+ نوع حدث)، وداشبورد ويب كامل لإدارة كل شي بدون كتابة أوامر. كل الإعدادات محفوظة بـ MongoDB لكل سيرفر لحاله، وقابلة للتعديل من /setup بديسكورد أو من الداشبورد — نفس البيانات، نفس اللحظة.

المحتويات

• الميزات
• التشغيل لأول مرة
• إعداد الداشبورد (OAuth2)
• الأوامر المتاحة
• صفحات الداشبورد
• نظام اللوقز الكامل
• هيكلية المشروع
• النشر على Render
• ملاحظات أمان مهمة
• Checklist لكل عميل جديد

---

الميزات

الإدارة (Moderation) kick / ban / mute (timeout) / warn، مع سجل تحذيرات لكل عضو محفوظ بقاعدة البيانات.

قناة الفخ (Trap Channel) قناة تحددها — أي حدا (غير الأدمن/رول المشرفين) يكتب فيها، بينحظر فوراً ويتحذف كل رسائله بآخر 7 أيام من كل السيرفر تلقائياً (أقصى مدة يدعمها ديسكورد للحذف الجماعي عند الحظر).

نظام التذاكر (Tickets) لوحة "🎫 فتح تذكرة" بزر، Private Thread لكل تذكرة، مطالبة/استدعاء/إغلاق، حفظ transcript كامل بقناة اللوق عند الإغلاق، وحذف تلقائي للثريد بعد 24 ساعة.

الموسيقى (Music) تشغيل من يوتيوب/SoundCloud/سبوتيفاي (رابط أو بحث)، لوحة تحكم بأزرار تتعدل بمكانها (مش سبام رسائل)، قائمة انتظار بصفحات، تكرار (أغنية/قائمة)، وتبديل تلقائي لـ SoundCloud لو يوتيوب رفض التشغيل (مشكلة حماية-البوتات المعروفة). التفاصيل التقنية موثقة جوا utils/music_source.py و utils/music_player.py.

Embed Builder احترافي بناء Embed كامل التخصيص (عنوان، وصف، لون، صورة، حقول، إلخ) من الداشبورد مع معاينة حية، أو أمر /embed quick بديسكورد مباشرة. يُحفظ كـ "draft" وينبعت لأي قناة وقت ما بدك.

قوالب الرسائل (Message Templates) اربط أي embed محفوظ ليكون شكل رسالة الترحيب أو بانر التذاكر — بدل الشكل الافتراضي، بمتغيرات ديناميكية زي {member} و {guild}.

الفاصل التلقائي (Auto Divider) صورة تحددها من الداشبورد تنبعث تلقائياً بعد أي رسالة بقنوات تختارها — كملف مرفق نظيف بدون أي إطار Embed.

الذكاء الاصطناعي أمر /ask متصل بـ OpenRouter (نموذج قابل للتغيير من .env)، يشتغل بقناة واحدة تحددها بس.

نظام لوقز شامل (30+ نوع حدث) كل نوع حدث بقناته وبلونه الخاص، منفصلين عن بعض بالكامل — شوف نظام اللوقز الكامل.

داشبورد ويب كامل تسجيل دخول عبر Discord OAuth2، وإدارة كل شي أعلاه بدون كتابة أوامر — شوف صفحات الداشبورد.

---

التشغيل لأول مرة

1. ثبّت Python 3.11+ إذا مو موجود.
2. أنشئ بيئة افتراضية (اختياري بس موصى به):

   python -m venv venv
   source venv/bin/activate   # ماك/لينكس
   venv\Scripts\activate      # ويندوز
   

3. ثبّت المكتبات:

   pip install -r requirements.txt
   

4. انسخ .env.example باسم .env واملأ القيم (Token، MongoDB URI، بيانات OAuth2 للداشبورد...).
5. شغّل البوت:

   cd src
   python main.py
   

إعداد الداشبورد (OAuth2)

الداشبورد يحتاج تطبيق Discord مسجّل بـ developer portal:

1. من صفحة تطبيقك → OAuth2 → General: خذ Client ID و Client Secret.
2. بنفس الصفحة، تحت Redirects، ضيف رابط بالشكل: https://your-domain.com/callback (لو محلي: http://localhost:8080/callback).
3. حط نفس القيم بـ .env:

   DISCORD_CLIENT_ID=...
   DISCORD_CLIENT_SECRET=...
   REDIRECT_URI=https://your-domain.com/callback
   DASHBOARD_SECRET_KEY=...   # أي نص عشوائي طويل، يستخدم لتشفير الجلسة
   

4. الداشبورد بيشتغل على نفس البورت يلي البوت شغال عليه (PORT بـ .env، افتراضي 10000) — ما بحتاج استضافة منفصلة.

---

الأوامر المتاحة

الأمر	الوصف	الصلاحية
/kick	طرد عضو	رول المشرفين + Kick Members
/ban	حظر عضو	رول المشرفين + Ban Members
/mute	إسكات مؤقت (حتى 28 يوم)	رول المشرفين + Moderate Members
/warn	تحذير عضو	رول المشرفين
/warnings	عرض تحذيرات عضو	رول المشرفين
/say	يخلي البوت يبعت رسالة بقناة (نافذة نص متعدد الأسطر)	رول المشرفين
/ping	فحص استجابة البوت	الجميع
/info	معلومات عن البوت	الجميع
/ask	سؤال الذكاء الاصطناعي	قناة الـ AI المحددة بس
/setup	إعداد كل شي (9 صفحات، 34 إعداد)	Manage Server
/ticket-panel	نشر لوحة فتح التذاكر بالقناة الحالية	رول المشرفين
/embed quick	نموذج سريع لبناء embed	رول المشرفين
/embed builder	رابط لأداة البناء الكاملة بالداشبورد	رول المشرفين
/embed send / preview / list / delete	إدارة الـ embeds المحفوظة	-
/music play	تشغيل أغنية (بحث/رابط)	يفتح روم صوتك تلقائياً
/music skip / pause / resume / stop / leave	تحكم بالتشغيل	لازم تكون بنفس الروم
/music queue / nowplaying	عرض القائمة/الحالية	-
/music volume / loop / shuffle / remove	تحكم متقدم بالقائمة	لازم تكون بنفس الروم

---

صفحات الداشبورد

الصفحة	الوصف
Overview	معلومات السيرفر، عدد الإعدادات المكتملة، روابط سريعة
Server Settings	الرولات والقنوات الأساسية (مش اللوقز)
Logs	كل قنوات اللوقز الـ30+، مجمعة بفئات مع تنقل سريع بالأعلى، ولون قابل للتخصيص لكل نوع
Branding	اللون والأيقونة والفوتر الافتراضي لكل embeds البوت
Ticket Panel	نشر لوحة فتح التذاكر بأي قناة
Embed Builder	بناء embed كامل التخصيص مع معاينة حية
Message Templates	ربط embed محفوظ ليكون شكل الترحيب/بانر التذاكر
Auto Divider	صورة الفاصل التلقائي + القنوات يلي تنطبق عليها

---

نظام اللوقز الكامل

كل صف = قناة + لون منفصلين تماماً عن باقي الصفوف. مقسومة لفئات بصفحة Logs بالداشبورد وبصفحات /setup (9 صفحات).

لوقز الإدارة: تحذير، حظر/رفع حظر، طرد، إسكات، حذف رسالة، تعديل رسالة، حذف جماعي

لوقز الصوت: دخول/خروج، تبديل روم (بنفسه)، نقل (من مشرف)، فصل قسري، كتم/رفع كتم، صم/رفع صم

لوقز السيرفر والأعضاء: دخول/خروج السيرفر، تغيير نك نيم، تغيير رولات عضو

لوقز القنوات: إنشاء، حذف، تعديل (اسم/موضوع/slowmode)

لوقز الرولات: إنشاء، حذف، تعديل (اسم/لون/صلاحيات)

لوقز الثريدات: إنشاء، حذف، تعديل (أرشفة/قفل/اسم)

التذاكر والنظام: لوق التذاكر (transcript)، لوق تحديثات الإعدادات نفسها — أي تغيير تعمله من /setup أو من الداشبورد ينسجل هون تلقائياً (مين غيّر شو ومتى).

معظم لوقز القنوات/الرولات/الأعضاء تحتاج صلاحية View Audit Log للبوت عشان تعرف "مين عمل الفعل" — بدونها بتسجل الحدث بس بدون اسم الفاعل.

---

هيكلية المشروع

src/
├── main.py                    # نقطة البداية + تحميل الـ Cogs
├── config.py                  # كل متغيرات البيئة القابلة للتخصيص
├── dashboard.py                # الداشبورد الكامل (OAuth2 + كل الصفحات + API)
│
├── cogs/
│   ├── moderation.py            # kick, ban, mute, warn
│   ├── welcome.py                # ترحيب + رول تلقائي (أعضاء/بوتات منفصلين)
│   ├── ai_chat.py                 # /ask متصل بـ OpenRouter
│   ├── utility.py                  # ping, info, say
│   ├── setup.py                     # /setup (9 صفحات، مبني ديناميكياً)
│   ├── tickets.py                    # نظام التذاكر الكامل
│   ├── trap_channel.py                # قناة الفخ (حظر تلقائي)
│   ├── auto_divider.py                 # الفاصل التلقائي
│   ├── embed_builder.py                 # أوامر /embed
│   ├── music.py                          # أوامر /music + لوحة التحكم بالأزرار
│   ├── voice_logs.py                      # لوقز الصوت (6 أنواع)
│   ├── audit_logs.py                       # ban/unban/kick/timeout logs
│   └── server_logs.py                       # لوقز القنوات/الرولات/الأعضاء/الثريدات/الرسائل
│
└── utils/
    ├── checks.py                # فحوصات قناة/رول قابلة لإعادة الاستخدام
    ├── db.py                     # كل التعامل مع MongoDB
    ├── embed_helper.py            # تطبيق الـ Branding على embeds البوت الداخلية
    ├── embed_builder.py            # محرك بناء الـ embeds المخصصة (لا علاقة له بـ embed_helper)
    ├── message_templates.py         # ربط embed محفوظ بمكان رسالة افتراضية
    ├── log_helper.py                 # إرسال موحد لكل اللوقز + قراءة Audit Log مشتركة
    ├── error_handler.py               # معالجة موحدة للأخطاء
    ├── music_source.py                 # استخراج الصوت (yt-dlp) + fallback لـ SoundCloud
    ├── music_player.py                  # محرك التشغيل لكل سيرفر (queue, loop, volume)
    └── http_audio_source.py              # بث الصوت عبر Python (ليس FFmpeg) - راجع الملف لليش

---

النشر على Render

• الصوت (Music): المشروع يستخدم imageio-ffmpeg (نسخة ffmpeg جاهزة عبر pip، بدون Docker) و davey (مكتبة إجبارية من discord.py 2.7+ لأي اتصال صوتي، حتى الغير مشفر). مهم: لا تخلي ffmpeg يتصل بالشبكة مباشرة على هالبيئة — راجع تعليق music_player.py لليش (باغ segfault موثق بالبناء الثابت المستخدم هون).
• يوتيوب: أحياناً بيرفض التشغيل برسالة "Sign in to confirm you're not a bot" (حماية بوتات على IPs مشتركة بالسحابة). البوت بيتعامل معها تلقائياً (fallback لـ SoundCloud)، بس لو حبيت موثوقية أعلى، فيك تضيف YTDLP_COOKIES_B64 بـ .env (راجع .env.example).
• الداشبورد: يشتغل بنفس عملية البوت (نفس python main.py)، ما بحتاج Web Service منفصل.

---

ملاحظات أمان مهمة

• لا ترفع ملف .env أبداً على GitHub (محمي بـ .gitignore).
• فعّل بس الـ Intents اللي فعلاً محتاجها (مبدأ أقل صلاحيات ممكنة) — راجع main.py.
• DASHBOARD_SECRET_KEY لازم يكون نص عشوائي طويل وسري — أي حدا يعرفه فيه يزوّر جلسات دخول.
• إذا العميل هو اللي سجل الـ Application وأعطاك التوكين، اطلب منه إعادة توليده (Regenerate) بعد انتهاء شغلك إذا ما في اتفاق صيانة مستمر.
• كوكيز يوتيوب (لو استخدمتها) من حساب حقيقي — استخدامها لبوت فيه مخاطرة حظر الحساب، وزنها بنفسك قبل ما تفعّلها.

---

Checklist لكل عميل جديد

• استخدم "Use this template" على GitHub لإنشاء ريبو جديد نظيف
• أنشئ Application جديد بـ Discord Developer Portal، خذ Token + Client ID/Secret
• أنشئ قاعدة بيانات MongoDB Atlas جديدة (مجانية) للعميل
• املأ .env بكل القيم (توكين، MongoDB، OAuth2)
• عدّل BOT_NAME و WELCOME_MESSAGE و EMBED_COLOR حسب هوية العميل
• شغّل /setup بسيرفر العميل واضبط كل الرولات/القنوات
• فعّل Branding من الداشبورد (لون/أيقونة/فوتر)
• اختبر كل أمر وكل صفحة داشبورد على سيرفر تجريبي قبل التسليم النهائي
• اختر طريقة الاستضافة (Render أو غيرها) وجهز التوكين المناسب