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

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

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

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

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

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

OpenAPI договор ROOTE

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

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

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

Не възприемайте състояния 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

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

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

Обработка на празни отговори и грешки

Прилагане на тези правила в AI асистент

Потребителско ръководство за намиране на колело

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

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

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

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

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

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

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