# 02 — المشتركين وأولياء الأمور

## نظرة عامة

المشترك هو الشخص الذي يتدرب في الأكاديمية. يمكن أن يكون طفلاً (مرتبط بولي أمر) أو بالغاً.
النظام يفصل بين "الشخص" (Person) و"المشترك" (Participant) — نفس الشخص يمكن أن يكون مشتركاً في أكثر من أكاديمية.

---

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

### 1. قائمة المشتركين (`/participants`)

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

**الفلاتر:**
| الفلتر | النوع | الخيارات |
|--------|------|----------|
| بحث | نص حر | اسم، هاتف، رقم المشترك |
| الحالة | select | مسجل، نشط، مجمد، موقوف، غير نشط، متخرج، محول، منسحب، محظور |
| النشاط | select | قائمة الأنشطة المفعّلة |
| مستوى المهارة | select | مبتدئ، متوسط، متقدم، محترف |

**أعمدة الجدول:**
| العمود | الوصف |
|--------|-------|
| رقم المشترك | participant_number (يُولّد تلقائياً) |
| الاسم | person.name_ar |
| النشاط الأساسي | primary_activity.name_ar |
| الحالة | شارة ملونة |
| مستوى المهارة | beginner/intermediate/advanced/professional |
| تاريخ التسجيل | created_at |
| الإجراءات | عرض، تعديل |

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

---

### 2. تسجيل مشترك جديد (`/participants/create`)

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

**الحقول — بيانات الشخص (إذا جديد):**
| الحقل | النوع | مطلوب | ملاحظات |
|--------|------|-------|---------|
| الاسم بالعربية | text | ✓ | |
| الاسم بالإنجليزية | text | ✓ | |
| الرقم القومي | text | ✗ | 14 رقم — يستنتج منه تاريخ الميلاد والجنس |
| تاريخ الميلاد | date | ✗ | |
| الجنس | select | ✓ | ذكر / أنثى |
| الهاتف | text | ✗ | |
| البريد الإلكتروني | email | ✗ | |

**الحقول — بيانات المشترك:**
| الحقل | النوع | مطلوب | ملاحظات |
|--------|------|-------|---------|
| الفرع | select | ✗ | يأخذ الفرع النشط تلقائياً |
| مصدر التسجيل | select | ✓ | walk_in, online, referral, social_media, event, transfer, other |
| النشاط الأساسي | select | ✗ | قائمة الأنشطة المفعّلة |
| ولي الأمر الأساسي | select | ✗ | |
| مستوى المهارة | select | ✗ | مبتدئ، متوسط، متقدم، محترف |
| نوع العضوية | select | ✗ | عضو / غير عضو |
| رقم العضوية | text | مشروط | مطلوب إذا نوع العضوية = عضو — فريد بالفرع |
| إفادة طبية | toggle | — | |
| تاريخ انتهاء الإفادة | date | ✗ | |
| رقم التيشيرت | number | ✗ | 0-999 |
| مقاس التيشيرت | text | ✗ | |
| مقاس الحذاء | text | ✗ | |
| اليد المسيطرة | select | ✗ | يسار، يمين، كلاهما |
| القدم المسيطرة | select | ✗ | يسار، يمين، كلاهما |
| الطول (سم) | number | ✗ | 50-250 |
| الوزن (كجم) | number | ✗ | 10-200 |
| ملاحظات | textarea | ✗ | |

**ميزة الاكتشاف التلقائي:** عند إدخال الرقم القومي يتم استنتاج تاريخ الميلاد والجنس تلقائياً (خدمة NationalIdService).

**ميزة كشف التكرار:** النظام يبحث عن مشتركين بنفس الاسم أو الرقم القومي ويحذر قبل الإنشاء (DuplicateDetectionService).

```mermaid
flowchart TD
    A[موظف الاستقبال يبدأ تسجيل جديد] --> B{شخص موجود؟}
    B -->|نعم| C[اختيار الشخص من القائمة]
    B -->|لا| D[إدخال بيانات شخص جديد]
    C --> E[إدخال بيانات المشترك]
    D --> E
    E --> F{كشف التكرار}
    F -->|وُجد تطابق| G[تحذير + خيار المتابعة]
    F -->|لا يوجد| H[حفظ]
    G --> H
    H --> I[مشترك جديد بحالة 'مسجل']
```

---

### 3. ملف المشترك (`/participants/{id}`)

**من يراها:** من لديه صلاحية `participants.view`

**التبويبات:**

#### تبويب المعلومات الأساسية:
- الاسم، الجنس، تاريخ الميلاد، العمر
- رقم المشترك، رقم العضوية
- النشاط الأساسي، مستوى المهارة
- مصدر التسجيل
- ولي الأمر الأساسي
- البيانات البدنية (طول، وزن، يد/قدم مسيطرة)
- الإفادة الطبية وتاريخ انتهائها

#### تبويب الاشتراكات النشطة:
- المجموعات المسجّل فيها حالياً
- البرنامج لكل مجموعة
- المدرب الرئيسي
- جدول الحصص

#### تبويب الحضور (ملخص):
| المؤشر | القيمة |
|--------|--------|
| إجمالي الحصص | عدد |
| حاضر | عدد |
| متأخر | عدد |
| غائب | عدد |
| جزئي | عدد |
| نسبة الحضور | % |

**معادلة نسبة الحضور:**
```
(حاضر + متأخر + جزئي) ÷ (الإجمالي - ملغى - معفى) × 100
```

#### تبويب المدفوعات (آخر 10):
- تاريخ الدفع، المبلغ، طريقة الدفع، الفاتورة المرتبطة

#### تبويب المحفظة:
- الرصيد الحالي (إن وُجدت محفظة)

#### تغيير الحالة:
زر يفتح نافذة منبثقة تطلب:
- الحالة الجديدة (يظهر فقط الحالات المسموح الانتقال إليها)
- سبب التغيير (مطلوب — 3 حروف على الأقل)

---

### 4. تعديل مشترك (`/participants/{id}/edit`)

**من يراها:** من لديه صلاحية `participants.update`

نفس نموذج الإنشاء مع تعبئة البيانات الحالية.

---

### 5. تجميد مشترك (Freeze)

**المكوّن:** `FreezeParticipant`

**الحقول:**
- تاريخ بدء التجميد
- تاريخ نهاية التجميد (اختياري)
- سبب التجميد

**السلوك:**
- يُغيّر الحالة إلى "مجمد"
- يوقف توليد سجلات حضور مستقبلية
- يوقف الفوترة (لا تُنشأ فواتير تجديد)

---

### 6. تغيير حالة جماعي (`/participants/bulk-status`)

**من يراها:** من لديه صلاحية `participants.update`

**السلوك:**
- اختيار مجموعة مشتركين
- اختيار الحالة الجديدة
- إدخال السبب
- تنفيذ التغيير لكل المحددين

---

### 7. استيراد مشتركين (`/participants/import`)

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

**السلوك:**
- رفع ملف Excel/CSV
- معاينة البيانات قبل الاستيراد
- كشف الأخطاء والتكرارات
- استيراد الصالح فقط

---

### 8. طباعة كارت المشترك (`/participants/{id}/card`)

**من يراها:** من لديه صلاحية `participants.view`

**المحتوى:**
- اسم المشترك
- رقم المشترك
- النشاط
- الفرع
- شعار الأكاديمية
- صورة (إن وُجدت)

---

### 9. شهادة الحضور (`/participants/{id}/certificate/{enrollment}`)

**من يراها:** من لديه صلاحية `participants.view`

**المحتوى:**
- شهادة حضور للاشتراك المحدد
- اسم المشترك، البرنامج، الفترة، نسبة الحضور

---

## حالات المشترك — آلة الحالة

```mermaid
stateDiagram-v2
    [*] --> مسجل
    مسجل --> نشط : تفعيل (بعد الدفع أو يدوي)
    مسجل --> منسحب : انسحاب

    نشط --> مجمد : تجميد مؤقت
    نشط --> موقوف : 5 غيابات متتالية (تلقائي) أو يدوي
    نشط --> غير_نشط : عدم تجديد
    نشط --> متخرج : إنهاء البرنامج
    نشط --> منسحب : طلب انسحاب
    نشط --> محظور : قرار إداري

    مجمد --> نشط : إنهاء التجميد
    مجمد --> منسحب : انسحاب أثناء التجميد
    مجمد --> غير_نشط : عدم تجديد

    موقوف --> نشط : رفع الإيقاف
    موقوف --> منسحب : انسحاب
    موقوف --> محظور : تصعيد

    غير_نشط --> نشط : إعادة تفعيل

    متخرج --> نشط : تسجيل في برنامج جديد

    منسحب --> نشط : إعادة تسجيل
```

**الحالات النهائية:**
- `محول` (transferred) — لا رجعة
- `محظور` (blacklisted) — لا رجعة (إلا بتدخل super_admin)

---

## سجل تغيير الحالة (Status Timeline)

**المكوّن:** `StatusTimeline`

يعرض تسلسل زمني لكل تغييرات الحالة:
- التاريخ والوقت
- من الحالة → إلى الحالة
- السبب
- من نفّذ التغيير

---

## تاريخ الاشتراكات (Enrollment History)

**المكوّن:** `EnrollmentHistory`

يعرض كل الاشتراكات (نشطة + منتهية + ملغاة):
- البرنامج
- المجموعة
- تاريخ البدء والانتهاء
- الحالة

---

## الأشخاص (People) — الطبقة الأساسية

### قائمة الأشخاص (`/people`)
- بحث بالاسم أو الرقم القومي أو الهاتف
- الأعمدة: الاسم، الهاتف، البريد، تاريخ الميلاد

### إنشاء/تعديل شخص (`/people/create`, `/people/{id}/edit`)
| الحقل | النوع | مطلوب |
|--------|------|-------|
| الاسم بالعربية | text | ✓ |
| الاسم بالإنجليزية | text | ✗ |
| الرقم القومي | text | ✗ |
| تاريخ الميلاد | date | ✗ |
| الجنس | select | ✓ |
| الهاتف | text | ✗ |
| البريد | email | ✗ |
| العنوان | text | ✗ |

### ملف الشخص (`/people/{id}`)
- بياناته الأساسية
- المشتركين المرتبطين (إذا كان أكثر من مشترك لنفس الشخص)
- أبناؤه (إذا كان ولي أمر)

---

## أولياء الأمور (Guardians)

ولي الأمر هو شخص (Person) مرتبط بمشترك واحد أو أكثر عبر جدول وسيط `guardian_participant`.

**العلاقة:**
- ولي أمر واحد ← عدة مشتركين (أبناؤه)
- مشترك واحد ← عدة أولياء أمور (أب + أم مثلاً)
- ولي أمر أساسي (primary_guardian_id) على سجل المشترك

**لوحة ولي الأمر (`/guardian`):**
- يرى بيانات أبنائه فقط
- حضور كل ابن
- فواتير كل ابن
- تقييمات كل ابن

---

## المستندات المرتبطة بالمشترك

**المكوّن:** `ParticipantDocuments`

يُظهر المستندات المرفوعة للمشترك:
- إفادة طبية
- شهادة ميلاد
- صورة شخصية
- أي مستند آخر

**تنبيه الشهادة الطبية:** `MedicalCertificateAlert` — يظهر تنبيه إذا الشهادة الطبية تنتهي خلال 7 أيام أو منتهية.

---

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

```mermaid
sequenceDiagram
    participant R as موظف الاستقبال
    participant S as النظام
    participant G as ولي الأمر
    participant P as المشترك

    R->>S: إنشاء شخص جديد (اسم، رقم قومي، هاتف)
    S->>S: استنتاج العمر والجنس من الرقم القومي
    S->>S: كشف التكرار
    S-->>R: لا يوجد تكرار
    R->>S: إنشاء مشترك (نشاط، فرع، ولي أمر)
    S-->>R: مشترك بحالة "مسجل"
    R->>S: تسجيل في مجموعة (Enrollment)
    S->>S: حساب السعر (محرك التسعير)
    S->>S: إنشاء فاتورة
    S-->>R: فاتورة بمبلغ X ج.م
    R->>S: تحصيل الدفعة
    S->>S: تسجيل الدفع + قيد مزدوج
    S->>S: تفعيل الاشتراك
    S->>S: تغيير حالة المشترك → "نشط"
    S->>S: توليد سجلات الحضور المتوقعة
    S-->>G: إشعار: تم تسجيل ابنك
```

---

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

### مثال 1: طفل عمره 8 سنوات يسجّل في كرة قدم
> 1. ولي الأمر يأتي مع ابنه
> 2. الاستقبال يُسجّل بيانات الطفل (رقم قومي → العمر 8 سنوات تلقائياً)
> 3. يختار نشاط "كرة قدم"
> 4. يُضاف ولي الأمر كـ primary_guardian
> 5. الحالة: "مسجل"
> 6. بعد الدفع: الحالة → "نشط"

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

### مثال 3: 5 غيابات متتالية → إيقاف تلقائي
> 1. المشترك يغيب 5 حصص متتالية
> 2. المهمة المجدولة `attendance:enforce-thresholds` تكتشف ذلك
> 3. الحالة → "موقوف" تلقائياً
> 4. إشعار لولي الأمر: "تم إيقاف ابنك بسبب الغياب المتكرر"
> 5. إشعار للإدارة
> 6. لا يمكن للمشترك حضور حصص حتى يُرفع الإيقاف

### مثال 4: مشترك بعضوية نادي
> 1. عضوية نوعها "member" + رقم عضوية "M-2024-0001"
> 2. الرقم فريد داخل الفرع
> 3. يمكن أن يحصل على أسعار مختلفة (قاعدة تسعير حسب العضوية)

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

---

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

| الميزة | الفائدة |
|--------|---------|
| فصل Person عن Participant | نفس الشخص يمكن أن يكون مشتركاً + ولي أمر + موظف |
| آلة الحالة الصارمة | لا يمكن الانتقال لحالة غير منطقية (مثلاً: من "مسجل" إلى "متخرج") |
| الإيقاف التلقائي | يحفّز المشتركين على الالتزام بدون تدخل يدوي |
| كشف التكرار | يمنع تسجيل نفس الشخص مرتين بالخطأ |
| رقم العضوية | ربط النظام بأنظمة النادي الموجودة |
| البيانات البدنية | ضروري لرياضات مثل الجمباز والسباحة والكاراتيه |
| الاستيراد بالجملة | نقل 500 مشترك من نظام قديم بملف Excel واحد |
| طباعة الكارت | بطاقة هوية للمشترك عند الدخول للملعب |

---

## التكاملات مع الوحدات الأخرى

| الوحدة | العلاقة |
|--------|---------|
| التسجيل (Enrollment) | المشترك يُسجّل في مجموعات |
| المالية | الفواتير والمدفوعات مرتبطة بالمشترك |
| الحضور | سجلات الحضور مرتبطة بالمشترك |
| التقييمات | درجات التقييم مرتبطة بالمشترك |
| المحفظة | محفظة إلكترونية لكل مشترك |
| المستندات | مستندات مرفوعة (شهادة طبية، إلخ) |
| الإشعارات | إشعارات لولي الأمر عن ابنه |
| نقطة البيع | شراء منتجات |
