# 📖 المرجع الشامل والنهائي لبوت التحميل ومسابقات الإحالة (Marj3 Master Reference)

> **وثيقة مرجعية شاملة لكافة مكونات، معايير، أوامر، وقواعد عمل النظام**  
> **الإصدار:** 3.2.0 Ultra  
> **البيئة المستهدفة:** استضافات cPanel / DirectAdmin / VPS (PHP 8.0+ و SQLite)  
> **البوت:** بوت التحميل الذكي من جميع المنصات ومسابقات التيليجرام متعدد اللغات.

---

## 📌 الفهرس السريع للمحتويات
1. [نظرة عامة وهيكلية النظام (System Architecture)](#1-نظرة-عامة-وهيكلية-النظام)
2. [قواعد ومعايير الاشتراك الإجباري الصارم (Mandatory Subscription)](#2-قواعد-ومعايير-الاشتراك-الإجباري-الصارم)
3. [محرك التحميل والتعامل مع قيود cPanel و YouTube](#3-محرك-التحميل-والتعامل-مع-قيود-cpanel-و-youtube)
4. [نظام مسابقات الإحالة والجوائز متعددة المستويات (Multi-Tier Referrals)](#4-نظام-مسابقات-الإحالة-والجوائز-متعددة-المستويات)
5. [نظام البحث المزدوج: الشات المباشر ووضع الإنلاين (Search Modes)](#5-نظام-البحث-المزدوج)
6. [نظام تخصيص وتعديل نصوص وأزرار البوت (Button Customizer)](#6-نظام-تخصيص-وتعديل-نصوص-وأزرار-البوت)
7. [تعدد اللغات والترجمة المتقنة (عربي / كوردي / إنجليزي)](#7-تعدد-اللغات-والترجمة-المتقنة)
8. [لوحة تحكم الأدمن للويب والتليجرام (Admin Dashboard & Commands)](#8-لوحة-تحكم-الأدمن)
9. [تسريع الأداء وتقليل زمن الاستجابة (Latency Optimization)](#9-تسريع-الأداء-وتقليل-زمن-الاستجابة)
10. [دليل التثبيت، التهيئة، وحل المشكلات (Deployment & Troubleshooting)](#10-دليل-التثبيت-والتهيئة-وحل-المشكلات)

---

## 1. نظرة عامة وهيكلية النظام

النظام عبارة عن بوت تيليجرام هجين متقدم، يجمع بين:
1. **محرك تحميل خارق:** يدعم يوتيوب، تيك توك، إنستغرام، فيسبوك، تويتر (X)، بينترست، ساوندكلاود، وغيرها بأعلى جودة ممكنة مع خيارات فيديو، صوت نقي، وبصمة صوتية (Voice Note).
2. **محرك نمو وزيادة مشتركين (Viral Growth Engine):** نظام إحالات ذكي بجوائز متعددة المستويات يحفز المستخدمين على مشاركة البوت في القنوات والمجموعات للحصول على مكافآت.
3. **نظام اشتراك إجباري صارم وموثوق 100%:** لدعم القنوات العامة والخاصة مع التحقق الحقيقي اللحظي لمنع التخطي الوهمي.
4. **بحث يوتيوب فوري:** سواء بكتابة اسم الفيديو في الشات مباشرة، أو عبر وضع الـ Inline في أي محادثة.
5. **لوحة تحكم كاملة (ويب وتيليجرام):** للتحكم بالقنوات، مستويات الجوائز، تخصيص نصوص الأزرار، والإذاعات الجماعية.

### هيكلية الملفات في المشروع:
```text
telegram-downloader-cpanel/
├── bot.php              # نقطة دخول التيليجرام، معالجة الرسائل، الكولباك، التنزيل، والبحث
├── admin.php            # لوحة تحكم الأدمن للويب (إحصائيات، قنوات، جوائز، أزرار، إذاعة)
├── db.php               # إدارة قاعدة بيانات SQLite والجداول وعمليات الاستعلام
├── lang.php             # قاموس اللغات الثلاث (العربية، الكردية، الإنجليزية)
├── telegram.php         # كلاس التخاطب السريع مع Telegram Bot API (cURL IPv4)
├── downloader.php       # كلاس التنزيل واستدعاء yt-dlp ومعالجة قيود السيرفرات
├── config.php           # إعدادات التوكن، الأدمن، روابط البوت، ومسار التخزين
├── check_server.php     # فحص بيئة السيرفر وتوافق الصلاحيات ومكتبات PHP
├── set_webhook.php      # تثبيت أو حذف أو فحص الويب هوك الرسمي لتيليجرام
├── marj3.md             # المرجع الشامل والنهائي للنظام وكافة إعداداته
├── downloads/           # مجلد التخزين المؤقت للملفات والـ TMPDIR للـ yt-dlp
├── database.sqlite      # قاعدة البيانات الذاتية
└── yt-dlp               # الملف التنفيذي المخصص لمحرك التنزيل
```

---

## 2. قواعد ومعايير الاشتراك الإجباري الصارم

### أ. المبدأ الأساسي للتحقق
- **فحص حقيقي وصارم 100%:** لا يُسمح بأي تخطي وهمي أو قبول تلقائي بمجرد الضغط على زر التحقق.
- **المرجع الرسمي:** استدعاء الدالة الرسمية `getChatMember` لكل قناة من القنوات المضافة في قاعدة البيانات.
- **الحالات المقبولة كعضو حقيقي:**
  - `status === 'creator'` (المالك)
  - `status === 'administrator'` (المشرف)
  - `status === 'member'` (عضو عادي)
  - `status === 'restricted'` مع تحقق `is_member === true`
- **حالات الرفض الصارم:**
  - `status === 'left'` أو `status === 'kicked'`
  - أو استجابة الخطأ `user not found` / `member not found`
  - عند حدوث أي من هذه الحالات، يُمنع المستخدم فوراً من التحميل وتُعرض له القنوات الناقصة مع روابط الانضمام.

### ب. معالجة القنوات الخاصة وروابط الدعوة (`t.me/+...`)
- **القيد التقني في تيليجرام:** واجهة Telegram Bot API ترفض رفضاً قاطعاً البحث بروابط الدعوة المؤقتة (`+...`) في دالة `getChatMember`. الدالة تقبل فقط:
  1. المعرف العام المسبوق بـ `@` (مثل `@MyChannel`).
  2. المعرف الرقمي الصريح للقنوات الخاصة الذي يبدأ بـ `-100` (مثل `-1001234567890`).

- **طرق الاستخراج التلقائي للمعرف الرقمي `-100...`:**
  1. **حدث إضافة البوت كأدمن (`my_chat_member`):**
     - عند رفع البوت مشرفاً في القناة الخاصة، يرسل تيليجرام حدثاً تلقائياً يحمل `chat.id` الرقمي، يقوم البوت فوراً بربطه بالقناة المضافة وتحديثها بقاعدة البيانات.
  2. **نشر منشور بالقناة (`channel_post`):**
     - عند إرسال أي منشور داخل القناة، يقرأ البوت المعرف الرقمي ويحدث سجل القناة فوراً.
  3. **توجيه رسالة من القناة للبوت (`forward_from_chat`):**
     - يقوم الأدمن بتوجيه أي رسالة من قناته الخاصة إلى شات البوت، فيقوم البوت باستخراج `forward_from_chat.id` وتحديث القناة بالمعرف `-100...`.
  4. **زر مشاركة القناة الرسمي (`KeyboardButtonRequestChat`):**
     - يطلب البوت من الأدمن الضغط على زر "مشاركة القناة"، فتفتح نافذة قنواته الرسمية بتيليجرام، وبمجرد اختيارها يرسل تيليجرام كائن `chat_shared` يحمل المعرف الرقمي `-100...` تلقائياً دون أي كتابة يدوية.

---

## 3. محرك التحميل والتعامل مع قيود cPanel و YouTube

### أ. تخطي قفل الأمان `noexec` على `/tmp` في خوادم cPanel
- **طبيعة المشكلة:** نسخة `yt-dlp` المستقلة (PyInstaller Standalone Linux Binary) تستخرج مكتباتها الديناميكية في مجلد `/tmp`. استضافات cPanel المشتركة تقوم بتركيب مجلد `/tmp` بخاصية `noexec` لمنع تشغيل السكربتات، مما يسبب الانهيار الفوري بخطأ:  
  `libz.so.1: failed to map segment from shared object: Operation not permitted`.
- **الحل الجذري والقاعدة الصارمة:**
  - يتم دائماً إجبار المعالج على استخدام مجلد محلي قابل للتنفيذ والقراءة والكتابة داخل مسار البوت (مجلد `downloads/`) عبر تعيين المتغير البيئي `TMPDIR`:
  ```bash
  TMPDIR=/home/user/public_html/bot/downloads /home/user/public_html/bot/yt-dlp [options]
  ```

### ب. تحميل الصوتيات بدون الحاجة إلى مكتبة `ffmpeg`
- **طبيعة المشكلة:** معظم استضافات cPanel المشتركة لا توفر برنامج `ffmpeg`. استخدام الخيار التقليدي `-x --audio-format mp3` يُلزم `yt-dlp` بطلب `ffmpeg`، وعند غيابه يفشل التنزيل فوراً ويُحذف الملف مع خطأ `ERROR: Postprocessing: ffprobe and ffmpeg not found`.
- **الحل والقاعدة الصارمة:**
  - منع تمرير `-x --audio-format mp3` إطلاقاً في البيئات التي تفتقر لـ `ffmpeg`.
  - سحب المسار الصوتي الأصلي المباشر بأعلى جودة عبر الأمر:
    ```bash
    -f "ba[ext=m4a]/ba[ext=mp3]/ba/b[ext=mp4]/b" -o "target.%(ext)s"
    ```
  - يتم إرسال الملف بصيغة `.m4a` أو `.mp3` أو `.aac` أو `.mp4` الأصلية عبر `Telegram::sendAudio`؛ حيث يدعم مشغل تيليجرام الرسمي تشغيلها وتضمين الغلاف والوسوم بسلاسة مطلقة.

### ج. استراتيجية البصمة الصوتية الذكية (Smart Voice Fallback)
- **القيد:** رسالة البصمة (`sendVoice`) في تيليجرام تتطلب حصراً ترميز `.ogg` بتقنية Opus. بدون `ffmpeg` يستحيل تقنياً تحويل الملفات إلى هذا الترميز.
- **الحل الذكي:**
  1. يقوم البوت بفحص وجود `ffmpeg` في الخادم.
  2. إذا كان متوفراً: يقوم بالتحويل إلى `.ogg` وإرسالها كبصمة صوتية فورية (`sendVoice`).
  3. إذا لم يتوفر `ffmpeg` أو فشل التحويل: **لا يتم إظهار أي خطأ للمستخدم إطلاقاً**؛ بل يقوم البوت فوراً بالتحويل التلقائي وإرسال المقطع عبر `sendAudio` كملف صوتي عالي النقاء، وبذلك تضمن تجربة مستخدم خالية من أي رسائل فشل.

### د. تجاوز حظر يوتيوب (HTTP 403 Forbidden)
- **طبيعة المشكلة:** يوتيوب يحظر عناوين IP الخاصة بالسيرفرات ومراكز البيانات (Datacenters) عند الطلب من المتصفح الافتراضي بفرض كود 403 وحل اختبارات البوت. كما يفصل مسارات الصوت عن الفيديو في الجودات العالية مما يتطلب `ffmpeg` للدمج.
- **الحل الصارم:**
  1. تمرير عميل أندرويد الرسمي عبر:
     ```bash
     --extractor-args "youtube:player_client=android"
     ```
     هذا العميل يتجاوز حظر 403 ولا يتطلب تشغيل محركات JavaScript إضافية.
  2. اختيار مسار الفيديو المدمج مسبقاً (Progressive Stream) بالصيغة:
     ```bash
     -f "18/22/b[ext=mp4]/best[ext=mp4]/best"
     ```
     الصيغة `18` تمنح جودة 360p متوازنة جداً تحوي الفيديو مع صوت AAC كامل بملف MP4 واحد، تعمل بسرعة فائقة وخفة تامة دون حاجة للدمج.
  3. لتحميل صوت يوتيوب بدون دمج: استخدام الصيغة `18/ba[ext=m4a]/ba/b`.

### هـ. حفظ روابط الكاش المؤقت
- يتم تخزين مفتاح التنزيل والروابط `url_{hash}.txt` داخل مجلد `downloads/` المحلي مع التحقق الاحتياطي في مجلد النظام لضمان عدم ضياع رابط التحميل عند تنقل المستخدم بين أزرار التنسيقات (فيديو / صوت / بصمة).

---

## 4. نظام مسابقات الإحالة والجوائز متعددة المستويات

تم بناء نظام إحالة تسويقي كامل يتيح لمدير البوت تحديد مستويات جوائز متعددة غير محدودة.

### أ. الهيكل البرمجي وقاعدة البيانات
- **جدول المستويات (`referral_tiers`):**
  - `id`: المعرف الرقمي للمستوى.
  - `target_invites`: عدد الدعوات المطلوبة لبلوغ هذا المستوى (مثال: 10، 25، 50، 100).
  - `reward_title`: وصف الجائزة (مثال: "حساب نتفلكس شهر"، "بطاقة رصيد 10$"، "اشتراك تيليجرام بريميوم").
- **بيانات المتسابقين في جدول `users`:**
  - `referral_count`: إجمالي عدد المستخدمين الحقيقيين الذين انضموا عبر رابط هذا المستخدم.
  - `referred_by`: معرّف المستخدم الذي دعاه.
  - `wallet_name`: اسم المتسابق لاستلام الجائزة.
  - `wallet_phone`: رقم هاتف أو محفظة المتسابق.
  - `reward_claimed`: حالة استلام الجائزة.

### ب. واجهة المستخدم في قسم المسابقات
- **عرض المستوى المؤهل له حالياً (Qualified Tier):** يرى المستخدم الجائزة التي فاز بها وحقق شرطها.
- **عرض الهدف القادم (Next Target):** يوضح البوت عدد الإحالات المتبقية بالضبط للوصول للجائزة التالية مع شريط تقدم رسومي.
- **جدول قائمة الجوائز الكاملة:** يعرض جميع المستويات المتاحة في المسابقة ليشاهد المستخدم كافة خيارات الربح.
- **زر استلام الجائزة وتسجيل المحفظة:** يتيح للمتسابق المؤهل إدخال اسمه ورقم هاتفه ومحفظته لتصل في لوحة تحكم الأدمن فوراً.
- **لوحة الشرف (Leaderboard 🏆):** استعراض أفضل 10 متسابقين على مستوى البوت مع عدد إحالات كل منهم لبث روح المنافسة.

---

## 5. نظام البحث المزدوج

### أ. البحث المباشر في الشات (Direct In-Chat Search)
- لا يحتاج المستخدم إلى حفظ أوامر معقدة.
- بمجرد أن يكتب المستخدم في شات البوت اسم أغنية، سورة قرآنية، أو فيديو (مثال: `سورة الكهف ماهر المعيقلي` أو `Alan Walker Faded`):
  1. يلتقط البوت النص تلقائياً عبر دالة `searchYouTubeVideos`.
  2. يقوم بكشط نتائج يوتيوب واستخراج أفضل 5 نتائج دقيقة (العنوان، القناة، المدة، ومعرف الفيديو).
  3. يرسل للمستخدم بطاقات تفاعلية فورية لكل فيديو تحتوي على زر: **📥 تحميل (اختر الجودة)**.
  4. عند الضغط عليه، ينتقل البوت فوراً لمعالجة الرابط وإظهار خيارات التحميل (فيديو MP4، صوت MP3، بصمة صوتية).

### ب. وضع الإنلاين (Inline Query Mode)
- يعمل في أي محادثة أو قروب أو قناة خاصة عن طريق كتابة:
  `@اسم_البوت كلمة_البحث`
- يوفر خيارين:
  1. **مشاركة رابط الدعوة:** بطاقة دعوة جاهزة مع زر للانضمام واحتساب الإحالة للمستخدم.
  2. **نتائج يوتيوب المباشرة:** استعراض نتائج الفيديو مع صور مصغرة وإمكانية إرسال الرابط في أي شات بضغطة زر.

---

## 6. نظام تخصيص وتعديل نصوص وأزرار البوت

تم دمج نظام تخصيص ديناميكي كامل يسمح بتعديل نصوص واجهة البوت والأزرار الـ 12 الأساسية دون الحاجة لتعديل الكود البرمجي:
- **جدول التخصيص (`custom_buttons`):**
  - `btn_key`: المفتاح البرمجي للزر.
  - `lang`: رمز اللغة (`ar`, `ku`, `en`).
  - `btn_text`: النص المخصص الذي يظهر للمستخدمين.
- **التكامل الذكي في كلاس `Lang`:**
  - عند طلب أي نص من الواجهة عبر `Lang::get($key, $lang)`، يقوم السكربت بالتحقق أولاً من جدول `custom_buttons`.
  - إذا وجد نصاً مخصصاً محفوظاً من الأدمن، يتم تطبيقه فوراً.
  - إذا لم يجد، يعود للنص الافتراضي في ملف `lang.php`.
- **الأزرار القابلة للتعديل من لوحة التحكم:**
  1. `btn_change_lang` (تغيير اللغة / زمان گۆڕین)
  2. `btn_help` (المساعدة والشرح / ڕێنمایی)
  3. `btn_referral` (المسابقات والجوائز / پێشبڕکێ و خەڵاتەکان)
  4. `btn_my_account` (حسابي وإحصائياتي / هەژمارەکەم)
  5. `btn_share` (مشاركة الرابط / هاوبەشکردنی لینک)
  6. `btn_leaderboard` (لوحة المتصدرين / ڕیزبەندی سەرکەوتووان)
  7. `btn_submit_wallet` (تسجيل بيانات الاستلام / تۆمارکردنی جزدان)
  8. `btn_format_video` (تحميل فيديو / داگرتنی ڤیدیۆ)
  9. `btn_format_audio` (تحميل صوت / داگرتنی دەنگ)
  10. `btn_format_voice` (تحميل بصمة / داگرتنی دەنگی کورت)
  11. `btn_check_sub` (تحقق من الاشتراك / دڵنیابوونەوە لە ئەندامبوون)
  12. `btn_cancel` (إلغاء / پاشگەزبوونەوە)

---

## 7. تعدد اللغات والترجمة المتقنة

يدعم البوت ثلاث لغات بدقة واحترافية:
- **العربية (AR):** لغة عربية فصحى نقية، منسقة ومطعمة بالإيموجي التوضيحي.
- **الكردية (KU - سۆرانی):** ترجمة احترافية رصينة خالية من الأخطاء والكلمات المعربة الغريبة:
  - استبدال الكلمات الركيكة (استخدام **"جزدان"** للمحفظة بدلاً من الكلمات غير المفهومة).
  - استخدام **"پێشبڕکێ"** للمسابقات بدلاً من الجمع الخاطئ.
  - ترجمة أزرار التراجع والإلغاء إلى **"پاشگەزبوونەوە"** و **"گەڕانەوە"**.
- **الإنجليزية (EN):** لغة إنجليزية قياسية احترافية مناسبة لجميع المستخدمين العالميين.

---

## 8. لوحة تحكم الأدمن

### أ. لوحة تحكم الويب (`admin.php`)
لوحة ويب متجاوبة وجذابة مع الوضع المظلم العصري (Dark Mode) محمية برقم سري:
- **الإحصائيات المباشرة:**
  - إجمالي المستخدمين والمستخدمين الجدد اليوم.
  - إجمالي عمليات التحميل وعمليات اليوم.
  - عدد القنوات الإجبارية الفعالة.
  - إجمالي الإحالات النشطة.
- **إدارة القنوات الإجبارية:**
  - إضافة قنوات عامة بالمعرف `@`.
  - إضافة قنوات خاصة برابط الدعوة أو المعرف الرقمي `-100...`.
  - فحص حالة اشتراك البوت كأدمن في القناة بضغطة زر.
  - حذف وتعديل القنوات.
- **إدارة مسابقة الإحالة والجوائز:**
  - إضافة مستويات ربح جديدة (تحديد عدد الإحالات المطلوبة + اسم الهدية).
  - حذف أي مستوى.
  - استعراض طلبات الفائزين المسجلة وبيانات محافظهم للتواصل وتسليم الجوائز.
- **محرر أزرار البوت:**
  - تعديل وحفظ نصوص الأزرار الـ 12 لجميع اللغات (عربي، كردي، إنجليزي) بضغطة زر.
- **نظام الإذاعة الجماعية (Broadcast):**
  - دعم تنسيق HTML الغني.
  - إمكانية إضافة زر شفاف تفاعلي (نص الزر + رابط خارجي).
  - إمكانية إرفاق صورة/بانر ترويجي.
  - إمكانية تثبيت الرسالة تلقائياً لدى جميع المشتركين (`Pin Message`).

### ب. أوامر الأدمن عبر التيليجرام
- `/admin`: فتح لوحة الإدارة السريعة داخل شات التيليجرام لعرض الإحصائيات وإرسال الرسائل.
- `/adminmsto`: الإذاعة المتقدمة السريعة عبر الشات بالصيغة:
  ```text
  /adminmsto النص هنا || نص الزر || رابط الزر
  ```

---

## 9. تسريع الأداء وتقليل زمن الاستجابة (Latency Optimization)

لضمان أعلى سرعة تنفيذ وتجنب أخطاء المهلة الزمنية (Timeouts) على خوادم الاستضافة المشتركة:
1. **إجبار cURL على بروتوكول IPv4:**
   - تم تعيين `CURLOPT_IPRESOLVE => CURL_IPRESOLVE_V4` في جميع طلبات التخاطب مع تيليجرام لتجنب تعليق استعلامات DNS المزدوجة لـ IPv6 على خوادم cPanel.
2. **ضبط مهلات اتصال ذكية (Fast Timeouts):**
   - مهلة الاتصال: 4 ثوانٍ (`CURLOPT_CONNECTTIMEOUT = 4`).
   - مهلة القراءة القصوى: 8 ثوانٍ (`CURLOPT_TIMEOUT = 8`).
3. **إنهاء اتصال الويب هوك مبكراً (Fast Webhook Acknowledgment):**
   - استخدام `fastcgi_finish_request()` لتحرير خادم تيليجرام وإرسال كود `200 OK` فوراً، مما يمنع تيليجرام من تكرار إرسال الرسالة أثناء قيام البوت بتنزيل الملفات الكبيرة.
4. **تخزين كاش القنوات الإجبارية:**
   - تخزين نتيجة فحص الاشتراك لمدة ثوانٍ معدودة لكل مستخدم لتقليل استدعاءات الـ API أثناء الضغط العالي.

---

## 10. دليل التثبيت والتهيئة وحل المشكلات

### أ. المتطلبات الأساسية
- خادم استضافة (cPanel أو VPS أو خادم سحابي).
- إصدار PHP: **8.0** أو **8.1** أو **8.2**.
- إضافات PHP المفعلة: `curl`, `pdo_sqlite`, `mbstring`, `json`.
- تفعيل دالة التنفيذ `exec` أو `shell_exec` في الخادم لكي يعمل محرك التنزيل `yt-dlp`.

### ب. خطوات الرفع والتثبيت
1. ارفع محتويات المجلد إلى مسار موقعك (مثلاً داخل مجلد `bot/` في `public_html`).
2. تأكد من إعطاء الصلاحيات التالية:
   - مجلد `downloads/` ⬅️ ترخيص **777** أو **755** (قابل للكتابة والتنفيذ).
   - ملف `yt-dlp` ⬅️ ترخيص **755** (قابل للتنفيذ Executable).
   - ملف `database.sqlite` (إن وجد) ⬅️ ترخيص **666** أو **777**.
3. افتح ملف `config.php` واضبط الإعدادات التالية:
   - `BOT_TOKEN`: توكن البوت المستخرج من `@BotFather`.
   - `ADMIN_ID`: معرّفك الرقمي في تيليجرام.
   - `BOT_USERNAME`: يوزر البوت بدون `@`.
   - `ADMIN_PASSWORD`: كلمة مرور لوحة تحكم الويب.
   - `WEBHOOK_URL`: رابط ملف `bot.php` الكامل مع `https://`.
4. ثبّت الويب هوك: افتح متصفحك واطلب الرابط:
   ```text
   https://yourdomain.com/bot/set_webhook.php?action=set
   ```
   ستظهر لك رسالة نجاح الربط وتأكيد الويب هوك.
5. افتح فاحص السيرفر للتأكد من خلو الاستضافة من أي نواقص:
   ```text
   https://yourdomain.com/bot/check_server.php
   ```

### ج. حل المشكلات الشائعة (Troubleshooting)

| المشكلة | السبب المحتمل | الحل المعتمد |
| :--- | :--- | :--- |
| **خطأ `libz.so.1` عند التحميل** | مجلد `/tmp` مقفل بـ `noexec` في السيرفر | تم حله جذرياً؛ يقوم السكربت بتمرير `TMPDIR` إلى مجلد `downloads/` المحلي تلقائياً. |
| **خطأ Postprocessing: ffmpeg not found** | السيرفر يفتقر لـ `ffmpeg` | تم ضبط السكربت لتنزيل الصيغ المدمجة `ba/b` مباشرة دون طلب تحويل `mp3`، وإرسال الصوت عبر `sendAudio`. |
| **خطأ HTTP 403 Forbidden من يوتيوب** | حظر يوتيوب لـ IP السيرفر | تم تمرير معامل أندرويد `--extractor-args "youtube:player_client=android"` والصيغة المدمجة `18`. |
| **البوت لا يستجيب في القنوات الخاصة** | القناة الخاصة لا تدعم رابط `+` | ارفع البوت مشرفاً، ثم مرر المعرف `-100...` عبر زر مشاركة القناة أو توجيه رسالة للبوت. |
| **فشل حفظ البيانات أو الأزرار** | انعدام صلاحية الكتابة لـ SQLite | تأكد من صلاحية 777 لمجلد البوت وملف `database.sqlite`. |

---
**تم إعداد هذا المرجع ليكون الدليل الموحد والشامل لكافة تحديثات وتشغيل البوت.**