Norėdami programėlėje rodyti dviraciu prieinamumą tiesioginiu laiku, susiekite grąžintą kiekį su jo šviežumu ir galimybėmis paimti transporto priemonę. Stebėsena aprašo, ką šaltinis žinojo tam tikru momentu; ji negarantuoja, kad dviratis vis dar bus vietoje atvykus.
ROOTE mobilumo sutartis skiria stotis, atskirus transporto priemonių vienetus ir jų būsenas. Sąsaja turi atspindėti šiuos skirtumus be klaidų, nepainioti nežinomos reikšmės, tuščios stoties ir laikinai neprieinamo šaltinio.
Atskirti stotį nuo atskiro transporto priemonės vieneto
Stotis gali rodyti dviraciu ir grąžinimo vietų skaitiklius. Atskirame transporto vienete yra prieinamumo būsena ir kiti galimi duomenys. Venkite laikyti stotį kaip dviratį arba sudėti tuos pačius atsargų skaitiklius.
ROOTE mobilumo DTO laukeliai availability.bikes ir availability.docks gali būti nežinomi. Variklio tipo ar baterijos laukai turėtų būti rodomi tik jei egzistuoja ir yra interpretuojami pagal sutartį.
Skaityti šviežumą ir laiko žymes
| Laukas | Interpretacija |
|---|---|
| freshness.state | Pranešta būsena: fresh, stale, unknown arba static |
| freshness.source_updated_at | Šaltinio atnaujinimo data, jei žinoma |
| freshness.received_at | Sutarties nurodyta gavimo data |
| freshness.expires_at | Galiojimo terminas, jei žinomas |
| availability.bikes | Žinomas kiekis arba nežinoma reikšmė |
| pickup.enabled ir pickup.state | Informacija apie dviračio paėmimą iš stoties |
Jūsų kvietimo laikas nėra automatiškai stebėsenos laikas. Rezultatas, gautas 10 val., gali turėti šaltinį atnaujintą 9:45. Nerodykite „atnaujinta dabar“ tik pagal jūsų sąsajos gavimo laiką.
Numatykite skirtingas rodymo būsenas
| Gauti duomenys | Numatomas rodymas |
|---|---|
| Žinomas kiekis ir švieži duomenys | Stebėtas kiekis ir laiko indikacija |
| Kiekis lygus nuliui | Nėra stebimų dviračių su laiko kontekstu |
| Kiekis lygus null | Prieinamumas nežinomas |
| Būsena stale arba galiojimas pasibaigęs | Seni duomenys; siūlyti atnaujinimą |
| pickup.enabled=false | Paėmimas nepasiekiamas, nors skaitiklis teigiamas |
| Paieškos klaida | Prieinamumas laikinai nepasiekiamas, nekeičiant į nulį |
Nepriskirkite būsenos unknown arba static kaip šviežios. Stoties informacija gali būti stabili, o skaitiklis greitai keistis. Išsaugokite perspėjimus ir atsakymų priskyrimus.
Normalizavimo pavyzdys prieš pateikimą
Ši funkcija pateikia pateikimo būseną iš stoties, jau patikrintos pagal ROOTE schemą. Tai nėra pilnas atsakymo validatorius. Matomi tekstai turėtų būti jūsų sąsajos vertimų raktai.
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
};
}Net ir su būsenos observed, nepaverskite pickupState=unknown į patvirtintą paėmimą. Skaitiklis vis dar yra stebėsena. Rodykite paėmimo kontekstą, jei jūsų produktas padeda vartotojui pasirinkti stotį.
Atnaujinkite, vengdami nereikalingų kvietimų dauginimo
Priderinkite atnaujinimą prie paskelbtos galiojimo pabaigos, paslaugos sąlygų ir vartotojo elgesio. Grupiuokite identiškus užklausimus, venkite kviesti fone inaktyviame puslapyje, atšaukite pakeistas paieškas.
Vietinis kešavimas neįrodo šaltinio šviežumo. Po klaidos galite išlaikyti paskutinę datuotą stebėseną, jei sąsaja aiškiai rodo, kad ji sena. Neištrinkite šio skirtumo pirma sėkminga pakartotina užklausa, jei šaltinis išlieka stale.
Suprasti ryšį su GBFS
GBFS aprašo bendro naudojimo mobilumo paslaugas ir jų paskelbtas būsenas. Tiesioginė integracija turi interpretuoti failus, versiją ir srauto laiko žymes. Naudokite standartizuotą API sutartį; nenaudokite GBFS laukų, jei jų nėra atsakyme.
Pasirinkimas tarp GTFS, GTFS Realtime ir GBFS
Testuoti skaitytoją klaidinančias situacijas
Išbandykite tikrą nulį, nežinomą reikšmę, pasibaigusį terminą, išjungtą paėmimą ir klaidą po galiojančio rezultato. Taip pat tikrinkite laiko juostas. Teigiamas skaitiklis neturėtų rodyti „užrezervuoto dviračio“, o neprieinamumas – fiktyvaus nulio.
Valdyti tuščius atsakymus ir klaidas
Taikyti šias taisykles IA asistentui
Naudotojo gidas, kaip rasti dviratį
Dažnai užduodami klausimai
Ar teigiamas kiekis garantuoja dviratį atvykus?
Ne. Tai stebėsena, kuri gali pasikeisti tarp paieškos ir atvykimo.
Ar null galima pakeisti nuliu?
Ne. Null žymi nežinomą reikšmę; nulis yra žinomas kiekis ir turi kitokią prasmę.
Ar reikia atnaujinti kas kelias sekundes?
Naudokite galiojimo indikacijas, paslaugos apribojimus ir sąsajos poreikius. Atsitiktinis dažnis negarantuoja švaresnio šaltinio.