Ketersediaan Basikal Masa Nyata: Bagaimana Memaparkannya Dalam Aplikasi?

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

Membaca kesegaran dan cap waktu

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

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

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

Menerapkan peraturan ini dalam pembantu AI

Panduan pengguna mencari basikal

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.