# توثيق Ele API

**Base URL (الإنتاج):** `https://razan.bcite.org/api/v1`

> التطوير المحلي: `http://127.0.0.1:8001/api/v1` (مع `php artisan serve`) أو `http://localhost/ele-api/public/api/v1` (مع Apache). المحاكي: `http://10.0.2.2:8001/api/v1`.

## قواعد عامة
| البند | القيمة |
|---|---|
| الصيغة | JSON |
| الهيدرات | `Accept: application/json` (دائمًا) |
| المصادقة | `Authorization: Bearer <token>` للمسارات المعلّمة 🔒 |
| الترقيم | `?page=1&per_page=20` (حتى 50)، والرد فيه `data` و`links` و`meta` |
| العملة | شيكل (₪)، الأسعار أرقام عشرية |

### الأخطاء
| الكود | المعنى |
|---|---|
| 401 | لا يوجد توكن أو غير صالح |
| 404 | غير موجود |
| 422 | بيانات غير صالحة: `{"message":"...","errors":{"field":["..."]}}` |
| 429 | طلبات كثيرة (login/register: 10 بالدقيقة) |

---
## 1) المصادقة
### POST `/register`
`name` (3 أحرف+)، `email` (فريد)، `phone` (اختياري)، `password` (6+)، `password_confirmation`، `device_name` (اختياري).

**201**
```json
{ "message": "Account created successfully.",
  "data": { "user": { "id": 3, "name": "Sara", "email": "sara@mail.com", "phone": null, "created_at": "..." },
            "token": "1|abc..." } }
```
### POST `/login`
`email`, `password`. نفس شكل الرد. بيانات خاطئة: 422 على الحقل `email`.
### POST `/logout` 🔒  /  GET `/me` 🔒

---
## 2) التصنيفات والمنتجات (عام)
### GET `/categories`
```json
{ "data": [ {"id":1,"name":"عبايات"}, {"id":2,"name":"بناطيل"} ] }
```
### GET `/products`
لا يحتاج توكن. إذا أرسلتِ التوكن يظهر `is_favorite` الصحيح، وبدونه دائمًا `false`.

| Query | وصف |
|---|---|
| q | بحث بالاسم/الوصف/التصنيف (شريط "ابحثي عن جاكيت...") |
| category | اسم التصنيف مثل `جكيتات`. القيمة `all` أو بدونها = الكل ("عرض الكل") |
| category_id | رقم التصنيف |
| min_price, max_price | نطاق السعر |
| sort | `newest` (افتراضي) / `price_asc` / `price_desc` |
| page, per_page | ترقيم |

```json
{ "data": [ {
  "id": 7, "name": "جاكيت", "description": "جاكيت دافئ بتصميم عصري.", "price": 180.0,
  "category": "جكيتات", "category_id": 6,
  "image_url": null, "image_asset": "lib/assets/جاكيت.jpg",
  "sizes":  [ {"id":1,"name":"S"}, {"id":2,"name":"M"}, {"id":3,"name":"L"}, {"id":4,"name":"XL"} ],
  "colors": [ {"id":1,"name":"أسود","hex":"#000000"}, {"id":2,"name":"سكني","hex":"#808080"}, {"id":3,"name":"أبيض","hex":"#FFFFFF"} ],
  "is_favorite": false } ], "links": {...}, "meta": {...} }
```
- `image_url`: رابط الصورة من السيرفر (null للبيانات التجريبية). أثناء الانتقال استخدمي `image_asset` (مسار الصورة داخل التطبيق) إذا كانت `image_url` فاضية.
- الملابس لها مقاسات S/M/L/XL، الأحذية 37 إلى 41، والحجابات والشنط **بدون مقاسات** (`sizes` فاضية، وما تعرضي اختيار المقاس).

### GET `/products/{id}`
شاشة تفاصيل المنتج: `{"data": Product}`.

---
## 3) المفضلة 🔒
- GET `/favorites`: `{"data":[Product,...]}`
- POST `/products/{id}/favorite`: toggle، يرجع `{"data":{"product_id":7,"is_favorite":true}}`

---
## 4) السلة 🔒
شكل الرد لكل عمليات السلة:
```json
{ "message": "Added to cart.",
  "data": {
    "items": [ { "id": 5, "product_id": 7, "name": "جاكيت", "price": 180.0,
                 "image_url": null, "image_asset": "lib/assets/جاكيت.jpg",
                 "size": {"id":2,"name":"M"}, "color": {"id":1,"name":"أسود","hex":"#000000"},
                 "quantity": 2, "line_total": 360.0, "available": true } ],
    "count": 2, "subtotal": 360.0, "total": 360.0 } }
```
`count` = مجموع الكميات (الرقم على أيقونة السلة).

| المسار | الوصف |
|---|---|
| GET `/cart` | عرض السلة |
| POST `/cart/items` | إضافة: `product_id`, `size_id`, `color_id`, `quantity` (اختياري، الافتراضي 1) |
| PATCH `/cart/items/{id}` | `{"quantity": 3}`، والقيمة `0` تحذف السطر (بدل `removeq`) |
| DELETE `/cart/items/{id}` | حذف سطر |
| DELETE `/cart` | تفريغ السلة |

قواعد الإضافة:
- نفس المنتج بنفس المقاس واللون يزيد الكمية (حتى 20)، وبمقاس أو لون مختلف يصير سطر جديد.
- لو المنتج له مقاسات/ألوان لازم ترسلي `size_id`/`color_id` منها (422 إذا ناقص أو غير صالح). ولو ما له مقاسات لا ترسلي `size_id`.

---
## 5) الطلبات 🔒 (الدفع عند الاستلام)
### POST `/orders`
ينشئ طلب من السلة الحالية ويفرّغها:
`full_name`, `phone` (9 أرقام+), `city`, `address`, `notes` (اختياري).

**201**
```json
{ "message": "Order placed successfully.",
  "data": { "id": 1, "order_number": "ELE-261022-K3F9A", "status": "Pending", "payment_method": "cod",
            "full_name": "...", "phone": "...", "city": "Nablus", "address": "...", "notes": null,
            "subtotal": 360.0, "shipping_fee": 0.0, "total": 360.0,
            "items": [ { "product_id": 7, "name": "جاكيت", "size": "M", "color": "أسود", "price": 180.0, "quantity": 2, "line_total": 360.0 } ],
            "created_at": "..." } }
```
السعر والاسم يتخزنوا وقت الشراء، فتغيير سعر المنتج لاحقًا لا يغيّر الطلبات القديمة.
أخطاء 422: السلة فاضية، أو منتج في السلة لم يعد متاحًا.

- GET `/orders`: طلباتي (مرقّم)
- GET `/orders/{id}`
- POST `/orders/{id}/cancel`: فقط إذا الحالة `Pending`

حالات الطلب: `Pending` ← `Confirmed` ← `Shipped` ← `Delivered`، أو `Cancelled`. (تغيير الحالة من طرف الإدارة غير موجود حاليًا، انظري الأسفل.)

---
## 6) الملف الشخصي 🔒
- GET `/profile`
- PUT `/profile`: `name`, `email`, `phone`
- PUT `/profile/password`: `current_password`, `password`, `password_confirmation`
- DELETE `/profile`: يتطلب `password`

---
## 7) سير تجربة كامل
1. `POST /login` (customer@ele.test)
2. `GET /products?category=جكيتات`
3. `POST /cart/items` `{"product_id":7,"size_id":2,"color_id":1,"quantity":2}`
4. `GET /cart` ثم `POST /orders`
5. `GET /orders`

## 8) غير مغطى حاليًا
- لوحة إدارة: إضافة المنتجات ورفع صورها، وتغيير حالة الطلبات (حاليًا بالـ SQL أو phpMyAdmin)
- استعادة كلمة السر، ودفع إلكتروني، وكوبونات، ورسوم شحن حسب المدينة (العمود `shipping_fee` جاهز)
