# توافر الدراجات في الوقت الحقيقي: كيف تعرضه في تطبيق؟

> اعرض توافر الدراجات باستخدام API ROOTE: الطابع الزمني، الحداثة، القيم غير المعروفة، التحديث والبيانات المنتهية الصلاحية في تطبيقك.

Source: https://www.roote.ai/ar/guides/%D8%AA%D9%88%D8%A7%D9%81%D8%B1-%D8%A7%D9%84%D8%AF%D8%B1%D8%A7%D8%AC%D8%A7%D8%AA-%D9%81%D9%8A-%D8%A7%D9%84%D9%88%D9%82%D8%AA-%D8%A7%D9%84%D8%AD%D9%82%D9%8A%D9%82%D9%8A-%D9%83%D9%8A%D9%81-%D8%AA%D8%B9%D8%B1%D8%B6%D9%87%D8%A7-%D9%81%D9%8A-%D8%AA%D8%B7%D8%A8%D9%8A%D9%82/
Language: ar
Author: ROOTE

لعرض توافر الدراجات في الوقت الحقيقي داخل تطبيق، اربط العدد المعاد مع حداثته وإمكانيات استلام المركبة. الملاحظة تصف ما كانت المصدر تعرفه في لحظة معينة؛ ولا تضمن استمرار وجود الدراجة عند الوصول.

عقد التنقل ROOTE يميز بين المحطات، المركبات الفردية وحالاتها. يجب على الواجهة ترجمة هذه الاختلافات دون الخلط بين القيمة غير المعروفة، محطة فارغة أو مصدر غير متاح مؤقتًا.

## فصل المحطة عن المركبة الفردية

يمكن للمحطة عرض عدادات الدراجات وأماكن الإرجاع. المركبة الفردية لها حالة التوفر ومعلومات إضافية محتملة. تجنب احتساب المحطة كدراجة أو جمع العدادات التي تمثل نفس المخزون.

في DTO التنقل ROOTE، يمكن أن تكون availability.bikes و availability.docks غير معروفة. يجب عرض حقول الدفع أو البطارية فقط إذا كانت موجودة وتفسر وفق العقد.

[عقد OpenAPI ROOTE](https://api.roote.ai/openapi.json)

## قراءة الحداثة والطوابيت الزمنية

| حقل | تفسير |
| --- | --- |
| freshness.state | الحالة المعلنة: جديد، قديم، غير معروف أو ثابت |
| freshness.source_updated_at | تاريخ تحديث المصدر، إذا كان معروفاً |
| freshness.received_at | تاريخ الاستلام المشار إليه بالعقد |
| freshness.expires_at | تاريخ انتهاء الصلاحية المشار إليه، إذا كان معروفاً |
| availability.bikes | كمية معروفة أو قيمة غير معروفة |
| pickup.enabled و pickup.state | معلومات حول استلام الدراجة من المحطة |

زمن مكالمتك ليس بالضرورة زمن الملاحظة. النتيجة المستلمة الساعة 10:00 قد تحتوي على مصدر تم تحديثه الساعة 9:45. لا تعرض "تم التحديث الآن" بناءً على زمن استلام الواجهة فقط.

## التخطيط لحالات عرض مميزة

| بيانات مستلمة | العرض المتوقع |
| --- | --- |
| كمية معروفة وبيانات جديدة | كمية ملحوظة وإشارة زمنية |
| كمية تساوي صفر | لا توجد دراجات ملحوظة، مع سياقها الزمني |
| كمية فارغة (null) | توافر غير معروف |
| الحالة قديمة أو انتهاء الصلاحية | بيانات قديمة؛ اقترح التحديث |
| pickup.enabled=false | الاستلام غير متوفر حتى مع عداد إيجابي |
| خطأ في البحث | توافر مؤقت غير متاح، دون التحويل إلى صفر |

لا تصنف حالة unknown أو static كأنها جديدة. معلومات المحطة قد تكون مستقرة بينما العداد يتغير بسرعة. احتفظ أيضاً بالتحذيرات والتصنيفات المطلوبة في الرد.

## مثال على التطبيع قبل العرض

الدالة التالية تنتج حالة عرض من محطة تم التحقق منها بالفعل وفق مخطط ROOTE. ليست صالحة للتحقق الكامل للردود. يجب أن تأتي التسميات المرئية من مفاتيح الترجمة في واجهتك.

```
function availabilityView(station, now = Date.now()) {
  const freshness = station.freshness;
  const expiresAt = freshness.expires_at
    ? Date.parse(freshness.expires_at) : null;
  const expired = expiresAt !== null &&
    Number.isFinite(expiresAt) && expiresAt <= now;
  if (station.pickup.enabled === false ||
      station.pickup.state === 'unavailable_now') {
    return { state: 'pickup_unavailable', count: null };
  }
  if (expired || freshness.state === 'stale') {
    return { state: 'stale', count: null };
  }
  const count = station.availability.bikes;
  if (freshness.state !== 'fresh' || count === null ||
      !Number.isFinite(count) || count < 0) {
    return { state: 'unknown', count: null };
  }
  return {
    state: count === 0 ? 'empty' : 'observed', count,
    sourceUpdatedAt: freshness.source_updated_at,
    receivedAt: freshness.received_at,
    pickupState: station.pickup.state
  };
}
```

حتى مع حالة observed، لا تحول pickupState=unknown إلى استلام مؤكد. العداد يبقى ملاحظة. عرض سياق الاستلام إذا كان منتجك يساعد المستخدم في اختيار المحطة.

## التحديث دون تضخيم المكالمات غير الضرورية

عدّل التحديث بناءً على تاريخ انتهاء الصلاحية المنشور، ظروف الخدمة وسلوك المستخدم. اجمع الطلبات المتطابقة، تجنب المكالمات الخلفية في صفحة غير نشطة وألغِ تلك التي تم استبدالها.

تأخير التخزين المؤقت المحلي لا يثبت حداثة المصدر. بعد الخطأ، يمكنك الاحتفاظ بآخر ملاحظة مؤرخة إذا عرضت واجهتك ذلك صراحةً على أنه قديم. لا تمسح هذا التمييز في أول استرجاع ناجح إذا ظل المصدر قديمًا.

## فهم الرابط مع GBFS

يصف GBFS خدمات التنقل المشترك وحالاتها المنشورة. التكامل المباشر يجب أن يفسر الملفات، النسخة والطوابع الزمنية للتدفق. مع API موحَّد، استخدم عقدة API؛ لا تضف حقل GBFS من المفترض غيابه في الرد.

[الاختيار بين GTFS، GTFS Realtime و GBFS](https://www.roote.ai/ar/guides/gtfs-gtfs-rt-wlgbfs-matha-farq/)

## اختبار الحالات التي قد تخدع القارئ

اختبر الصفر الحقيقي، القيمة غير المعروفة، انتهاء الصلاحية، الاستلام المعطل وخطأ بعد نتيجة صالحة. تحقق أيضاً من مناطق التوقيت للعرض. العداد الإيجابي لا يجب أن ينتج "دراجة محجوزة" وعدم التوفر لا يجب أن ينتج صفراً مبتكرًا.

[التعامل مع الردود الفارغة والأخطاء](https://www.roote.ai/ar/guides/%D9%84%D8%A7-%D9%86%D8%AA%D8%A7%D8%A6%D8%AC-%D8%A7%D9%88-%D8%AE%D8%B7%D8%A3-%D9%81%D9%8A-%D9%88%D8%A7%D8%AC%D9%87%D8%A9-%D8%A8%D8%B1%D9%85%D8%AC%D8%A9-%D8%A7%D9%84%D8%AA%D8%B7%D8%A8%D9%8A%D9%82%D8%A7%D8%AA-%D9%83%D9%8A%D9%81-%D9%86%D9%81%D8%B1%D9%82/)

[تطبيق هذه القواعد في مساعد ذكي](https://www.roote.ai/ar/guides/%D9%83%D9%8A%D9%81%D9%8A%D8%A9-%D8%A5%D9%86%D8%B4%D8%A7%D8%A1-%D9%85%D8%B3%D8%A7%D8%B9%D8%AF-%D9%8A%D8%AC%D8%AF-%D9%88%D8%B3%D8%A7%D8%A6%D9%84-%D8%A7%D9%84%D9%86%D9%82%D9%84-%D8%AD%D9%88%D9%84-%D8%A7%D9%84%D8%B9%D9%86%D9%88%D8%A7%D9%86/)

[دليل المستخدم لإيجاد دراجة](https://www.roote.ai/ar/guides/kaifa-tajid-duraja-bayklaat-fit-takhrid-al-shakhsi-qurib-mink/)

## الأسئلة الشائعة

### هل تضمن كمية موجبة وجود دراجة عند وصولي؟

لا. هي تصف ملاحظة قد تتغير بين البحث ووصولك.

### هل يمكن استبدال null بصفر؟

لا. null تشير إلى قيمة غير معروفة؛ الصفر كمية معروفة وله معنى مختلف.

### هل يجب التحديث كل بضع ثوان؟

استخدم إشارات الصلاحية، حدود الخدمة واحتياجات واجهتك. التردد العشوائي لا يضمن مصدرًا أحدث.