# دليل إعداد إشعارات التليجرام

## نظرة عامة
تم إضافة نظام إشعارات التليجرام لإرسال تنبيهات فورية عند:
- إنشاء طلب جديد
- تحديث حالة الطلب

## الملفات المضافة

### 1. Helper Class
- `backend/helpers/telegram.php` - كلاس للتعامل مع Telegram Bot API

### 2. Setup Script
- `backend/setup/add_telegram_settings.php` - إضافة إعدادات التليجرام للقاعدة

### 3. Admin Interface
- تم إضافة تاب "تليجرام" في صفحة الإعدادات
- `backend/admin/settings/test_telegram.php` - اختبار الاتصال

## خطوات الإعداد

### 1. إنشاء البوت
1. افتح [@BotFather](https://t.me/BotFather) على التليجرام
2. أرسل الأمر `/newbot`
3. اتبع التعليمات واختر اسم للبوت
4. احصل على Bot Token (مثال: `123456789:ABCdefGHIjklMNOpqrsTUVwxyz`)

### 2. الحصول على Chat ID
1. افتح [@userinfobot](https://t.me/userinfobot)
2. أرسل أي رسالة
3. احصل على Chat ID الخاص بك (مثال: `123456789`)

**ملاحظة:** لإرسال الإشعارات لمجموعة:
1. أضف البوت للمجموعة
2. اجعله Admin
3. استخدم Chat ID المجموعة (يبدأ بـ `-`)

### 3. إعداد النظام
1. افتح لوحة التحكم → الإعدادات → تليجرام
2. الصق Bot Token و Chat ID
3. فعّل الإشعارات
4. اضغط "اختبار الاتصال" للتأكد
5. احفظ الإعدادات

## الميزات

### إشعار الطلب الجديد
يتم إرساله تلقائياً عند إنشاء طلب جديد ويحتوي على:
- رقم الطلب
- معلومات العميل (الاسم، الجوال، البريد)
- العنوان والمدينة
- قائمة المنتجات والكميات
- الإجمالي وطريقة الدفع
- الملاحظات (إن وجدت)

### إشعار تحديث الحالة
يتم إرساله عند تغيير حالة الطلب من لوحة التحكم:
- رقم الطلب
- معلومات العميل
- الحالة الجديدة
- المبلغ الإجمالي

## الإعدادات في قاعدة البيانات

```sql
-- جدول settings
telegram_enabled      -- تفعيل/إيقاف (0 أو 1)
telegram_bot_token    -- توكن البوت
telegram_chat_id      -- معرف المحادثة
```

## API Methods المستخدمة

### TelegramBot Class

```php
// إنشاء instance
$telegram = new TelegramBot($db);

// إرسال رسالة عادية
$telegram->sendMessage($message, $parse_mode = 'HTML');

// إرسال إشعار طلب جديد
$telegram->sendNewOrderNotification($order, $items);

// إرسال إشعار تحديث الحالة
$telegram->sendOrderStatusUpdate($order, $new_status);

// اختبار الاتصال
$result = $telegram->testConnection();
```

## استكشاف الأخطاء

### البوت لا يرسل رسائل
1. تأكد من صحة Bot Token
2. تأكد من صحة Chat ID
3. تأكد من تفعيل الإشعارات في الإعدادات
4. استخدم "اختبار الاتصال" لفحص الاتصال

### رسائل الخطأ الشائعة
- `Unauthorized`: Bot Token خاطئ
- `Chat not found`: Chat ID خاطئ أو البوت غير مضاف للمجموعة
- `Bot was blocked by the user`: المستخدم حظر البوت

### Logs
الأخطاء يتم تسجيلها في PHP error log:
```php
error_log("Telegram notification failed: " . $e->getMessage());
```

## الأمان

- Bot Token حساس ويجب حمايته
- لا تشارك التوكن مع أحد
- استخدم HTTPS دائماً
- يمكن تعطيل الإشعارات مؤقتاً من الإعدادات

## التطوير المستقبلي

يمكن إضافة:
- إشعارات للمخزون المنخفض
- إشعارات للمراجعات الجديدة
- إشعارات للرسائل الجديدة
- أزرار تفاعلية (Inline Keyboards)
- إرسال صور المنتجات

## الدعم

للمزيد من المعلومات:
- [Telegram Bot API Documentation](https://core.telegram.org/bots/api)
- [BotFather Commands](https://core.telegram.org/bots#6-botfather)