# دسترس‌پذیری دوچرخه‌ها به‌صورت لحظه‌ای: چگونه در یک اپلیکیشن نمایش دهیم؟

> دسترسی دوچرخه‌ها را با API ROOTE نمایش دهید: زمان‌بندی، تازگی، مقادیر ناشناخته، تازه‌سازی و داده‌های منقضی شده در اپلیکیشن شما.

Source: https://www.roote.ai/fa/guides/dastresan-vazn-dochkheh-be-zamani-vaghei/
Language: fa
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 | اطلاعات مربوط به برداشت دوچرخه از ایستگاه |

زمان تماس شما لزوماً زمان مشاهده نیست. نتیجه دریافت‌شده در ساعت ۱۰ ممکن است شامل منبعی به‌روزرسانی شده در ساعت ۹:۴۵ باشد. تنها بر اساس زمان دریافت اینترفیس، «به‌روزرسانی شده همین الان» را نمایش ندهید.

## در نظر گرفتن وضعیت‌های نمایش متفاوت

| داده دریافت‌شده | نمایش مورد انتظار |
| --- | --- |
| مقدار شناخته‌شده و داده تازه | مقدار مشاهده شده به همراه نشانگر زمانی |
| مقدار برابر صفر | هیچ دوچرخه‌ای مشاهده نشده، به همراه زمینه زمانی آن |
| مقدار 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
  };
}
```

حتی با وضعیت مشاهده‌شده، pickupState=unknown را به برداشت تأیید شده تبدیل نکنید. شمارنده یک مشاهده باقی می‌ماند. اگر محصول شما به کاربر در انتخاب ایستگاه کمک می‌کند، زمینه برداشت را نمایش دهید.

## تازه‌سازی بدون تکرار نادرست درخواست‌ها

تازه‌سازی را با انقضای منتشرشده، شرایط سرویس و رفتار کاربر تطبیق دهید. درخواست‌های مشابه را گروه‌بندی کنید، از فراخوانی در پس‌زمینه در صفحات غیرفعال خودداری و درخواست‌های جستجوی جایگزین شده را لغو کنید.

تاخیر کش محلی تازگی منبع را تضمین نمی‌کند. پس از خطا، می‌توانید آخرین مشاهده تاریخ‌دار را نگه دارید اگر اینترفیس شما صراحتاً آن را به عنوان داده قدیمی نشان دهد. این تمایز را هنگام اولین بازیابی موفق پاک نکنید اگر منبع هنوز قدیمی است.

## درک ارتباط با GBFS

GBFS خدمات حمل و نقل اشتراکی و وضعیت‌های منتشر شده آن‌ها را توصیف می‌کند. یک ادغام مستقیم باید فایل‌ها، نسخه و زمان‌بندی‌های جریان را تفسیر کند. با API استاندارد، از قرارداد API استفاده کنید؛ فیلد GBFS اضافه نکنید که احتمالاً در پاسخ آن وجود ندارد.

[انتخاب بین GTFS، GTFS Realtime و GBFS](https://www.roote.ai/fa/guides/gtfs-gtfs-rt-va-gbfs-che-tafavotha/)

## آزمایش موقعیت‌هایی که ممکن است کاربر را گمراه کنند

صفر واقعی، مقدار ناشناخته، منقضی شدن مهلت، برداشت غیرفعال و خطا پس از نتیجه معتبر را آزمایش کنید. همچنین مناطق زمانی نمایش را بررسی کنید. شمارنده مثبت هرگز نباید «دوچرخه رزرو شده» تولید کند و در دسترس نبودن نباید صفر ساختگی ایجاد کند.

[مدیریت پاسخ‌های خالی و خطاها](https://www.roote.ai/fa/guides/no-result-or-api-error-how-to-differentiate/)

[اعمال این قوانین در یک دستیار هوش مصنوعی](https://www.roote.ai/fa/guides/chek-kardan-ye-dastgahi-ke-mobility-ha-ra-dar-hamkoli-ye-adress-peida-mikonad/)

[راهنمای کاربر برای یافتن دوچرخه](https://www.roote.ai/fa/guides/chera-tavane-find-kardane-docharkhe-az-rooz/)

## سؤالات متداول

### آیا مقدار مثبت تضمین دوچرخه در هنگام رسیدن است؟

خیر. این مقدار یک مشاهده را توصیف می‌کند که ممکن است بین جستجو و رسیدن شما تغییر کند.

### آیا می‌توان null را با صفر جایگزین کرد؟

خیر. null مقدار ناشناخته است؛ صفر مقداری شناخته‌شده است و معنای متفاوتی دارد.

### آیا باید هر چند ثانیه تازه‌سازی کرد؟

از نشانه‌های اعتبار، محدودیت‌های سرویس و نیازهای اینترفیس خود استفاده کنید. فرکانس دلخواه تازگی بیشتر منبع را تضمین نمی‌کند.