localesp/openspec/specs/proveedores-ubicacion/spec.md

Proveedores de ubicación (integraciones extensible)

Purpose

Sistema extensible de integraciones con backends de ubicación (Google Maps, Waze, OpenStreetMap, coordenadas sueltas y geocodificación Nominatim) bajo una interfaz común (id/detecta/extrae), capaz de autodetectar el proveedor de una entrada libre, extraer coordenadas e inferir nombre y provincia, y ampliable a otras extracciones futuras sin modificar los proveedores existentes.

Requirements

Requirement: Interfaz común para proveedores de ubicación

Cada integración con un backend de ubicación SHALL implementarse como una clase que cumpla una misma interfaz: identificarse (id), indicar si reconoce una entrada (detecta(entrada)) y extraer la información disponible (extrae(entrada)).

Scenario: Contrato uniforme

• WHEN se consulta cualquier proveedor registrado
• THEN expone los métodos detecta(entrada) y extrae(entrada) con la misma firma y semántica, de modo que el consumidor no necesita conocer la clase concreta

Requirement: Resultado de extracción extensible

El método extrae(entrada) SHALL devolver un objeto de resultado extensible que incluya como mínimo las coordenadas (lat, lng) y el identificador del proveedor que las extrajo, pudiendo incorporar campos adicionales en el futuro sin romper a los consumidores.

Scenario: Extracción mínima

• WHEN un proveedor extrae una ubicación válida
• THEN el resultado contiene lat, lng y el identificador del proveedor

Scenario: Campos adicionales sin ruptura

• WHEN en el futuro un proveedor añade nuevos campos al resultado (horarios, teléfono, fotos…)
• THEN los consumidores existentes siguen funcionando sin modificación, ignorando los campos que no conocen

Requirement: Autodetección del proveedor a partir de la entrada

El sistema SHALL autodetectar automáticamente el proveedor adecuado para una entrada dada, recorriendo los proveedores registrados y usando el primero que la reconozca.

Scenario: Enlace de Google Maps

• WHEN el usuario pega un enlace de Google Maps (formatos @lat,lng, !3d…!4d… o ?q=lat,lng)
• THEN el sistema lo resuelve con el proveedor de Google Maps y obtiene las coordenadas

Scenario: Enlace de Waze

• WHEN el usuario pega un enlace de Waze (waze.com/ul, parámetro ll=lat,lng o búsqueda q=)
• THEN el sistema lo resuelve con el proveedor de Waze y obtiene las coordenadas

Scenario: Enlace de OpenStreetMap

• WHEN el usuario pega un enlace de openstreetmap.org (parámetros mlat/mlon o fragmento #map=zoom/lat/lng)
• THEN el sistema lo resuelve con el proveedor de OpenStreetMap y obtiene las coordenadas

Scenario: Coordenadas geográficas sueltas

• WHEN el usuario escribe coordenadas directamente (por ejemplo 41.3851, 2.1734)
• THEN el sistema lo resuelve con el proveedor de coordenadas y obtiene lat/lng

Scenario: Texto de dirección como fallback

• WHEN la entrada no coincide con ningún enlace soportado y parece una dirección en texto
• THEN el sistema la resuelve con el proveedor de geocodificación (Nominatim) realizando una búsqueda por texto

Scenario: Entrada no reconocida

• WHEN la entrada no es reconocida por ningún proveedor ni resuelta como dirección
• THEN el sistema informa de que no se pudo interpretar la ubicación y no avanza de pantalla

Requirement: Inferencia de nombre y provincia

Los proveedores SHALL extraer, cuando estén disponibles, los campos inferibles nombre y provincia a partir de la entrada resuelta (geocodificación inversa cuando solo hay coordenadas), normalizando la provincia al listado canónico de provincias de España.

Scenario: Inferencia desde coordenadas

• WHEN la entrada se resuelve a coordenadas sin más contexto
• THEN una geocodificación inversa obtiene un nombre descriptivo y la provincia canónica (coincidencia insensible a acentos y mayúsculas con el listado de PROVINCIAS)

Scenario: Provincia fuera del listado

• WHEN la provincia inferida no coincide con ninguna provincia del listado canónico
• THEN el campo provincia queda vacío para que el usuario lo seleccione manualmente

Requirement: Extensibilidad sin modificar proveedores existentes

Añadir un proveedor nuevo SHALL consistir en crear una nueva clase que implemente la interfaz y registrarla en el resolver, sin modificar las clases existentes ni la lógica de la pasarela (principio abierto/cerrado).

Scenario: Registro de un proveedor nuevo

• WHEN se añade una clase MiProveedor con detecta/extrae y se registra en la lista de proveedores
• THEN el campo universal empieza a aceptar las entradas que ese proveedor reconoce sin ningún otro cambio de código

Requirement: Errores de red degradados

Los proveedores SHALL tratar sus errores de red o de servicio devolviendo un fallo controlado, sin romper la pasarela ni propagar excepciones al consumidor.

Scenario: Fallo del servicio de geocodificación

• WHEN Nominatim no responde o devuelve un error
• THEN la pantalla de Ubicación muestra un aviso de error y el usuario puede reintentar o continuar sin inferencia