# دورة العروض والخصومات — الدليل الكامل

## ملخص سريع

النظام فيه 3 طبقات منفصلة للخصومات:

| الطبقة | الغرض | من يستفيد | التطبيق |
|--------|--------|-----------|---------|
| عروض مجلس الإدارة (Board Offers) | شروط دفع مخصصة (خصم كاش + أقساط مخفضة) | كل الأعضاء خلال فترة العرض | تلقائي |
| الخصومات الخاصة (Special Discounts) | خصم على قيمة العضوية | عضو محدد أو بشرط سداد | يدوي أو تلقائي |
| الخصومات اللائحية (Regulatory Discounts) | خصم منصوص عليه في اللائحة | فئات محددة (موظفين، مجموعات، etc.) | يدوي + اعتماد |
| تعديل الاشتراك السنوي | نسبة على الاشتراك | كل المشتركين في سنة معينة | تلقائي عند التوليد |

### هل تتراكم؟

| | Board Offer | Special Discount | Regulatory Discount |
|---|---|---|---|
| **Board Offer** | — | نعم | نعم |
| **Special Discount** | نعم | — | لا (أحدهما فقط) |
| **Regulatory Discount** | نعم | لا (أحدهما فقط) | — |

- عرض مجلس الإدارة يعمل على **المبلغ المدفوع** (بعد كل الخصومات)
- الخصم الخاص واللائحي يعملان على **قيمة العضوية الأصلية** — ويأخذ الأعلى فقط

---

## 1. عروض مجلس الإدارة (Board Offers)

### ما هو

قرار مجلس إدارة بشروط دفع تفضيلية لفترة محدودة. يؤثر على طريقة السداد (خصم كاش / شروط أقساط مخفضة) — لكن لا يغيّر قيمة العضوية نفسها.

### أين في النظام

**إدارة**: `/pricing/board-offers`
**صلاحية المشاهدة**: `pricing.board_offers.view`
**صلاحية الإنشاء/التعديل**: `pricing.board_offers.create` / `pricing.board_offers.edit`

---

### خطوات إنشاء عرض جديد

#### الخطوة 1: الذهاب للصفحة

انتقل إلى: **التسعير ← عروض مجلس الإدارة ← إضافة عرض جديد**

URL: `/pricing/board-offers/create`

#### الخطوة 2: البيانات الأساسية

| الحقل | الوصف | مطلوب |
|-------|-------|-------|
| عنوان العرض (عربي) | مثل "عرض الصيف 2026" | نعم |
| عنوان (إنجليزي) | ترجمة اختيارية | لا |
| الوصف | تفاصيل إضافية | لا |
| الفرع | فرع محدد أو "كل الفروع" | لا |
| تاريخ البداية | أول يوم يسري فيه العرض | نعم |
| تاريخ الانتهاء | آخر يوم يسري فيه العرض | نعم |
| رقم قرار مجلس الإدارة | للتوثيق | لا |
| تاريخ القرار | للتوثيق | لا |
| مجال التطبيق | `membership_fee` أو `all` | نعم |

#### الخطوة 3: تفعيل مسار الكاش (اختياري)

فعّل checkbox "مسار كاش" ثم حدد:

| الحقل | الخيارات | مثال |
|-------|----------|------|
| نوع الخصم | `percentage` أو `fixed_amount` | percentage |
| قيمة الخصم | النسبة أو المبلغ | 10 (= 10%) |

**النتيجة**: عضو يدفع كاش يحصل على خصم. مثال: عضوية 150,000 × 10% = يدفع 135,000

#### الخطوة 4: تفعيل مسار التقسيط (اختياري)

فعّل checkbox "مسار تقسيط" ثم حدد:

| الحقل | الافتراضي | مثال |
|-------|-----------|------|
| نسبة المقدم | 25% | 20% |
| عدد الأشهر | 30 | 48 |
| نسبة الفائدة السنوية | 22% | 15% |
| فترة السماح (نوع) | بدون | `first_n_months` أو `full_free_under_n` |
| أشهر السماح | 0 | 6 |
| فائدة ما بعد السماح | — | 25% |

**أنواع فترة السماح**:
- `first_n_months`: أول N شهر بدون فوائد، بعدها الفائدة العادية
- `full_free_under_n`: لو إجمالي الأقساط ≤ N شهر → إعفاء كامل من الفوائد

#### الخطوة 5: حفظ

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

---

### كيف يظهر للعضو (صفحة `/members/{id}`)

1. بانر أصفر يظهر: "عرض مجلس الإدارة: {عنوان العرض}"
2. **لو فيه Tiers** (عرض متعدد المستويات):
   - شبكة بطاقات — كل بطاقة = مستوى (كاش أو تقسيط)
   - كل بطاقة فيها زر "إرسال للخزينة"
3. **لو فيه مسار واحد** (عرض بسيط):
   - الكاش: يظهر بالسعر بعد الخصم + "وفّرت X"
   - التقسيط: يظهر بالشروط الجديدة (مقدم + فائدة + أشهر)

### ماذا يحدث عند "إرسال للخزينة"

1. يُنشأ `payment_request` بـ `board_offer_id` + `offer_snapshot_json`
2. الـ snapshot يحفظ شروط العرض لحظة الإرسال
3. حتى لو العرض تغيّر أو انتهى بعدها — الشروط المحفوظة هي المُطبَّقة

### Multi-Tier Offers (عروض متعددة المستويات)

العرض الواحد يمكن أن يحتوي على عدة **Tiers** (جدول `board_offer_tiers`):

| الحقل | الوصف |
|-------|-------|
| `tier_order` | ترتيب العرض (1, 2, 3...) |
| `tier_name_ar` | اسم المستوى ("كاش كامل"، "تقسيط 12 شهر"...) |
| `payment_type` | `cash` أو `installment` |
| `cash_discount_pct` | نسبة الخصم (للكاش) |
| `down_payment_pct` | نسبة المقدم (للتقسيط) |
| `months` | عدد الأشهر (للتقسيط) |
| `interest_rate` | نسبة الفائدة (للتقسيط) |

مثال: عرض بـ 3 مستويات:
1. كاش: خصم 15%
2. تقسيط 12 شهر: مقدم 30%، بدون فائدة
3. تقسيط 36 شهر: مقدم 20%، فائدة 18%

---

### Edge Cases

- **العرض انتهى أثناء ما الطلب في الخزينة**: snapshot محفوظ — الخصم يُطبَّق
- **العرض اتعطّل (is_active=0)**: لا يظهر لأعضاء جدد — الطلبات القديمة لا تتأثر
- **عرض مستقبلي**: لا يظهر — ينشط تلقائياً عند effective_from
- **أكثر من عرض ساري**: الأكثر تحديداً يفوز (branch_id محدد > NULL, ثم الأحدث)
- **بدون مسار كاش ولا تقسيط**: لا يمكن حفظه (validation يمنع)

---

## 2. الخصومات الخاصة (Special Discounts)

### ما هو

خصم على **قيمة العضوية الأصلية** — ينقّص المبلغ المطلوب دفعه. يمكن تعيينه يدوياً لعضو أو أن يُطبَّق تلقائياً عند استيفاء شرط.

### أين في النظام

**إدارة**: `/pricing/special-discounts`
**صلاحية المشاهدة**: `pricing.special_discounts.view`
**صلاحية الإنشاء/التعديل**: `pricing.special_discounts.create` / `pricing.special_discounts.edit`

---

### خطوات إنشاء خصم خاص جديد

#### الخطوة 1: الذهاب للصفحة

انتقل إلى: **التسعير ← الخصومات الخاصة ← إضافة خصم جديد**

URL: `/pricing/special-discounts/create`

#### الخطوة 2: تعبئة النموذج

| الحقل | الخيارات | ملاحظات |
|-------|----------|---------|
| اسم الخصم (عربي) | نص حر | مطلوب. مثال: "خصم أبناء الشهداء" |
| اسم (إنجليزي) | نص حر | اختياري |
| نوع الخصم | `percentage` / `fixed_amount` / `free_subscription` | — |
| نسبة الخصم | 0.01 – 100 | فقط لنوع percentage |
| مبلغ الخصم الثابت | رقم > 0 | فقط لنوع fixed_amount |
| مجال التطبيق | `membership_fee` / `subscription` / `all` | — |
| تاريخ البداية | YYYY-MM-DD أو فارغ (ساري دائماً) | — |
| تاريخ الانتهاء | YYYY-MM-DD أو فارغ | — |
| شرط التطبيق | `none` / `full_payment` / `min_payment` | — |
| الحد الأدنى للسداد | رقم | فقط لشرط min_payment |
| سنوات اشتراك مجانية | 0 – 5 | مكافأة إضافية |
| يتطلب مستند | نعم/لا | لو نعم: العضو لازم يرفع PDF/صورة |
| وصف | نص حر | اختياري |

#### الخطوة 3: حفظ

الخصم يصبح نشطاً فوراً ومتاحاً للتعيين.

---

### كيف يُعيَّن لعضو (التطبيق اليدوي)

يوجد **3 أماكن** يمكن تعيين خصم خاص منها:

#### الطريقة 1: من صفحة العضو (الأسرع)

1. افتح صفحة العضو: `/members/{id}`
2. في قسم "خصم خاص" (يظهر فقط لو العضو في حالة `accepted` أو `payment_pending`)
3. اختر الخصم من القائمة المنسدلة
4. لو الخصم يتطلب مستند → ارفع الملف
5. اضغط "تطبيق الخصم"

**النتيجة**: يُحفظ `special_discount_id` + `discount_amount` في جدول `members`

#### الطريقة 2: من صفحة ملء الاستمارة

1. افتح صفحة ملء الاستمارة: `/members/{id}/fill-form`
2. القسم 6: "خصم خاص (اختياري)"
3. اختر الخصم → ارفع المستند (لو مطلوب)
4. يُحفظ عند إرسال الاستمارة

#### الطريقة 3: من صفحة تعديل العضو

1. افتح صفحة التعديل: `/members/{id}/edit`
2. قسم "خصم خاص" → اختر من القائمة
3. النظام يحسب المبلغ تلقائياً ويعرضه

---

### كيف يُطبَّق تلقائياً (بشرط)

خصومات بـ `condition_type != 'none'` تُطبَّق تلقائياً:

| الشرط | المعنى | مثال |
|-------|--------|------|
| `full_payment` | العضو سدّد كامل قيمة العضوية | "ادفع كاش واحصل على 5%" |
| `min_payment` | العضو سدّد ≥ الحد الأدنى المحدد | "سدّد 100,000 واحصل على 3%" |

**كيف يعمل**: `SpecialDiscountService::evaluateForMember()` يُستدعى أثناء حساب الفاتورة → يفحص الشروط → يُطبَّق أعلى خصم مطابق

---

### المكافأة: سنوات اشتراك مجانية

- حقل `bonus_free_subscription_years` (0-5)
- بعد تفعيل العضوية → `applyFreeSubscriptionBonus()` يحوّل اشتراكات pending إلى paid
- الإيصال يُسجَّل كـ `FREE-BONUS`

مثال: خصم "كاش كامل" + bonus=1 → العضو يدفع كاش → يُفعَّل → اشتراك أول سنة مجاناً

---

### كيف يُزال الخصم

1. صفحة العضو `/members/{id}`
2. لو خصم مُطبَّق → يظهر "خصم مُطبق: {اسم}" + زر "إزالة"
3. اضغط "إزالة" → يُمسح `special_discount_id` و `discount_amount`

---

### Edge Cases

- **خصم بدون فترة (dates = null)**: ساري دائماً
- **percentage = 100%**: العضوية مجاناً (مثل أبناء شهداء)
- **عضو بخصم يدوي + خصم شرطي ساري**: اليدوي يفوز (يُفحص أولاً)
- **خصم معطّل (is_active=0) ومعيّن لعضو**: لا يُطبَّق — يُتجاهل في BillingService
- **عضو دفع جزء ثم أضيف خصم**: الخصم ينقّص المتبقي فقط

---

## 3. الخصومات اللائحية (Regulatory Discounts)

### ما هو

خصومات **منصوص عليها في لائحة النادي** بموجب مواد محددة (97-102, 110). تُمنح لفئات معينة من المتقدمين بعد إثبات الأهلية واعتماد المسؤول.

### أين في النظام

**إدارة**: `/pricing/regulatory-discounts`
**طلبات الاعتماد**: `/pricing/regulatory-discounts/applications`
**صلاحية المشاهدة**: `pricing.regulatory_discounts.view`
**صلاحية الإنشاء**: `pricing.regulatory_discounts.create`
**صلاحية التعديل**: `pricing.regulatory_discounts.edit`
**صلاحية الاعتماد**: `pricing.regulatory_discounts.approve`

---

### أنواع الخصومات اللائحية (6 أنواع)

| المادة | النوع (`eligibility_type`) | الفئة المستفيدة | طريقة الإثبات |
|--------|---------------------------|-----------------|---------------|
| 97 | `cross_branch_member` | عضو فرع آخر يريد الانضمام لهذا الفرع | التحقق من عضوية نشطة في الفرع المصدر |
| 98 | `government_employee` | موظف حكومي | مستند إثبات وظيفة حكومية |
| 98/99 | `ministry_youth_employee` | موظف وزارة الشباب والرياضة | مستند وزاري + شروط تقسيط خاصة |
| 100 | `board_of_trustees` | عضو مجلس أمناء | قرار مجلس أمناء |
| 102 | `club_employee` | موظف النادي | التحقق من HR (سنوات الخدمة) |
| 110 | `group_membership` | مجموعة ≥ 5 أعضاء | عدد الأعضاء في الطلب الجماعي |

---

### خطوات إنشاء خصم لائحي جديد

#### الخطوة 1: الذهاب للصفحة

انتقل إلى: **التسعير ← الخصومات اللائحية ← إضافة خصم جديد**

URL: `/pricing/regulatory-discounts/create`

#### الخطوة 2: البيانات الأساسية

| الحقل | الوصف | مطلوب |
|-------|-------|-------|
| رقم المادة | 97, 98, 99, 100, 102, أو 110 | نعم |
| اسم الخصم (عربي) | مثل "خصم الموظف الحكومي" | نعم |
| اسم (إنجليزي) | ترجمة | لا |
| الوصف | تفاصيل | لا |
| نوع الاستحقاق | أحد الأنواع الستة | نعم |
| نسبة الخصم | 0.01 – 100 | نعم (ما عدا group_membership) |
| الحد الأقصى للنسبة | cap على النسبة | لا |
| الفرع المصدر | لـ cross_branch_member فقط | حسب النوع |
| الفرع المستهدف | الفرع اللي يُطبَّق فيه | حسب النوع |
| الحد الأدنى لسنوات الخدمة | لـ club_employee فقط | حسب النوع |
| يسمح بالتقسيط | نعم/لا | لا |
| أقصى سنوات تقسيط | لو نعم | لا |
| فائدة التقسيط | نسبة خاصة (مختلفة عن الافتراضية) | لا |
| مجال التطبيق | `membership_fee` | — |
| تاريخ البداية/الانتهاء | فترة السريان | لا |
| رقم قرار مجلس الإدارة | توثيق | لا |
| تاريخ القرار | توثيق | لا |
| ملاحظات | نص حر | لا |

#### الخطوة 3: شرائح المجموعات (لـ `group_membership` فقط)

لو اخترت نوع "عضوية مجمعة" (مادة 110)، أضف شرائح:

| الحد الأدنى | الحد الأقصى | نسبة الخصم |
|-------------|-------------|------------|
| 5 | 9 | 10% |
| 10 | 19 | 15% |
| 20 | — | 20% |

كل شريحة: `tier_min[]`, `tier_max[]`, `tier_pct[]`

#### الخطوة 4: حفظ

---

### كيف يُطبَّق على عضو

#### الطريقة 1: أثناء ملء الاستمارة (الطريقة الأساسية)

1. افتح صفحة ملء الاستمارة: `/members/{id}/fill-form`
2. انزل للقسم 7: "خصم لائحي (المواد 97-102، 110)"
3. يظهر جدول FYI بكل الخصومات المتاحة ونِسَبها
4. اختر نوع الاستحقاق من القائمة المنسدلة:
   - `عضو فرع آخر (مادة 97)`
   - `موظف حكومي (مادة 98)`
   - `موظف وزارة الشباب (مادة 98/99)`
   - `عضو مجلس أمناء (مادة 100)`
   - `موظف النادي (مادة 102)`
   - `عضوية مجمعة (مادة 110)`
5. أدخل البيانات الإضافية حسب النوع:
   - **عضو فرع آخر**: اختر الفرع المصدر + رقم العضو
   - **موظف النادي**: اختر الموظف من HR (النظام يتحقق تلقائياً)
   - **مجموعة**: أدخل عدد الأعضاء (≥ 5)
6. النظام يرسل AJAX request لـ `/pricing/regulatory-discounts/check-eligibility`
7. يظهر الخصم المستحق: "خصم X% = Y ج.م"
8. ارفع مستند الإثبات (PDF أو صورة)
9. احفظ الاستمارة

**النتيجة**: يُحفظ `regulatory_discount_id` + `regulatory_discount_amount` + `regulatory_discount_document` في جدول `members`

#### الطريقة 2: من صفحة تعديل العضو

1. افتح `/members/{id}/edit`
2. قسم "خصم لائحي" → يظهر جدول FYI + dropdown
3. اختر الخصم → النظام يحسب المبلغ
4. ارفع المستند
5. احفظ

---

### دورة الاعتماد (Approval Workflow)

1. الموظف يطبّق الخصم اللائحي على العضو
2. يُنشأ سجل في `regulatory_discount_applications`:
   - `status = 'pending'`
   - `discount_percentage`, `original_amount`, `discount_amount`, `final_amount`
   - `verification_data` (JSON — بيانات التحقق)
3. المسؤول يذهب لـ `/pricing/regulatory-discounts/applications`
4. يراجع الطلبات المعلقة → يعتمد أو يرفض
5. **الاعتماد**: `status → 'approved'`, `approved_by`, `approved_at`
6. **الرفض**: `status → 'rejected'`, `rejection_reason`

---

### التحقق التلقائي من الأهلية

النظام يتحقق تلقائياً عند الاختيار:

| النوع | طريقة التحقق |
|-------|-------------|
| `club_employee` | `RegulatoryDiscountService::verifyClubEmployee($employeeId)` — يفحص HR: هل الموظف نشط؟ كم سنة خدمة؟ |
| `cross_branch_member` | `verifyCrossBranchMembership($memberId, $sourceBranchId)` — يفحص: هل عضو نشط في الفرع المصدر؟ |
| بقية الأنواع | يعتمد على المستند المرفق + اعتماد المسؤول |

---

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

#### مثال 1: موظف حكومي يتقدم للعضوية

1. أنشئ العضو كالمعتاد
2. عند ملء الاستمارة → القسم 7 → "موظف حكومي (مادة 98)"
3. النظام يحسب: 150,000 × 25% = خصم 37,500
4. ارفع صورة بطاقة الوظيفة
5. المتبقي المطلوب: 112,500 ج.م

#### مثال 2: موظف نادي (5 سنوات خدمة)

1. عند اختيار "موظف النادي (مادة 102)"
2. النظام يتحقق من HR → يجد الموظف بـ 5 سنوات
3. لو الخصم يتطلب min_service_years=3 → مؤهل
4. يُطبَّق الخصم تلقائياً

#### مثال 3: مجموعة 15 عضو

1. اختر "عضوية مجمعة (مادة 110)"
2. أدخل العدد: 15
3. النظام يبحث في الشرائح → 10-19 = 15%
4. خصم 15% لكل فرد في المجموعة

---

### Edge Cases

- **خصم لائحي + خصم خاص**: كلاهما يُحفظ في members لكن `BillingService` يطبّق الاثنين كبنود منفصلة في الفاتورة
- **max_discount_percentage**: لو الشريحة تعطي 20% لكن الحد الأقصى 15% → يُطبَّق 15%
- **موظف نادي غير نشط في HR**: `verifyClubEmployee()` يرفض — لا يمكن التطبيق
- **خصم يسمح بالتقسيط بشروط خاصة**: `allows_installment=1` + `installment_max_years=2` + `installment_interest_rate=0` → تقسيط سنتين بدون فائدة (مثل وزارة الشباب)
- **خصم لائحي معطّل**: لا يظهر في dropdown — لكن لو مُطبَّق على عضو فيُعرض كمعلومة

---

## 4. تعديل الاشتراك السنوي (Subscription Year Adjustment)

### ما هو

خصم/إعفاء على الاشتراكات السنوية لكل المشتركين في سنة مالية معينة.

### أين في النظام

**المسار**: `/pricing` (لوحة التسعير)

### كيف يعمل

- Rule Engine key: `SUBSCRIPTION_YEAR_ADJUSTMENT_{year}`
- يحتوي `discount_percentage` (مثل 50 = خصم 50%)
- `SubscriptionGenerator` يطبّق الخصم عند إنشاء سطر الاشتراك

### متى يُستخدم

- سنة كورونا: خصم 100% (اشتراك مجاني)
- سنة تأخير افتتاح: خصم 50%
- لا يؤثر على اشتراكات سبق إنشاؤها — فقط الجديدة

---

## 5. مقارنة شاملة بين أنواع الخصومات

| | Board Offer | Special Discount | Regulatory Discount |
|---|---|---|---|
| **يخصم من** | المبلغ المدفوع فعلياً | قيمة العضوية في الفاتورة | قيمة العضوية في الفاتورة |
| **يُطبَّق على** | كل من يدفع خلال الفترة | عضو معيّن أو بشرط | فئات لائحية محددة |
| **مصدره** | قرار مجلس إدارة | قرار إدارة | نص لائحة النادي |
| **يتطلب اعتماد** | لا | لا | نعم (applications) |
| **يتطلب مستند** | لا | اختياري | نعم (غالباً) |
| **أين يُحفظ** | `payment_requests.board_offer_id` | `members.special_discount_id` | `members.regulatory_discount_id` |
| **تأثير على الفاتورة** | لا (معلوماتي حتى الدفع) | نعم (ينقّص total_pending) | نعم (ينقّص total_pending) |
| **فترة صلاحية** | مطلوبة (from/to) | اختيارية | اختيارية |
| **يمكن إزالته** | لا (snapshot) | نعم (زر إزالة) | يدوياً من التعديل |

---

## 6. مثال تراكم كامل

عضو عضويته 150,000 ج.م:

```
قيمة العضوية الأصلية:         150,000 ج.م
- خصم لائحي (مادة 98, 25%):   - 37,500 ج.م
- خصم خاص (10%):              - 15,000 ج.م
===================================================
المطلوب سداده:                  97,500 ج.م

→ العضو يختار "كاش" مع عرض مجلس (خصم 10% كاش):
  97,500 × 10% = وفّر 9,750
  المدفوع فعلياً:              87,750 ج.م

→ مكافأة: سنة اشتراك مجانية (من الخصم الخاص)
  اشتراك 2026/2027 (492 + 35) = مجاناً
```

---

## 7. السيناريوهات الشائعة — Step by Step

### سيناريو 1: "عايزين عرض كاش 10% لمدة 3 شهور"

1. `/pricing/board-offers/create`
2. العنوان: "عرض الصيف — خصم 10% كاش"
3. فعّل مسار الكاش → percentage → 10
4. التواريخ: اليوم → بعد 3 شهور
5. احفظ ← كل عضو يدفع كاش خلال الفترة يحصل على 10% تلقائي

### سيناريو 2: "تقسيط على 48 شهر بفائدة 15% بدل 30 شهر بـ 22%"

1. `/pricing/board-offers/create`
2. فعّل مسار التقسيط → 48 شهر → 15%
3. ممكن تفعّل الكاش أيضاً

### سيناريو 3: "إعفاء فوائد لو دفع في 6 شهور أو أقل"

1. مسار تقسيط → grace_type = `full_free_under_n` → grace_months = 6
2. ≤ 6 أقساط → فائدة = 0%
3. > 6 أقساط → الفائدة العادية

### سيناريو 4: "خصم 10% + سنة مجانية لأي عضو يدفع كامل"

1. `/pricing/special-discounts/create`
2. نوع: percentage → 10%
3. شرط: full_payment
4. bonus_free_subscription_years = 1
5. ← أي عضو يسدّد كامل → 10% خصم + اشتراك سنة مجاناً

### سيناريو 5: "خصم ثابت 5000 ج.م لفئة معينة بمستند"

1. `/pricing/special-discounts/create`
2. نوع: fixed_amount → 5000
3. شرط: none (يدوي)
4. requires_document = 1
5. ← الموظف يعيّنه يدوياً + يرفع المستند

### سيناريو 6: "تطبيق خصم مادة 102 لموظف نادي"

1. أنشئ العضو → ادفع رسم الاستمارة
2. افتح ملء الاستمارة → القسم 7
3. اختر "موظف النادي (مادة 102)"
4. اختر الموظف → النظام يتحقق من HR
5. يظهر "خصم X% = Y ج.م"
6. احفظ الاستمارة

### سيناريو 7: "تسجيل مجموعة 20 عضو بخصم مادة 110"

1. `/pricing/regulatory-discounts` → تأكد أن مادة 110 موجودة بشرائحها
2. عند تسجيل كل عضو → في الاستمارة اختر "عضوية مجمعة"
3. أدخل العدد: 20
4. النظام يحسب الشريحة المناسبة → يُطبَّق الخصم

---

## 8. الملفات المسؤولة

| الملف | الدور |
|-------|-------|
| `Pricing/Controllers/BoardOfferController.php` | CRUD عروض مجلس الإدارة |
| `Pricing/Controllers/SpecialDiscountController.php` | CRUD الخصومات الخاصة |
| `Pricing/Controllers/RegulatoryDiscountController.php` | CRUD + اعتماد الخصومات اللائحية |
| `Members/Services/BoardOfferService.php` | جلب العرض الأفضل + حساب Tiers + خصم كاش + شروط تقسيط + snapshot |
| `Pricing/Services/SpecialDiscountService.php` | تقييم خصم عضو + تطبيق مكافأة سنوات مجانية |
| `Pricing/Services/RegulatoryDiscountService.php` | تقييم أهلية + التحقق من HR/عضوية + إنشاء/اعتماد طلبات |
| `Members/Services/BillingService.php` | يحسب كل الخصومات ويعرضها كبنود في الفاتورة |
| `Members/Controllers/MemberController.php` | `applyDiscount()` + `fillForm()` + `payMembership()` |
| `Members/Views/show.php` | عرض الخصومات + دليل FYI + أزرار التطبيق |
| `Members/Views/fill-form.php` | نموذج تطبيق الخصم اللائحي + الخاص |
| `Members/Views/edit.php` | تعديل الخصم الخاص واللائحي |
| `Pricing/Views/board_offers/form.php` | نموذج إنشاء/تعديل عرض |
| `Pricing/Views/special_discounts/form.php` | نموذج إنشاء/تعديل خصم خاص |
| `Pricing/Views/regulatory_discounts/form.php` | نموذج إنشاء/تعديل خصم لائحي |
| `Pricing/Views/regulatory_discounts/applications.php` | صفحة اعتماد الطلبات |

---

## 9. جداول قاعدة البيانات

### `board_offers`
```
id, title_ar, title_en, description,
cash_discount_type (percentage|fixed_amount|NULL),
cash_discount_value,
inst_down_payment_pct, inst_months, inst_interest_rate,
inst_grace_type (first_n_months|full_free_under_n|NULL),
inst_grace_months, inst_post_grace_rate,
branch_id (FK|NULL), applies_to (membership_fee|all),
effective_from, effective_to, is_active,
board_decision_number, board_decision_date, notes,
created_by, updated_by, created_at, updated_at
```

### `board_offer_tiers`
```
id, board_offer_id (FK), tier_order, tier_name_ar,
payment_type (cash|installment),
cash_discount_pct,
down_payment_pct, months, interest_rate,
is_active, created_at, updated_at
```

### `special_discounts`
```
id, name_ar, name_en,
discount_type (percentage|fixed_amount|free_subscription),
discount_percentage, fixed_amount,
applies_to (membership_fee|subscription|all),
effective_from (nullable), effective_to (nullable),
condition_type (none|full_payment|min_payment),
condition_min_amount,
bonus_free_subscription_years (0-5),
requires_document (0|1),
description, is_active,
created_at, updated_at, created_by, updated_by
```

### `regulatory_discounts`
```
id, article_number, name_ar, name_en, description,
discount_percentage, max_discount_percentage,
eligibility_type (cross_branch_member|government_employee|ministry_youth_employee|board_of_trustees|club_employee|group_membership),
source_branch_id (FK|NULL), target_branch_id (FK|NULL),
min_service_years (for club_employee),
allows_installment (0|1), installment_max_years, installment_interest_rate,
applies_to, effective_from, effective_to,
board_decision_number, board_decision_date, notes,
is_active, created_by, updated_by, created_at, updated_at
```

### `regulatory_discount_group_tiers`
```
id, regulatory_discount_id (FK),
min_quantity, max_quantity (nullable),
discount_percentage, is_active
```

### `regulatory_discount_applications`
```
id, regulatory_discount_id (FK), member_id (FK|NULL),
applicant_name, discount_percentage,
original_amount, discount_amount, final_amount,
status (pending|approved|rejected),
verification_data (JSON), notes,
rejection_reason,
created_by, approved_by, approved_at,
created_at, updated_at
```

### `members` (الحقول المتعلقة بالخصومات)
```
special_discount_id (FK|NULL),
discount_amount (calculated),
special_discount_document (file path),
regulatory_discount_id (FK|NULL),
regulatory_discount_amount (calculated),
regulatory_discount_document (file path),
regulatory_eligibility_type (enum)
```

### `payment_requests` (الحقول المتعلقة)
```
board_offer_id (FK|NULL),
offer_snapshot_json (JSON — frozen offer state at request time)
```

---

## 10. ما لا يجب فعله

- **لا تنشئ board offer + special discount بنفس النسبة بدون قصد** — هيتراكموا
- **لا تعدّل عرض ساري والطلبات في الخزينة** — الطلبات محمية بالـ snapshot لكن يسبب لخبطة تقارير
- **لا تحذف خصم مُعيَّن لعضو** — عطّله (is_active=0) بدل الحذف
- **لا تضع effective_to = null في board offer** — مطلوب دائماً
- **لا تنسى إن الفائدة سنوية** — 22% سنوي × (أشهر/12)
- **لا تطبّق خصم لائحي بدون مستند** — حتى لو النظام يسمح، الاعتماد قد يُرفض
- **لا تتجاوز max_discount_percentage** — النظام يطبّقه تلقائياً
- **لا تنسى اعتماد طلبات الخصم اللائحي** — تبقى pending حتى يعتمدها مسؤول
