# Наличност на колелета в реално време: как да се показва в приложение?

> Показвайте наличността на колелета с API ROOTE: отметки за време, актуалност, неизвестни стойности, обновяване и остарели данни в приложението ви.

Source: https://www.roote.ai/bg/guides/nalichnost-na-kolichkite-v-realno-vreme-kak-da-se-pokaje-v-prilozhenie/
Language: bg
Author: ROOTE

За да показвате наличността на колелета в реално време в приложение, свържете върнатото количество с неговата актуалност и възможностите за вземане на превозното средство. Едно наблюдение описва това, което източникът е знаел в даден момент; то не гарантира, че колело все още ще е налично при пристигането.

Договорът за мобилност ROOTE различава станции, отделни превозни средства и техните състояния. Интерфейсът трябва да превежда тези разлики без да обърква неизвестна стойност, празна станция и временно недостъпен източник.

## Разграничавайте станция от отделно превозно средство

Станцията може да предоставя броячи за колелета и места за връщане. Отделното превозно средство има състояние на наличие и други евентуални данни. Избягвайте да броите станция като колело или да сумирате броячи, които представят същия инвентар.

В DTO за мобилност ROOTE, availability.bikes и availability.docks могат да бъдат неизвестни. Полетата за задвижване или батерия трябва да се показват само ако съществуват и се интерпретират според договора.

[OpenAPI договор ROOTE](https://api.roote.ai/openapi.json)

## Четене на актуалност и отметки за време

| Поле | Интерпретация |
| --- | --- |
| freshness.state | Обявено състояние: fresh, stale, unknown или static |
| freshness.source_updated_at | Дата на обновяване на източника, ако е известна |
| freshness.received_at | Дата на получаване, посочена от договора |
| freshness.expires_at | Обявен срок на валидност, ако е известен |
| availability.bikes | Известно количество или неизвестна стойност |
| pickup.enabled и pickup.state | Информация за вземане на колело от станцията |

Часът на вашето повикване не е автоматично часът на наблюдението. Резултат, получен в 10 ч., може да съдържа източник обновен в 9:45 ч. Не показвайте „обновено сега“ само въз основа на часа на получаване от вашия интерфейс.

## Предвидете отделни състояния за показване

| Получени данни | Очакван показател |
| --- | --- |
| Известно количество и пресни данни | Наблюдавано количество и времево указание |
| Количество, равно на нула | Няма наблюдавани колелета, с техния времеви контекст |
| Количество null | Наличност неизвестна |
| Състояние stale или изтекъл срок | Стара информация; предложете обновяване |
| pickup.enabled=false | Вземане недостъпно, дори ако броячът е положителен |
| Грешка при търсене | Наличността временно недостъпна, без да се преобразува в нула |

Не възприемайте състояния unknown или static като пресни. Информацията за станцията може да е стабилна, докато броячът се променя бързо. Запазете предупредителните съобщения и присъдите, изисквани от отговора.

## Пример за нормализация преди рендериране

Следната функция произвежда статус за показване от станция, която вече е валидирана спрямо схемата ROOTE. Тя не е пълен валидатор на отговори. Видимите етикети трябва да идват от ключовете за превод на вашия интерфейс.

```
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
  };
}
```

Дори при състояние observed, не преобразувайте pickupState=unknown в потвърдено вземане. Броячът остава наблюдение. Покажете контекста за вземане, ако продуктът ви помага на потребителя да избере станция.

## Обновяване без излишно умножаване на повикванията

Адаптирайте обновяването към публикувания срок, условията на услугата и поведението на потребителя. Групирайте идентични заявки, избягвайте повиквания на заден план на неактивна страница и отменяйте тези от заменено търсене.

Локален кеш не доказва актуалността на източника. След грешка можете да запазите последното наблюдение с дата, ако интерфейсът ви го показва явно като старо. Не изтривайте тази разлика при първото успешно възстановяване, ако източникът остава stale.

## Разбиране на връзката с GBFS

GBFS описва споделените услуги за мобилност и техните публикувани състояния. Директната интеграция трябва да интерпретира файловете, версията и отметките за време на потока. С нормализирано API използвайте договора на API; не добавяйте поле GBFS, което липсва в неговия отговор.

[Избор между GTFS, GTFS Realtime и GBFS](https://www.roote.ai/bg/guides/gtfs-gtfs-rt-i-gbfs-kakvi-sa-razlikite/)

## Тествайте ситуации, които подвеждат потребителя

Тествайте истинско нула, неизвестна стойност, изтекъл срок, деактивирано вземане и грешка след валиден резултат. Проверете и часовите зони за показване. Положителен брояч никога не трябва да води до „запазено колело“ и недостъпност никога не трябва да създава измислена нула.

[Обработка на празни отговори и грешки](https://www.roote.ai/bg/guides/prazni-rezultati-ili-greshka-api-kak-da-otlichim/)

[Прилагане на тези правила в AI асистент](https://www.roote.ai/bg/guides/kak-da-sazdaem-asistent-za-mobilnost-okolo-adres/)

[Потребителско ръководство за намиране на колело](https://www.roote.ai/bg/guides/kak-da-namera-velosiped-v-zona-svobodna-polzvane-blizo-do-men/)

## Често задавани въпроси

### Гарантира ли положително количество, че ще има колело при пристигане?

Не. То описва наблюдение, което може да се промени между търсенето и вашето пристигане.

### Може ли null да се замени с нула?

Не. null означава неизвестна стойност; нулата е известно количество и има различен смисъл.

### Трябва ли да се обновява на всеки няколко секунди?

Използвайте указанията за валидност, ограниченията на услугата и нуждите на вашия интерфейс. Произволната честота не гарантира по-пресен източник.