# 01 — الهوية والمنظمة

## نظرة عامة

هذه الوحدة هي أساس النظام بالكامل. تتحكم في:
- من يمكنه الدخول (المصادقة)
- ماذا يمكنه فعله (الصلاحيات)
- أين يعمل (الفروع)
- تحت أي مظلة (الأكاديمية)

---

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

### 1. شاشة تسجيل الدخول (`/login`)

**الوصف:** شاشة واحدة لجميع المستخدمين — الإدارة، المدربين، الاستقبال، أولياء الأمور.

**الحقول:**
| الحقل | النوع | مطلوب | ملاحظات |
|--------|------|-------|---------|
| البريد الإلكتروني | email | ✓ | |
| كلمة المرور | password | ✓ | |
| تذكرني | checkbox | ✗ | |

**السلوك بعد الدخول:**
- المدرب/رئيس المدربين → لوحة المدرب (`/trainer`)
- موظف الاستقبال → مكتب الاستقبال (`/receptionist`)
- ولي الأمر → لوحة ولي الأمر (`/guardian`)
- باقي الأدوار → لوحة التحكم الرئيسية (`/`)

**سجل الدخول:** كل عملية دخول تُسجّل في جدول `login_history` (IP، المتصفح، التوقيت).

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

---

### 2. لوحة التحكم الرئيسية (`/`)

**من يراها:** مدير النظام، مالك الأكاديمية، مدير الأكاديمية، مدير الفرع، المحاسب.

**المحتوى:**

#### الصف الأول — إحصائيات اليوم (4 بطاقات):
| البطاقة | القيمة | المصدر |
|---------|--------|--------|
| حصص اليوم | عدد | الحصص المجدولة + الجارية |
| مدربين حاضرين | عدد | سجلات حضور المدربين اليوم |
| مدفوعات اليوم | مبلغ (ج.م) | مجموع المدفوعات المؤكدة |
| مشتركين نشطين | عدد | حالة = active |

#### الصف الثاني — يحتاج انتباه:
| التنبيه | الحالة |
|---------|--------|
| فواتير متأخرة | عدد الفواتير overdue |
| كشوف رواتب معلقة | draft أو pending_approval |
| مستندات تنتظر موافقة | حالة = pending |
| مخزون منخفض | أصناف وصلت للحد الأدنى |
| شهادات طبية تنتهي قريباً | تنتهي خلال 7 أيام |
| حصص بدون تسجيل حضور | انتهت ولم يُسجّل حضورها |

#### الصف الثالث:
- **يسار:** جدول حصص اليوم (الوقت، المجموعة، المدرب، الملعب، الحالة)
- **يمين:** آخر 10 مدفوعات (يظهر فقط لمن لديه صلاحية مالية)

**تصفية بالفرع:** إذا اختار المستخدم فرع من أعلى الصفحة، تُعرض بيانات هذا الفرع فقط.

---

### 3. إدارة الفروع (`/branches`)

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

**شاشة القائمة:**
| العمود | الوصف |
|--------|-------|
| الاسم (عربي) | name_ar |
| الاسم (إنجليزي) | name |
| العنوان | address |
| الهاتف | phone |
| الحالة | active/inactive |
| الإجراءات | تعديل |

**شاشة الإنشاء/التعديل (`/branches/create`, `/branches/{id}/edit`):**
| الحقل | النوع | مطلوب | ملاحظات |
|--------|------|-------|---------|
| الاسم بالعربية | text | ✓ | |
| الاسم بالإنجليزية | text | ✗ | |
| العنوان | text | ✗ | |
| رقم الهاتف | text | ✗ | |
| البريد الإلكتروني | email | ✗ | |
| مفعّل | toggle | — | افتراضي: نعم |

**لماذا يحتاج عملك هذا:**
- أكاديمية بها 3 فروع → كل فرع له مشتركين ومدربين وورديات مالية منفصلة
- مدير الفرع يرى بيانات فرعه فقط
- التقارير يمكن تصفيتها بالفرع أو عرض الكل

**مثال عملي:**
> أكاديمية "الكابتن" لديها فرع المعادي وفرع المقطم وفرع التجمع. كل فرع له ملاعب مختلفة ومدربين مختلفين. مدير فرع المعادي لا يرى مشتركي المقطم.

---

### 4. محوّل الفروع (Branch Switcher)

**موقعه:** في شريط التنقل العلوي (Topbar)

**السلوك:**
- يظهر قائمة منسدلة بالفروع المتاحة للمستخدم
- اختيار "كل الفروع" يُظهر بيانات الأكاديمية كاملة
- اختيار فرع محدد يُصفّي جميع الشاشات بهذا الفرع
- التحديد يُحفظ في الجلسة

---

### 5. إدارة المستخدمين (`/users`)

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

**شاشة القائمة:**
- بحث بالاسم أو البريد
- تصفية بالحالة (active, inactive, suspended, pending)
- تصفية بالدور

| العمود | الوصف |
|--------|-------|
| الاسم | name |
| البريد | email |
| الدور | الدور الأساسي |
| الفرع | branch_id |
| الحالة | الشارة الملونة |
| آخر دخول | last_login_at |
| الإجراءات | تعديل |

**شاشة الإنشاء/التعديل (`/users/create`, `/users/{id}/edit`):**
| الحقل | النوع | مطلوب | ملاحظات |
|--------|------|-------|---------|
| الاسم بالكامل | text | ✓ | |
| البريد الإلكتروني | email | ✓ | فريد على مستوى الأكاديمية |
| كلمة المرور | password | ✓ (إنشاء فقط) | |
| رقم الهاتف | text | ✗ | |
| الدور | select | ✓ | لا يمكن اختيار دور أعلى من دورك |
| الفرع | select | ✗ | |
| الحالة | select | ✓ | active, inactive, suspended, pending |

**قاعدة هرمية الأدوار:** لا يمكن لمستخدم أن يُنشئ أو يُعدّل مستخدم بدور أعلى من دوره. مثلاً: مدير الفرع (70) لا يمكنه إنشاء مدير أكاديمية (80).

```mermaid
flowchart TD
    A[مدير النظام - 100] --> B[مالك الأكاديمية - 90]
    B --> C[مدير الأكاديمية - 80]
    C --> D[مدير الفرع - 70]
    D --> E[رئيس المدربين - 60]
    E --> F[مدرب - 50]
    D --> G[موظف الاستقبال - 40]
    D --> H[محاسب - 35]
    D --> I[إدخال بيانات - 30]
    A --> J[ولي أمر - 5]
```

---

### 6. إدارة الأدوار والصلاحيات (`/roles`)

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

**شاشة القائمة:**
| العمود | الوصف |
|--------|-------|
| اسم الدور | name_ar |
| المستوى | level (رقمي) |
| عدد المستخدمين | العدد المرتبط |
| الإجراءات | تعديل |

**شاشة الإنشاء/التعديل (`/roles/create`, `/roles/{id}/edit`):**
| الحقل | النوع | مطلوب |
|--------|------|-------|
| الاسم بالعربية | text | ✓ |
| الاسم بالإنجليزية | text | ✓ |
| المعرّف (slug) | text | ✓ |
| المستوى | number | ✓ |
| الصلاحيات | checkboxes مجمّعة | ✓ |

**تنسيق الصلاحيات:** `module.action` — مثل:
- `participants.list` / `participants.create` / `participants.view` / `participants.update` / `participants.delete`
- `invoices.list` / `invoices.create` / `invoices.view` / `invoices.cancel`
- `attendance.list` / `attendance.mark`
- `pos.sell` / `pos.list`
- `settings.view` / `settings.manage`

**نقاط التطبيق (4 طبقات):**
1. Middleware على الـ Route → يمنع الدخول أصلاً
2. `$this->authorize()` في Livewire → حماية إضافية
3. PermissionService::applyScope() → تصفية البيانات حسب النطاق
4. `@can()` في Blade → إخفاء الأزرار/الروابط

**أمثلة على النطاقات (Scopes):**
| النطاق | المعنى | مثال |
|--------|--------|------|
| academy | يرى كل بيانات الأكاديمية | مدير الأكاديمية |
| branch | يرى بيانات فرعه فقط | مدير الفرع |
| own | يرى ما أنشأه فقط | إدخال بيانات |
| own_groups | يرى مجموعاته فقط | مدرب |
| own_children | يرى أبناءه فقط | ولي أمر |

---

### 7. الملف الشخصي (`/profile`)

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

**المحتوى:**
- تغيير الاسم
- تغيير كلمة المرور
- عرض الدور والفرع

---

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

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

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

---

### 9. سجل النشاط (`/admin/activity-log`)

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

**المحتوى:**
- تاريخ كل عملية (إنشاء، تعديل، حذف)
- المستخدم الذي نفّذ العملية
- القيم القديمة والجديدة
- عنوان IP

---

### 10. لوحة مدير النظام (`/admin`)

**من يراها:** من لديه صلاحية `super_admin.access`

**المحتوى:**
- إدارة الأكاديميات (تفعيل/تعطيل)
- إعدادات النظام العامة
- عرض شامل عبر الأكاديميات

---

### 11. ويزارد الإعداد الأولي (`/setup`)

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

**الخطوات (12 خطوة):**
1. معلومات الأكاديمية الأساسية
2. إعداد الفروع
3. الأنشطة الرياضية
4. البرامج التدريبية
5. المجموعات
6. إعدادات الحضور
7. إعدادات مالية
8. إعدادات الإشعارات
9. إعداد المستخدمين والأدوار
10. إعداد المنشآت
11. إعداد المخزون
12. مراجعة وتأكيد

**لماذا يحتاج عملك هذا:**
> بدلاً من إعداد كل شيء يدوياً شاشة بشاشة، الويزارد يأخذك بترتيب منطقي ويضمن عدم نسيان أي إعداد أساسي.

---

### 12. إعدادات الأكاديمية (`/settings`)

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

**المحتوى:**
- اسم الأكاديمية (عربي + إنجليزي)
- الشعار
- اللون الأساسي
- معلومات التواصل
- العنوان

---

### 13. إعدادات العلامة التجارية (`/settings/branding`)

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

**المحتوى:**
- رفع الشعار
- ألوان الواجهة
- النص في ذيل الصفحة

---

### 14. إعدادات النظام (`/settings/system`)

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

**أمثلة على الإعدادات:**
| الإعداد | النوع | الوصف |
|---------|-------|-------|
| فترة السماح للتأخير (مشتركين) | رقم (دقائق) | افتراضي 15 |
| فترة السماح للتأخير (مدربين) | رقم (دقائق) | افتراضي 10 |
| عدد الغيابات قبل الإيقاف | رقم | افتراضي 5 |
| نسبة الحضور الأدنى | نسبة % | افتراضي 75% |
| الحد الأقصى للخصم | نسبة % | افتراضي 50% |
| العملة | text | ج.م |
| المنطقة الزمنية | select | Africa/Cairo |

---

### 15. البحث العام (Global Search)

**موقعه:** في شريط التنقل العلوي

**يبحث في:**
- المشتركين (بالاسم، الهاتف، الرقم القومي)
- البرامج
- المجموعات
- الفواتير

---

### 16. تبديل الوضع الداكن (Dark Mode)

**موقعه:** في شريط التنقل العلوي
**السلوك:** يبدّل بين الوضع الفاتح والداكن

---

### 17. تبديل اللغة (Language Switcher)

**موقعه:** في شريط التنقل العلوي
**اللغات:** العربية (افتراضي) + الإنجليزية

---

## دورة العمل — إعداد أكاديمية جديدة

```mermaid
flowchart TD
    A[تسجيل دخول مدير النظام] --> B[إنشاء أكاديمية]
    B --> C[تشغيل ويزارد الإعداد]
    C --> D[بيانات الأكاديمية]
    D --> E[إنشاء الفروع]
    E --> F[تعريف الأنشطة]
    F --> G[إنشاء برامج]
    G --> H[إنشاء مجموعات]
    H --> I[إعدادات الحضور والمالية]
    I --> J[إنشاء مستخدمين]
    J --> K[✓ جاهز للعمل]
```

---

## دورة العمل — إنشاء مستخدم جديد

```mermaid
sequenceDiagram
    participant Admin as المدير
    participant System as النظام
    participant User as المستخدم الجديد

    Admin->>System: إنشاء مستخدم (اسم، بريد، دور، فرع)
    System->>System: التحقق: هل الدور أقل من دور المنشئ؟
    System->>System: التحقق: هل البريد فريد في الأكاديمية؟
    System->>System: إنشاء المستخدم + ربطه بالدور
    System-->>Admin: تم الإنشاء بنجاح
    User->>System: تسجيل الدخول بالبيانات
    System->>System: تحديد الشاشة حسب الدور
    System-->>User: توجيه للوحة المناسبة
```

---

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

### مثال 1: أكاديمية بفرع واحد
> أكاديمية صغيرة فيها مالك واحد يدير كل شيء. يُنشئ حسابه كـ academy_owner ويختار "كل الفروع" دائماً.

### مثال 2: أكاديمية بـ 3 فروع
> أكاديمية كبيرة. لكل فرع مدير (branch_manager) لا يرى إلا فرعه. المالك يرى الكل من لوحة التحكم.
> - فرع المعادي: 2 مدربين، 80 مشترك
> - فرع المقطم: 3 مدربين، 120 مشترك
> - فرع التجمع: 1 مدرب، 40 مشترك

### مثال 3: مدرب يسجّل دخوله
> يسجّل الدخول → يُحوّل تلقائياً إلى `/trainer` → يرى حصص اليوم فقط + زر تسجيل الحضور.

### مثال 4: ولي أمر يسجّل دخوله
> يسجّل الدخول → يُحوّل إلى `/guardian` → يرى بيانات أبنائه فقط (حضور، تقييمات، فواتير).

---

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

| الميزة | الفائدة |
|--------|---------|
| Multi-tenancy بـ academy_id | أكاديمية واحدة لا ترى بيانات أخرى أبداً |
| هرمية الأدوار | لا يمكن لموظف أن يُعطي نفسه صلاحيات أعلى |
| تصفية بالفرع | مدير الفرع يركّز على عمله بدون تشتت |
| توجيه حسب الدور | كل شخص يرى ما يحتاجه فقط — بدون تعقيد |
| سجل الدخول | تتبع من دخل ومتى — للأمان والمحاسبة |
| ويزارد الإعداد | أكاديمية جديدة جاهزة في 30 دقيقة بدلاً من أيام |

---

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

| الوحدة | العلاقة |
|--------|---------|
| المشتركين | كل مشترك مرتبط بـ academy_id + branch_id |
| المالية | الوردية مرتبطة بالمستخدم + الفرع |
| الحضور | تسجيل الحضور يتطلب صلاحية attendance.mark |
| التقارير | تُصفّى بالفرع النشط |
| الإشعارات | تُرسل حسب تفضيلات المستخدم |
