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

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

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

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

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

البدء السريع

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.

المسؤولون

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

بادئة الصلاحية: 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
}

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

نفس حقول الإنشاء. جميع الحقول اختيارية ما عدا حيث تُطبّق 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

نقاط النهاية

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

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

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

{
  "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"
}

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

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

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

هذه النماذج موجودة في قاعدة البيانات وستشغّل ميزات الشحنات/المسارات. لا توجد نقاط نهاية HTTP لها بعد.

Shipment (shipments)

طلب التوصيل الأساسي الذي يقدّمه العميل.

العلاقات:

• user → User
• shipment_items → ShipmentItem[]
• shipment_stops → ShipmentStop[]
• shipment_events → ShipmentEvent[]
• proof_of_deliveries → ProofOfDelivery[]
• failed_deliveries → FailedDelivery[]

ShipmentItem (shipment_items)

العناصر الفردية ضمن شحنة.

ShipmentStop (shipment_stops)

محطات التحصيل أو التسليم أو المحطات الوسيطة على مسار الشحنة.

ShipmentEvent (shipment_events)

إدخالات سجل التدقيق / الجدول الزمني للشحنة.

Route (routes)

مسار يومي مُحسّن مُخصّص لسائق ومركبة.

العلاقات:

• driver → Driver
• vehicle → Vehicle
• route_stops → RouteStop[]
• route_assignments → RouteAssignment[]

RouteStop (route_stops)

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

RouteAssignment (route_assignments)

يتتبّع سجل تعيين السائق للمسار.

ProofOfDelivery (proof_of_deliveries)

سجل تأكيد التسليم.

FailedDelivery (failed_deliveries)

سجل محاولة تسليم فاشلة.

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

ShipmentStopTypes

PaymentTypes

RouteStatuses

RouteStopStatuses

ShipmentEvents

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

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
• ميزات الشحنات/المسارات: استخدم التعدادات من هذا المستند لكن انتظر مسارات واجهة برمجة التطبيقات في الخلفية

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

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