Pro zobrazení dostupnosti kol v reálném čase v aplikaci spojte počet vrácený s jeho čerstvostí a možnostmi vyzvednutí vozidla. Pozorování popisuje, co zdroj věděl v daný okamžik; nezaručuje, že kolo bude stále k dispozici při vašem příchodu.
Mobilitní kontrakt ROOTE odlišuje stanice, jednotlivá vozidla a jejich stavy. Rozhraní musí tyto rozdíly rozlišovat, aniž by zaměňovalo neznámou hodnotu, prázdnou stanici a dočasně nedostupný zdroj.
Oddělení stanice od jednotlivého vozidla
Stanice může zobrazovat počty kol a volných míst pro vrácení. Jednotlivé vozidlo má stav dostupnosti a případné další informace. Vyhněte se počítání stanice jako kola nebo sčítání počtů představujících stejný sklad.
V DTO mobility ROOTE mohou být availability.bikes a availability.docks neznámé. Pole pohonu nebo baterie by se měla zobrazovat jen pokud existují a jsou interpretovány dle kontraktu.
Čtení čerstvosti a časových značek
| Pole | Interpretace |
|---|---|
| freshness.state | Oznámený stav: fresh, stale, unknown nebo static |
| freshness.source_updated_at | Datum aktualizace zdroje, pokud je známo |
| freshness.received_at | Datum přijetí dle kontraktu |
| freshness.expires_at | Uvedená platnost do, pokud je známa |
| availability.bikes | Známé množství nebo neznámá hodnota |
| pickup.enabled a pickup.state | Informace o možnosti odebrání kola na stanici |
Čas vašeho dotazu není automaticky časem pozorování. Výsledek přijatý v 10 hodin může obsahovat zdroj aktualizovaný v 9:45. Nezobrazujte „aktualizováno právě teď“ pouze na základě času přijmutí vaší aplikací.
Naplánujte různé stavy zobrazení
| Přijatý údaj | Navrhované zobrazení |
|---|---|
| Známé množství a čerstvá data | Pozorované množství s časovou indikací |
| Množství rovné nule | Žádné pozorované kolo s časovým kontextem |
| Množství null | Neznámá dostupnost |
| Stav stale nebo překročená platnost | Starý údaj; navrhněte aktualizaci |
| pickup.enabled=false | Odebírání není dostupné i když je kladný počet |
| Chyba vyhledávání | Dostupnost dočasně nedostupná, neprepísat na nulu |
Nezařazujte stav unknown nebo static jako čerstvý. Informace o stanici může být stabilní, zatímco počítadlo se rychle mění. Zachovejte také varování a přidělení požadovaná odpovědí.
Příklad normalizace před renderingem
Následující funkce generuje prezentační stav ze stanice již validované podle schématu ROOTE. Není kompletním validátorem odpovědí. Viditelné popisky musí pocházet z klíčů překladů vašeho rozhraní.
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
};
}I při stavu observed nepřevádějte pickupState=unknown na potvrzené vyzvednutí. Počítadlo je stále pozorování. Kontext vyzvednutí zobrazte jen pokud váš produkt pomáhá uživateli vybrat stanici.
Aktualizujte bez zbytečného množení požadavků
Přizpůsobte aktualizaci vydané expiraci, podmínkám služby a chování uživatele. Sloučte identické požadavky, vyhněte se voláním na pozadí na neaktivní stránce a zrušte požadavky nahrazené novým vyhledáváním.
Místní cache nejde považovat za důkaz čerstvosti zdroje. Po chybě můžete zachovat poslední datované pozorování, pokud vaše rozhraní jasně ukazuje jeho starý stav. Neodstraňujte toto rozlišení při první úspěšné aktualizaci, pokud je zdroj stale.
Porozumět vazbě na GBFS
GBFS popisuje sdílené mobility služby a jejich publikované stavy. Přímá integrace by měla interpretovat soubory, verzi a časové značky toku. S normalizovaným API použijte kontrakt API; nepřidávejte pole GBFS předpokládané mimo jeho odpověď.
Volba mezi GTFS, GTFS Realtime a GBFS
Testování situací klamajících čtenáře
Otestujte skutečnou nulu, neznámou hodnotu, překročenou expiraci, deaktivované vyzvednutí a chybu po platném výsledku. Ověřte také časová pásma zobrazení. Kladné počítadlo nesmí nikdy znamenat „rezervované kolo“ a nedostupnost nesmí nikdy znamenat vymyšlenou nulu.
Řízení prázdných odpovědí a chyb
Aplikace těchto pravidel v AI asistentovi
Uživatelský průvodce pro nalezení kola
Často kladené otázky
Zajišťuje kladné množství kolo při mém příchodu?
Ne. Popisuje pozorování, které se může změnit mezi vyhledáním a vaším příjezdem.
Lze nahradit null nulou?
Ne. null značí neznámou hodnotu; nula je známé množství s jiným významem.
Je nutné aktualizovat každých pár sekund?
Použijte informace o platnosti, omezení služby a potřeby rozhraní. Náhodná frekvence nezaručuje čerstvější zdroj.