# E-Commerce Cart — Frontend Integration

دليل دمج سلة المشتريات في تطبيق العميل + إشعارات تحديثات السلة
(نزول سعر / خصم / كمية محدودة).

- الكارت **مربوط بالـ contact** بتاع العميل — بيفضل محفوظ على السيرفر
  حتى لو العميل سجّل من جهاز تاني.
- الأسعار **مش متخزنة في الكارت** — السيرفر بيحسبها live في كل قراءة
  بنفس منطق الأوردر (`sell_price_inc_tax` ناقص خصم المنتج)، وبيحسبها
  تاني server-side وقت عمل الأوردر. التطبيق **مبيبعتش أسعار أبداً**.
- الكارت مستقل عن الـ checkout — لما العميل يدوس "اطلب" التطبيق بيقرأ
  الكارت ويبعت الـ items لـ `POST /ecommerce/orders` زي ما هو شغال
  دلوقتي.

---

## 1. نظرة عامة على التدفق

```
1) العميل يضيف منتج        → POST /connector/api/ecommerce/cart/items
2) شاشة السلة              → GET  /connector/api/ecommerce/cart
3) تعديل كمية/ملاحظة       → PUT  /connector/api/ecommerce/cart/items/{item_id}
4) حذف منتج من السلة       → DELETE /connector/api/ecommerce/cart/items/{item_id}
5) تفريغ السلة             → DELETE /connector/api/ecommerce/cart
6) إتمام الطلب             → POST /connector/api/ecommerce/orders
                              (products[] من السلة — زي الحالي بالظبط)
```

كل الـ endpoints تحت `https://{host}/connector/api` ومحتاجة
`Authorization: Bearer {token}` زي باقي الـ e-commerce APIs.

---

## 2. الـ Endpoints

| Method | URL | الوظيفة |
|---|---|---|
| GET | `/connector/api/ecommerce/cart` | الكارت الحالي بالأسعار الحية |
| POST | `/connector/api/ecommerce/cart/items` | إضافة منتج (بيتدمج لو موجود) |
| PUT | `/connector/api/ecommerce/cart/items/{item}` | تعديل الكمية / الملاحظة |
| DELETE | `/connector/api/ecommerce/cart/items/{item}` | حذف سطر من السلة |
| DELETE | `/connector/api/ecommerce/cart` | تفريغ السلة كلها |

### تحديد العميل (`contact_id`)

- لو الـ token بتاع **عميل التطبيق** → الكارت بيتربط بـ `crm_contact_id`
  تلقائياً — مش لازم تبعت حاجة.
- لو الـ token بتاع **staff بيضيف لعميل** → ابعت `contact_id` في الـ
  body (POST/PUT) أو كـ query param (GET/DELETE).
- لو مفيش contact محدد → `422` مع
  `{"success": false, "msg": "..."}` (customer_not_found).

---

## 3. `GET /connector/api/ecommerce/cart`

بيرجع الكارت + الأسعار المحسوبة لحظياً من السيرفر.

**Response**

```json
{
  "success": true,
  "cart": {
    "id": 12,
    "contact_id": 55,
    "items": [
      {
        "id": 34,
        "product_id": 10,
        "product_name": "إطار 205/55",
        "product_image": "https://{host}/uploads/img/xxx.png",
        "variation_id": 55,
        "variation_name": "DUMMY",
        "quantity": 2,
        "unit_price": 1300,
        "discount_on_product": 10,
        "discount_type": "percentage",
        "final_unit_price": 1170,
        "line_total": 2340,
        "is_available": true,
        "note": "بدون تركيب"
      }
    ],
    "items_count": 1,
    "total_quantity": 2,
    "subtotal": 2340
  }
}
```

**حقول السطر المهمة**

| Field | المعنى |
|---|---|
| `unit_price` | سعر الوحدة قبل خصم المنتج (شامل الضريبة) |
| `discount_on_product` + `discount_type` | خصم المنتج — `fixed` أو `percentage` |
| `final_unit_price` | سعر الوحدة الفعلي بعد الخصم — **ده اللي يتعرض للعميل** |
| `line_total` | `final_unit_price × quantity` |
| `is_available` | `false` لو المنتج أو الـ variation اتمسح — اعرضه بشكل مختلف أو اقترح الحذف |

`subtotal` = مجموع الـ line_total — **من غير** مصاريف التوصيل أو خصومات
الأوردر (دي بتتحسب في `POST /ecommerce/orders`).

---

## 4. `POST /connector/api/ecommerce/cart/items`

**Body**

```json
{
  "product_id": 10,
  "variation_id": 55,
  "quantity": 2,
  "note": "بدون تركيب"
}
```

| Field | Required | الوصف |
|---|---|---|
| `product_id` | نعم | |
| `variation_id` | لا | لو مش متبعت السيرفر بياخد أول variation (نفس منطق الأوردر) |
| `quantity` | نعم | `> 0` — decimal مسموح |
| `note` | لا | ملاحظة على السطر (≤ 500 حرف) |

**سلوك الدمج:** لو نفس `product_id + variation_id` موجود في السلة →
الكمية الجديدة **بتتضاف** على السطر القديم، ومش بيتعمل سطر جديد.

**Response** — `201` + نفس شكل `cart` بتاع الـ GET.

**أخطاء**

| الحالة | ليه |
|---|---|
| `422` | validation (quantity صفر/سالب، منتج مش موجود للـ business ده، مفيش variation) |
| `422` + `customer_not_found` | اليوزر مش مربوط بعميل ومفيش `contact_id` متبعت |

---

## 5. `PUT /connector/api/ecommerce/cart/items/{item}`

تعديل سطر موجود. `{item}` هو `id` بتاع سطر السلة (مش product_id).

**Body** (كلهم optional — ابعت اللي بتغيره)

```json
{
  "quantity": 3,
  "note": "مع تركيب"
}
```

- `quantity` لازم `> 0` — عايز تصفّر الكمية؟ استخدم `DELETE`.
- `note: null` بيمسح الملاحظة.
- السطر لو مش تبع كارت العميل ده → `404`.

**Response** — `200` + الكارت المحدّث.

---

## 6. `DELETE /connector/api/ecommerce/cart/items/{item}`

بيحذف السطر ويرجع الكارت بعد الحذف — `200` + `cart`. السطر مش تبع
العميل → `404`.

## 7. `DELETE /connector/api/ecommerce/cart`

تفريغ السلة كلها — `200` + كارت فاضي. استخدمها بعد الـ checkout الناجح
لو عايز تمسح سلة العميل من السيرفر.

---

## 8. إشعارات تحديثات السلة (Push + In-App)

السيرفر بيعمل polling داخلي على منتجات السلة كل دقيقة، ولما حاجة تتغير
بيبعت **نوتيفيكيشن واحدة مجمّعة لكل عميل** (مش واحدة لكل منتج).

### الـ types الجديدة

| `data.type` | `reference_id` | امتى بتتبعت |
|---|---|---|
| `cart_price_update` | `product_id` | سعر منتج في السلة اتغير — خصم اتطبق/اتشال أو سعر اتعدل (نزول أو صعود) |
| `cart_low_stock` | `product_id` | الكمية نزلت تحت حد المخزون (`alert_quantity` بتاع المنتج أو 5) |
| `back_in_stock` *(موجود)* | `product_id` | منتج العميل مشترك في "notify me" رجع متوفر |

### شكل الـ payload

```json
{
  "notification": {
    "title": "السعر نزل في سلتك 🎉",
    "body": "إطار 205/55 في سلتك نزل لـ 1170 بدل 1300 — اطلب قبل ما يرجع يغلى",
    "image": "https://{host}/uploads/img/xxx.png"
  },
  "data": {
    "type": "cart_price_update",
    "reference_id": "10"
  }
}
```

- `reference_id` = **product_id** — استخدمه عشان تفتح صفحة المنتج
  لما العميل يدوس على الإشعار.
- لو العميل عنده أكتر من منتج اتغير → رسالة واحدة مجمّعة
  (`:count منتجات في سلتك اتعدل سعرها`) و`reference_id` = أول منتج —
  الأفضل توجّه لشاشة **السلة** في الحالة دي لو بتحب.
- الإشعارات دي بتتسجل في جدول الـ notifications زي باقي الأنواع —
  بتظهر في الـ in-app notifications list اللي بيقرأ منه التطبيق.

### ملاحظات للفرونت

- **السعر في السلة قد يتغير** — دايماً اعرض `final_unit_price` من آخر
  `GET /cart` ومتعتمدش على سعر اتخزن محلياً وقت الإضافة.
- لو جالك `cart_low_stock` والمنتج لسه متوفر — ممكن تبانر "الكمية
  بتخلص" على السطر في شاشة السلة.
- الإشعار بيتبعت **مرة واحدة لكل تغيير** — لو المخزون رجع ونقص تاني
  هيجيله إشعار جديد.

---

## 9. ملخص الـ cURL للتجربة

```bash
# إضافة
curl -X POST 'https://{host}/connector/api/ecommerce/cart/items' \
  -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' \
  -d '{"product_id":10,"quantity":2,"note":"بدون تركيب"}'

# قراءة السلة
curl 'https://{host}/connector/api/ecommerce/cart' \
  -H 'Authorization: Bearer TOKEN'

# تعديل كمية
curl -X PUT 'https://{host}/connector/api/ecommerce/cart/items/34' \
  -H 'Authorization: Bearer TOKEN' -H 'Content-Type: application/json' \
  -d '{"quantity":3}'

# حذف سطر / تفريغ
curl -X DELETE 'https://{host}/connector/api/ecommerce/cart/items/34' \
  -H 'Authorization: Bearer TOKEN'
curl -X DELETE 'https://{host}/connector/api/ecommerce/cart' \
  -H 'Authorization: Bearer TOKEN'
```
