DOCUMENTATION.md

📘 Games In Arabic Bot — توثيق المشروع

نظرة عامة

بوت تيليجرام متكامل باللغة العربية يخدم عالم الألعاب:

• 🔍 مكتبة تعريبات قابلة للبحث
• 🎮 مواصفات فنية من IGDB
• 🖥 متطلبات تشغيل PC من Steam
• 🖼 خلفيات عالية الجودة من Wallhaven
• 🔔 نظام إشعارات للمشتركين
• 📡 فهرسة تلقائية لمنشورات القناة

---

هيكل المشروع

bot_v4/
│
├── main.py                     # نقطة الدخول — إعداد وتشغيل البوت
├── config.py                   # كل الإعدادات من .env
├── requirements.txt
├── .env.example                # قالب متغيرات البيئة
│
├── database/
│   ├── __init__.py             # تصدير الواجهة العامة
│   ├── connection.py           # اتصال SQLite مع PRAGMA
│   ├── migrations.py           # إنشاء الجداول والفهارس والـ Triggers
│   ├── messages.py             # CRUD الرسائل المفهرسة
│   ├── users.py                # CRUD المستخدمين، الاشتراكات، الإذاعات
│   └── settings.py             # get/set إعدادات ديناميكية
│
├── handlers/
│   ├── __init__.py
│   ├── start.py                # /start، /myid، الواجهة الرئيسية
│   ├── search.py               # البحث والتصنيفات
│   ├── specs.py                # مواصفات فنية (IGDB) + تشغيل (Steam)
│   ├── wallpapers.py           # خلفيات Wallhaven
│   ├── notifications.py        # زر التنبيهات الديناميكي
│   ├── inline.py               # Inline Mode (@bot اسم_اللعبة)
│   ├── admin.py                # لوحة الإدارة، فهرسة القناة، إشعار عضو جديد
│   └── callbacks.py            # Router المركزي لكل Callbacks والرسائل
│
├── services/
│   ├── __init__.py
│   ├── igdb.py                 # IGDB API (OAuth2 + بحث + تفاصيل كاملة)
│   ├── steam.py                # Steam API (PC Specs)
│   ├── wallhaven.py            # Wallhaven API (خلفيات)
│   ├── indexer.py              # محرك الفهرسة
│   ├── searcher.py             # محرك البحث متعدد المراحل
│   └── broadcaster.py         # نظام الإذاعة والإشعارات
│
├── utils/
│   ├── __init__.py
│   ├── html.py                 # تنسيق HTML لتيليجرام (esc, b, blockquote...)
│   ├── arabic.py               # توحيد النص العربي وتحليله
│   ├── genres.py               # قاموس 60+ نوع لعبة (EN→AR)
│   ├── buttons.py              # بناء أزرار النتائج والتنقل
│   ├── links.py                # بناء روابط تيليجرام
│   └── guards.py               # is_admin، @admin_only، @register_user
│
└── logs/
    ├── bot.log                 # كل الأحداث (5MB × 3 نسخ)
    └── errors.log              # الأخطاء فقط (2MB × 5 نسخ)

---

قواعد البيانات (SQLite)

جدول messages — الرسائل المفهرسة

العمود	النوع	الوصف
id	INTEGER PK	معرف تلقائي
message_id	INTEGER	معرف المنشور في القناة
channel_id	INTEGER	معرف القناة
channel_name	TEXT	اسم القناة
channel_username	TEXT	يوزرنيم القناة
message_text	TEXT	نص المنشور الكامل
text_normalized	TEXT	النص موحد (للبحث)
message_date	TEXT	تاريخ المنشور
hashtags	TEXT	الهاشتاقات مفصولة بفاصلة
platform	TEXT	pc / ps / general
has_media	INTEGER	0 أو 1
media_type	TEXT	photo/video/document
indexed_at	TEXT	وقت الفهرسة

جدول messages_fts — فهرس البحث الكامل FTS5

Virtual table متزامنة تلقائياً مع messages عبر Triggers.

جدول users — المستخدمون

العمود	النوع	الوصف
user_id	INTEGER PK	معرف تيليجرام
username	TEXT	يوزرنيم
first_name	TEXT	الاسم
joined_at	TEXT	تاريخ أول /start
is_banned	INTEGER	0=نشط، 1=محظور

جدول notification_subscribers — المشتركون في التنبيهات

العمود	النوع	الوصف
user_id	INTEGER PK FK	معرف المستخدم
platform	TEXT	all/pc/ps
subscribed_at	TEXT	تاريخ الاشتراك

جدول broadcasts — سجل الإذاعات

العمود	النوع	الوصف
id	INTEGER PK	معرف تلقائي
admin_id	INTEGER	معرف المشرف
message_text	TEXT	نص الإذاعة (500 حرف)
broadcast_type	TEXT	new_post/update/manual
game_title	TEXT	اسم اللعبة
game_link	TEXT	رابط التعريب
sent_count	INTEGER	أُرسلت
failed_count	INTEGER	فشلت
blocked_count	INTEGER	حظروا البوت
sent_at	TEXT	وقت الإرسال

جدول settings — الإعدادات الديناميكية

المفتاح	القيمة الافتراضية	الوصف
channel_text	نص افتراضي	نص صفحة القناة
auto_notify	"1"	إشعار تلقائي عند الفهرسة
auto_channel_index	"notify_only"	وضع مراقبة القناة

---

واجهات API الخارجية

IGDB (Twitch)

• التوثيق: OAuth2 Client Credentials
• الرابط: https://api.igdb.com/v4/games
• لغة الاستعلام: Apicalypse
• البيانات: اسم، غلاف، تاريخ، مطور، ناشر، منصات، تقييمات، تصنيف عمري، لغات، أنواع، ثيمات، فيديوهات، موقع Steam
• Cache Token: في الذاكرة مع asyncio.Lock لتجنب race conditions

Steam

• AppDetails: https://store.steampowered.com/api/appdetails
• Search: https://store.steampowered.com/api/storesearch
• البيانات: متطلبات PC (minimum/recommended) كـ HTML يُحلَّل بـ regex
• تحذير: pc_requirements قد يكون list فارغة، dict، أو None

Wallhaven

• البحث: https://wallhaven.cc/api/v1/search
• التفاصيل: https://wallhaven.cc/api/v1/w/{id}
• API Key: اختياري (بدونه SFW فقط)
• الفلتر: atleast=1920x1080 لضمان جودة 1080p+

---

نظام البحث (4 مراحل)

المرحلة 1: FTS5 مباشر (مطابقة تامة للعبارة)
     ↓ إذا < min_results
المرحلة 2: FTS5 بالنص الموحد (بدون تشكيل/همزات)
     ↓ إذا < min_results
المرحلة 3: FTS5 بالبادئة ("كلم"* يطابق "كلمة")
     ↓ إذا < min_results
المرحلة 4: ضبابي Levenshtein (SequenceMatcher ≥ 0.5)

---

نظام الإذاعة

الحد: 25 رسالة/دفعة، انتظار 1 ثانية بين الدفعات.

معالجة الأخطاء:

• RetryAfter (429): انتظار retry_after ثم إعادة المحاولة (حتى 3 مرات)
• Forbidden/BadRequest: المستخدم حظر البوت → يُحذف من قائمة المشتركين
• TimedOut/NetworkError: Exponential backoff (2ث، 4ث، 8ث)

---

متغيرات البيئة (.env)

المتغير	إجباري	الوصف
BOT_TOKEN	✅	توكن البوت من @BotFather
IGDB_CLIENT_ID	✅	من dev.twitch.tv
IGDB_CLIENT_SECRET	✅	من dev.twitch.tv
CHANNEL_ID	✅	معرف القناة (مثال: -1001234567890)
CHANNEL_USERNAME	❌	يوزرنيم القناة بدون @
WALLHAVEN_API_KEY	❌	من wallhaven.cc/settings

---

التشغيل

# 1. تثبيت المكتبات
pip install -r requirements.txt

# 2. إنشاء .env من القالب
cp .env.example .env
# عدّل .env بالقيم الحقيقية

# 3. تشغيل البوت
python main.py

---

أوامر البوت

عامة (للجميع)

الأمر	الوظيفة
/start	القائمة الرئيسية
/myid	معلومات الحساب

الإدارة (للمشرفين فقط)

الأمر	الوظيفة
/pc	فهرسة ألعاب PC
/ps	فهرسة ألعاب PS
/general	فهرسة عامة
/stop	إنهاء جلسة الفهرسة
/undo	حذف آخر منشور
/status	حالة الجلسة والإحصائيات
/admin	لوحة التحكم
/setch نص	تعديل نص صفحة القناة

---

إضافة مشرف جديد

في config.py:

ADMIN_IDS: list[int] = [7299579109, ID_الجديد]

---

السجلات (Logs)

logs/bot.log     — كل الأحداث INFO+  (5MB × 3 نسخ احتياطية)
logs/errors.log  — الأخطاء ERROR+    (2MB × 5 نسخ احتياطية)

كل خطأ يُسجل: الوقت، user_id، الأمر أو callback، traceback كامل.