# سير عمل الطلب (Checkout Flow)

## نظرة عامة

```
[Home] → [Catalog] → [Product + Editor] → [Cart] → [Map/Zone] → [Quote] → [Confirm] → [Order Detail]
```

السلة **محلية** في التطبيق. الخادم يتحقق ويُنشئ الطلب عند `POST /checkout`.

---

## المرحلة 1 — بناء السلة

لكل عنصر في السلة:

| الحقل | مطلوب | ملاحظة |
|-------|--------|--------|
| `product_id` | ✅ | منتج نشط |
| `variant_id` | ✅* | *إذا كان للمنتج variants |
| `quantity` | ✅ | ≥ 1 |
| `design_id` | ⚡ | تصميم مرفوع و **approved** |
| `gallery_design_id` | ⚡ | من المعرض |
| `print_config` | ⭕ | موضع/مقياس على كل face |

> يجب وجود **مصدر تصميم واحد على الأقل** (`design_id` أو `gallery_design_id`).

---

## المرحلة 2 — اختيار موقع التوصيل

### Option A — خريطة تفاعلية

1. `GET /api/app/zones` — اعرض المضلعات
2. المستخدم يحدد نقطة → `POST /api/app/zones/check`
3. احفظ `zone.id`, `lat`, `lng`

### Option B — إرسال إحداثيات فقط

أرسل `lat` + `lng` في checkout — الخادم يحدد المنطقة تلقائياً.

### Option C — zone_id مع إحداثيات

أرسل `zone_id` + `lat` + `lng` — الخادم يتحقق أن النقطة داخل المضلع.

---

## المرحلة 3 — الكوبون (اختياري)

```http
POST /api/app/coupons/validate
{ "code": "SAVE20", "subtotal": 450 }
```

اعرض `discount` و `free_shipping` للمستخدم قبل التأكيد.

---

## المرحلة 4 — حساب السعر (Quote)

```http
POST /api/app/checkout/quote
Authorization: Bearer ...
```

**Body:** items + lat/lng/zone_id + coupon_code (اختياري)

**استخدم الاستجابة لعرض:**

| الحقل | العرض |
|-------|--------|
| `subtotal` | مجموع المنتجات |
| `discount` | خصم الكوبون |
| `shipping_fee` | رسوم التوصيل (0 إذا free_shipping) |
| `total` | الإجمالي النهائي |
| `zone.eta_days` | مدة التوصيل المتوقعة |
| `cod_label_ar` | «الدفع عند الاستلام» |

---

## المرحلة 5 — التأكيد وإنشاء الطلب

```http
POST /api/app/checkout
```

**حقول إضافية مطلوبة:**

- `shipping_name`
- `shipping_phone`
- `shipping_address`
- `notes` (اختياري)

**Response:**

```json
{
  "order_id": 42,
  "order_number": "ARK-20260530-A1B2",
  "total": 485
}
```

→ امسح السلة محلياً → انتقل لشاشة تفاصيل الطلب.

---

## المرحلة 6 — متابعة الطلب

```http
GET /api/app/orders/:id
```

**timeline** يعرض تغيّرات الحالة للعميل:

```
pending → confirmed → printing → out_for_delivery → delivered
```

### الإلغاء

```http
PATCH /api/app/orders/:id/cancel
```

مسموح فقط في `pending`.

---

## قواعد العمل

1. **`orders_accepting: false`** → امنع checkout واعرض رسالة من الإعدادات
2. **تصميم `pending`** → لا يُقبل في quote/checkout
3. **المخزون** → يُخصم عند إنشاء الطلب؛ quote يتحقق مسبقاً
4. **الحد الأدنى** → `max(store.min_order_amount, zone.min_order_amount)`
5. **COD** → لا يوجد دفع إلكتروني؛ `payment_method` دائماً `cod`

---

## مخطط تسلسل

```mermaid
sequenceDiagram
  participant App as Flutter App
  participant API as Arkan API

  App->>API: POST /uploads/design (multipart)
  API-->>App: file_url
  App->>API: POST /designs
  API-->>App: status pending

  Note over App,API: انتظار موافقة الإدارة → approved

  App->>API: POST /checkout/quote
  API-->>App: subtotal, shipping, total

  App->>API: POST /checkout + shipping
  API-->>App: order_number

  App->>API: GET /orders/:id
  API-->>App: items + timeline
```

---

## أخطاء شائعة

| رسالة | السبب | الحل |
|--------|--------|------|
| التصميم لم تتم الموافقة عليه | `design_id` pending | انتظر أو استخدم gallery |
| الموقع خارج مناطق التوصيل | lat/lng خارج المضلعات | اختر موقعاً آخر |
| الحد الأدنى للطلب X | subtotal < min | أضف منتجات |
| الكمية غير متوفرة | stock | قلّل الكمية أو variant آخر |
| المتجر لا يستقبل طلبات | orders_accepting false | أظهر رسالة للمستخدم |