README

نظام إشعارات متكامل واحترافي لبيئة عمل Laravel، يدعم الإشعارات الفورية (Real-time) عبر Reverb/Pusher، وإشعارات الهاتف/المتصفح عبر Firebase (FCM)، مع لوحة تحكم متطورة للتحليلات وإدارة الحملات.

📋 المميزات

• إشعارات فورية (Real-time): دعم كامل لـ Laravel Reverb و Pusher مع تحديثات حية.
• Firebase Cloud Messaging (FCM):
  • إرسال للمستخدمين (Tokens).
  • إرسال للموضوعات (Topics).
  • معالجة ذكية للأخطاء (حذف التوكنات المنتهية تلقائياً).
• تحليلات متقدمة (Analytics):
  • تتبع الإرسال (Sent).
  • تتبع الوصول (Delivered) - للويب.
  • تتبع القراءة (Read).
  • تتبع النقر (Clicked).
• لوحة تحكم (Dashboard): واجهة لإرسال الإشعارات ومشاهدة الإحصائيات.
• مكونات Blade جاهزة: دمج سهل في الفرونت إند بـ سطر واحد.

🚀 دليل التثبيت (Installation)

1. تثبيت الباكدج

composer require advanced-notifications/core

2. نشر الملفات

php artisan vendor:publish --provider="AdvancedNotifications\AdvancedNotificationsServiceProvider"

3. إعداد قاعدة البيانات

php artisan notifications:table
php artisan migrate

⚙️ الإعداد والتهيئة (Configuration)

1. إعداد ملف .env

أضف المتغيرات التالية في ملف .env الخاص بمشروعك:

إعدادات Firebase (للإشعارات):

FIREBASE_CREDENTIALS_PATH=/path/to/your/firebase_credentials.json
FIREBASE_API_KEY=AIzaSy...
FIREBASE_AUTH_DOMAIN=your-app.firebaseapp.com
FIREBASE_PROJECT_ID=your-project-id
FIREBASE_STORAGE_BUCKET=your-app.appspot.com
FIREBASE_MESSAGING_SENDER_ID=123456789
FIREBASE_APP_ID=1:123456789:web:abcdef
FIREBASE_VAPID_KEY=B... (المفتاح العام الطويل)

إعدادات Reverb (للإشعارات الفورية):

REVERB_APP_ID=...
REVERB_APP_KEY=...
REVERB_APP_SECRET=...
REVERB_HOST="localhost"
REVERB_PORT=8080
REVERB_SCHEME="http"

VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="${REVERB_HOST}"
VITE_REVERB_PORT="${REVERB_PORT}"
VITE_REVERB_SCHEME="${REVERB_SCHEME}"

2. إعداد موديل المستخدم (User.php)

أضف الـ Trait HasAdvancedNotifications في موديل المستخدم:

use AdvancedNotifications\Traits\HasAdvancedNotifications;

class User extends Authenticatable
{
    use HasAdvancedNotifications;
    // ...
}

3. إعداد قنوات البث (routes/channels.php)

تأكد من وجود تصريح للقناة الخاصة بالمستخدم:

Broadcast::channel('App.Models.User.{id}', function ($user, $id) {
    return (int) $user->id === (int) $id;
});

💻 الاستخدام (Usage)

1. دمج الإشعارات في الفرونت إند (Frontend)

فقط أضف هذا السطر في ملف الـ Layout الرئيسي (قبل إغلاق </body>):

<x-advanced-notifications::scripts topic="1" user-id="{{ auth()->id() }}" />

• topic="1": (اختياري) للاشتراك تلقائياً في موضوع معين.
• user-id: (ضروري) لتفعيل الإشعارات الخاصة بالمستخدم.

هذا المكون سيقوم تلقائياً بـ:

1. تحميل مكتبات Firebase و Echo.
2. طلب إذن الإشعارات.
3. الاستماع للقنوات الخاصة.
4. عرض الإشعارات بـ SweetAlert جميل.
5. إرسال تقارير "تم الوصول" و "تم النقر" للباك إند.

2. إرسال إشعار برمجياً (Code)

use AdvancedNotifications\Notifications\GenericNotification;
use App\Models\User;

$user = User::find(1);

$user->notify(new GenericNotification(
    'عنوان الإشعار',
    'نص الإشعار هنا...',
    null,               // الأيقونة
    'https://google.com', // رابط عند النقر
    [],                 // بيانات إضافية
    ['broadcast', 'database', 'fcm'] // القنوات
));

🧪 خطة الاختبار النهائي (Final Testing Plan)

اتبع هذه الخطوات للتأكد من أن النظام يعمل 100%:

الاختبار 1: الإرسال لمستخدم واحد (Single User)

1. افتح لوحة التحكم: /advanced-notifications/send.
2. اختر Target Type: User.
3. أدخل Recipient ID: رقم المستخدم الخاص بك (مثلاً 1).
4. اختر القنوات: Database, Realtime, FCM.
5. اضغط Send.
   • ✅ النتيجة المتوقعة: يظهر SweetAlert فوراً، ويصل إشعار متصفح (FCM)، ويتم تسجيل الإشعار في قاعدة البيانات.

الاختبار 2: الإرسال لعدة مستخدمين (Multiple Users)

1. في نفس الصفحة، أدخل في Recipient ID: 1,2 (أرقام مستخدمين موجودين).
2. اضغط Send.
   • ✅ النتيجة المتوقعة: يصل الإشعار لكلا المستخدمين، ويتم تسجيل سجلين في التحليلات.

الاختبار 3: الإرسال لموضوع (Topic)

1. تأكد أنك مشترك في التوبيك (عبر كود الـ Blade topic="news" مثلاً).
2. اختر Target Type: Topic.
3. أدخل اسم التوبيك: news.
4. اضغط Send.
   • ✅ النتيجة المتوقعة: يصل إشعار FCM لجميع المشتركين في هذا التوبيك.

الاختبار 4: الإرسال الجماعي (Mass Send)

1. اختر Target Type: All Users.
2. اضغط Send.
   • ✅ النتيجة المتوقعة: يتم جدولة الإرسال لجميع المستخدمين في النظام (على دفعات).

الاختبار 5: التحليلات (Analytics)

1. بعد وصول الإشعار (SweetAlert)، لا تضغط عليه فوراً.
2. اذهب لجدول notification_analytics في الداتابيس.
   • ✅ يجب أن تجد سجل event_type = delivered.
3. اضغط على الإشعار.
   • ✅ يجب أن يتم توجيهك للرابط.
   • ✅ يجب أن تجد سجل event_type = clicked.
   • ✅ يجب أن تتحدث حالة الإشعار في جدول advanced_notifications لتصبح read_at لها قيمة.

تم التطوير بحب ❤️ بواسطة [فريقك]