# Ketersediaan Basikal Masa Nyata: Bagaimana Memaparkannya Dalam Aplikasi?

> Pamerkan ketersediaan basikal dengan API ROOTE: cap waktu, kesegaran, nilai tidak diketahui, penyegaran dan data luput dalam aplikasi anda.

Source: https://www.roote.ai/ms/guides/pamer-ketersediaan-basikal-masa-nyata-dalam-aplikasi/
Language: ms
Author: ROOTE

Untuk memaparkan ketersediaan basikal masa nyata dalam aplikasi, kaitkan jumlah yang dipulangkan dengan kesegarannya dan kemungkinan pengambilan kenderaan. Satu pemerhatian menggambarkan apa yang sumber tahu pada satu saat; ia tidak menjamin basikal masih ada semasa tiba.

Kontrak mobiliti ROOTE membezakan stesen, kenderaan individu dan statusnya. Antara muka harus menterjemah perbezaan ini tanpa mengelirukan nilai tidak diketahui, stesen kosong dan sumber sementara tidak tersedia.

## Memisahkan stesen dari kenderaan individu

Sebuah stesen boleh memaparkan pengira basikal dan tempat pengembalian. Kenderaan individu mempunyai status ketersediaan dan maklumat tambahan lain jika ada. Elakkan mengira stesen sebagai basikal atau menjumlahkan pengira yang mewakili stok yang sama.

Dalam DTO mobiliti ROOTE, availability.bikes dan availability.docks boleh menjadi tidak diketahui. Medan propulsion atau bateri hanya perlu dipaparkan jika ia wujud dan ditafsirkan mengikut kontrak.

[Kontrak OpenAPI ROOTE](https://api.roote.ai/openapi.json)

## Membaca kesegaran dan cap waktu

| Medan | Tafsiran |
| --- | --- |
| freshness.state | Status yang diisytiharkan: fresh, stale, unknown atau static |
| freshness.source_updated_at | Tarikh kemaskini sumber, jika diketahui |
| freshness.received_at | Tarikh penerimaan yang dinyatakan dalam kontrak |
| freshness.expires_at | Tarikh tamat sah yang dinyatakan, jika diketahui |
| availability.bikes | Kuantiti diketahui atau nilai tidak diketahui |
| pickup.enabled dan pickup.state | Maklumat tentang pengambilan basikal di stesen |

Masa panggilan anda tidak semestinya masa pemerhatian. Keputusan diterima pada jam 10 pagi mungkin mengandungi sumber yang dikemaskini jam 9:45 pagi. Jangan paparkan "dikemaskini sekarang" hanya berdasarkan masa penerimaan antaramuka anda.

## Sediakan status paparan berbeza

| Data diterima | Paparan yang perlu disediakan |
| --- | --- |
| Kuantiti diketahui dan data segar | Kuantiti diperhatikan dan petunjuk masa |
| Kuantiti sama dengan sifar | Tiada basikal diperhatikan, dengan konteks masa |
| Kuantiti null | Ketersediaan tidak diketahui |
| Status stale atau tamat tempoh | Data lama; cadangkan penyegaran |
| pickup.enabled=false | Pengambilan tidak tersedia walaupun pengira positif |
| Ralat pencarian | Ketersediaan sementara tidak tersedia, tanpa ditukar menjadi sifar |

Jangan klasifikasikan status unknown atau static sebagai segar. Maklumat stesen mungkin stabil walaupun pengira berubah dengan cepat. Simpan juga amaran dan atribusi yang diperlukan oleh respons.

## Contoh normalisasi sebelum paparan

Fungsi berikut menghasilkan status paparan berdasarkan stesen yang telah disahkan mengikut skema ROOTE. Ia bukan pemeriksa respons lengkap. Label yang nampak harus berasal dari kekunci terjemahan antaramuka anda.

```
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
  };
}
```

Walaupun dengan status observed, jangan tukar pickupState=unknown menjadi pengambilan disahkan. Pengira kekal sebagai pemerhatian. Paparkan konteks pengambilan jika produk anda membantu pengguna memilih stesen.

## Segarkan tanpa memanggil berulang kali secara tidak perlu

Sesuaikan penyegaran mengikut tamat tempoh yang diterbitkan, keadaan perkhidmatan dan tingkah laku pengguna. Gabungkan permintaan sama, elakkan panggilan latar belakang pada halaman tidak aktif dan batalkan pencarian yang digantikan.

Jeda cache tempatan tidak membuktikan kesegaran sumber. Selepas ralat, anda boleh menyimpan pemerhatian terakhir yang bertarikh jika antaramuka anda memperlihatkannya secara jelas sebagai lama. Jangan hapuskan perbezaan ini pada pemulihan pertama jika sumber masih stale.

## Memahami hubungan dengan GBFS

GBFS menerangkan perkhidmatan mobiliti kongsi dan status yang diterbitkan. Integrasi langsung harus mentafsir fail, versi dan cap waktu aliran. Dengan API standard, gunakan kontrak API; jangan tambah medan GBFS yang tidak terdapat dalam responsnya.

[Memilih antara GTFS, GTFS Realtime dan GBFS](https://www.roote.ai/ms/guides/gtfs-gtfs-rt-dan-gbfs-apakah-perbezaannya/)

## Uji situasi yang mengelirukan pembaca

Uji sifar sebenar, nilai tidak diketahui, tamat tempoh, pengambilan dilumpuhkan dan ralat selepas keputusan sah. Periksa juga zon waktu paparan. Pengira positif tidak boleh memaparkan "basikal ditempah" dan ketidaktersediaan tidak boleh menghasilkan sifar rekaan.

[Mengendalikan respons kosong dan ralat](https://www.roote.ai/ms/guides/tiada-keputusan-atau-ralat-api-bagaimana-membuat-perbezaan/)

[Menerapkan peraturan ini dalam pembantu AI](https://www.roote.ai/ms/guides/cara-cipta-pembantu-mobiliti-sekitar-alamat/)

[Panduan pengguna mencari basikal](https://www.roote.ai/ms/guides/bagaimana-cara-mencari-basikal-sewa-dekat-saya/)

## Soalan lazim

### Adakah kuantiti positif menjamin basikal apabila saya tiba?

Tidak. Ia hanya menggambarkan pemerhatian yang mungkin berubah antara pencarian dan ketibaan anda.

### Bolehkah null digantikan dengan sifar?

Tidak. null menunjukkan nilai tidak diketahui; sifar ialah kuantiti diketahui dengan makna berbeza.

### Perlukah penyegaran setiap beberapa saat?

Gunakan petunjuk kesahihan, batas perkhidmatan dan keperluan antaramuka anda. Kekerapan sewenang-wenangnya tidak menjamin sumber lebih segar.