# دليل عمليات النشاط الرياضي — Sports Activity Workflows

---

## 1. مكتب الاشتراكات — تسجيل لاعب جديد

### الهدف
تسجيل لاعب (عضو أو غير عضو) في النشاط الرياضي، دفع رسوم التسجيل، التقاط صورة، واختيار الأنشطة المطلوبة.

### المسار
`/sa/registration`

### الخطوات

#### خطوة 1: إدخال البيانات
1. ادخل على **مكتب الخدمة** ← **التسجيل الرياضي** من الشريط الجانبي
2. أدخل **رقم العضوية** (للأعضاء — يملأ الاسم والهاتف والرقم القومي تلقائياً)
3. أو أدخل **الرقم القومي** (14 رقم — يستخرج تاريخ الميلاد والنوع تلقائياً)
4. أكمل الاسم بالعربي + هاتف ولي الأمر (إن وُجد)
5. اضغط **بدء التسجيل**

> **ملاحظة**: إذا كان الشخص عضو في النادي (موجود في قاعدة البيانات)، يدفع **50 ج.م**. غير الأعضاء يدفعون **100 ج.م**.

#### خطوة 2: الدفع (Step 1 في الويزارد)
- تظهر شاشة الدفع بالمبلغ المطلوب
- اضغط **إرسال للخزينة**
- يتم إنشاء طلب دفع يظهر عند الخزينة في طابور الدفع
- بعد ما الخزينة تحصّل المبلغ → الويزارد يتقدم تلقائياً

> **لاعب عائد** (سبق ودفع رسوم التسجيل قبل كده): يتخطى هذه الخطوة مباشرة.

#### خطوة 3: التقاط الصورة (Step 2)
- افتح الكاميرا أو ارفع ملف صورة
- اضغط **التالي**

#### خطوة 4: اختيار الأنشطة (Step 3)
- اختر النشاط/الأنشطة المطلوبة (كرة قدم، سباحة، كاراتيه، إلخ)
- هذا لا يعيّن مجموعة — فقط يسجل رغبة اللاعب
- اضغط **حفظ الأنشطة المختارة**

#### خطوة 5: الاستلام (Step 4)
- **طباعة الاستمارة** — استمارة ورقية بالبيانات + QR
- **إنشاء الكارت** — كارت النشاط الرياضي (يعمل فقط بعد اكتمال الدفع)
- **طباعة الكارت** — بعد إنشائه

### النتيجة
اللاعب مسجل بحالة `completed` وينتظر **التقييم الفني من المدرب**.

---

## 2. تقييم المدرب — تعيين لاعب في مجموعة

### الهدف
المدرب يقيّم اللاعب فنياً ويعيّنه في المجموعة المناسبة.

### المسار
`/sa/coach-assessment`

### من يستخدمه
المدرب أو الإدارة (صلاحية `sa.coach_assessment.view` + `sa.coach_assessment.manage`)

### الخطوات

#### خطوة 1: فتح شاشة التقييم
1. من الشريط الجانبي ← **تقييم اللاعبين** (تحت قسم "── تقييم المدربين ──")
2. تظهر قائمة اللاعبين المنتظرين للتقييم
3. إذا المدرب مرتبط بنشاط معين (مثلاً كاراتيه)، يرى فقط اللاعبين اللي اختاروا الكاراتيه
4. يمكن فلترة بنشاط معين من القائمة المنسدلة

#### خطوة 2: تقييم لاعب
1. اضغط **تقييم** بجانب اسم اللاعب
2. تفتح صفحة التقييم:
   - بيانات اللاعب + الأنشطة المطلوبة ظاهرة
   - اختر **المستوى**: مبتدئ / متوسط / متقدم
   - اكتب **ملاحظات** (اختياري)
   - اختر **المجموعة** من القائمة (مفلترة حسب أنشطة اللاعب المختارة)
3. اضغط **تأكيد التقييم والتعيين**

### ماذا يحدث بعد التأكيد
- اللاعب يُضاف للمجموعة بحالة `active`
- يُنشأ اشتراك شهري بمبلغ المجموعة (عضو/غير عضو)
- **يُرسل طلب دفع للخزينة** (اشتراك شهري) — يظهر في طابور الدفع
- حالة التسجيل تتحول إلى `assessed`

### الدورة الكاملة: تقييم ← خزينة
1. المدرب يقيّم ويعيّن ← تسجيل "assessed"
2. طلب دفع اشتراك يظهر في الخزينة
3. اللاعب يروح يدفع
4. الخزينة تحصّل ← الاشتراك يُعلّم "paid" تلقائياً

---

## 3. تعيين مدربين على المجموعات

### الهدف
إضافة مدرب أساسي + مدربين مساعدين على مجموعة واحدة.

### المسار
`/sa/groups` ← إنشاء أو تعديل مجموعة

### الخطوات

#### عند إنشاء مجموعة جديدة
1. اذهب إلى **المجموعات** ← **إنشاء مجموعة**
2. اختر البرنامج + الاسم + السعة
3. **المدرب الأساسي** — اختره من القائمة (مطلوب)
4. **مدربين مساعدين** — اختر واحد أو أكثر (اختياري)
5. احفظ

#### تعديل مدربين مجموعة قائمة
1. اذهب إلى **المجموعات** ← اختر المجموعة ← **تعديل**
2. غيّر المدرب الأساسي أو أضف/أزل مساعدين
3. احفظ

### الأدوار
- `primary` — المدرب الأساسي (واحد فقط)
- `assistant` — مدرب مساعد (عدد غير محدود)

---

## 4. حضور التدريب

### الهدف
تسجيل حضور/غياب اللاعبين في التدريبات اليومية.

### المسار
`/sa/training-attendance`

### من يستخدمه
المدرب أو الإدارة (صلاحية `sa.attendance.manage`)

### الخطوات

#### خطوة 1: اختيار اليوم والمجموعة
1. من الشريط الجانبي ← **حضور التدريب**
2. اختر التاريخ (افتراضي: اليوم)
3. تظهر المجموعات المجدولة لهذا اليوم (حسب `sa_group_schedule`)
4. اضغط **تسجيل حضور** بجانب المجموعة

#### خطوة 2: تسجيل الحضور
1. تظهر قائمة لاعبي المجموعة النشطين
2. لكل لاعب اختر: **حاضر** / **غائب** / **معذور** / **متأخر** / **تعويضي**
3. اضغط **حفظ**

### التنبيهات الآلية
- إذا تجاوز لاعب حد الغياب (افتراضي 5 مرات/شهر) ← SMS لولي الأمر تلقائياً
- يمكن رؤية التقرير من `/sa/training-attendance/report`

### معلومات المجموعة
- كل مجموعة تظهر: اسمها + المدرب + عدد اللاعبين
- من صفحة المجموعة (`/sa/groups/{id}`) يمكن رؤية:
  - المدرب الأساسي + المساعدين
  - قائمة اللاعبين + حالة كل واحد
  - جدول التدريب الأسبوعي

---

## 5. مدربين السباحة (Freelance) — حجز حارات

### الهدف
إدارة مدربين السباحة المستقلين وحجز حارات لهم.

### المسار
`/sa/swimming/coaches` — إدارة المدربين
`/sa/mirror/pool/{facility_id}` — مراية حمام السباحة (حجز الحارات)

### إضافة مدرب سباحة
1. من الشريط الجانبي ← **مدربين السباحة** (تحت قسم "── السباحة ──")
2. اضغط **إضافة مدرب**
3. أدخل: الاسم + الرقم القومي + الهاتف + نوع التعاقد (freelance/staff/contract)
4. يُربط تلقائياً بنشاط "السباحة"

### حجز حارة لمدرب Freelance
1. اذهب إلى **المراية** ← **مراية حمام السباحة** (أو `/sa/mirror/pool/{id}`)
2. تظهر شبكة الحارات × المواعيد (grid)
3. حدد الخانات (حارة + وقت) المطلوبة
4. اختر نوع الحجز: **hourly**
5. اختر المجموعة/المدرب
6. احفظ

### التحقق من التوفر
- الشبكة تظهر الخانات المحجوزة بألوان مختلفة:
  - أخضر = تدريب (training)
  - أزرق = حجز ساعي (hourly) — freelance
  - رمادي = مقفول (blocked)
  - أحمر = صيانة (maintenance)
- لا يمكن حجز خانة محجوزة بالفعل (unique constraint)
- المراية في real-time — كل حجز يظهر فوراً

### عدد أفراد الحارة
- نظام Open Access (`open_access`) فيه `max_occupancy` لكل منطقة
- إذا المنطقة وصلت الحد الأقصى → لا يمكن إصدار تذاكر إضافية
- تذاكر السباحة (`/sa/pool-tickets`) تتحكم في الإشغال

### تذاكر الدخول (Booking Passes)
- عند حجز ساعي بنمط "passes" ← تُنشأ تذاكر دخول لكل فرد
- رقم التذكرة: `{رقم_الحجز}-P01`, `P02`, ...
- عند البوابة: يُمسح رقم التذكرة ← تُعلّم "مستخدمة"
- تذاكر غير مستخدمة تنتهي صلاحيتها بعد الحجز

---

## 6. الشهادات الطبية

### الهدف
كل لاعب يحتاج شهادة طبية سارية للتدريب. بدونها يُوقف الاشتراك.

### المسار
`/medical-board` — لجنة الفحص الطبي

### أنواع الشهادات
| النوع | المدة |
|-------|-------|
| ترفيهي (recreational) | 12 شهر |
| أكاديمي (academy) | 6 شهور |
| دولي (international) | 3 شهور |

### الدورة الكاملة

#### خطوة 1: تقديم الشهادة
- من صفحة اللاعب ← رفع شهادة طبية (صورة/PDF)
- أو من تطبيق الموبايل (Player API)
- الحالة: `pending`

#### خطوة 2: المراجعة والاعتماد
1. اذهب إلى **لجنة الفحص الطبي** (`/medical-board`)
2. تظهر الشهادات المنتظرة من كلا المصدرين (عضوية + نشاط رياضي)
3. لكل شهادة:
   - **اعتماد** — يحدد تاريخ الانتهاء ← `medical_status = fit`
   - **رفض** — `medical_status = unfit` ← اللاعب لا يمكنه التدريب

#### خطوة 3: التأثير على الاشتراكات
- عند توليد اشتراكات شهرية ← يتم التحقق من الشهادة الطبية
- إذا منتهية: الاشتراك يُنشأ لكن `medical_verified = 0`

#### خطوة 4: التذكيرات والإيقاف (Cron — يومياً)
- **قبل 30 يوم من الانتهاء** ← تذكير SMS
- **بعد الانتهاء** ← `medical_status = expired`
- **بعد انتهاء فترة السماح** ← إيقاف التسجيل في المجموعة + إنقاص عداد المجموعة

---

## 7. تجديد الاشتراك الشهري

### الهدف
كل أول شهر يُنشأ اشتراك جديد لكل لاعب نشط في مجموعاته.

### المسار
`/sa/subscriptions` → زر **توليد اشتراكات**

### من يستخدمه
الإدارة (صلاحية `sa.subscription.generate`)

### الخطوات

#### خطوة 1: توليد الاشتراكات
1. اذهب إلى **الاشتراكات** (`/sa/subscriptions`)
2. اضغط **توليد اشتراكات**
3. اختر الشهر (مثلاً `2026-08`)
4. اضغط **توليد**

#### ماذا يحدث
- يتم جلب كل لاعب نشط (`sa_group_players.status = active`) في مجموعة نشطة
- يُتحقق من عدم وجود اشتراك مسبق لنفس الشهر
- يُتحقق من حالة الشهادة الطبية
- يُنشأ سجل `sa_subscriptions` بحالة `unpaid`
- المبلغ حسب نوع اللاعب:
  - عضو ← `monthly_fee_member` (من البرنامج)
  - غير عضو ← `monthly_fee_nonmember`
- لو أول شهر للاعب ودخل بعد يوم 15 ← المبلغ ينخفض للنصف

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

### الاشتراك المتأخر
- Cron يومي يعلّم الاشتراكات المنتهية (`period_end < today`) بحالة `overdue`
- يرسل SMS لولي الأمر

---

## 8. دورة الدفع بعد تعيين المدرب — من التقييم للخزينة

### الهدف
بعد ما المدرب يعيّن لاعب في مجموعة ← اللاعب يروح الخزينة يدفع اشتراك الشهر.

### الدورة

```
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  المدرب يقيّم   │────▶│  طلب دفع يُنشأ  │────▶│  يظهر في الخزينة│
│  ويعيّن مجموعة  │     │  (sports_subscription) │  │  (طابور الدفع)  │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                                          │
                                                          ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│  الاشتراك paid  │◀────│  Event يُطلق     │◀────│  الخزينة تحصّل  │
│  تلقائياً       │     │  payment_request  │     │  المبلغ         │
└─────────────────┘     │  .completed       │     └─────────────────┘
                        └──────────────────┘
```

### الخطوات التفصيلية

1. **المدرب** يفتح `/sa/coach-assessment` ← يقيّم لاعب ← يختار مجموعة ← يأكد
2. **النظام** ينشئ:
   - تسجيل في المجموعة (`sa_group_players`)
   - اشتراك شهري (`sa_subscriptions`) بحالة `unpaid`
   - طلب دفع (`payment_requests`) بنوع `sports_subscription`
3. **طابور الخزينة** — الطلب يظهر في خزينة النشاط الرياضي (SUB_SA)
4. **اللاعب/ولي الأمر** يذهب للخزينة ← يدفع المبلغ
5. **الخزينة** تحصّل ← event `payment_request.completed` يُطلق
6. **Event Listener** (`SaEventListenerService::handleSubscriptionPaid`) يعلّم الاشتراك `paid`

### ملاحظة مهمة
اللاعب يكون نشط في المجموعة فوراً بعد التقييم (لا ينتظر الدفع). الدفع يحصل بالتوازي ولا يمنع الحضور.

---

## ملخص المسارات

| الخطوة | من يفعلها | أين |
|--------|----------|-----|
| تسجيل لاعب جديد | مكتب الاشتراكات | `/sa/registration` |
| دفع رسوم التسجيل | الخزينة | طابور الدفع |
| تقييم فني + تعيين مجموعة | المدرب | `/sa/coach-assessment` |
| دفع اشتراك شهري | الخزينة | طابور الدفع |
| تسجيل حضور يومي | المدرب | `/sa/training-attendance` |
| توليد اشتراكات شهرية | الإدارة | `/sa/subscriptions` → توليد |
| اعتماد شهادة طبية | لجنة الفحص | `/medical-board` |
| حجز حارة سباحة | الإدارة | `/sa/mirror/pool/{id}` |
| إدارة مدربين سباحة | الإدارة | `/sa/swimming/coaches` |
