# توثيق نظام الإشعارات المطور - موقع "وصلي"

تم تطوير نظام إشعارات متكامل يربط بين العميل والكابتن لضمان تجربة مستخدم سلسة واحترافية.

## 1. التغييرات في الواجهة الخلفية (Backend)

### أ. الملفات الجديدة
*   **`utils/notificationHelper.js`**: ملف مساعد يحتوي على دالة `sendNotification` التي تقوم بحفظ الإشعار في قاعدة البيانات وإرساله فوراً عبر Socket.io.

### ب. التحديثات في المسارات (Routes)
*   **`routes/orders.js`**:
    *   إضافة إشعار للعميل عند قبول الطلب (`order_accepted`).
    *   إضافة إشعار للعميل عند استلام الطلب (`order_picked_up`).
    *   إضافة إشعار للعميل عند إتمام التوصيل (`order_completed`).
    *   إضافة إشعار للكابتن عند إلغاء العميل للطلب (`order_update`).
    *   إرسال حدث `new_order_available` لكل الكباتن عند إنشاء طلب جديد.
*   **`routes/chat.js`**:
    *   تحديث نظام إشعارات الدردشة لاستخدام المساعد الجديد وتوحيد بنية البيانات.
*   **`routes/auth.js`**:
    *   التأكد من إرسال `_id` المستخدم عند تسجيل الدخول لربطه بنظام Socket.io.

## 2. التغييرات في الواجهة الأمامية (Frontend)

### أ. نظام التنبيهات المنبثقة (Toast System)
*   تم إنشاء ملف `public/notification-toast.js` (اختياري للاستخدام العام).
*   تم دمج نظام Toast مخصص في `client-orders.html` و `captain-dashboard.html` لإظهار تنبيهات جذابة تنزل من أعلى الشاشة.

### ب. الربط مع Socket.io
*   تحديث صفحات تسجيل الدخول (`client-login.html`, `captain-login.html`) لتخزين `userId` في `localStorage`.
*   إضافة كود الاستماع للأحداث في لوحات التحكم لتحديث الواجهة فوراً عند حدوث أي تغيير.

## 3. كيفية الاستخدام البرمجي
لإرسال إشعار جديد من أي مكان في السيرفر:
```javascript
const { sendNotification } = require('../utils/notificationHelper');

await sendNotification(req.app, {
    userId: 'ID_المستخدم',
    title: 'عنوان الإشعار',
    message: 'نص الرسالة',
    type: 'نوع_الإشعار', // chat, order_accepted, etc.
    relatedId: 'ID_الطلب_المرتبط'
});
```

## 4. المميزات الإبداعية المضافة
1.  **إشعارات فورية**: لا يحتاج المستخدم لتحديث الصفحة لرؤية التغييرات.
2.  **تنبيهات ذكية**: الكابتن يحصل على تنبيه فوري عند وجود طلب جديد في النظام دون أن يكون هو صاحب الطلب.
3.  **توجيه تلقائي**: عند النقر على الإشعار المنبثق، يتم توجيه المستخدم لصفحة الإشعارات.
4.  **تحديث الحالة**: يتم تحديث حالة الطلب في صفحة العميل فوراً عند قبول الكابتن له.