Pentru a afișa disponibilitatea bicicletelor în timp real într-o aplicație, asociați numărul returnat cu starea sa de actualitate și cu posibilitățile de preluare a vehiculului. O observație descrie ceea ce sursa știa la un moment dat; aceasta nu garantează că o bicicletă va mai fi prezentă la sosire.
Contractul de mobilitate ROOTE diferențiază stațiile, vehiculele individuale și stările acestora. Interfața trebuie să reflecte aceste diferențe fără a confunda o valoare necunoscută, o stație goală și o sursă temporar indisponibilă.
Separarea unei stații de un vehicul individual
O stație poate oferi contoare pentru biciclete și locuri de returnare. Un vehicul individual are un statut de disponibilitate și alte informații eventuale. Evitați să numărați o stație ca pe o bicicletă sau să adunați contoare care reprezintă același stoc.
În DTO-ul de mobilitate ROOTE, availability.bikes și availability.docks pot fi necunoscute. Câmpurile legate de propulsie sau baterie trebuie afișate doar dacă există și sunt interpretate conform contractului.
Citirea actualității și a marcajelor temporale
| Câmp | Interpretare |
|---|---|
| freshness.state | Stare comunicată: fresh (proaspăt), stale (vechi), unknown (necunoscut) sau static |
| freshness.source_updated_at | Data ultimei actualizări a sursei, dacă este cunoscută |
| freshness.received_at | Data recepției indicată de contract |
| freshness.expires_at | Data de expirare indicată, dacă este cunoscută |
| availability.bikes | Cantitate cunoscută sau valoare necunoscută |
| pickup.enabled și pickup.state | Informații despre preluarea unei biciclete la stație |
Ora apelului dvs. nu este automat aceeași cu cea a observației. Un rezultat primit la ora 10:00 poate conține o sursă actualizată la 9:45. Nu afișați „actualizat acum” doar pe baza orei de recepție din interfața dvs.
Pregătiți stări de afișare distincte
| Date primite | Afișare recomandată |
|---|---|
| Cantitate cunoscută și date proaspete | Cantitate observată și indicație temporală |
| Cantitate egală cu zero | Nici o bicicletă observată, cu contextul temporal al acesteia |
| Cantitate null | Disponibilitate necunoscută |
| Stare stale (veche) sau dată de expirare depășită | Date vechi; sugerați o actualizare |
| pickup.enabled=false | Preluare indisponibilă chiar dacă un contor este pozitiv |
| Eroare de interogare | Disponibilitate temporar indisponibilă, fără a o transforma în zero |
Nu clasificați o stare unknown (necunoscută) sau static (statică) ca fiind proaspătă. O informație despre stație poate fi stabilă, în timp ce contorul evoluează rapid. Păstrați și avertismentele și atribuțiile cerute de răspuns.
Un exemplu de normalizare înainte de redare
Funcția următoare produce o stare de prezentare pornind de la o stație deja validată conform schemei ROOTE. Nu este un validator complet de răspuns. Etichetele vizibile trebuie să provină din cheile de traducere ale interfeței dvs.
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
};
}Chiar și cu o stare observed (observată), nu transformați pickupState=unknown (necunoscut) în preluare confirmată. Contorul rămâne o observație. Afișați contextul de preluare dacă produsul dvs. ajută utilizatorul să aleagă o stație.
Reîmprospătare fără a multiplica inutil apelurile
Adaptați reîmprospătarea la expirarea publicată, la condițiile serviciului și la comportamentul utilizatorului. Grupează cererile identice, evitați apelurile în fundal pe o pagină inactivă și anulați cele ale unei căutări înlocuite.
Un timp local de caching nu dovedește actualitatea sursei. După o eroare, puteți păstra o ultimă observație datată dacă interfața dvs. o prezintă explicit ca fiind veche. Nu eliminați această distincție la prima reluare reușită dacă sursa rămâne stale (veche).
Înțelegerea legăturii cu GBFS
GBFS descrie serviciile de mobilitate partajată și stările lor publicate. O integrare directă trebuie să interpreteze fișierele, versiunea și marcajele temporale ale fluxului. Cu un API normalizat, folosiți contractul API; nu adăugați un câmp GBFS presupus absent din răspuns.
Alegerea între GTFS, GTFS Realtime și GBFS
Testați situațiile care pot induce în eroare utilizatorul
Testați un zero real, o valoare necunoscută, o expirare depășită, o preluare dezactivată și o eroare după un rezultat valid. Verificați și fusurile orare pentru afișare. Un contor pozitiv nu trebuie să producă niciodată „bicicletă rezervată”, iar o indisponibilitate nu trebuie să genereze niciodată un zero inventat.
Gestionarea răspunsurilor goale și a erorilor
Aplicarea acestor reguli într-un asistent AI
Ghid al utilizatorului pentru găsirea unei biciclete
Întrebări frecvente
O cantitate pozitivă garantează o bicicletă la sosirea mea?
Nu. Ea descrie o observație, care se poate modifica între căutare și sosirea dvs.
Se poate înlocui null cu zero?
Nu. null indică o valoare necunoscută; zero este o cantitate cunoscută și are alt sens.
Trebuie actualizat la fiecare câteva secunde?
Folosiți indicațiile de valabilitate, limitele serviciului și nevoile interfeței dvs. O frecvență arbitrară nu garantează o sursă mai proaspătă.