# Nest — نظام الخصومات (Discounts)

دليل استخدام كامل للأربع خصومات، كل واحد **من A إلى Z**: الإضافة من الباك إند → الظهور للعميل → التطبيق على الأوردر.

> **القاعدة الذهبية:** خصم واحد فقط بيتطبّق على الأوردر.
> - **أول أوردر** و **تحقيق التوتال** = أوتوماتيك (بدون كود).
> - **البانر** و **العجلة** = بيعرضوا **كود كوبون** للعميل، والعميل هو اللي يدخله يدوي في خانة الكوبون وقت الأوردر لو حب.
> - لو دخل كوبون → الكوبون يكسب ويلغي الأوتوماتيك. لو مادخلش → أعلى خصم أوتوماتيك يتطبّق.

---

## ⚠️ إنشاء كوبون صحيح (سبب "الكوبون غير صالح")

أي كوبون (للبانر/العجلة) لازم يتعمل صح في **Ecommerce → Discounts → Create**:
1. Select type = **Coupon code**
2. اكتب الكود (مثلاً `OFFER20`) — مش فاضي
3. Discount type = **Percentage** أو **Fixed amount** (مش سايبها فاضية)
4. Discount = قيمة > 0 (مثلاً 20)
5. Apply to = **All orders** (للتجربة)
6. **Never expired ✅**
7. **Save**

---

# 1) خصم أول أوردر (#3) — من A إلى Z

**A. الفكرة:** خصم أوتوماتيك لأول أوردر للعميل المسجّل.

**B. الإضافة (Backend):** Appearance → Theme Options → **First order discount**
- Enable = Yes
- Discount type: Percentage / Fixed
- Discount value، Max (سقف للنسبة، 0 = بدون)، Minimum subtotal (0 = بدون)

**C. الظهور:** مفيش أي واجهة — بيشتغل في الخلفية.

**D. التطبيق على الأوردر:** لو العميل **مسجّل** ومعندوش أي أوردر مكتمل، ومادخلش كوبون → الخصم يدخل المقارنة، ولو الأعلى يتطبّق تلقائيًا في صفحة الدفع.

**E. ملاحظة:** الضيوف (غير المسجّلين) مش بياخدوه (منعًا للتحايل).

---

# 2) خصم تحقيق التوتال (#4) — من A إلى Z

**A. الفكرة:** خصم أوتوماتيك لما التوتال يوصل رقم معيّن (مثلاً 1000).

**B. الإضافة (Backend):** Theme Options → **Order total target discount**
- Enable = Yes
- Target amount (العتبة، مثلاً 1000)
- Discount type + value + Max

**C. الظهور:** بدون واجهة — أوتوماتيك.

**D. التطبيق:** لو التوتال ≥ العتبة وبدون كوبون → يدخل المقارنة مع "أول أوردر"، والأعلى قيمة يكسب.

---

# 3) بانر بعد التصفّح (#11) — من A إلى Z

**A. الفكرة:** بانر بيظهر ويعرض كود خصم؛ العميل ينسخه ويستخدمه لو حب.

**B. الإضافة (Backend):**
1. اعمل الكوبون في Discounts (قسم ⚠️ فوق).
2. Theme Options → **Ad Banner / Discount Offer Modal**:
   - فعّل البانر، اضبط الصورة/النصوص/العدّاد (كلها حقول جاهزة).
   - `Coupon code` = كود الكوبون (أو القالب لو متغيّر).
   - `Banner coupon mode` = **Fixed** (نفس الكود للكل) أو **Unique** (كود فريد لكل زائر).

**C. الظهور:** البانر يطلع بعد المدة المحددة ويعرض الكود. تجربة سريعة: `?open_discount_popup=1`.

**D. التطبيق:**
- العميل ينسخ الكود (في وضع Unique السيرفر يولّد كود فريد ويظهره وقت النسخ).
- **مش بيتطبّق تلقائيًا** — العميل يكتبه في خانة الكوبون في صفحة الدفع لو حب.
- ساعتها بيشتغل عادي عبر نظام كوبونات Botble، وقاعدة "خصم واحد" بتضمن إنه يلغي أي خصم أوتوماتيك.

---

# 4) عجلة الحظ (#12) — من A إلى Z

**A. الفكرة:** عجلة يلفّها العميل ويكسب كود خصم. **التصميم والألوان والأيقونات ثابتة** (من ألوان النظام) — إنت بتتحكم في **المحتوى فقط**.

**B. الإضافة (Backend):** Theme Options → **Lucky wheel**
- **الإعدادات العامة:** Enable = Yes · Limit to one spin per session (اختياري).
- **النصوص (تتحكم فيها):** Top badge · Title · Subtitle · Spin button text · Countdown label · Countdown duration (days) · Win message prefix · Action button text · Shop link text · Shop link URL.
- **Wheel segments (repeater):** كل خانة = **Prize label** + **Sub label** + **Coupon code** + **Coupon mode** (Fixed/Unique).
  - مفيش أيقونة ولا نسبة (weight) — الأيقونات ثابتة وكل الخانات احتمالها متساوي.
  - اترك الكود فاضي لخانة "من غير جائزة".

**C. الظهور:** العجلة ترسم الخانات وتعرض العدّاد والنصوص اللي ظبطتها. تجربة سريعة: `?open_wheel=1`.

**D. التطبيق:**
- العميل يلف → السيرفر يختار خانة **عشوائيًا** (مينفعش يتلاعب من المتصفح).
- في وضع Unique: السيرفر يولّد كود فريد (استخدام واحد، صلاحية 30 يوم) ويعرضه.
- الكود بيتعرض والعميل ينسخه؛ **مش بيتطبّق تلقائيًا** — يكتبه في خانة الكوبون وقت الأوردر لو حب.

---

## الربط مع الـ Checkout

| المصدر | إزاي بيتطبّق |
|--------|--------------|
| أول أوردر / التوتال (أوتو) | تلقائيًا لو مفيش كوبون مُدخل |
| البانر / العجلة (كوبون) | العميل يكتب الكود في خانة الكوبون → يكسب ويلغي الأوتوماتيك |

**قاعدة الخصم الواحد** مطبّقة مركزيًا في `NestApplyPromotionsService`: لو فيه كوبون مُدخل → الأوتوماتيك = 0. لو مفيش → أعلى خصم أوتوماتيك واحد.

---

## بعد أي تعديل في الإعدادات

```bash
php artisan optimize:clear
```

---

## ملفات النظام

```
platform/themes/nest/
├── src/Services/CustomerDiscountService.php      # منطق الأوتوماتيك + قاعدة الفائز الواحد
├── src/Services/NestApplyPromotionsService.php    # override محرك البروموشن
├── src/Http/Controllers/DiscountController.php    # يعرض/يولّد أكواد العجلة والبانر (بدون تطبيق تلقائي)
├── routes/web.php                                 # مسارات ajax
├── functions/functions.php                        # binding
├── functions/theme-options.php                    # كل حقول الإعداد
├── partials/lucky-wheel.blade.php                 # واجهة العجلة (نصوص وعدّاد قابلين للتحكم)
└── partials/banner-offer-modal.blade.php          # واجهة البانر
```