# 🚀 المرجع الشامل لـ API نظام المطعم (إصدار v1)

هذا المستند هو الدليل التقني الكامل لربط تطبيقات الموبايل (Android/iOS) ولوحات التحكم الخارجية بنظام إدارة المطاعم.

---

## 📌 1. الإعدادات العامة (Global Config)
- **رابط النظام المركزي (Discovery)**: `http://localhost:8000/api/v1`
- **رابط المطعم الفرعي (Tenant)**: `http://{subdomain}.localhost:8000/api/v1`
- **Headers المطلوبة**:
  - `Accept: application/json`
  - `Authorization: Bearer {your_token}` (للروابط المحمية)

---

## 🔑 2. نظام الهوية (Authentication)
| الوظيفة | الرابط | النوع | الصلاحية |
| :--- | :--- | :--- | :--- |
| تسجيل الدخول | `/login` | `POST` | عام |
| جلب بياناتي | `/me` | `GET` | الجميع |
| تسجيل الخروج | `/logout` | `POST` | الجميع |

---

## 👑 3. لوحة تحكم الأدمن (Admin Panel)
*هذه الروابط متاحة للأدمن فقط.*

### ● الإحصائيات المالية
- **الرابط**: `GET /admin/stats`
- **الوظيفة**: جلب مبيعات اليوم، عدد الطلبات، والطلبات المعلقة.

### ● إدارة الموظفين
- **عرض الموظفين**: `GET /admin/staff`
- **إضافة موظف**: `POST /admin/staff` (المدخلات: `name`, `email`, `password`, `role`).

### ● الإدارة المالية (Finance)
- **عرض المصاريف**: `GET /admin/expenses`
- **تسجيل مصروف**: `POST /admin/expenses` (المدخلات: `amount`, `category_id`).
- **الموردين**: `GET /admin/suppliers`

---

## 💰 4. الكاشير والويتر (Waiter & Cashier)

### ● إدارة الطلبات (POS)
- **إنشاء طلب**: `POST /api/v1/orders`
- **دفع الطلب**: `POST /api/v1/orders/{id}/pay`
- **إلغاء الطلب**: `POST /api/v1/orders/{id}/cancel`

### ● إدارة الورديات (Shifts)
- **حالة الوردية الحالية**: `GET /shifts/current`
- **فتح وردية**: `POST /shifts/open` (المدخلات: `opening_balance`).
- **إغلاق وردية**: `POST /shifts/close`

---

## 👨‍🍳 5. نظام المطبخ (Kitchen Display)

### ● إدارة التحضير
- **طلبات المطبخ**: `GET /kitchen/pending`
- **تحديث حالة الصنف**: `POST /kitchen/items/{id}/status` (القيم: `preparing`, `ready`).

---

## 🚚 6. نظام السائقين (Driver App)

### ● مهام التوصيل
- **طلباتي النشطة**: `GET /driver/orders`
- **إحصائيات السائق**: `GET /driver/stats`
- **تم التوصيل**: `POST /driver/orders/{id}/status` (القيمة: `delivered`).

---

## 📱 7. تطبيق الزبائن (Customer & Guest)

### ● المنيو والعروض
- **الأقسام والصناف**: `GET /categories`
- **العروض النشطة**: `GET /promotions`

### ● الحجوزات والطلب
- **حجز طاولة**: `POST /reservations/public`
- **طلب أونلاين (Guest)**: `POST /orders/guest`

---

## ⚠️ 8. دليل الأخطاء (Error Codes)
- **401 Unauthorized**: التوكن منتهي أو غير صحيح.
- **422 Validation Error**: هناك بيانات ناقصة أو خاطئة في الطلب.
- **419 CSRF Mismatch**: (تم حلها برمجياً) لا تقلق بشأنها.
- **500 Server Error**: خطأ في قاعدة البيانات أو الكود.