RF-006 — Administración de envíos y geozonas en el dashboard

Estado	En desarrollo (rama hquintero)
Tipo	Widgets de admin + rutas API de administración
Ubicación	src/admin/widgets/location-shipping-config.tsx · src/admin/widgets/location-geozones.tsx · src/api/admin/fulfillment-sets/[id]/ · src/api/admin/shipping-options/[id]/metadata/
Depende de	RF-005
Ver también	Widgets de administración de envíos

Requisito

Permitir al equipo comercial administrar los parámetros del flete calculado —tipos de caja, precios por caja, categorías con tarifa propia, ciudades cubiertas y plazos por transportista— desde el dashboard de administración, sin acceso a la base de datos ni despliegue de código.

Solución adoptada

Extender la página de detalle del depósito (location.details.after) con dos widgets que escriben sobre la metadata de entidades nativas de Medusa. Donde la API de administración de Medusa no expone el recurso o exige el objeto completo, se agregan rutas propias.

flowchart LR
    subgraph W1[Widget · Configuración de envíos]
        T1[Tipos de caja]
        T2[Precios por caja]
        T3[Categorías especiales]
    end
    subgraph W2[Widget · Geozonas]
        C1[Ciudades por zona de servicio]
        C2[Cobertura y plazo por transportista]
    end
    T1 --> R1["/admin/fulfillment-sets/:id"]
    T2 --> R2["/admin/shipping-options/:id/metadata"]
    T3 --> R2
    C1 --> R3[Admin SDK · updateServiceZone]
    C2 --> R3
    R1 --> M1[(FulfillmentSet.metadata)]
    R2 --> M2[(ShippingOption.metadata)]
    R3 --> M3[(GeoZone.metadata)]

Funciones por widget

Widget	Zona	Operaciones
Configuración de envíos	location.details.after	Alta, edición, orden y borrado de tipos de caja con sus dimensiones y peso máximo; marca de caja por defecto; carga del precio de cada caja por opción de envío; alta de categorías de producto con tarifa propia, con buscador sobre el catálogo
Geozonas	location.details.after	Selección de zona de servicio; alta, edición y baja de ciudades; asignación de departamento sobre la lista ISO 3166-2:PY; habilitación y plazo en horas por transportista (mc, clx, aex)

Rutas API propias

Ruta	Método	Motivo
/admin/fulfillment-sets/:id	GET	Medusa no expone la lectura individual del recurso con sus zonas de servicio
/admin/fulfillment-sets/:id	POST	Persistir box_types fusionando la metadata existente en lugar de reemplazarla
/admin/shipping-options/:id/metadata	POST	Actualizar solo la metadata de precios y categorías sin enviar el resto de la definición de la opción de envío

Reglas de negocio

• Fusionar la metadata entrante con la almacenada, para que un widget no pise la configuración escrita por el otro.
• Administrar ciudades como geozonas de tipo city dentro de la zona de servicio seleccionada, con su código de departamento.
• Resolver desde el propio widget las categorías de producto disponibles, consultando el catálogo por el Admin SDK.
• Reutilizar la sesión del dashboard: los widgets operan con el Admin SDK y no manejan credenciales propias.

Criterios de aceptación

#	Criterio
1	Dar de alta un tipo de caja con sus dimensiones y verlo disponible para asignarle precio
2	Modificar el precio de una caja y ver el nuevo importe aplicado en la cotización del checkout
3	Agregar una categoría con tarifa propia y verla cobrada por unidad en el flete
4	Habilitar una ciudad con plazo de entrega y verla ofrecida en el selector del checkout
5	Conservar la configuración previa de la entidad tras guardar desde cualquiera de los dos widgets

Limitaciones conocidas

• Actualizar la metadata de la opción de envío mediante sentencia SQL directa sobre la tabla shipping_option, sin pasar por el módulo de fulfillment ni sus validaciones.
• Fijar la lista de departamentos en el código, duplicada entre el widget y /store/geozones.
• Convivir dos widgets en la misma zona del detalle de depósito, sin control de orden entre ellos.