# Disponibilitatea bicicletelor în timp real: cum să o afișați într-o aplicație?

> Afișați disponibilitatea bicicletelor cu API-ul ROOTE: marcaj temporal, actualitate, valori necunoscute, reîmprospătare și date expirate în aplicația dvs.

Source: https://www.roote.ai/ro/guides/disponibilitate-velocipede-timp-real-afisare-aplicatie/
Language: ro
Author: ROOTE

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.

[Contract OpenAPI ROOTE](https://api.roote.ai/openapi.json)

## 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](https://www.roote.ai/ro/guides/gtfs-gtfs-rt-si-gbfs-ce-diferente/)

## 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](https://www.roote.ai/ro/guides/fara-rezultate-sau-eroare-api-cum-sa-faci-diferenta/)

[Aplicarea acestor reguli într-un asistent AI](https://www.roote.ai/ro/guides/cum-sa-creezi-un-asistent-pentru-mobilitati-in-jurul-unei-adrese/)

[Ghid al utilizatorului pentru găsirea unei biciclete](https://www.roote.ai/ro/guides/cum-sa-gasesti-o-bicicleta-in-sistem-liber-in-apropierea-ta/)

## Î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ă.