# استراتيجية الإشعارات — Notification Strategy

## النظام

| النظام | القناة | الاستخدام | حالات التشغيل |
|--------|--------|-----------|---------------|
| **Expo Push** | Push Notification (HTTP) | التطبيق مفتوح أو في الخلفية أو مغلق | Expo Push API (`https://exp.host/--/api/v2/push/send`) |

المنطق: **كل إشعار يُرسل عبر Expo Push API مباشرة لكل مستخدم حسب توكناته**. الـ client يستقبل الإشعار ويعرضه حسب حالة التطبيق.

---

## أنواع الإشعارات وأحداثها

### 1. إشعارات الحضور (Attendance Notifications)

| الحدث | المُرسِل | المُستقبِل | القناة | البيانات |
|-------|---------|----------|--------|---------|
| سجل المعلم حضور طفل | المعلم | ولي الأمر | Expo Push | `{ student_name, status, date, arrival_time }` |
| تسجيل الحضور للصف كاملاً | المعلم | جميع أولياء أمور الصف | Expo Push | `{ student_name, status, date }` |

**نوع Laravel Event:** `AttendanceRecorded`
**نوع Laravel Notification:** `AttendanceNotification`

---

### 2. إشعارات الوجبات (Meal Notifications)

| الحدث | المُرسِل | المُستقبِل | القناة | البيانات |
|-------|---------|----------|--------|---------|
| المعلم يسجل حالة وجبة لطفل | المعلم | ولي الأمر | Expo Push | `{ student_name, meal_type, status, date }` |

ملاحظة: الإشعار يُرسل لكل وجبة على حدة (إفطار، غداء، عصر) — أو دفعة واحدة بعد تسجيل bulk حسب قرار التصميم.

**نوع Laravel Event:** `MealRecorded`
**نوع Laravel Notification:** `MealNotification`

---

### 3. إشعارات النوم (Sleep Notifications)

| الحدث | المُرسِل | المُستقبِل | القناة | البيانات |
|-------|---------|----------|--------|---------|
| المعلم يسجل حالة نوم لطفل | المعلم | ولي الأمر | Expo Push | `{ student_name, sleep_status, date }` |

**نوع Laravel Event:** `SleepRecorded`
**نوع Laravel Notification:** `SleepNotification`

---

### 4. إشعارات الأنشطة (Activity Notifications)

| الحدث | المُرسِل | المُستقبِل | القناة | البيانات |
|-------|---------|----------|--------|---------|
| المعلم ينشر نشاط جديد لصف | المعلم | جميع أولياء أمور الصف | Expo Push | `{ title, objective, date, class_name }` |

**نوع Laravel Event:** `ActivityPublished`
**نوع Laravel Notification:** `ActivityNotification`

---

### 5. إشعارات الصور (Media Notifications)

| الحدث | المُرسِل | المُستقبِل | القناة | البيانات |
|-------|---------|----------|--------|---------|
| رفع صورة جديدة للطفل (إذا الإعداد فوري) | المعلم | ولي الأمر | Expo Push | `{ student_name, image_count }` |
| Admin وافق على صورة صف كامل | Admin | أولياء أمور الصف | Expo Push | `{ class_name, image_count }` |

**نوع Laravel Event:** `PhotoUploaded`
**نوع Laravel Notification:** `PhotoNotification`

---

### 6. إشعارات الإعلانات (Announcement Notifications)

| الحدث | المُرسِل | المُستقبِل | القناة | البيانات |
|-------|---------|----------|--------|---------|
| Admin ينشر إعلان | Admin | حسب النطاق (الجميع/صف/فرد) | Expo Push | `{ title, body, published_at }` |

**نوع Laravel Event:** `AnnouncementSent`
**نوع Laravel Notification:** `AnnouncementNotification`

---

### 7. إشعارات "أنا قادم" (Pickup Alert)

| الحدث | المُرسِل | المُستقبِل | القناة | البيانات |
|-------|---------|----------|--------|---------|
| ولي أمر يضغط "أنا قادم" | ولي الأمر | جميع معلمي صف الطفل | Expo Push | `{ student_name, parent_name, class_name, estimated_minutes, created_at }` |

**ملاحظة:** هذا الإشعار عالي الأولوية — يجب أن يصل فورًا بصوت/اهتزاز مميز.
**نوع Laravel Event:** `ParentOnTheWay`
**نوع Laravel Notification:** `PickupAlertNotification`

---

## تدفق الإشعار في Laravel

```
Controller
  → event(new AttendanceRecorded($student, $record))
    → Listener dispatches Job to database queue
      → Job::SendExpoPushNotification
        → Expo Push API (POST to exp.host)
        → Laravel Notification (database for in-app list)
```

---

## Expo Push Tokens

يُخزّن توكن Expo Push على موديل المستخدم (`expo_push_token`). كل مستخدم يستقبل إشعاراته عبر توكنه الخاص — لا حاجة لمواضيع (Topics) أو قنوات اشتراك.

| المخزن | الوصف |
|--------|-------|
| `users.expo_push_token` | توكن Expo Push الخاص بجهاز المستخدم |

---

## جدول الإشعارات الإلزامي حسب الوقت

| الإشعار | التوقيت | ملاحظات |
|---------|---------|---------|
| حضور | فور تسجيله (صباحًا) | - |
| فطور | فور تسجيله (~10 صباحًا) | - |
| غداء | فور تسجيله (~12 ظهرًا) | - |
| عصر/خفيفة | فور تسجيله (~3 عصرًا) | - |
| نوم | فور تسجيله (~1 ظهرًا) | فقط للصفوف التي لديها قيلولة |
| أنشطة | عند النشر | - |
| صور جديدة | عند الرفع (إذا فوري) أو عند الموافقة | - |
| إعلانات | عند النشر | - |
| "أنا قادم" | فوري | أولوية عالية |

---

## إعدادات الإشعارات لكل مستخدم (User Notification Preferences)

جدول أو إعدادات تسمح لولي الأمر بتعطيل أنواع معينة من الإشعارات:

| الإعداد | الافتراضي |
|---------|-----------|
| receive_attendance_notifications | true |
| receive_meal_notifications | true |
| receive_sleep_notifications | true |
| receive_activity_notifications | true |
| receive_photo_notifications | true |
| receive_announcement_notifications | true |

---

## اعتبارات هامة

1. **لا توجد رسائل/محادثات** — تم إلغاء نظام المراسلة بناءً على قرار العميل.
2. **Expo Push فقط** — هو القناة الوحيدة للإشعارات في v1، ويعمل في جميع حالات التطبيق (مفتوح، خلفية، مغلق).
3. **Expo priority** لتنبيه "أنا قادم" — يُستخدم `priority: 'high'` في payload لضمان وصوله فورًا حتى في وضع Doze على Android.
4. **Localization**: نص الإشعار يكون باللغة التي يفضلها المستخدم (`en` أو `tr`) من إعدادات حسابه.
5. **الدفع (Payments) غير مشمول في v1** — لا توجد إشعارات متعلقة بالمدفوعات في هذا الإصدار.

(End of file)