# 13 — الإشعارات والمستندات

## نظرة عامة

### الإشعارات:
نظام إشعارات متعدد القنوات (داخل النظام، بريد إلكتروني، SMS) مع قوالب قابلة للتخصيص وتفضيلات لكل مستخدم.

### المستندات:
نظام رفع وإدارة المستندات (شهادات طبية، إثبات هوية، شهادات مؤهلات) مع دورة موافقة.

---

## شاشات الإشعارات

### 1. مركز الإشعارات (`/notifications`)

**من يراها:** أي مستخدم مسجّل

**المحتوى:**
- قائمة إشعارات المستخدم (مقروءة وغير مقروءة)
- زر "تحديد الكل كمقروء"
- تصفية: الكل / غير مقروءة فقط

---

### 2. قوالب الإشعارات (`/notifications/templates`)

**من يراها:** من لديه صلاحية `notifications.manage`

**القائمة:**
| العمود | الوصف |
|--------|-------|
| الحدث | event_type |
| القناة | channel (in_app, email, sms) |
| اللغة | locale |
| العنوان | subject |
| مفعّل | is_active |

---

### 3. إنشاء/تعديل قالب (`/notifications/templates/create`, `/notifications/templates/{id}/edit`)

**الحقول:**
| الحقل | النوع | مطلوب | ملاحظات |
|--------|------|-------|---------|
| الحدث | select | ✓ | enrollment_created, payment_received, etc. |
| القناة | select | ✓ | in_app, email, sms |
| اللغة | select | ✓ | ar, en |
| العنوان | text | ✓ | يدعم متغيرات {{name}}, {{amount}} |
| المحتوى | textarea | ✓ | يدعم متغيرات |
| مفعّل | toggle | — | |

**المتغيرات المتاحة:**
- `{{participant_name}}` — اسم المشترك
- `{{amount}}` — المبلغ
- `{{date}}` — التاريخ
- `{{group_name}}` — اسم المجموعة
- `{{academy_name}}` — اسم الأكاديمية

**قاعدة:** كل المتغيرات في القالب يجب أن تُملأ عند الإرسال — إذا ناقصة → exception.

---

### 4. سجل الإشعارات (`/notifications/logs`)

**من يراها:** من لديه صلاحية `notifications.manage`

**أعمدة:**
| العمود | الوصف |
|--------|-------|
| التاريخ | created_at |
| المستلم | recipient |
| القناة | channel |
| الحدث | event_type |
| الحالة | sent, failed, pending |
| سبب الفشل | error_message |

---

### 5. رسائل جماعية (`/messaging`)

**من يراها:** من لديه صلاحية `notifications.manage`

**الحقول:**
| الحقل | النوع | مطلوب |
|--------|------|-------|
| المستلمين | multi-select | ✓ | بالمجموعة / البرنامج / يدوي |
| القناة | select | ✓ | sms, email, in_app |
| العنوان | text | مشروط | مطلوب للبريد |
| المحتوى | textarea | ✓ | |

---

### 6. تفضيلات الإشعارات (`/profile/notifications`)

**من يراها:** أي مستخدم

**المحتوى:**
- لكل نوع حدث: تفعيل/تعطيل البريد والـ SMS
- ملاحظة: الإشعارات داخل النظام لا يمكن تعطيلها

---

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

```mermaid
flowchart TD
    A[حدث في النظام] --> B[Listener]
    B --> C[NotificationService]
    C --> D[تحديد المستلمين]
    D --> E[قراءة تفضيلات كل مستلم]
    E --> F{القناة مفعّلة؟}
    F -->|نعم| G[تحميل القالب]
    F -->|لا| H[تخطي]
    G --> I[تعبئة المتغيرات]
    I --> J[إرسال]
    J --> K[تسجيل في notification_logs]
```

---

## أنواع الأحداث المُشعَر عنها

| الحدث | المستلم | القنوات |
|-------|---------|---------|
| تسجيل مشترك جديد | ولي الأمر + إدارة | in_app, email |
| دفعة مستلمة | ولي الأمر | in_app, email, sms |
| فاتورة متأخرة | ولي الأمر | in_app, sms |
| اقتراب موعد قسط | ولي الأمر | in_app, sms |
| غياب مشترك | ولي الأمر | in_app, sms |
| إيقاف مشترك | ولي الأمر + إدارة | in_app, email, sms |
| تجميد مشترك | ولي الأمر | in_app |
| تقييم جديد | ولي الأمر | in_app, email |
| إلغاء حصة | المشتركون + أولياء الأمور | in_app, sms |
| فتح مكان (قائمة انتظار) | ولي الأمر | in_app, sms |
| اكتمال اشتراك | ولي الأمر | in_app, email |
| مخزون منخفض | الإدارة | in_app |
| إقفال وردية | الإدارة | in_app |
| تعثر خطة دفع | ولي الأمر + إدارة | in_app, sms |
| صرف راتب | المدرب | in_app |
| عيد ميلاد | المشترك/ولي الأمر | in_app, sms |
| تقرير أسبوعي | ولي الأمر | email |
| شهادة طبية تنتهي | الإدارة | in_app |

---

## شاشات المستندات

### 1. رفع مستند (`/documents/upload/{type}/{id}`)

**ويزارد من 3 خطوات:**
1. اختيار نوع المستند
2. رفع الملف
3. إدخال بيانات إضافية (تاريخ انتهاء، رقم)

**أنواع المستندات:**
| النوع | الوصف |
|-------|-------|
| medical_certificate | شهادة طبية |
| birth_certificate | شهادة ميلاد |
| national_id | بطاقة هوية |
| photo | صورة شخصية |
| qualification | مؤهل/شهادة |
| contract | عقد |
| other | أخرى |

---

### 2. قائمة طلبات الموافقة (`/documents/approvals`)

**من يراها:** من لديه صلاحية `documents.approve`

**أعمدة:**
| العمود | الوصف |
|--------|-------|
| المستند | اسم الملف + النوع |
| الكيان | المشترك أو الموظف |
| رافع المستند | اسم المستخدم |
| تاريخ الرفع | created_at |
| الحالة | pending |
| الإجراءات | مراجعة |

---

### 3. مراجعة مستند (`/documents/{id}/review`)

**من يراها:** من لديه صلاحية `documents.approve`

**المحتوى:**
- عرض المستند (صورة أو PDF)
- بيانات المستند (نوع، تاريخ انتهاء، رقم)
- أزرار: قبول / رفض
- سبب الرفض (إذا رُفض)

---

### 4. مستندات المشترك

**المكوّن:** `ParticipantDocuments` (ضمن ملف المشترك)

- قائمة المستندات المرتبطة
- حالة كل مستند (pending, approved, rejected, expired)
- تنبيه الشهادة الطبية (إذا منتهية أو تنتهي قريباً)

---

## حالات المستند

```mermaid
stateDiagram-v2
    [*] --> معلّق
    معلّق --> معتمد : موافقة
    معلّق --> مرفوض : رفض

    معتمد --> منتهي : تجاوز تاريخ الانتهاء
    مرفوض --> معلّق : إعادة رفع
```

---

## انتهاء المستندات

**المهمة المجدولة:** `documents:expire` (يومياً 06:00)

**الآلية:**
- مستندات معتمدة + تاريخ انتهاء < اليوم → حالة "expired"
- إشعار للإدارة

---

## أمثلة عملية

### مثال 1: رفع شهادة طبية
> 1. ولي الأمر يرفع شهادة طبية لابنه
> 2. الحالة: "pending" (تنتظر موافقة)
> 3. الإدارة تراجع → "approved" + تاريخ انتهاء: بعد 6 أشهر
> 4. قبل الانتهاء بأسبوع: تنبيه "شهادة أحمد الطبية تنتهي قريباً"
> 5. بعد الانتهاء: "expired" + تنبيه

### مثال 2: رسالة جماعية
> 1. المدير يريد إرسال تذكير لمشتركي مجموعة الأحد
> 2. يختار: مستلمين = مجموعة "أحد-ثلاثاء"، قناة = SMS
> 3. يكتب الرسالة: "تذكير: غداً حصة تدريب الساعة 4 مساءً"
> 4. يُرسل → تُسجّل في logs

### مثال 3: تفضيلات إشعارات
> - ولي أمر يعطّل SMS لإشعارات الحضور (يكتفي بداخل النظام)
> - لكن يُبقي SMS للفواتير المتأخرة (مهم)
> - النظام يحترم تفضيلاته

---

## لماذا يحتاج عملك هذا

| الميزة | الفائدة |
|--------|---------|
| قوالب مخصصة | كل أكاديمية تصيغ رسائلها بأسلوبها |
| تفضيلات المستخدم | لا إزعاج — كل شخص يختار ما يريد |
| سجل الإشعارات | إثبات أن الرسالة أُرسلت (لحل النزاعات) |
| المستندات + انتهاء | لا مشترك بشهادة طبية منتهية يتدرب |
| دورة الموافقة | لا مستند يُعتمد بدون مراجعة |
| الرسائل الجماعية | تواصل سريع مع مجموعة كاملة |

---

## التكاملات

| الوحدة | العلاقة |
|--------|---------|
| المشتركين | مستندات + إشعارات لأولياء الأمور |
| الموارد البشرية | مستندات ومؤهلات الموظفين |
| المالية | إشعارات فواتير وأقساط |
| الحضور | إشعارات غياب وإيقاف |
| التسجيل | إشعارات تسجيل وانتظار |
