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 |

---

## التشغيل

```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 كامل.