# بوت تيليجرام بمستوى مؤسسي لمعالجة الملفات الضخمة

تم تصميم هذا المشروع لتنفيذ بوت تيليجرام احترافي باستخدام لغة PHP 8.3+، مخصص لمعالجة الملفات الضخمة (CSV, TXT, JSON, ZIP, RAR) بكفاءة عالية، مع الاعتماد على بنية برمجية تعتمد على البث (Streaming) وتوفير الذاكرة والقابلية للتوسع.

## المميزات الأساسية

- **تكامل مع واجهة برمجة تطبيقات بوت تيليجرام**: تفاعل سلس ومباشر مع منصة تيليجرام.
- **بدون قاعدة بيانات**: يعتمد كلياً على التخزين المحلي للملفات والمجلدات المؤقتة.
- **تصميم كائني التوجه (OOP)**: بنية برمجية منظمة مع فصل كامل للمسؤوليات وتصميم وحداتي (Modular).
- **معايير PSR-12**: الالتزام بقواعد كتابة الكود الاحترافية في PHP.
- **نظام احترافي لمعالجة الأخطاء والسجلات**: إدارة قوية للأخطاء مع سجلات تفصيلية للمراقبة.
- **معالجة موفرة للذاكرة**: مصمم للتعامل مع ملفات تتجاوز أحجامها 25 جيجابايت عبر أسلوب القراءة السطرية (line-by-line).
- **أداء عالٍ في التعامل مع الملفات**: محسن للعمل على خوادم VPS والخوادم المخصصة.
- **محرك تقسيم الملفات**: يقوم بتقسيم الملفات الضخمة إلى أجزاء قابلة للتكوين (افتراضياً 20 جزءاً) مع موازنة تلقائية.
- **محرك التحويل إلى JSON**: يحول كل جزء مقسم إلى تنسيق JSON آمن (UTF-8)، مع معالجة الأحرف غير الصالحة والأسطر التالفة.
- **نظام تتبع التقدم اللحظي**: يوفر نسب الإنجاز، إشعارات الحالة، وتتبع وقت التنفيذ.
- **الأمان**: فحص شامل للملفات (النوع، الحجم، MIME)، عزل المجلدات، حماية من تجاوز المسارات (Path Traversal)، وتخزين مؤقت آمن.
- **الإدارة**: إشعارات للمطور عند حدوث أخطاء ومراقبة النظام.

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

```
. 
├── bot/
│   ├── classes/          # جميع فئات PHP (Bot, Telegram, Logger, Security, إلخ)
│   ├── config/           # ملفات الإعدادات (settings.php)
│   ├── core/             # المنطق الأساسي ونقاط الدخول (webhook.php, set_webhook.php)
│   ├── helpers/          # دوال مساعدة (فارغ حالياً)
│   └── storage/          # تخزين الملفات المرفوعة، المؤقتة، المخرجات، والسجلات
│       ├── logs/         # سجلات نشاط البوت
│       ├── output/       # الملفات المعالجة (مثل أجزاء JSON)
│       ├── temp/         # الملفات المؤقتة ومساحات العمل المعزولة
│       └── uploads/      # الملفات الخام المرفوعة من تيليجرام
└── vendor/               # ملحقات Composer (autoload.php)
└── composer.json         # إعدادات Composer
└── README_AR.md          # هذا الملف (التعليمات باللغة العربية)
```

## الإعداد والتثبيت

### المتطلبات الأساسية

- PHP 8.3+ مع تفعيل إضافات `curl` و `fileinfo` و `zip`.
- تثبيت مدير الحزم Composer.
- أداة `unrar` (عبر الأمر `sudo apt install unrar` في أنظمة Debian/Ubuntu) لفك ضغط ملفات RAR.

### الخطوات

1. **تحميل المشروع:**

   قم بفك الضغط عن الملف المرسل أو انسخ الملفات إلى خادمك.

2. **تثبيت الملحقات عبر Composer:**

   ```bash
   composer install
   ```

3. **إعداد رمز البوت (Bot Token) ومعرف المطور:**

   قم بتحرير الملف `bot/classes/Config.php` واستبدل القيم التالية:

   ```php
   public const BOT_TOKEN = "ضع_رمز_البوت_هنا";
   public const DEVELOPER_ID = معرف_تيليجرام_الخاص_بك; 
   ```

   *يمكنك الحصول على معرفك (User ID) عبر مراسلة بوت `@userinfobot` على تيليجرام.*

4. **إعداد الويب هوك (Webhook):**

   يعمل البوت عبر نظام الويب هوك. تحتاج إلى رابط (URL) عام متاح للوصول إلى ملف `bot/core/webhook.php`.

   قم بتحرير ملف `bot/core/set_webhook.php` واستبدل `YOUR_PUBLIC_WEBHOOK_URL_HERE` برابطك الفعلي:

   ```php
   $webhookUrl = 'https://your-domain.com/bot/core/webhook.php'; 
   ```

   ثم قم بتشغيل الملف لإعداد الويب هوك:

   ```bash
   php bot/core/set_webhook.php
   ```

5. **صلاحيات المجلدات:**

   تأكد من أن مجلد `bot/storage` والمجلدات الفرعية قابلة للكتابة من قبل الخادم.

   ```bash
   chmod -R 775 bot/storage
   ```

## الاستخدام

بمجرد إعداد الويب هوك، يصبح البوت جاهزاً للعمل:

- ابدأ محادثة مع البوت على تيليجرام.
- أرسل الأمر `/start`.
- قم برفع ملف (CSV, TXT, JSON, ZIP, RAR). سيقوم البوت بمعالجته، تقسيمه، تحويله إلى JSON، ثم إرسال أول جزء معالج إليك.

## معالجة الأخطاء والسجلات

- يتم تسجيل الأخطاء في `bot/storage/logs/` بملفات يومية.
- الأخطاء الحرجة ترسل تنبيهاً مباشراً إلى المطور (DEVELOPER_ID).

## التراخيص

هذا المشروع مرخص بموجب رخصة MIT.