# 04 — التسجيل في المجموعات (Enrollment)

## نظرة عامة

التسجيل هو ربط مشترك بمجموعة تدريبية. يشمل:
- التحقق من الأهلية (العمر، الجنس، المستوى، التوفر)
- حساب السعر
- إنشاء فاتورة
- تفعيل الاشتراك بعد الدفع
- إدارة قائمة الانتظار
- النقل بين المجموعات

---

## الشاشات المنفذة

### 1. قائمة التسجيلات (`/enrollments`)

**من يراها:** من لديه صلاحية `enrollments.list`

**الفلاتر:**
- بحث بالاسم أو رقم المشترك
- تصفية بالبرنامج
- تصفية بالمجموعة
- تصفية بالحالة

**أعمدة الجدول:**
| العمود | الوصف |
|--------|-------|
| المشترك | اسم المشترك |
| المجموعة | اسم المجموعة |
| البرنامج | اسم البرنامج |
| تاريخ البدء | start_date |
| تاريخ الانتهاء | end_date |
| حالة الدفع | paid/pending/partial/overdue/waived |
| الحالة | شارة ملونة |
| الإجراءات | — |

**التصدير:** زر تصدير Excel (`/export/enrollments`)

---

### 2. تسجيل مشترك في مجموعة (`/enrollments/create`)

**من يراها:** من لديه صلاحية `enrollments.create`

**الحقول:**
| الحقل | النوع | مطلوب | ملاحظات |
|--------|------|-------|---------|
| المشترك | select/search | ✓ | بحث بالاسم أو الرقم |
| المجموعة | select | ✓ | تُعرض المجموعات المتاحة فقط |
| تاريخ البدء | date | ✗ | افتراضي: اليوم |
| حالة الدفع | select | ✓ | paid, pending, partial, overdue, waived |
| ملاحظات | textarea | ✗ | حتى 1000 حرف |

**التحققات عند الحفظ:**
1. هل المشترك مسجّل بالفعل في هذه المجموعة؟ → رفض
2. هل المجموعة ممتلئة؟ → إضافة لقائمة الانتظار (أو رفض إذا لا توجد قائمة انتظار)
3. هل المشترك مؤهل (عمر، جنس، مستوى)؟
4. هل المشترك موقوف أو محظور؟ → رفض

```mermaid
flowchart TD
    A[طلب تسجيل] --> B{مسجّل بالفعل؟}
    B -->|نعم| C[رفض: مسجل بالفعل]
    B -->|لا| D{المشترك مؤهل؟}
    D -->|لا| E[رفض: غير مؤهل]
    D -->|نعم| F{المجموعة ممتلئة؟}
    F -->|لا| G[تسجيل مباشر]
    F -->|نعم| H{قائمة انتظار مفعّلة؟}
    H -->|نعم| I[إضافة لقائمة الانتظار]
    H -->|لا| J[رفض: لا أماكن]
    G --> K[حساب السعر]
    K --> L[إنشاء فاتورة]
    L --> M{الدفع تم؟}
    M -->|نعم| N[حالة: نشط]
    M -->|لا| O[حالة: معلّق]
    N --> P[توليد سجلات حضور]
```

---

### 3. إدارة قائمة الانتظار (`/enrollments/waitlist`)

**من يراها:** من لديه صلاحية `enrollments.list`

**الفلاتر:**
- بحث بالاسم
- تصفية بالمجموعة
- تصفية بالبرنامج

**أعمدة الجدول:**
| العمود | الوصف |
|--------|-------|
| المشترك | الاسم |
| المجموعة | اسم المجموعة |
| تاريخ الإضافة | created_at |
| الترتيب | الأولوية في القائمة |
| الإجراءات | تأكيد التسجيل، حذف |

**السلوك عند فتح مكان:**
1. أول شخص في القائمة يحصل على إشعار
2. لديه مهلة محددة (configurable) للرد
3. إذا لم يرد: ينتقل للتالي
4. عند القبول: يُنقل من waitlisted إلى pending ثم active بعد الدفع

---

### 4. نقل بين المجموعات (`/enrollments/transfer`)

**من يراها:** من لديه صلاحية `enrollments.create`

**الحقول:**
- المشترك
- المجموعة الحالية
- المجموعة الجديدة
- سبب النقل

**السلوك:**
1. الاشتراك القديم → ملغى
2. اشتراك جديد في المجموعة الجديدة
3. سجلات الحضور المستقبلية تُنقل
4. عداد المجموعة القديمة -1
5. عداد المجموعة الجديدة +1

---

### 5. ويزارد نقل مشترك (`/enrollments/transfer-wizard`)

**من يراها:** من لديه صلاحية `enrollments.create`

**خطوات الويزارد:**
1. اختيار المشترك والاشتراك الحالي
2. اختيار المجموعة الجديدة
3. مراجعة التأثيرات (حضور، مالية)
4. تأكيد النقل

---

## حالات التسجيل (Enrollment Status)

```mermaid
stateDiagram-v2
    [*] --> معلّق
    معلّق --> نشط : بعد الدفع أو يدوي
    معلّق --> ملغى : إلغاء قبل التفعيل
    معلّق --> قائمة_انتظار : المجموعة ممتلئة

    قائمة_انتظار --> معلّق : فتح مكان + قبول
    قائمة_انتظار --> ملغى : انسحاب

    نشط --> مكتمل : انتهاء البرنامج
    نشط --> ملغى : إلغاء
    نشط --> منتهي : انتهاء المدة بدون تجديد
```

| الحالة | المعنى |
|--------|--------|
| pending | معلّق — بانتظار الدفع |
| active | نشط — يحضر التدريب |
| completed | مكتمل — أنهى البرنامج |
| cancelled | ملغى — إلغاء يدوي |
| expired | منتهي — انتهت المدة |
| waitlisted | في قائمة الانتظار |

---

## إنهاء الاشتراكات المنتهية

**المهمة المجدولة:** `enrollments:deactivate-expired` (يومياً 00:30)

**الآلية:**
- اشتراكات حالتها "نشط" وتاريخ انتهائها مرّ
- تُحوّل إلى "منتهي"
- تُزال سجلات الحضور المستقبلية
- عداد المجموعة يُنقّص

---

## تنبيه اشتراكات تنتهي قريباً

**المهمة المجدولة:** `reminders:expiring-enrollments` (يومياً 10:00 و 10:30)
- قبل 7 أيام: تذكير أول
- قبل 3 أيام: تذكير ثاني

---

## دورة العمل — تسجيل مشترك مع قائمة انتظار

```mermaid
sequenceDiagram
    participant R as الاستقبال
    participant S as النظام
    participant W as ولي الأمر (في الانتظار)

    R->>S: طلب تسجيل مشترك في مجموعة ممتلئة
    S-->>R: المجموعة ممتلئة — إضافة لقائمة الانتظار؟
    R->>S: نعم
    S->>S: إضافة لقائمة الانتظار (ترتيب 3)
    S-->>R: ✓ أُضيف — حالة: waitlisted

    Note over S: --- بعد أسبوع: مشترك آخر ينسحب ---
    S->>S: عداد المجموعة: 19/20
    S->>S: فحص قائمة الانتظار
    S->>W: إشعار: "يوجد مكان متاح — هل تريد التأكيد؟"
    W->>S: نعم أريد التسجيل
    S->>S: نقل من waitlisted → pending
    S->>S: إنشاء فاتورة
    R->>S: تحصيل الدفعة
    S->>S: pending → active
    S->>S: توليد سجلات الحضور
```

---

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

### مثال 1: تسجيل عادي ناجح
> 1. اختيار مشترك "أحمد" + مجموعة "السبت-الاثنين"
> 2. التحقق: مؤهل (عمر 7، المجموعة ليست ممتلئة)
> 3. حساب السعر: 1500 ج.م/شهر
> 4. إنشاء فاتورة
> 5. الدفع الفوري → حالة "نشط"
> 6. توليد 12 سجل حضور (4 أسابيع × 3 حصص)

### مثال 2: تسجيل بدون دفع
> 1. الاستقبال يسجّل المشترك بحالة دفع "pending"
> 2. حالة الاشتراك: "pending" (لا يحضر بعد)
> 3. لا تُولّد سجلات حضور حتى يدفع
> 4. بعد أسبوع: الأب يأتي ويدفع
> 5. الاشتراك يتفعّل → سجلات الحضور تُولّد

### مثال 3: نقل مشترك لمجموعة أخرى
> 1. "سارة" مسجلة في مجموعة السبت/الاثنين
> 2. الأم تطلب نقلها لمجموعة الأحد/الثلاثاء
> 3. نقل: إلغاء القديم + تسجيل جديد
> 4. سجلات الحضور المستقبلية تُحذف من القديمة وتُنشأ في الجديدة
> 5. التاريخ السابق محفوظ

### مثال 4: مشترك موقوف يحاول التسجيل
> 1. "محمد" حالته "موقوف" (5 غيابات متتالية)
> 2. الاستقبال يحاول تسجيله في مجموعة
> 3. النظام يرفض: "لا يمكن تسجيل مشترك موقوف"
> 4. يجب رفع الإيقاف أولاً

---

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

| الميزة | الفائدة |
|--------|---------|
| قائمة الانتظار | لا تفقد عملاء محتملين عندما المجموعة ممتلئة |
| الربط بالدفع | الاشتراك يتفعّل فقط بعد الدفع — لا مجاملات |
| النقل | مرونة لتلبية طلبات أولياء الأمور بدون إعادة بناء |
| الإنهاء التلقائي | لا اشتراكات "شبح" — تُنظّف تلقائياً |
| التذكير بالتجديد | يذكّر أولياء الأمور قبل الانتهاء — أقل عملاء مفقودين |
| التصدير | تقرير لمن يدير عدة مجموعات يريد نظرة شاملة |

---

## التكاملات

| الوحدة | العلاقة |
|--------|---------|
| المشتركين | المشترك هو صاحب التسجيل |
| المجموعات | المجموعة هي هدف التسجيل |
| المالية | إنشاء فاتورة عند التسجيل |
| التسعير | حساب السعر عند التسجيل |
| الحضور | توليد سجلات حضور عند التفعيل |
| الإشعارات | تنبيهات قائمة الانتظار والتجديد |
