Estimación del tiempo de conducción hasta una gasolinera

Implementa: api
Consume: web, app
Estado: activa
Última revisión: 2026-05-21T19:38:35Z

# Implementa: api
# Consume: web, app
# Estado: activa
# Última revisión: 2026-05-21T19:38:35Z
# Position: 2

Feature: Estimación del tiempo de conducción hasta una gasolinera

  El tiempo estimado es un dato informativo para el usuario.
  No influye en el ranking de recomendación — ese ya penaliza
  la distancia a través del coste efectivo de combustible.

  La lógica reside en el API y se devuelve como campo `drive_time_min`
  en la respuesta. Web y app solo muestran el valor sin calcularlo.
  Esto centraliza la lógica y permite escalar al caso de uso
  "más barata en ruta" cambiando solo el backend.

  La estimación parte de la distancia en línea recta (haversine),
  corregida por un factor 1.3 para aproximar la distancia real
  por carretera, y dividida por una velocidad media por tramos
  que permite escalar automáticamente al caso de uso "en ruta".

  Background:
    Given el factor de corrección línea recta → carretera es 1.3
    And las velocidades medias por tramo son:
      | distancia_km | velocidad_kmh |
      | < 2          | 20            |
      | 2 – 10       | 40            |
      | > 10         | 80            |

  Scenario Outline: Estimación según tramo de distancia
    Given una gasolinera a <distancia_km> km en línea recta
    When el API calcula el tiempo estimado de conducción
    Then la respuesta incluye el campo `drive_time_min` con aproximadamente <minutos> minutos

    Examples:
      | distancia_km | minutos | tramo                  |
      | 1.0          | 4       | urbano denso           |
      | 2.0          | 4       | límite urbano / ronda  |
      | 5.0          | 10      | ronda / ciudad media   |
      | 10.0         | 20      | límite ronda / carretera |
      | 15.0         | 15      | carretera              |

  Scenario: Tiempo mínimo de 1 minuto para distancias muy cortas
    Given una gasolinera a menos de 0.5 km en línea recta
    When el API calcula el tiempo estimado de conducción
    Then la respuesta incluye el campo `drive_time_min` con valor 1

  Scenario: El campo drive_time_min está presente en el contrato del endpoint
    Given una petición válida a GET /v2/cheapest
    Then la respuesta incluye `drive_time_min` como integer en `best`
    And la respuesta incluye `drive_time_min` como integer en cada elemento de `runner_ups`
    And el valor es siempre mayor o igual a 1

  Scenario: El detalle de una estación incluye distancia y tiempo cuando se pasan coordenadas
    Given una petición válida a GET /v2/stations/{id} con los parámetros `lat` y `lng`
    Then la respuesta incluye `distance_km` como float mayor que 0
    And la respuesta incluye `drive_time_min` como integer mayor o igual a 1

  Scenario: El detalle de una estación devuelve null cuando no se pasan coordenadas
    Given una petición válida a GET /v2/stations/{id} sin los parámetros `lat` ni `lng`
    Then `distance_km` es null
    And `drive_time_min` es null