| # 📘 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 | |
| |
| --- |
| |
| ## التشغيل |
| |
| ```bash |
| # 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`: |
| ```python |
| ADMIN_IDS: list[int] = [7299579109, ID_الجديد] |
| ``` |
| |
| --- |
| |
| ## السجلات (Logs) |
| |
| ``` |
| logs/bot.log — كل الأحداث INFO+ (5MB × 3 نسخ احتياطية) |
| logs/errors.log — الأخطاء ERROR+ (2MB × 5 نسخ احتياطية) |
| ``` |
| |
| كل خطأ يُسجل: الوقت، user_id، الأمر أو callback، traceback كامل. |
|
|
