# 📱 الرسائل النصية السريعة - WhatsApp Gateway

## 🎯 نظرة عامة

تم إضافة **أزرار إرسال سريع** تتيح لك إرسال رسائل واتساب جاهزة بضغطة زر واحدة **بدون الحاجة لكتابة الرسالة**.

### ✨ الميزات الجديدة:

- ⚡ **إرسال بضغطة واحدة** - بدون نوافذ منبثقة
- 📝 **رسائل جاهزة** - محفوظة مسبقاً
- 🎨 **تخصيص كامل** - عدّل الرسائل من الإعدادات
- 🔄 **متغيرات ذكية** - {name}, {balance}, {credit_limit}
- 🎯 **أزرار ملونة** - سهلة التمييز

---

## 🆕 الأزرار الجديدة

### في صفحة العملاء:

```
┌─────────────────────────────────────────────────────────────┐
│ العميل: أحمد محمد | الهاتف: 01234567890                     │
│                                                              │
│ أزرار واتساب المتاحة:                                       │
│                                                              │
│ [✏️ تعديل]                                                  │
│ [💬 إرسال واتساب (Twilio)]        ← نافذة منبثقة           │
│ [📱 إرسال واتساب (رقمي الخاص)]     ← نافذة منبثقة           │
│ [✉️ رسالة ترحيب سريعة]            ← جديد ⭐ إرسال مباشر   │
│ [🔔 إرسال تذكير]                   ← جديد ⭐ إرسال مباشر   │
│ [🗑️ حذف]                                                    │
└─────────────────────────────────────────────────────────────┘
```

---

## 📋 أنواع الأزرار السريعة

### 1️⃣ زر الترحيب السريع ✉️
- **اللون:** أصفر (warning)
- **الوظيفة:** إرسال رسالة ترحيب للعميل
- **الرسالة الافتراضية:** "مرحباً {name}! كيف حالك اليوم؟"
- **متى يظهر:** عند وجود رقم هاتف للعميل

**مثال الاستخدام:**
1. اضغط على الزر ✉️
2. ستظهر نافذة تأكيد: "سيتم إرسال رسالة ترحيب إلى أحمد محمد"
3. اضغط **إرسال الآن**
4. تم الإرسال! ✅

### 2️⃣ زر التذكير 🔔
- **اللون:** أحمر (danger)
- **الوظيفة:** إرسال تذكير بالرصيد
- **الرسالة الافتراضية:** "تذكير: عزيزي {name}، رصيدك الحالي {balance}. يرجى المراجعة."
- **متى يظهر:** عند وجود رصيد للعميل أكبر من صفر

**مثال الاستخدام:**
1. اضغط على الزر 🔔
2. ستظهر نافذة: "سيتم إرسال تذكير بالرصيد إلى أحمد محمد (الرصيد: 5,000 جنيه)"
3. اضغط **إرسال الآن**
4. تم الإرسال! ✅

---

## ⚙️ تخصيص الرسائل

### الطريقة 1: من الإعدادات (موصى به)

1. انتقل إلى **الإعدادات** > **رسائل واتساب السريعة**
2. ستجد قائمة بجميع الرسائل الجاهزة
3. عدّل الرسائل أو أضف رسائل جديدة
4. استخدم المتغيرات:
   - `{name}` - اسم العميل
   - `{balance}` - الرصيد الحالي
   - `{credit_limit}` - حد الائتمان
5. اضغط **حفظ التغييرات**

**مثال:**
```
الرسالة: "عزيزي {name}، رصيدك {balance} وحد الائتمان {credit_limit}"
النتيجة: "عزيزي أحمد محمد، رصيدك 5000.00 وحد الائتمان 10000.00"
```

### الطريقة 2: من ملف الإعداد

عدّل ملف `config/whatsapp-gateway.php`:

```php
'quick_messages' => [
    'greeting' => 'مرحباً {name}! كيف حالك اليوم؟',
    'follow_up' => 'السلام عليكم {name}، نتمنى أن تكون بخير.',
    'reminder' => 'تذكير: عزيزي {name}، رصيدك الحالي {balance}.',
    'thank_you' => 'شكراً لك {name} على تعاملك معنا!',
    'offer' => '{name}، عرض خاص لك! خصم 20% اليوم فقط.',
    
    // أضف رسائلك الخاصة
    'custom' => 'رسالتك المخصصة هنا...',
],
```

ثم نفذ:
```bash
php artisan config:clear
```

---

## 🎨 إضافة رسائل جديدة

### من صفحة الإعدادات:

1. انتقل إلى **رسائل واتساب السريعة**
2. اضغط **إضافة رسالة جديدة**
3. املأ البيانات:
   - **مفتاح الرسالة:** `new_year` (اسم فريد)
   - **اسم الرسالة:** "تهنئة العام الجديد"
   - **نص الرسالة:** "كل عام وأنت بخير {name}! 🎉"
4. اضغط **حفظ**

---

## 🔧 استخدام الرسائل من الكود

### إرسال رسالة ترحيب:

```php
use App\Jobs\SendWhatsAppGatewayMessageJob;

// طريقة 1: استخدام Template
$template = config('whatsapp-gateway.quick_messages.greeting');
$message = str_replace(
    ['{name}', '{balance}', '{credit_limit}'],
    [$customer->name, $customer->current_balance, $customer->credit_limit],
    $template
);

SendWhatsAppGatewayMessageJob::dispatch(
    $customer->phone,
    $message,
    ['customer_id' => $customer->id, 'type' => 'greeting']
);
```

### إرسال جماعي لجميع العملاء:

```php
use App\Models\Customer;

$customers = Customer::whereNotNull('phone')->get();

foreach ($customers as $customer) {
    $template = config('whatsapp-gateway.quick_messages.offer');
    $message = str_replace('{name}', $customer->name, $template);
    
    SendWhatsAppGatewayMessageJob::dispatch(
        $customer->phone,
        $message,
        ['customer_id' => $customer->id, 'type' => 'offer']
    )->delay(now()->addSeconds($loop->index * 5)); // تأخير 5 ثواني بين كل رسالة
}
```

### إرسال تذكير لمن عليهم مبالغ:

```php
$customers = Customer::where('current_balance', '>', 0)->get();

foreach ($customers as $customer) {
    $template = config('whatsapp-gateway.quick_messages.reminder');
    $message = str_replace(
        ['{name}', '{balance}'],
        [$customer->name, number_format($customer->current_balance, 2)],
        $template
    );
    
    SendWhatsAppGatewayMessageJob::dispatch(
        $customer->phone,
        $message
    )->delay(now()->addSeconds($loop->index * 10));
}
```

---

## 📊 أمثلة الرسائل الجاهزة

### 1. رسالة ترحيب صباحية:
```
صباح الخير {name}! نتمنى لك يوماً سعيداً 🌞
```

### 2. متابعة طلب:
```
عزيزي {name}، نود متابعة طلبك معنا. هل كل شيء على ما يرام؟
```

### 3. تذكير بالدفع:
```
السلام عليكم {name}،
رصيدك الحالي: {balance} جنيه
يرجى التواصل لترتيب الدفع.
شكراً لتفهمك.
```

### 4. عرض خاص:
```
🎉 عرض خاص لك يا {name}!
خصم 15% على جميع المشتريات حتى نهاية الأسبوع
```

### 5. شكر وتقدير:
```
شكراً جزيلاً {name} على ثقتك بنا 💚
نتطلع لخدمتك دائماً
```

---

## 🔄 الفرق بين أنواع الأزرار

| | نافذة منبثقة | إرسال سريع ⭐ |
|---|---|---|
| **عدد الضغطات** | 2-3 ضغطات | ضغطة واحدة ✅ |
| **كتابة الرسالة** | يدوياً | تلقائياً ✅ |
| **السرعة** | بطيء | سريع جداً ✅ |
| **التخصيص** | كامل | محدود |
| **الاستخدام المثالي** | رسائل خاصة | رسائل متكررة ✅ |

---

## 💡 نصائح الاستخدام

### 1. وقت الإرسال المناسب:
```
✅ أفضل الأوقات:
   - 9 صباحاً - 12 ظهراً
   - 2 ظهراً - 5 مساءً
   - 7 مساءً - 9 مساءً

❌ تجنب:
   - قبل 8 صباحاً
   - بعد 10 مساءً
   - أيام الجمعة صباحاً
```

### 2. التكرار الآمن:
```
✅ آمن:
   - رسالة ترحيب: مرة كل أسبوع
   - تذكير بالرصيد: مرة كل 3 أيام
   - عروض: مرة كل أسبوعين

❌ خطر الحظر:
   - أكثر من رسالة يومياً لنفس العميل
   - رسائل متطابقة لأكثر من 50 شخص بسرعة
```

### 3. جدولة الإرسال:
```php
// إرسال كل صباح الساعة 9
$schedule->call(function () {
    $customers = Customer::where('is_active', true)->get();
    
    foreach ($customers as $customer) {
        // ... إرسال رسالة
    }
})->dailyAt('09:00');
```

---

## 🎯 حالات الاستخدام العملية

### 1. متابعة العملاء الجدد:
```php
// في CustomerObserver
public function created(Customer $customer)
{
    if ($customer->phone) {
        $message = "مرحباً {$customer->name}! شكراً لانضمامك لعملائنا 🎉";
        
        SendWhatsAppGatewayMessageJob::dispatch($customer->phone, $message)
            ->delay(now()->addMinutes(5));
    }
}
```

### 2. تذكير تلقائي للمتأخرين:
```php
// في Console/Kernel.php
$schedule->call(function () {
    $customers = Customer::where('current_balance', '>', 5000)->get();
    
    foreach ($customers as $customer) {
        // إرسال تذكير
    }
})->weekly();
```

### 3. عروض المواسم:
```php
// قبل عيد الفطر مثلاً
$customers = Customer::where('is_active', true)->get();

foreach ($customers as $customer) {
    $message = "كل عام وأنت بخير {$customer->name}! 🌙 عروض رمضان الآن!";
    SendWhatsAppGatewayMessageJob::dispatch($customer->phone, $message)
        ->delay(now()->addSeconds($loop->index * 10));
}
```

---

## 🔒 الأمان والحدود

### حدود الإرسال الآمنة:

```
📊 يومياً:
   - 50 رسالة/ساعة ✅
   - 300 رسالة/يوم ✅
   - 5-10 ثواني بين كل رسالة ✅

⚠️ تحذير:
   - 100+ رسالة/ساعة = خطر
   - رسائل متطابقة = spam
   - بدون تأخير = حظر محتمل
```

### أمثلة آمنة:

```php
// ✅ صحيح: تأخير بين الرسائل
foreach ($customers as $customer) {
    SendWhatsAppGatewayMessageJob::dispatch($phone, $message)
        ->delay(now()->addSeconds($loop->index * 5));
}

// ❌ خطأ: إرسال فوري جماعي
foreach ($customers as $customer) {
    SendWhatsAppGatewayMessageJob::dispatch($phone, $message); // خطر!
}
```

---

## 📖 ملخص الميزات الجديدة

```
✨ تم إضافة:

1. ✉️ زر رسالة ترحيب سريعة
2. 🔔 زر تذكير بالرصيد
3. ⚙️ صفحة إعدادات للرسائل
4. 🎨 تخصيص كامل للرسائل
5. 🔄 متغيرات ذكية {name}, {balance}, {credit_limit}
6. 📝 رسائل جاهزة قابلة للتوسع
7. 🎯 نافذة تأكيد قبل الإرسال

✅ المميزات:
   - سريع: ضغطة واحدة
   - ذكي: يملأ البيانات تلقائياً
   - آمن: تأكيد قبل الإرسال
   - مرن: قابل للتخصيص بالكامل
```

---

## 🎓 مثال شامل

```php
// في Controller أو Service
class CustomerNotificationService
{
    public function sendQuickGreeting(Customer $customer)
    {
        $template = config('whatsapp-gateway.quick_messages.greeting');
        $message = $this->fillTemplate($template, $customer);
        
        SendWhatsAppGatewayMessageJob::dispatch(
            $customer->phone,
            $message,
            ['type' => 'quick_greeting', 'customer_id' => $customer->id]
        );
    }
    
    public function sendBalanceReminder(Customer $customer)
    {
        if ($customer->current_balance <= 0) {
            return;
        }
        
        $template = config('whatsapp-gateway.quick_messages.reminder');
        $message = $this->fillTemplate($template, $customer);
        
        SendWhatsAppGatewayMessageJob::dispatch(
            $customer->phone,
            $message,
            ['type' => 'reminder', 'customer_id' => $customer->id]
        );
    }
    
    protected function fillTemplate(string $template, Customer $customer): string
    {
        return str_replace(
            ['{name}', '{balance}', '{credit_limit}'],
            [
                $customer->name,
                number_format($customer->current_balance, 2),
                number_format($customer->credit_limit, 2)
            ],
            $template
        );
    }
}
```

---

## 🚀 الخلاصة

الآن لديك **3 طرق** لإرسال رسائل واتساب:

1. **💬 Twilio مع نافذة منبثقة** - للرسائل المخصصة
2. **📱 Gateway مع نافذة منبثقة** - للرسائل المخصصة من رقمك
3. **✉️ أزرار سريعة** ⭐ **جديد** - للرسائل المتكررة بضغطة واحدة

**استخدم الأزرار السريعة عندما:**
- ✅ تريد السرعة
- ✅ نفس الرسالة تتكرر كثيراً
- ✅ لا تحتاج تخصيص لكل عميل

---

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