دليل ربط فحص حالة التطبيق

المتطلبات (تُرسل في الـ Headers أو الـ Query Params):

• Client-Type: نوع الجهاز (android أو ios أو flutter)
• Client-Version: إصدار التطبيق المثبت (مثال: 1.85.1)
• Accept-Language أو lang: لغة التطبيق الحالية (ar أو en)

{
    "status": "success",
    "type": "maintenance",
    "data": {
        "title": "تحت الصيانة",
        "message": "نعمل على تحسين النظام حالياً. يرجى المحاولة لاحقاً."
    }
}

{
    "status": "success",
    "type": "update",
    "data": {
        "is_force": true,
        "version": "1.86.0",
        "store_link": "https://play.google.com/store/apps/details?id=...",
        "title": "تحديث التطبيق",
        "message": "يتوفر تحديث جديد قم بتحديث التطبيق لتجربة أفضل."
    }
}

1. إذا كان type == 'maintenance': اعرض شاشة الصيانة باستخدام تفاصيل الـ data المرفقة وامنع المستخدم من الدخول. (الصيانة لها الأولوية القصوى دائماً).
2. إذا كان type == 'update': اعرض نافذة التحديث (Pop-up) بالعنوان والنص المرفق في الـ data.
3. في حالة التحديث، إذا كان data.is_force == true: قم بإخفاء زر الإغلاق/التخطي من نافذة التحديث (لإجبار المستخدم على التحديث).

الحل وسلوك النظام:

• في حالة "التحديث الاختياري": الـ APIs لن تتوقف ولن تُرجع رسالة تحديث. الموبايل سيعرف بالتحديث مرة واحدة فقط عند فتح التطبيق (عبر مناداة الرابط الأول /app-status).
• في حالة "التحديث الإجباري": كل الـ APIs في التطبيق ستقوم بإيقاف طلب المستخدم فوراً وتُرجع له كود 426 Upgrade Required مع بيانات التحديث في الـ Body. هذا يضمن أنه لو حاول المستخدم إرسال رسالة، السيرفر سيرفض ويوجه الموبايل لإظهار شاشة الإجبار.
• في حالة "الصيانة": كل الـ APIs بلا استثناء ستتوقف فوراً وتُرجع كود 503 Service Unavailable مع بيانات الصيانة في الـ Body.

dio.interceptors.add(InterceptorsWrapper(
  onError: (DioError e, handler) {
    
    // اصطياد الصيانة والتحديث الإجباري
    if (e.response?.statusCode == 503 || e.response?.statusCode == 426) {
       // 1. استخراج بيانات الصيانة والتحديث
       var data = e.response?.data['data'];
       
       // 2. إظهار نافذة الصيانة أو التحديث دون مسح التوكن
       showAppStatusDialog(data);
       
       // 3. منع الخطأ من التسبب في Crash لباقي التطبيق
       return handler.reject(e);
    }
    
    // معالجة الأخطاء الأخرى مثل 401 و 440 (وهي التي نمسح فيها التوكن كالمعتاد)
    if (e.response?.statusCode == 401 || e.response?.statusCode == 440) {
       logoutUser();
    }
    
    return handler.next(e);
  }
));

يجب التقاط الأكواد 503 و 426 في الـ AuthInterceptor أو الـ OkHttpClient Interceptor قبل أن يقوم منشئ الـ Data Class (مثل GSON أو Moshi) بمحاولة تحويل الرد إلى الـ Model المطلوب للواجهة، لتجنب حدوث Parsing Exception.