نظام الشحن — مرجع واجهة برمجة التطبيقات للواجهة الأمامية

مرجع مفصّل لمطوّري الواجهة الأمامية الذين يتكاملون مع واجهة برمجة تطبيقات المسؤول (Admin API).

النطاق: تغطّي واجهة برمجة تطبيقات المسؤول (/api/admin/*) المصادقة، وإدارة المسؤولين/الأدوار/الصلاحيات، والسائقين، والمركبات، وفترات عدم التوفر، وتعيينات السائق–المركبة، والمستخدمين، والشحنات، ونقاط توقف الشحنات، وإثباتات التوصيل، وعمليات التوصيل الفاشلة، والمسارات ونقاط توقف المسار.

جدول المحتويات

1. البدء السريع
2. الاتفاقيات العامة
3. المصادقة
4. الملف الشخصي
5. المسؤولون
6. الأدوار والصلاحيات
7. السائقون
8. المركبات
9. فترات عدم توفر السائقين
10. تعيينات السائق–المركبة
11. المستخدمون (العملاء)
12. الشحنات
13. نقاط توقف الشحنات
14. إثباتات التوصيل
15. عمليات التوصيل الفاشلة
16. المسارات
17. نقاط توقف المسار
18. مرجع نماذج النطاق
19. مرجع التعدادات (Enums)
20. مرجع الصلاحيات
21. معالجة الأخطاء
22. قائمة التحقق لتكامل الواجهة الأمامية

البدء السريع

POST /api/admin/login
Content-Type: application/json
Accept-Language: en

{
  "email": "mousa@example.com",
  "password": "password"
}

احفظ رمز JWT المُعاد وأرسله مع كل طلب لاحق:

GET /api/admin/drivers
Authorization: Bearer {token}
Accept: application/json
Accept-Language: en

عنوان URL الأساسي: {APP_URL}/api — مثلًا http://localhost:8000/api عند تشغيل php artisan serve.

الاتفاقيات العامة

رؤوس الطلب (Request Headers)

غلاف الاستجابة (Response Envelope)

كل استجابة من واجهة برمجة التطبيقات تستخدم هذا الهيكل:

{
  "status": "Success",
  "message": "Data fetched successfully",
  "data": {},
  "statusCode": 200
}

عند نجاح تسجيل الدخول، يُعاد رمز JWT أيضًا في رأس الاستجابة Authorization كـ Bearer {token}.

طرق HTTP

التحديثات تستخدم POST، وليس PUT أو PATCH.

جميع نقاط نهاية التحديث تتبع النمط POST /api/admin/{resource}/{id}.

أنواع المحتوى (Content Types)

عند استخدام multipart/form-data:

• أرسل الحقول العددية كحقول نموذج.
• أرسل working_days كحقول متكررة أو كسلسلة JSON (مصفوفة).
• أرسل roles / permissions كحقول متكررة أو كسلسلة JSON للمصفوفة.
• أرسل image كحقل ملف (حد أقصى 5 ميجابايت، يجب أن يكون صورة).

القوائم والتصفية والترتيب

معظم نقاط نهاية القوائم GET تقبل معاملات سلسلة الاستعلام (query string):

تُحوّل قيم سلسلة الاستعلام "null" و "" تلقائيًا إلى null بواسطة الوسيط (middleware).

التقسيم إلى صفحات (Pagination)

نقاط النهاية المُقسّمة (GET .../paginated) تُغلّف النتائج كالتالي:

{
  "drivers": [],
  "total": 50,
  "count": 10,
  "per_page": 10,
  "current_page": 1,
  "total_pages": 5,
  "links": {
    "first": "http://localhost:8000/api/admin/drivers/paginated?page=1",
    "last": "http://localhost:8000/api/admin/drivers/paginated?page=5",
    "prev": null,
    "next": "http://localhost:8000/api/admin/drivers/paginated?page=2"
  }
}

مفتاح المجموعة يطابق اسم المورد:

حجم الصفحة ثابت عند 10 عناصر لكل صفحة.

المصادقة

جميع المسارات تحت /api/admin/* ما عدا POST /login تتطلب JWT صالحًا في رأس Authorization.

• الحارس (Guard): admin
• المكتبة: JWT Auth (tymon/jwt-auth)
• مدة صلاحية الرمز (Token TTL): تُعاد كـ expires_in (بالثواني) في استجابة تسجيل الدخول. تُضبط عبر متغير البيئة JWT_TTL (بالدقائق)؛ إذا لم يُضبط، قد لا ينتهي الرمز.

POST /api/admin/login

مصادقة مسؤول واستلام JWT.

المصادقة مطلوبة: لا

جسم الطلب:

مثال على جسم الطلب:

{
  "email": "mousa@example.com",
  "password": "SecurePass123!",
  "fcm_token": "device-fcm-token-abc123"
}

استجابة النجاح 200:

{
  "status": "Success",
  "message": "User successfully signed in",
  "data": {
    "admin": {
      "id": 1,
      "name": "mousa",
      "email": "mousa@example.com",
      "roles": ["operations_manager"],
      "permission_groups": [
        {
          "group": "Driver",
          "group_label": "Drivers",
          "permissions": [
            {
              "id": 1,
              "name": "ViewAny:Driver",
              "display_name": "View Any",
              "group": "Driver"
            }
          ]
        }
      ]
    },
    "token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
    "token_type": "bearer",
    "expires_in": 3600
  },
  "statusCode": 200
}

استجابات الخطأ:

POST /api/admin/logout

إبطال جلسة JWT الحالية.

المصادقة مطلوبة: نعم

جسم الطلب: لا يوجد

استجابة النجاح 200:

{
  "status": "Success",
  "message": "User successfully signed out",
  "data": null,
  "statusCode": 200
}

استجابات الخطأ:

الملف الشخصي

إدارة الملف الشخصي للمسؤول المصادق حاليًا. لا تتطلب صلاحيات إدارة المسؤولين.

GET /api/admin/profile

الصلاحية المطلوبة: لا شيء (المصادقة فقط)

استجابة النجاح 200: تُعيد AdminResource (انظر المسؤولون) مع:

• is_current_admin: true
• permission_groups مُضمّنة
• roles مُضمّنة

POST /api/admin/profile

تحديث ملف المسؤول المصادق.

الصلاحية المطلوبة: لا شيء (المصادقة فقط)

جسم الطلب (JSON أو multipart):

مثال على جسم الطلب:

{
  "name": "mousa",
  "email": "mousa.updated@example.com",
  "password": "NewSecurePass123!"
}

استجابة النجاح 200: AdminResource محدّث مع رسالة profileUpdatedSuccessfully.

إحصائيات لوحة التحكم

إحصائيات KPI مجمّعة للوحة تحكم العمليات. تتطلب كلا النقطتين صلاحية View:Dashboard (أو مسؤول عام).

GET /api/admin/dashboard/overview

بطاقات KPI العليا لليوم والأسبوع والشهر. لا توجد معاملات استعلام.

الصلاحية المطلوبة: View:Dashboard

استجابة النجاح 200:

{
  "data": {
    "shipments_created_today": 12,
    "shipments_created_this_week": 48,
    "shipments_created_this_month": 190,
    "active_routes": 5,
    "active_drivers": 18,
    "pending_pickups": 9,
    "out_for_delivery": 14,
    "delivered_today": 22
  }
}

GET /api/admin/dashboard/trends

سلسلة زمنية يومية للرسوم البيانية، تمتد 7 أو 30 يومًا.

الصلاحية المطلوبة: View:Dashboard

معاملات الاستعلام:

استجابة النجاح 200:

{
  "data": {
    "days": 30,
    "from": "2026-06-20",
    "to": "2026-07-19",
    "series": [
      {
        "date": "2026-06-20",
        "shipments_created": 8,
        "shipments_delivered": 6,
        "failed_deliveries": 1,
        "failure_rate": 0.1429
      }
    ]
  }
}

خطأ التحقق 422: يُعاد عند إرسال قيمة days غير 7 أو 30.

المسؤولون

إدارة مستخدمي المكتب الخلفي.

بادئة الصلاحية: Admin (مثل ViewAny:Admin, Create:Admin)

حسابات المسؤولين المخفية (المُضبطة عبر متغير البيئة HIDDEN_ADMIN) مستبعدة من القوائم.

نقاط النهاية

معاملات استعلام القائمة

جسم طلب الإنشاء

مثال على جسم الطلب:

{
  "name": "mousa",
  "email": "mousa@example.com",
  "password": "SecurePass123!",
  "roles": ["operations_manager"]
}

جسم طلب التحديث

نفس حقول الإنشاء، جميعها اختيارية (تُطبّق قواعد sometimes). احذف password للإبقاء على كلمة المرور الحالية. أرسل roles: [] لإزالة جميع الأدوار.

مثال على جسم الطلب:

{
  "name": "mousa",
  "email": "mousa.admin@example.com",
  "roles": ["super_admin"]
}

شكل مورد المسؤول (Admin Resource Shape)

{
  "id": 1,
  "name": "mousa",
  "email": "mousa@example.com",
  "image": "http://localhost:8000/storage/1/admin_image.jpg",
  "roles": ["super_admin"],
  "permission_groups": [],
  "is_current_admin": false,
  "created_at": "2026-01-15T10:00:00.000000Z",
  "updated_at": "2026-01-15T10:00:00.000000Z"
}

قيود الحذف

• لا يمكن حذف حسابك الخاص → 403 مع رسالة cannotDeleteCurrentAdmin

الأدوار والصلاحيات

التحكم في الوصول المبني على الأدوار باستخدام Spatie Permission (الحارس: admin).

بادئات الصلاحيات: Role, Permission

نقاط النهاية

معاملات استعلام القائمة (الأدوار)

جسم طلب إنشاء الدور

مثال على جسم الطلب:

{
  "name": "warehouse_manager",
  "permissions": ["ViewAny:Driver", "Create:Driver", "ViewAny:Vehicle"]
}

جسم طلب تحديث الدور

مثال على جسم الطلب:

{
  "name": "warehouse_manager",
  "permissions": ["ViewAny:Driver", "Update:Driver"]
}

جسم طلب مزامنة الصلاحيات

POST /api/admin/roles/{id}/permissions

مثال على جسم الطلب:

{
  "permissions": ["ViewAny:Driver", "Create:Driver", "ViewAny:Vehicle", "Create:Vehicle"]
}

رسالة النجاح: permissionsAssignedSuccessfully

شكل مورد الدور (Role Resource Shape)

{
  "id": 2,
  "name": "warehouse_manager",
  "guard_name": "admin",
  "permission_groups": [
    {
      "group": "Driver",
      "group_label": "Drivers",
      "permissions": [
        {
          "id": 1,
          "name": "ViewAny:Driver",
          "display_name": "View Any",
          "group": "Driver"
        }
      ]
    }
  ],
  "created_at": "2026-01-15T10:00:00.000000Z",
  "updated_at": "2026-01-15T10:00:00.000000Z"
}

شكل مجموعة الصلاحيات (Permission Group Shape)

يُستخدم في تسجيل الدخول والملف الشخصي والأدوار وقائمة الصلاحيات:

{
  "group": "Driver",
  "group_label": "Drivers",
  "permissions": [
    {
      "id": 1,
      "name": "ViewAny:Driver",
      "display_name": "View Any",
      "group": "Driver"
    }
  ]
}

القيود

• دور المسؤول الأعلى (super admin) لا يمكن تعديله أو حذفه → 403 (cannotModifySuperAdmin)

السائقون

إدارة سائقي التوصيل.

بادئة الصلاحية: Driver

نقاط النهاية

معاملات استعلام القائمة

الأعمدة القابلة للترتيب: name, phone, driver_number, work_start_time, work_end_time, created_at, distance

عند تقديم lat/lng، تتضمن النتائج حقل distance (كم) ويُرتّب افتراضيًا حسب الأقرب أولًا ما لم يُضبط sort_by صراحةً.

صيغة الوقت: HH:MM:SS أو HH:MM (تُطبّع تلقائيًا إلى HH:MM:SS).

جسم طلب الإنشاء

مثال على جسم الطلب:

{
  "name": "mousa",
  "phone": "944123456",
  "phone_country": "+963",
  "email": "mousa.driver@example.com",
  "password": "SecurePass123!",
  "address": "Damascus, Syria",
  "license_number": "SY-12345",
  "working_days": ["sun", "mon", "tue", "wed", "thu"],
  "work_start_time": "08:00:00",
  "work_end_time": "17:00:00",
  "lat": 33.5138,
  "lng": 36.2765,
  "is_active": true,
  "vehicle_id": 7
}

تعيين المركبة عند التحديث: أرسل vehicle_id لتعيين أو تبديل المركبة؛ أرسل vehicle_id: null لإلغاء التعيين الحالي. احذف الحقل لإبقاء التعيين دون تغيير.

جسم طلب التحديث

نفس حقول الإنشاء. جميع الحقول اختيارية ما عدا حيث تُطبّق sometimes + required. كلمة المرور اختيارية (احذفها للإبقاء على الحالية).

مثال على جسم الطلب:

{
  "name": "mousa",
  "phone": "944654321",
  "phone_country": "+963",
  "work_start_time": "09:00:00",
  "work_end_time": "18:00:00",
  "is_active": true
}

شكل مورد السائق (Driver Resource Shape)

{
  "id": 1,
  "driver_number": "482910",
  "name": "mousa",
  "phone": "944123456",
  "phone_country": "+963",
  "email": "mousa.driver@example.com",
  "image": "http://localhost:8000/storage/2/driver_image.jpg",
  "address": "Damascus, Syria",
  "license_number": "DL-12345",
  "working_days": ["sun", "mon", "tue", "wed", "thu"],
  "work_start_time": "08:00:00",
  "work_end_time": "17:00:00",
  "lat": 24.7136,
  "lng": 46.6753,
  "is_active": true,
  "created_at": "2026-01-15T10:00:00.000000Z",
  "updated_at": "2026-01-15T10:00:00.000000Z",
  "distance": 3.2,
  "vehicle": {
    "id": 7,
    "plate_number": "ABC-1234",
    "owner_type": "driver",
    "owner_type_label": "سائق",
    "owner_id": 1,
    "max_weight": 500,
    "max_volume": 10,
    "is_active": true,
    "created_at": "2026-01-15T10:00:00.000000Z",
    "updated_at": "2026-01-15T10:00:00.000000Z"
  }
}

المركبات

إدارة مركبات الأسطول.

بادئة الصلاحية: Vehicle

نقاط النهاية

معاملات استعلام القائمة

جسم طلب الإنشاء

مثال على جسم الطلب:

{
  "plate_number": "DMS-1234",
  "owner_type": "company",
  "max_weight": 1500,
  "max_volume": 12.5
}

مثال على جسم الطلب (مملوكة للسائق):

{
  "plate_number": "DMS-5678",
  "owner_type": "driver",
  "owner_id": 1,
  "max_weight": 2000,
  "max_volume": 15
}

جسم طلب التحديث

مثال على جسم الطلب:

{
  "plate_number": "DMS-9999",
  "max_weight": 1800,
  "max_volume": 14,
  "is_active": false
}

شكل مورد المركبة (Vehicle Resource Shape)

{
  "id": 1,
  "plate_number": "ABC-1234",
  "owner_type": "company",
  "owner_type_label": "الشركة",
  "owner_id": null,
  "max_weight": 1500,
  "max_volume": 12.5,
  "is_active": true,
  "created_at": "2026-01-15T10:00:00.000000Z",
  "updated_at": "2026-01-15T10:00:00.000000Z"
}

فترات عدم توفر السائقين

فترات الإجازة / عدم التوفر للسائقين.

بادئة الصلاحية: DriverUnavailability

نقاط النهاية

يمكن الوصول إليها أيضًا عبر GET /api/admin/drivers/{id}/unavailabilities.

معاملات استعلام القائمة

جسم طلب الإنشاء

مثال على جسم الطلب:

{
  "driver_id": 1,
  "start_date": "2026-06-01",
  "end_date": "2026-06-05",
  "reason": "Annual leave"
}

جسم طلب التحديث

نفس الحقول، جميعها اختيارية. إذا قُدّمت كلا التاريخين في التحديث، يجب أن يظل end_date بعد start_date.

مثال على جسم الطلب:

{
  "start_date": "2026-06-01",
  "end_date": "2026-06-10",
  "reason": "Extended leave"
}

شكل مورد عدم توفر السائق (Driver Unavailability Resource Shape)

{
  "id": 1,
  "driver_id": 5,
  "start_date": "2026-06-01T00:00:00.000000Z",
  "end_date": "2026-06-05T00:00:00.000000Z",
  "reason": "Annual leave",
  "created_at": "2026-05-20T10:00:00.000000Z",
  "updated_at": "2026-05-20T10:00:00.000000Z"
}

تعيينات السائق–المركبة

يربط السائقين بالمركبات للاستخدام التشغيلي. يمكن للمركبة أن يكون لها تعيين نشط واحد فقط في كل مرة (released_at === null).

بادئة الصلاحية: DriverVehicleAssignment

نقاط النهاية

التعيين (Assign)

لا يوجد جسم طلب. ينشئ سجلًا مع:

• assigned_at = الطابع الزمني الحالي
• released_at = null

خطأ: 422 إذا كانت المركبة لديها تعيين نشط بالفعل (vehicleAlreadyAssigned)

إلغاء التعيين (Unassign)

لا يوجد جسم طلب. يضبط released_at على الطابع الزمني الحالي للتعيين النشط.

خطأ: 404 إذا لم يوجد تعيين نشط (vehicleAssignmentNotFound)

شكل مورد تعيين السائق–المركبة (Driver Vehicle Assignment Resource Shape)

{
  "id": 1,
  "driver_id": 3,
  "vehicle_id": 7,
  "assigned_at": "2026-06-01T08:00:00.000000Z",
  "released_at": null,
  "vehicle": {
    "id": 7,
    "plate_number": "XYZ-5678",
    "owner_type": "company",
    "owner_type_label": "الشركة",
    "owner_id": null,
    "max_weight": 2000,
    "max_volume": 15,
    "is_active": true,
    "created_at": "...",
    "updated_at": "..."
  },
  "driver": {
    "id": 3,
    "driver_number": "482910",
    "name": "mousa"
  },
  "created_at": "2026-06-01T08:00:00.000000Z",
  "updated_at": "2026-06-01T08:00:00.000000Z"
}

المستخدمون (العملاء)

العملاء النهائيون الذين يقدّمون الشحنات. هؤلاء ليسوا حسابات مسؤولين.

بادئة الصلاحية: User

نقاط النهاية

معاملات استعلام القائمة

جسم طلب الإنشاء

مثال على جسم الطلب:

{
  "name": "mousa",
  "phone": "944123456",
  "phone_country": "+963",
  "email": "mousa@example.com",
  "company_name": "Mousa Trading Co."
}

جسم طلب التحديث

نفس الحقول، جميعها اختيارية. تُعاد التحقق من تفرد رقم الهاتف عند تغيير phone أو phone_country.

مثال على جسم الطلب:

{
  "name": "mousa",
  "phone": "944654321",
  "phone_country": "+963",
  "company_name": "Mousa Logistics"
}

شكل مورد المستخدم (User Resource Shape)

{
  "id": 1,
  "name": "mousa",
  "phone": "944123456",
  "phone_country": "+963",
  "email": "mousa@example.com",
  "company_name": "Mousa Trading Co.",
  "created_at": "2026-01-15T10:00:00.000000Z",
  "updated_at": "2026-01-15T10:00:00.000000Z"
}

الشحنات

إدارة دورة حياة الشحنات بالكامل — الإنشاء والتعديل والتأكيد والإلغاء والتعيين للمسارات والعمليات الجماعية.

بادئة الصلاحية: Shipment

نقاط النهاية (Endpoints)

معاملات البحث والتصفية

جلب شحنة واحدة

GET /api/admin/shipments/{id}

{id} يقبل المعرّف الرقمي أو shipment_number (مثل SH-AB12CD34).

نموذج طلب الإنشاء

إنشاء مع مستخدم (Upsert)

POST /api/admin/shipments/create-with-user

نفس حقول إنشاء الشحنة، مع استبدال user_id بكائن user. يطابق العميل عبر phone + phone_country ويحدّث الاسم/البريد/الشركة إن وُجد، أو ينشئ مستخدمًا جديدًا ثم ينشئ شحنة مسودة.

مثال:

{
  "user": {
    "name": "أحمد الفارسي",
    "phone": "0501234567",
    "phone_country": "SA",
    "email": "ahmed@example.com",
    "company_name": "Acme"
  },
  "delivery_date": "2026-07-15",
  "payment_type": "cod",
  "cod_amount": 150,
  "total_weight": 2.5,
  "total_volume": 0.0005,
  "stops": [
    { "type": "pickup", "country": "SA", "city": "Riyadh", "lat": 24.7136, "lng": 46.6753 },
    { "type": "delivery", "country": "SA", "city": "Jeddah", "lat": 21.4858, "lng": 39.1925 }
  ],
  "items": [{ "name": "صندوق إلكترونيات", "quantity": 1, "weight": 2.5 }]
}

شكل مورد الشحنة (Shipment Resource)

{
  "id": 1,
  "shipment_number": "AB3XZ7QR",
  "user_id": 5,
  "user_name": "أحمد الفارسي",
  "user": { "id": 5, "name": "أحمد الفارسي" },
  "delivery_date": "2026-07-15T00:00:00.000000Z",
  "status": "pending",
  "status_label": "في الانتظار",
  "type": "domestic",
  "type_label": "محلي",
  "payment_type": "cod",
  "payment_type_label": "عند الاستلام",
  "cod_amount": 150,
  "total_weight": 2.5,
  "total_volume": 0.0005,
  "priority": "normal",
  "priority_label": "عادية",
  "priority_color": "primary",
  "notes": "التعامل بحذر",
  "stops": [...],
  "items": [...],
  "events": [...],
  "created_at": "2026-06-21T10:00:00.000000Z",
  "updated_at": "2026-06-21T10:00:00.000000Z"
}

stops وitems وevents موجودة فقط عند جلب الشحنة عبر GET /shipments/{id}.

نقاط توقف الشحنات

قائمة نقاط توقف الشحنات مع فلاتر متعددة — مفيدة لتخطيط المسارات والعمليات اليومية. تتضمن كل نقطة ملخص الشحنة الأم.

بادئة الصلاحية: ShipmentStop

نقاط النهاية

معاملات الاستعلام للقائمة

شكل مورد نقطة التوقف

{
  "id": 12,
  "shipment_id": 4,
  "type": "pickup",
  "type_label": "تحصيل",
  "contact_name": "Warehouse",
  "phone": "0501234567",
  "phone_country": "SA",
  "country": "SA",
  "city": "Riyadh",
  "area": "Al Olaya",
  "street": "King Fahd Rd",
  "building": null,
  "floor": null,
  "apartment": null,
  "lat": 24.7136,
  "lng": 46.6753,
  "full_address": "King Fahd Rd, Al Olaya, Riyadh, SA",
  "sequence": 1,
  "created_at": "2026-06-21T10:00:00.000000Z",
  "updated_at": "2026-06-21T10:00:00.000000Z",
  "shipment": {
    "id": 4,
    "shipment_number": "SH-AB12CD34",
    "delivery_date": "2026-07-15T00:00:00.000000Z",
    "status": "pending",
    "type": "domestic",
    "priority": "normal",
    "user_id": 5,
    "user_name": "Ahmed Al-Farsi",
    "payment_type": "prepaid"
  }
}

إثباتات التوصيل

سجلات تأكيد التوصيل للشحنات.

بادئة الصلاحية: ProofOfDelivery

نقاط النهاية

نموذج الطلب

التأثيرات الجانبية: يُعيّن حالة الشحنة إلى delivered ويُسجّل حدث pod_uploaded.

شكل مورد إثبات التوصيل

{
  "id": 1,
  "shipment_id": 1,
  "receiver_name": "عمر أحمد",
  "receiver_phone": "0559876543",
  "receiver_phone_country": null,
  "delivered_at": "2026-07-15T14:30:00.000000Z",
  "notes": null,
  "created_by_type": "App\\Models\\Admin",
  "created_by_id": 1,
  "created_by_name": "Admin",
  "shipment": null,
  "created_at": "2026-07-15T14:31:00.000000Z",
  "updated_at": "2026-07-15T14:31:00.000000Z"
}

عمليات التوصيل الفاشلة

سجلات محاولات التوصيل الفاشلة. تُنشأ تلقائيًا عند فشل RouteStop من نوع delivery، أو يدويًا عبر هذه الواجهة.

بادئة الصلاحية: FailedDelivery

نقاط النهاية

نموذج الطلب

التأثيرات الجانبية: يُعيّن حالة الشحنة إلى delivery_failed ويُسجّل حدث delivery_failed.

شكل مورد التوصيل الفاشل

{
  "id": 1,
  "shipment_id": 1,
  "reason_code": "customer_refused",
  "reason_code_label": "العميل رفض الاستلام",
  "notes": null,
  "created_by_type": "App\\Models\\Admin",
  "created_by_id": 1,
  "created_by_name": "Admin",
  "shipment": null,
  "created_at": "2026-07-15T14:35:00.000000Z",
  "updated_at": "2026-07-15T14:35:00.000000Z"
}

المسارات

مسارات السائق اليومية مع نقاط توقف مرتبة ومقاييس المسافة وإجراءات دورة الحياة (بدء، إكمال، إلغاء). يمكن إنشاء المسارات يدويًا أو توليدها عبر مهمة التخطيط.

بادئة الصلاحية: Route

نقاط النهاية

معاملات الاستعلام للقائمة

نموذج طلب الإنشاء

غير مقبول عند الإنشاء: vehicle_id, status, total_stops, optimized_distance, duration — يتم حلها أو حسابها من الخادم.

سلوك الخادم:

• يحل vehicle_id من أحدث DriverVehicleAssignment نشط للسائق
• يُعيّن status إلى assigned (السائق مُعيَّن ولم يبدأ بعد)
• يحسب total_stops, optimized_distance (كم), وduration (دقيقة) من إحداثيات نقاط التوقف
• ينشئ سجلات RouteStop مع أوقات الوصول/المغادرة المتوقعة
• يُعيّن الشحنات المرتبطة (pending أو delivery_failed) إلى assigned

أخطاء:

• 422 vehicleAssignmentNotFound — لا يوجد تعيين مركبة نشط للسائق
• 422 shipmentStopAlreadyOnRoute — إحدى النقاط مُعيَّنة بالفعل لمسار نشط/مُعيَّن
• 422 deliveryStopBeforePickupStop — نقطة التسليم تظهر قبل نقطة الاستلام لنفس الشحنة

مثال على نموذج الطلب:

{
  "driver_id": 1,
  "route_date": "2026-06-25",
  "stops": [10, 11, 15]
}

نموذج طلب التحديث

غير مقبول عند التحديث: vehicle_id, total_stops, optimized_distance, duration.

مسموح فقط عندما لا يكون المسار في حالة نهائية (completed, cancelled).

طلب تخطيط المسارات

POST /api/admin/routes/plan

يُرسل مهمة غير متزامنة. استعلم عبر GET /api/admin/routes/plan/result?date=YYYY-MM-DD للحصول على الملخص.

شكل مورد المسار (Route Resource)

{
  "id": 1,
  "route_number": "AB12CD34",
  "route_date": "2026-06-25T00:00:00.000000Z",
  "status": "assigned",
  "status_label": "تم تخصيص السائق",
  "total_stops": 3,
  "optimized_distance": 42.5,
  "duration": 95.0,
  "driver": { "...": "DriverResource عند التحميل" },
  "vehicle": { "...": "VehicleResource عند التحميل" },
  "stops": [ { "...": "RouteStopResource عند التحميل" } ],
  "created_at": "2026-06-24T20:00:00.000000Z",
  "updated_at": "2026-06-24T20:00:00.000000Z"
}

driver وvehicle وstops تظهر فقط عند تحميل العلاقات عبر GET /routes/{id} أو قوائم تحمّل العلاقات.

تعيينات المسار

يتتبّع سجل تعيين السائق للمسار. يمكن تعيين سائق ثم إلغاء تعيينه عند إعادة تعيين المسار.

بادئة الصلاحية: RouteAssignment

شكل مورد تعيين المسار

{
  "id": 1,
  "assigned_at": "2026-06-01T08:00:00.000000Z",
  "unassigned_at": null,
  "driver": {
    "id": 3,
    "driver_number": "482910",
    "name": "mousa"
  },
  "created_at": "2026-06-01T08:00:00.000000Z",
  "updated_at": "2026-06-01T08:00:00.000000Z"
}

نقاط توقف المسار

نقاط توقف مرتبة على مسار السائق، مرتبطة بنقاط توقف الشحنة.

بادئة الصلاحية: Route

نقاط النهاية

تُنشأ نقاط التوقف تلقائيًا عند إنشاء أو تحديث مسار عبر POST /api/admin/routes.

نموذج طلب التحديث

شكل مورد نقطة توقف المسار (RouteStop Resource)

{
  "id": 1,
  "route_id": 1,
  "shipment_stop_id": 10,
  "sequence": 1,
  "status": "pending",
  "status_label": "قيد الانتظار",
  "stop_type": "pickup",
  "stop_type_label": "تحصيل",
  "lat": 24.7136,
  "lng": 46.6753,
  "full_address": "Riyadh, SA",
  "contact_name": "Ali Hassan",
  "phone": "0501234567",
  "shipment": { "...": "ShipmentResource عند التحميل" },
  "distance_from_previous_km": 5.2,
  "estimated_minutes_from_previous": 12.5,
  "estimated_arrival_at": "2026-06-25T08:12:00.000000Z",
  "estimated_departure_at": "2026-06-25T08:27:00.000000Z",
  "arrived_at": null,
  "completed_at": null,
  "created_at": "2026-06-24T20:00:00.000000Z",
  "updated_at": "2026-06-24T20:00:00.000000Z"
}

مرجع نماذج النطاق

المعرّض حاليًا عبر واجهة برمجة التطبيقات

النطاق المخطّط (غير موجود بعد في واجهة برمجة التطبيقات)

هذه النماذج موجودة في قاعدة البيانات ولكن ليس لها نقاط نهاية HTTP مخصصة بعد.

StaticContent (static_contents)

مخزن إعدادات CMS / التطبيق بصيغة مفتاح–قيمة (غير موجود بعد في واجهة برمجة التطبيقات).

مخطط علاقات الكيانات (نظرة عامة)

User ──< Shipment ──< ShipmentItem
                  ──< ShipmentStop ──< RouteStop >── Route >── Driver
                  ──< ShipmentEvent                  └── Vehicle
                  ──< ProofOfDelivery
                  ──< FailedDelivery

Driver ──< DriverVehicleAssignment >── Vehicle
       ──< DriverUnavailability
       ──< RouteAssignment >── Route

Admin ──< Role ──< Permission

مرجع التعدادات (Enums)

جميع قيم التعدادات هي سلاسل snake_case. خزّنها كثوابت سلسلة في الواجهة الأمامية.

OwnerTypes

مُستخدم في واجهة برمجة التطبيقات اليوم — ملكية المركبة.

تُعيد واجهة برمجة التطبيقات كلًا من owner_type (القيمة) و owner_type_label (التسمية العربية).

TypeScript مقترح:

type OwnerType = 'company' | 'driver';

ShipmentStatuses

مخطّط — حالة دورة حياة الشحنة.

التدفق النموذجي:

draft → pending → assigned → pickup_in_progress → picked_up → at_hub
  → out_for_delivery → delivered
                                    ↘ delivery_failed → returned
Any state → cancelled

ShipmentTypes

ShipmentPriorities

مستخدم في واجهة برمجة التطبيقات اليوم — أولوية الشحنة للتخطيط والتصفية.

الافتراضي normal عند الإنشاء إذا لم يُرسل الحقل. تُخطَّط الشحنات ذات الأولوية الأعلى أولًا أثناء تخطيط المسارات.

ShipmentStopTypes

PaymentTypes

RouteStatuses

RouteStopStatuses

ShipmentEvents

أنواع أحداث الجدول الزمني المُسجّلة على الشحنات. يحتوي كل حدث على حمولة JSON في حقل data.

FailedDeliveryReasons

MediaTypes

أسماء مجموعات الوسائط الداخلية (تُستخدم لرفع الصور).

StaticContentTypes

مفاتيح إعدادات CMS / التطبيق (غير موجودة بعد في واجهة برمجة التطبيقات).

NotificationTypes

فئات الإشعارات الفورية (تعداد مدعوم بـ PHP).

أيام العمل (ليست تعداد PHP)

أيام جدول السائق. تُقبل كقيم مصفوفة في طلبات الإنشاء/التحديث.

TypeScript مقترح:

type WorkingDay = 'sun' | 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat';

مرجع الصلاحيات

تتحكم الصلاحيات فيما يمكن لكل مسؤول فعله. تحقّق منها في جانب العميل لإظهار/إخفاء عناصر الواجهة.

اتفاقية التسمية

{Action}:{Model}

أمثلة:

• ViewAny:Driver — يمكنه عرض قائمة السائقين
• Create:Vehicle — يمكنه إنشاء مركبات
• Update:Admin — يمكنه تعديل المسؤولين
• Delete:Role — يمكنه حذف الأدوار

الصلاحيات المخصّصة

هذه لا ترتبط بنموذج CRUD:

كيفية التحقق من الصلاحيات في الواجهة الأمامية

بعد تسجيل الدخول، افحص data.admin.permission_groups:

function hasPermission(
  permissionGroups: PermissionGroup[],
  permissionName: string
): boolean {
  return permissionGroups.some(group =>
    group.permissions.some(p => p.name === permissionName)
  );
}

// Usage
if (hasPermission(admin.permission_groups, 'Create:Driver')) {
  // Show "Add Driver" button
}

دور المسؤول الأعلى (super admin) لديه جميع الصلاحيات ضمنيًا.

معالجة الأخطاء

رموز حالة HTTP

رسائل الخطأ الشائعة

أخطاء التحقق تُعيد أول رسالة تحقق كـ message.

شكل استجابة الخطأ

{
  "status": "Error",
  "message": "Wrong Credentials",
  "data": null,
  "statusCode": 401
}

قائمة التحقق لتكامل الواجهة الأمامية

• تخزين JWT من استجابة تسجيل الدخول (data.token)
• إرسال Authorization: Bearer {token} مع كل طلب مصادق
• ضبط Accept-Language: en أو ar للرسائل المترجمة
• استخدام POST لجميع التحديثات (وليس PUT/PATCH)
• استخدام multipart/form-data عند رفع حقول image
• التحكم في الواجهة بالتحقق من permission_groups من استجابة تسجيل الدخول/الملف الشخصي
• معالجة الغلاف القياسي { status, message, data, statusCode }
• استخدام نقاط النهاية المُقسّمة مع معامل page للجداول
• تمرير search, sort_by, sort_direction للقوائم القابلة للتصفية
• للمركبات: فرض قواعد owner_id بناءً على owner_type
• للسائقين: إرسال working_days كمصفوفة؛ الأوقات كـ HH:MM أو HH:MM:SS
• للشحنات: يجب أن يحتوي مصفوف stops على نقطة pickup واحدة بالضبط ونقطة delivery واحدة بالضبط
• للشحنات: cod_amount مطلوب عند payment_type = cod
• معالجة أحداث status_changed من GET /shipments/{id}/events لعرض الجدول الزمني
• تعيين المسار: يجب أن تكون الشحنة pending قبل assign-route؛ وassigned قبل unassign-route
• إنشاء المسار: أرسل driver_id + stops[]؛ لا ترسل vehicle_id أو status أو المقاييس — الخادم يحسبها
• إنشاء المسار يتطلب أن يكون للسائق تعيين مركبة نشط
• تخطيط المسارات: أرسل عبر POST /routes/plan، واستعلم عبر GET /routes/plan/result?date=

فهرس المسارات (مرجع سريع)

واجهة برمجة تطبيق السائق (Driver App API)

واجهة تطبيق السائق (/api/driver/*) مخصصة للتطبيق الجوال للسائقين. تستخدم نفس آلية JWT مع حارس driver. الرموز لا تنتهي صلاحيتها (expires_in: null).

مصادقة السائق

ملف السائق

مسارات السائق

جميع مسارات الطلبات مقيّدة تلقائيًا بالسائق المصادَق عليه. للسائق مسار واحد في اليوم.

نقاط توقف المسار

منطق إكمال نقطة التوقف حسب النوع:

قيم reason_code لنقطة الفشل: customer_unavailable, wrong_address, customer_refused, unable_to_contact, damaged_package, other.

مُولّد من قاعدة شفرة shipping_system. آخر تحديث: يوليو 2026.