# 📱 دليل إرسال رسائل واتساب للعملاء

## 📋 جدول المحتويات
- [نظرة عامة](#نظرة-عامة)
- [المتطلبات](#المتطلبات)
- [الإعداد والتثبيت](#الإعداد-والتثبيت)
- [كيفية الاستخدام](#كيفية-الاستخدام)
- [الميزات المتاحة](#الميزات-المتاحة)
- [استكشاف الأخطاء](#استكشاف-الأخطاء)
- [الأمثلة البرمجية](#الأمثلة-البرمجية)

---

## 🎯 نظرة عامة

تم تطوير نظام متكامل لإرسال رسائل واتساب للعملاء يتيح لك:

✅ **إرسال رسائل نصية** مباشرة للعملاء عبر واتساب  
✅ **إرسال كشوف الحساب PDF** عبر واتساب تلقائياً  
✅ **معالجة الإرسال في الخلفية** (Queue) لتحسين الأداء  
✅ **تتبع حالة الرسائل** والأخطاء عبر الـ Logs  
✅ **دعم متعدد اللغات** (عربي/إنجليزي/فرنسي)  

---

## 📦 المتطلبات

### 1. حساب Twilio
يجب أن يكون لديك حساب على [Twilio](https://www.twilio.com/) مع تفعيل WhatsApp Business API.

### 2. رقم WhatsApp Business
رقم واتساب بيزنس مرتبط بحساب Twilio الخاص بك.

### 3. متطلبات تقنية
- Laravel 12
- PHP 8.2+
- Queue Worker نشط (لمعالجة الرسائل)

---

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

### الخطوة 1: تثبيت الحزم المطلوبة

```bash
composer require twilio/sdk
```

> ✅ **تم بالفعل**: تم إضافة `"twilio/sdk": "^8.3"` إلى ملف [composer.json](composer.json)

### الخطوة 2: إضافة بيانات Twilio في ملف `.env`

أضف المتغيرات التالية إلى ملف `.env`:

```env
# Twilio Configuration
TWILIO_ACCOUNT_SID=your_account_sid_here
TWILIO_AUTH_TOKEN=your_auth_token_here
TWILIO_WHATSAPP_FROM=whatsapp:+14155238886
TWILIO_DEFAULT_COUNTRY_CODE=+20
TWILIO_ENABLED=true
TWILIO_LOG_MESSAGES=true
```

#### 🔑 كيفية الحصول على بيانات Twilio:

1. سجّل دخول على [Twilio Console](https://console.twilio.com/)
2. من Dashboard الرئيسية ستجد:
   - **Account SID**
   - **Auth Token**
3. من قسم **WhatsApp Senders** ستجد رقم واتساب الخاص بك

### الخطوة 3: تشغيل Queue Worker

الرسائل يتم إرسالها في الخلفية، لذا يجب تشغيل Queue Worker:

```bash
php artisan queue:work
```

أو في الـ Production يُفضل استخدام Supervisor:

```bash
php artisan queue:listen --tries=3
```

### الخطوة 4: إنشاء مجلد التخزين المؤقت

```bash
php artisan storage:link
```

تأكد من وجود صلاحيات الكتابة على المجلد:

```bash
chmod -R 775 storage/app/public/temp
```

---

## 🚀 كيفية الاستخدام

### 1. إرسال رسالة نصية لعميل واحد

من صفحة قائمة العملاء:

1. انتقل إلى **العملاء** > **قائمة العملاء**
2. اضغط على أيقونة **💬** (إرسال واتساب) بجانب العميل
3. اكتب رسالتك في النافذة المنبثقة
4. اضغط **إرسال**

✅ سيتم إضافة الرسالة لقائمة الانتظار وإرسالها تلقائياً

### 2. إرسال كشف حساب عبر واتساب

من صفحة **كشف حساب العميل**:

1. اختر العميل والتواريخ
2. اضغط **إنشاء التقرير**
3. اضغط زر **📱 إرسال عبر واتساب**

✅ سيتم:
- إنشاء ملف PDF لكشف الحساب
- رفعه على السيرفر مؤقتاً
- إرساله للعميل عبر واتساب
- حذف الملف تلقائياً بعد 24 ساعة

---

## ✨ الميزات المتاحة

### 📝 إرسال رسائل نصية

```php
use App\Jobs\SendWhatsAppMessageJob;

SendWhatsAppMessageJob::dispatch(
    phoneNumber: '+201234567890',
    message: 'مرحباً! هذه رسالة تجريبية',
    metadata: ['customer_id' => 1]
);
```

### 📄 إرسال كشف حساب PDF

```php
use App\Jobs\SendWhatsAppStatementJob;

SendWhatsAppStatementJob::dispatch(
    type: 'customer',
    entityId: $customerId,
    farmId: null,
    fromDate: '2026-01-01',
    toDate: '2026-01-25',
    customMessage: 'إليك كشف الحساب المطلوب'
);
```

### 🔍 التحقق من صلاحية رقم الهاتف

```php
use App\Services\WhatsAppService;

$whatsapp = app(WhatsAppService::class);

if ($whatsapp->isValidPhoneNumber($phone)) {
    // رقم صحيح
}
```

### 📊 الحصول على حالة الرسالة

```php
$status = $whatsapp->getMessageStatus('SM1234567890abcdef');

// النتيجة:
[
    'sid' => 'SM1234567890abcdef',
    'status' => 'delivered', // queued, sent, delivered, failed
    'to' => 'whatsapp:+201234567890',
    'error_code' => null,
    'error_message' => null
]
```

---

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

### مشكلة: الرسائل لا ترسل

**الحل:**
1. تأكد من تشغيل Queue Worker:
   ```bash
   php artisan queue:work
   ```

2. تحقق من الـ Logs:
   ```bash
   tail -f storage/logs/laravel.log
   ```

3. تأكد من صحة بيانات Twilio في `.env`

### مشكلة: خطأ في رقم الهاتف

**الحل:**
- تأكد من أن الرقم بصيغة دولية: `+201234567890`
- لا تستخدم أصفار في البداية
- تحقق من رمز الدولة الصحيح

### مشكلة: ملف PDF لا يُرسل

**الحل:**
1. تأكد من أن الرابط يمكن الوصول إليه عبر الإنترنت
2. تحقق من صلاحيات المجلد:
   ```bash
   chmod -R 775 storage/app/public
   ```

3. تأكد من ربط storage:
   ```bash
   php artisan storage:link
   ```

### مشكلة: "WhatsApp service is disabled"

**الحل:**
غيّر `TWILIO_ENABLED` في `.env` إلى `true`

---

## 📚 الأمثلة البرمجية

### مثال 1: إرسال رسالة ترحيبية للعميل الجديد

```php
// في Observer أو Event Listener
use App\Jobs\SendWhatsAppMessageJob;

Customer::created(function ($customer) {
    if ($customer->phone) {
        SendWhatsAppMessageJob::dispatch(
            $customer->phone,
            "مرحباً {$customer->name}!\nشكراً لانضمامك لعملائنا الكرام.",
            ['customer_id' => $customer->id]
        );
    }
});
```

### مثال 2: إرسال تنبيه عند اقتراب حد الائتمان

```php
use App\Jobs\SendWhatsAppMessageJob;

if ($customer->current_balance >= $customer->credit_limit * 0.9) {
    SendWhatsAppMessageJob::dispatch(
        $customer->phone,
        "تنبيه: رصيدك الحالي {$customer->current_balance} قارب الحد المسموح {$customer->credit_limit}.",
        ['customer_id' => $customer->id, 'alert_type' => 'credit_limit']
    );
}
```

### مثال 3: إرسال كشف حساب شهري تلقائي

```php
// في Console/Kernel.php
use App\Jobs\SendWhatsAppStatementJob;
use App\Models\Customer;

$schedule->call(function () {
    Customer::where('is_active', true)
        ->whereNotNull('phone')
        ->each(function ($customer) {
            SendWhatsAppStatementJob::dispatch(
                type: 'customer',
                entityId: $customer->id,
                fromDate: now()->subMonth()->startOfMonth()->toDateString(),
                toDate: now()->subMonth()->endOfMonth()->toDateString()
            );
        });
})->monthly();
```

### مثال 4: استخدام WhatsAppService مباشرة

```php
use App\Services\WhatsAppService;

$whatsapp = app(WhatsAppService::class);

// إرسال رسالة نصية
$result = $whatsapp->sendMessage(
    '+201234567890',
    'مرحباً! هذه رسالة اختبار'
);

if ($result['success']) {
    echo "تم الإرسال! Message SID: " . $result['message_sid'];
} else {
    echo "خطأ: " . $result['message'];
}

// إرسال رسالة مع PDF
$result = $whatsapp->sendMessageWithPdf(
    '+201234567890',
    'إليك كشف الحساب المطلوب',
    'https://yourdomain.com/storage/temp/statement.pdf'
);
```

---

## 📁 الملفات المُنشأة

تم إنشاء الملفات التالية في النظام:

### 1. ملفات الإعداد
- [config/twilio.php](config/twilio.php) - إعدادات Twilio

### 2. الخدمات (Services)
- [app/Services/WhatsAppService.php](app/Services/WhatsAppService.php) - خدمة إرسال واتساب

### 3. المهام (Jobs)
- [app/Jobs/SendWhatsAppMessageJob.php](app/Jobs/SendWhatsAppMessageJob.php) - مهمة إرسال رسالة نصية
- [app/Jobs/SendWhatsAppStatementJob.php](app/Jobs/SendWhatsAppStatementJob.php) - مهمة إرسال كشف حساب

### 4. ملفات الترجمة
- [lang/ar/filament/admin/customer_resource.php](lang/ar/filament/admin/customer_resource.php) - ترجمة عربية
- [lang/en/filament/admin/customer_resource.php](lang/en/filament/admin/customer_resource.php) - ترجمة إنجليزية
- [lang/ar/filament/admin/reports.php](lang/ar/filament/admin/reports.php) - ترجمة التقارير بالعربية
- [lang/en/filament/admin/reports.php](lang/en/filament/admin/reports.php) - ترجمة التقارير بالإنجليزية

### 5. تعديلات الواجهة
- [app/Filament/Resources/Customers/Tables/CustomersTable.php](app/Filament/Resources/Customers/Tables/CustomersTable.php) - زر إرسال واتساب
- [app/Filament/Pages/CustomerStatementReport.php](app/Filament/Pages/CustomerStatementReport.php) - زر إرسال كشف الحساب

---

## 🔐 الأمان

### 1. حماية البيانات الحساسة
- لا تشارك `TWILIO_ACCOUNT_SID` و `TWILIO_AUTH_TOKEN` مع أحد
- احفظها في `.env` فقط ولا ترفعها على Git

### 2. التحقق من أرقام الهواتف
- يتم التحقق تلقائياً من صحة تنسيق الأرقام
- يُرفض الإرسال للأرقام غير الصحيحة

### 3. Rate Limiting
- يوجد حماية ضد الإرسال الزائد في صفحات التقارير
- يُسمح بـ 5 طلبات كل دقيقة

---

## 💰 التكلفة

### أسعار Twilio WhatsApp (تقريبية):

| نوع الرسالة | التكلفة |
|-------------|---------|
| رسالة نصية | $0.005 |
| رسالة مع ملف | $0.005 |

> 💡 **ملاحظة**: الأسعار قد تختلف حسب البلد ونوع الحساب. راجع [صفحة أسعار Twilio](https://www.twilio.com/whatsapp/pricing)

---

## 📞 الدعم والمساعدة

### الموارد المفيدة:
- [Twilio Documentation](https://www.twilio.com/docs/whatsapp)
- [Twilio PHP SDK](https://www.twilio.com/docs/libraries/php)
- [Laravel Queue Documentation](https://laravel.com/docs/queues)

### المشاكل الشائعة:
- [Twilio Error Codes](https://www.twilio.com/docs/api/errors)
- [WhatsApp Best Practices](https://www.twilio.com/docs/whatsapp/best-practices)

---

## 🎉 ملاحظات ختامية

✅ **تم التنفيذ بنجاح!**

النظام جاهز الآن لإرسال:
1. رسائل نصية للعملاء
2. كشوف حساب PDF عبر واتساب
3. تنبيهات تلقائية

**خطوات البدء:**
1. أضف بيانات Twilio في `.env`
2. شغّل `composer install`
3. شغّل Queue Worker
4. ابدأ الإرسال!

---

**تم التطوير بواسطة:** GitHub Copilot  
**التاريخ:** 25 يناير 2026  
**الإصدار:** 1.0.0