# عقد إضافة مسافة الطلب لتطبيق المندوب

يحتاج تطبيق المندوب إلى عرض المسافة بالكيلومتر بجانب وقت تجهيز كل متجر، مثل `20 دقيقة • 4.5 كم`. التطبيق أصبح جاهزًا لقراءة الحقل `distance_km`، وسيظهر تلقائيًا بمجرد إضافته إلى استجابات الـAPI الموضحة أدناه.

## المطلوب من الباك إند

إضافة الحقل التالي داخل كائن المتجر `vendor`:

| الحقل | النوع | مطلوب | الوصف |
| --- | --- | --- | --- |
| `distance_km` | `number \| null` | نعم | المسافة بالكيلومتر بين موقع المتجر وعنوان تسليم العميل. ترسل كقيمة رقمية غير منسقة، مثل `4.5`. |

قواعد القيمة:

- تكون القيمة بالكيلومتر وليست بالمتر.
- تكون رقمًا موجبًا أو صفرًا، وليست نصًا يحتوي على الوحدة.
- يفضل إرسال الدقة المتاحة كاملة؛ التطبيق يقرب العرض إلى منزلة عشرية واحدة.
- عند تعذر الحساب بسبب إحداثيات مفقودة أو غير صالحة، ترسل `null`.
- لا ترسل قيمة تقديرية وهمية مثل `0` عند تعذر الحساب؛ الصفر يعني أن المسافة المحسوبة فعلًا تساوي صفرًا.

## Endpoint الطلبات المتاحة

```http
GET /api/app/driver/home
```

الموضع المطلوب داخل الاستجابة:

```text
data.orders[].vendors[].distance_km
```

مثال مختصر:

```json
{
  "status": "success",
  "data": {
    "orders": [
      {
        "id": 89,
        "status": "pending",
        "vendors": [
          {
            "id": 2,
            "name": "متجر 1",
            "order_processing_time": 20,
            "distance_km": 4.5,
            "location": {
              "lat": 24.6206,
              "lng": 46.6323
            }
          }
        ],
        "location": {
          "lat": 24.7136,
          "lng": 46.6753
        }
      }
    ]
  }
}
```

## Endpoint تفاصيل الطلب

```http
GET /api/app/driver/orders/{orderId}
```

الموضع المطلوب داخل الاستجابة:

```text
data.sub_orders[].vendor.distance_km
```

مثال مختصر:

```json
{
  "status": "success",
  "data": {
    "id": 89,
    "sub_orders": [
      {
        "id": 120,
        "vendor": {
          "id": 2,
          "name": "متجر 1",
          "order_processing_time": 20,
          "distance_km": 4.5
        }
      }
    ]
  }
}
```

يجب أن تكون قيمة `distance_km` لنفس المتجر والطلب متطابقة في endpoint الرئيسية وendpoint التفاصيل.

## طريقة الحساب

المسافة المقصودة هي المسافة بين إحداثيات المتجر `vendor.location.lat/lng` وإحداثيات عنوان تسليم العميل `order.location.lat/lng`، بالكيلومتر.

- إذا كان النظام يعتمد مسافة الطريق الفعلية من مزود خرائط، ترسل مسافة الطريق.
- إذا لم يتوفر مزود خرائط، يمكن استخدام المسافة الجغرافية المباشرة مؤقتًا، بشرط اعتماد نفس الطريقة في endpoint الرئيسية والتفاصيل.
- إذا كانت أي إحداثيات مفقودة أو قيمتها غير صالحة مثل `lat: 0` و`lng: 0`، تكون النتيجة `null`.
- في الطلب متعدد المتاجر، تحسب المسافة لكل متجر على حدة وتوضع داخل كائن ذلك المتجر.

## ما تم تنفيذه في تطبيق Flutter

- إضافة قراءة `distance_km` في موديل متجر الرئيسية.
- إضافة قراءة `distance_km` في موديل متجر تفاصيل الطلب.
- عرض الوقت والمسافة معًا بصيغة `20 دقيقة • 4.5 كم`.
- إضافة مفتاح الترجمة `km` بقيمتي `كم` و`km`.
- تقريب العرض إلى منزلة عشرية واحدة، مع الاحتفاظ بالقيمة الأصلية داخل الموديل.
- دعم الإطلاق التدريجي: إذا لم يصل الحقل أو كانت قيمته `null`، يستمر التطبيق في عرض الوقت فقط دون خطأ أو مساحة فارغة.

## حالات القبول

1. عند إرسال `distance_km: 4.5` يظهر `20 دقيقة • 4.5 كم` في الرئيسية.
2. تظهر القيمة نفسها بجانب وقت المتجر في تفاصيل الطلب.
3. عند إرسال عدد صحيح مثل `5` يظهر `5.0 كم`.
4. عند إرسال `null` أو حذف الحقل يظهر الوقت فقط.
5. لا تتعطل الاستجابة القديمة التي لا تحتوي على `distance_km`.
6. كل متجر في الطلب متعدد المتاجر يعرض مسافته الخاصة.

## ملاحظة التحديث بعد النشر

بعد نشر نسخة تطبيق Flutter المتضمنة هذا التعديل، لن يحتاج التطبيق إلى تعديل إضافي عند نشر حقل الباك إند. بمجرد وصول الاستجابة الجديدة، سيقرأ التطبيق `distance_km` ويعرضها في الرئيسية وتفاصيل الطلب عند إعادة تحميل البيانات.