Aby wyświetlić dostępność rowerów na żywo w aplikacji, połącz zwróconą liczbę z jej świeżością i możliwościami odbioru pojazdu. Obserwacja opisuje, co źródło wiedziało w danym momencie; nie gwarantuje, że rower będzie dostępny w chwili przybycia.
Kontrakt mobilności ROOTE rozróżnia stacje, pojedyncze pojazdy i ich stany. Interfejs musi odzwierciedlać te różnice, nie myląc wartości nieznanej, pustej stacji i tymczasowo niedostępnego źródła.
Oddzielenie stacji od pojedynczego pojazdu
Stacja może udostępniać liczniki rowerów i miejsc do zwrotu. Pojedynczy pojazd ma stan dostępności oraz inne możliwe informacje. Unikaj liczenia stacji jako roweru lub sumowania liczników reprezentujących ten sam zasób.
W DTO mobilności ROOTE, availability.bikes oraz availability.docks mogą być nieznane. Pola dotyczące napędu lub baterii powinny być wyświetlane tylko, gdy istnieją i są interpretowane zgodnie z kontraktem.
Odczyt świeżości i znaczników czasu
| Pole | Interpretacja |
|---|---|
| freshness.state | Deklarowany stan: fresh, stale, unknown lub static |
| freshness.source_updated_at | Data aktualizacji źródła, jeśli znana |
| freshness.received_at | Data odbioru podana w kontrakcie |
| freshness.expires_at | Data wygaśnięcia ważności, jeśli znana |
| availability.bikes | Znana ilość lub wartość nieznana |
| pickup.enabled i pickup.state | Informacje o możliwym odbiorze roweru na stacji |
Czas wywołania nie jest automatycznie czasem obserwacji. Wynik otrzymany o godz. 10 może zawierać źródło zaktualizowane o 9:45. Nie wyświetlaj "zaktualizowano teraz" tylko na podstawie czasu odbioru interfejsu.
Przewiduj różne stany wyświetlania
| Odebrane dane | Przewidziany sposób wyświetlania |
|---|---|
| Znana ilość i świeże dane | Zaobserwowana ilość i informacja czasowa |
| Ilość równa zero | Brak obserwowanych rowerów wraz z kontekstem czasowym |
| Ilość null | Dostępność nieznana |
| Stan stale lub przekroczony termin ważności | Dane przeterminowane; zalecane odświeżenie |
| pickup.enabled=false | Odbiór niedostępny, nawet jeśli licznik jest dodatni |
| Błąd wyszukiwania | Dostępność chwilowo niedostępna, bez zamiany na zero |
Nie klasyfikuj stanu unknown lub static jako świeży. Informacja o stacji może być stabilna, gdy licznik zmienia się szybko. Zachowaj także ostrzeżenia i atrybucje wymienione w odpowiedzi.
Przykład normalizacji przed renderowaniem
Następująca funkcja generuje stan wyświetlenia na podstawie stacji już zweryfikowanej względem schematu ROOTE. Nie jest to pełny walidator odpowiedzi. Widoczne etykiety powinny pochodzić z kluczy tłumaczeń Twojego interfejsu.
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
};
}Nawet ze stanem observed, nie zamieniaj pickupState=unknown na potwierdzony odbiór. Licznik pozostaje obserwacją. Wyświetl kontekst odbioru, jeśli Twój produkt pomaga użytkownikowi wybrać stację.
Odświeżanie bez niepotrzebnego mnożenia wywołań
Dostosuj odświeżanie do opublikowanego wygaśnięcia, warunków usługi i zachowań użytkownika. Grupuj identyczne zapytania, unikaj wywołań w tle na nieaktywnych stronach i anuluj te, które zostały zastąpione.
Lokalny timeout cache nie gwarantuje świeżości źródła. Po błędzie możesz zachować ostatnią datowaną obserwację, jeśli Twój interfejs wyraźnie pokazuje ją jako starą. Nie usuwaj tej różnicy przy pierwszym udanym ponownym połączeniu, jeśli źródło pozostaje stale.
Zrozumienie powiązania z GBFS
GBFS opisuje usługi współdzielonej mobilności i ich publikowane stany. Integracja bezpośrednia wymaga interpretowania plików, wersji i znaczników czasu strumienia. Przy standaryzowanym API stosuj kontrakt API; nie dodawaj pola GBFS, które może być nieobecne w jego odpowiedzi.
Wybór między GTFS, GTFS Realtime a GBFS
Testowanie sytuacji mylących użytkownika
Testuj rzeczywiste zero, wartość nieznaną, przekroczony termin ważności, wyłączony odbiór i błąd po poprawnym wyniku. Sprawdzaj też strefy czasowe wyświetlania. Dodatni licznik nigdy nie powinien oznaczać „rower zarezerwowany”, a niedostępność nie powinna generować wymyślonego zera.
Obsługa pustych odpowiedzi i błędów
Stosowanie tych zasad w asystencie AI
Poradnik użytkownika jak znaleźć rower
Najczęściej zadawane pytania
Czy dodatnia ilość gwarantuje rower po moim przybyciu?
Nie. Opisuje ona obserwację, która może się zmienić między wyszukiwaniem a Twoim przybyciem.
Czy można zastąpić null zerem?
Nie. null oznacza wartość nieznaną; zero to znana ilość i ma inne znaczenie.
Czy trzeba odświeżać co kilka sekund?
Używaj wskazań ważności, ograniczeń usługi i potrzeb Twojego interfejsu. Dowolna częstotliwość nie gwarantuje świeższego źródła.