RF-004 — Geografía del checkout: departamento y ciudad de Paraguay

Estado	Implementado
Tipo	Componentes propios de dirección + consumo de endpoint del backend
Ubicación	src/modules/checkout/components/department-select/ · city-select/ · shipping-address/ · src/lib/data/geozones.ts
Depende de	RF-000 · GET /store/geozones del backend — RF-005 de Medusa
Ver también	Medusa · GeoZones y ciudades

Requisito

Capturar la dirección de envío con la división política de Paraguay —departamento y ciudad— en lugar de un campo libre de ciudad y un código postal, de modo que la dirección resuelva la zona de cobertura del transportista; y advertir al cliente, antes de avanzar, cuando la ciudad elegida no tiene envío disponible.

Solución adoptada

Reemplazar los campos de ciudad y provincia del starter por dos selectores encadenados, alimentados por el endpoint de geozonas del backend: el departamento filtra las ciudades, y cada ciudad expone su cobertura.

flowchart LR
    B[(Backend · /store/geozones)] -->|departamentos + ciudades| SF[shipping-address]
    SF --> D[Selector de departamento]
    D -->|province_code| C[Selector de ciudad]
    C -->|ciudad sin cobertura| A["Marca (sin envío)"]
    C --> DIR[Dirección de envío del carrito]

Funciones

Función	Detalle
Carga de geografía	getGeoZones() consulta /store/geozones con caché de Next y etiqueta geozones
Selector de departamento	Lista los 18 departamentos publicados por el backend
Selector de ciudad	Habilitado solo con departamento elegido; filtra por province_code
Señal de cobertura	Las ciudades sin transportista disponible se rotulan (sin envio) en la lista
Recuperación de dirección guardada	Al reutilizar una dirección, resuelve el departamento a partir del valor almacenado

Reglas de negocio

• Derivar la lista de ciudades del departamento seleccionado; sin departamento, el selector de ciudad permanece deshabilitado.
• Persistir en la dirección del carrito los valores que el backend usa para resolver la geozona, de modo que el cálculo del flete encuentre la ciudad.
• Exhibir las ciudades sin cobertura en lugar de ocultarlas, señalando la ausencia de envío.
• Cachear la geografía: es un dato estable, no dependiente del carrito.
• Pedir departamento y ciudad solo cuando el cliente carga una dirección: la dirección es opcional porque quien retira en sucursal no la necesita. Si escribe la calle, el departamento y la ciudad pasan a ser obligatorios, porque sin ellos no se puede resolver la zona ni cotizar el envío.
• No preguntar el país: el sitio vende solo en Paraguay y el valor viaja oculto desde la región del carrito.

Criterios de aceptación

#	Criterio
1	Seleccionar un departamento y ver únicamente sus ciudades
2	Identificar en la lista las ciudades sin envío disponible
3	Persistir departamento y ciudad en la dirección del carrito y obtener la cotización de flete
4	Reutilizar una dirección guardada y ver ambos selectores resueltos

Limitaciones conocidas

• Depender de la coincidencia textual del nombre de ciudad con la geozona del backend: el cálculo del flete resuelve por nombre, no por código.
• Rotular la falta de cobertura sin impedir el avance: la restricción efectiva ocurre después, al no ofrecerse opciones de envío.