إنتقل إلى المحتوى الرئيسي

أنماط API للتطبيقات

آخر تحديث: أغسطس 2026 الحالة: تدقيق مكتمل - يتطلب إجراء

ملخص تنفيذي​

التطبيقالامتثالالمشاكل الحرجة
تطبيق العميل~75%عمليات الدفع تتجاوز REST API
تطبيق السائق~20%جميع العمليات تستخدم Supabase مباشرة

البنية الموصى بها​

┌─────────────────────────────────────────────────────────────────┐
│                        تطبيق الموبايل                            │
├─────────────────────────────────────────────────────────────────┤
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐       │
│  │   المصادقة   │    │   العمليات   │    │   الوقت      │       │
│  │              │    │   التجارية   │    │   الحقيقي    │       │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘       │
└─────────┼───────────────────┼───────────────────┼────────────────┘
          │                   │                   │
          ▼                   ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│  Supabase Auth  │  │    REST API     │  │    Supabase     │
│    (مباشر)      │  │   (Next.js)     │  │  Subscriptions  │
└─────────────────┘  └────────┬────────┘  └─────────────────┘
                              │
                              ▼
                     ┌─────────────────┐
                     │    Supabase     │
                     │   (PostgreSQL)  │
                     └─────────────────┘

قنوات الاتصال​

القناةالاستخدامالسبب
Supabase Authتسجيل الدخول، OTP، الجلساتمصمم لهذا الغرض
REST APIجميع العمليات التجاريةمنطق مركزي، معاملات
Supabase Subscriptionsتحديثات حية (اختياري)دعم مدمج

عقد الاستجابة في تطبيق العميل​

تتحقق ApiService من جسم الاستجابة قبل إعادته إلى طبقة الميزات. العقد العام هو Map<String, dynamic>، والاستجابة الناجحة الفارغة تصبح {}، أما JSON من نوع مصفوفة أو قيمة أولية فينتج خطأ INVALID_RESPONSE. يمنع ذلك انتشار dynamic والأخطاء المتأخرة في الشاشات، ويجب الحفاظ على هذا العقد عند إضافة endpoint جديد.

تنسق الخدمة أيضاً تحديث رمز الجلسة عبر عملية واحدة مشتركة بين الطلبات المتزامنة، وتعيد المحاولة فقط لأخطاء الشبكة والمهلات و5xx. لا تُعد إعادة المحاولة بديلاً عن idempotency في عمليات الكتابة.

حالة الامتثال​

✅ ممتثل - يستخدم REST API​

الفئةالعمليات
المصادقةsendOtp(), verifyOtp(), logout()
المدن والمساراتgetCities(), getPopularRoutes()
الرحلاتsearchTrips(), getTripById(), getTripSeats()
الحجوزاتcreateBookingWithSeats(), getBookings(), cancelBooking()
الملف الشخصيgetProfile(), updateProfile()
الدعمgetTickets(), createTicket()

❌ غير ممتثل - Supabase مباشر​

1. عمليات الدفع (حرج)​

العمليةالمشكلة
createPayment()استدعاء Edge Function مباشر
getPayment()استعلام قاعدة بيانات مباشر
cancelPayment()تحديث قاعدة بيانات مباشر

التوصية: إنشاء endpoints REST:

POST   /api/payments
GET    /api/payments/[id]
PATCH  /api/payments/[id]/cancel

2. توليد رمز QR​

العمليةالمشكلة
getBookingQRData()استخدام RPC مباشر

التوصية:

GET /api/bookings/[id]/qr

عناصر العمل​

الأولوية 1: حرج (أمان الدفع)​

  • إنشاء endpoints REST للدفع
  • تحديث التطبيق لاستخدام REST
  • إزالة طرق الدفع من SupabaseService

الأولوية 2: عالي (الاتساق)​

  • إنشاء endpoint QR
  • إزالة getBookingQRData() من SupabaseService

الأولوية 3: متوسط (تنظيف)​

  • إزالة الطرق المكررة غير المستخدمة

ملخص​

الفئةممتثلغير ممتثل
المصادقة✅-
الرحلات✅-
الحجوزات✅-
المدفوعات-❌ 7 طرق
الملف الشخصي✅❌ 2 طريقة

الامتثال الكلي: ~75%

تطبيق السائق​

❌ مشكلة رئيسية: لا يوجد طبقة REST API​

تطبيق السائق لا يحتوي على ApiService. جميع العمليات تستخدم Supabase مباشرة.

النمط الحالي (غير ممتثل)​

تطبيق السائق → Supabase مباشر (جميع العمليات)

يجب أن يكون​

تطبيق السائق → REST API (عمليات الأعمال) → Supabase
             → Supabase Auth (المصادقة فقط)

التوصيات​

  1. إنشاء DriverApiService
  2. إنشاء endpoints /api/driver/*
  3. تحديث SyncService لاستخدام REST API

آخر تحديث: أغسطس 2026