# 06 — المنشآت والمساحات

## نظرة عامة

المنشأة = ملعب أو حمام سباحة أو صالة. لكل منشأة تخطيطات (layouts) مختلفة حسب الوقت، والتخطيط مقسّم إلى أجزاء (segments) يمكن حجزها.

```
منشأة → تخطيط (حسب اليوم/الوقت) → أجزاء (قابلة للحجز)
```

---

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

### 1. قائمة المنشآت (`/facilities`)

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

**الفلاتر:**
| الفلتر | النوع | الخيارات |
|--------|------|----------|
| بحث | نص | اسم أو كود |
| الحالة | select | active, maintenance, closed, reserved, unavailable |
| النوع | select | indoor_field, outdoor_field, pool, gym, court, track, other |
| الفرع | select | قائمة الفروع |

**أعمدة الجدول:**
| العمود | الوصف |
|--------|-------|
| الكود | code |
| الاسم | name_ar |
| النوع | شارة |
| الفرع | branch.name_ar |
| المساحة | area_sqm م² |
| تكلفة الإيجار | monthly_rental_cost ج.م/شهر |
| الحالة | شارة ملونة |
| الإجراءات | تعديل، حذف، تخطيطات |

---

### 2. إنشاء/تعديل منشأة (`/facilities/create`, `/facilities/{id}/edit`)

**الحقول:**
| الحقل | النوع | مطلوب | ملاحظات |
|--------|------|-------|---------|
| الاسم بالعربية | text | ✓ | |
| الاسم بالإنجليزية | text | ✗ | |
| الكود | text | ✗ | |
| النوع | select | ✓ | indoor_field, outdoor_field, pool, gym, court, track, other |
| الفرع | select | ✗ | |
| المساحة (م²) | number | ✗ | |
| السعة القصوى | number | ✗ | |
| أوقات العمل (من) | time | ✗ | |
| أوقات العمل (إلى) | time | ✗ | |
| تكلفة إيجار شهرية | money | ✗ | بالقروش |
| الوصف | textarea | ✗ | |
| الحالة | select | ✓ | active, maintenance, closed |

---

### 3. ويزارد إنشاء منشأة (`/facilities/wizard`)

**خطوات:**
1. البيانات الأساسية (اسم، نوع، فرع)
2. المواصفات (مساحة، سعة، أوقات العمل)
3. التخطيط الأولي (نوع التقسيم + الأبعاد)
4. مراجعة وتأكيد

---

### 4. إدارة التخطيطات (`/facilities/{id}/layouts`)

**من يراها:** من لديه صلاحية `facilities.manage_layouts`

**المفهوم الأساسي:** المنشأة الواحدة يمكن أن يكون لها تخطيطات مختلفة حسب اليوم والوقت.

**مثال:**
> ملعب كرة قدم:
> - صباحاً (8:00-14:00): مقسّم 3×2 = 6 مساحات صغيرة (تدريب أطفال)
> - مساءً (14:00-22:00): مقسّم 2×1 = ملعبين كبيرين (مباريات)

**حقول التخطيط:**
| الحقل | النوع | مطلوب | ملاحظات |
|--------|------|-------|---------|
| الاسم بالعربية | text | ✓ | |
| الاسم بالإنجليزية | text | ✗ | |
| نوع التخطيط | select | ✓ | grid, lanes, zones, custom |
| متكرر أسبوعياً | toggle | — | |
| يوم الأسبوع | select | مشروط | إذا متكرر — 0(أحد) إلى 6(سبت) |
| تاريخ محدد | date | مشروط | إذا غير متكرر |
| وقت البداية | time | ✓ | |
| وقت النهاية | time | ✓ | |
| الأبعاد | حسب النوع | ✓ | |

**أنواع التخطيط:**

| النوع | الإعداد | النتيجة |
|-------|---------|---------|
| grid | صفوف × أعمدة | مثل: 3×2 = 6 مربعات |
| lanes | عدد الحارات | مثل: 6 حارات سباحة |
| zones | تعريف يدوي | مناطق بأسماء مخصصة |
| custom | تعريف يدوي | بدون قيود هندسية |

**توليد الأجزاء التلقائي:**
- Grid(3,2) → R1C1, R1C2, R2C1, R2C2, R3C1, R3C2
- Lanes(6) → Lane 1, Lane 2, ..., Lane 6
- Zones → جزء لكل تعريف

---

### 5. ويزارد تعيين المساحات (`/facilities/space-assignment`)

**من يراها:** من لديه صلاحية `facilities.manage_layouts`

**الوظيفة:** ربط مجموعة تدريبية بأجزاء محددة من المنشأة في أوقات محددة.

---

### 6. منشئ الجدول المرئي (`/facilities/schedule-builder`)

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

**الوصف:** واجهة مرئية تعرض المنشأة كشبكة (أيام × أوقات) مع الحجوزات الحالية ملوّنة.

---

## حالات المنشأة

| الحالة | المعنى | التأثير |
|--------|--------|---------|
| active | مفعّلة — تعمل | يمكن الحجز |
| maintenance | صيانة | تُلغى الحجوزات الجديدة — القائمة تُلغى |
| closed | مغلقة | لا حجوزات |
| reserved | محجوزة (بالكامل) | لا حجوزات جديدة |
| unavailable | غير متاحة | لا حجوزات |

---

## كشف التعارض (Collision Detection)

**الخدمة:** `SpaceCollisionService`

**الآلية:**
```
1. إيجاد الحجوزات المؤكدة (confirmed) في نفس المنشأة ونفس اليوم
2. تصفية: التي تتداخل مع الوقت المطلوب
3. استبعاد نفس الحجز (إذا تعديل)
4. فحص تقاطع الأجزاء المطلوبة مع الأجزاء المحجوزة
5. إذا لا تقاطع → لا مشكلة ✓
6. إذا تقاطع → رفض + تفاصيل التعارض
```

```mermaid
flowchart TD
    A[طلب حجز: منشأة X، يوم Y، 16:00-17:00، أجزاء 1,2,3] --> B[البحث عن حجوزات مؤكدة]
    B --> C[تصفية التداخل الزمني]
    C --> D{هل يوجد حجوزات متداخلة؟}
    D -->|لا| E[✓ لا تعارض — يمكن الحجز]
    D -->|نعم| F[فحص تقاطع الأجزاء]
    F --> G{هل الأجزاء نفسها؟}
    G -->|لا| E
    G -->|نعم| H[✗ تعارض — رفض]
```

**أنواع الحجز:**
| النوع | التأثير |
|-------|---------|
| confirmed | يمنع الآخرين (حجز صلب) |
| tentative | يحذّر فقط (لا يمنع) |
| cancelled | غير مرئي — لا تأثير |

---

## حجز المساحة عند إنشاء حصة

```mermaid
sequenceDiagram
    participant Job as مولّد الحصص
    participant S as النظام
    participant Col as خدمة التعارض

    Job->>S: إنشاء حصة (مجموعة X، السبت 16:00)
    S->>S: هل المجموعة لها مساحة محجوزة في الجدول؟
    S->>Col: فحص: هل المساحة متاحة يوم السبت 16:00?
    Col-->>S: ✓ متاحة
    S->>S: إنشاء حجز (confirmed)
    S->>S: إنشاء الحصة + ربطها بالحجز
```

**عند إلغاء الحصة:**
- الحجز المرتبط → cancelled
- المساحة تصبح متاحة فوراً

---

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

### مثال 1: ملعب كرة قدم بتخطيطين
> **صباحاً (8:00-14:00):** Grid 3×2 = 6 مساحات صغيرة
> - المساحة 1+2: مجموعة براعم 4-6
> - المساحة 3+4: مجموعة أشبال 7-9
> - المساحة 5+6: فارغة
>
> **مساءً (14:00-22:00):** Grid 2×1 = ملعبين
> - الملعب 1: مجموعة ناشئين 10-14
> - الملعب 2: إيجار خارجي

### مثال 2: حمام سباحة بـ 6 حارات
> - التخطيط: Lanes(6) → 6 حارات
> - الحارات 1-3: مجموعة تعليم مبتدئين (4:00-5:00)
> - الحارات 4-6: مجموعة متقدمين (4:00-5:00)
> - الحارات 1-6: مجموعة فريق المنافسات (5:00-7:00)

### مثال 3: محاولة حجز مساحة محجوزة
> 1. المدير يحاول تعيين مجموعة جديدة في الملعب 1، السبت 16:00
> 2. النظام يكتشف: مجموعة الناشئين محجوزة هناك 14:00-18:00
> 3. رفض: "تعارض مع حجز مجموعة الناشئين"
> 4. البدائل: اختيار ملعب آخر أو وقت آخر

### مثال 4: منشأة تدخل في صيانة
> 1. حالة المنشأة → maintenance
> 2. كل الحجوزات المستقبلية المؤكدة → cancelled
> 3. إشعارات للمجموعات المتأثرة
> 4. الحصص المرتبطة تحتاج إعادة تعيين لمنشأة أخرى

---

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

| الميزة | الفائدة |
|--------|---------|
| التخطيطات المتعددة | نفس الملعب يُستخدم بطرق مختلفة صباحاً ومساءً |
| كشف التعارض | يستحيل حجز نفس المكان مرتين — لا فوضى |
| الحجز التلقائي | عند إنشاء الحصص، المساحة تُحجز تلقائياً |
| تكلفة الإيجار | حساب break-even: كم مشترك نحتاج لتغطية الإيجار؟ |
| أنواع التخطيط | يناسب أي رياضة: ملاعب، حمامات سباحة، صالات |

---

## التكاملات

| الوحدة | العلاقة |
|--------|---------|
| المجموعات | الجدول الأسبوعي مرتبط بمنشأة |
| الحصص | كل حصة مرتبطة بمنشأة + أجزاء |
| التعيينات | المدرب مُعيّن في مساحة محددة |
| المالية | تكلفة الإيجار تدخل في الحسابات |
| لوحة التحكم | عرض حصص اليوم مع المنشأة |
