docs: add sports activity workflows tutorial (Arabic)

Covers: registration desk, coach assessment, group coaches,
training attendance, swimming coaches/lanes, medical certificates,
monthly subscription renewal, and payment flow after assessment.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/tutorials/sports-activity-workflows.md

+# دليل عمليات النشاط الرياضي — 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` |