RF-005 — Flete calculado por caja, ciudad y categoría¶


Estado	En desarrollo (rama `hquintero`)
Tipo	Fulfillment provider propio + ruta API de cobertura
Ubicación	`src/modules/mc-fulfillment/` · identificador `mc-group` · `src/api/store/geozones/`
Depende de	Módulo Fulfillment de Medusa — RF-000 · configuración — RF-006
Ver también	Fulfillment MC Group · Selección de ciudades en el checkout

Requisito¶

Calcular el costo de envío en función de la ciudad de destino, del volumen de la mercadería y de las categorías de producto con tarifa propia, en lugar de aplicar una tarifa plana; ofrecer la opción de envío únicamente en las ciudades donde el transportista opera; y publicar la cobertura y el plazo de entrega por ciudad para su consulta desde el checkout.

Solución adoptada¶

Implementar un fulfillment provider con precio calculado (canCalculate), que resuelve la tarifa en el momento en que el cliente ingresa su dirección. La configuración —tipos de caja, precios y categorías especiales— se persiste en la metadata de entidades nativas de Medusa (FulfillmentSet, ShippingOption, GeoZone), sin tablas propias.

flowchart TD
    A[Dirección de envío] --> B[Resolver GeoZone por nombre de ciudad]
    B --> C{mc_available}
    C -->|no| D[No ofrecer la opción de envío]
    C -->|sí| E[Localizar ShippingOption de mc-group en la ServiceZone]
    E --> F[Cargar box_types del FulfillmentSet]
    F --> G[Separar ítems especiales y normales]
    G --> H[Ítems especiales:<br/>precio de categoría × cantidad]
    G --> I[Ítems normales:<br/>producto de mayor volumen]
    I --> J[Caja más chica en la que entra<br/>fallback: caja por defecto]
    H --> K[Total del flete]
    J --> K

Modelo de configuración¶

Dato	Dónde se persiste	Contenido
Tipos de caja	`FulfillmentSet.metadata.box_types`	Código, nombre, largo, ancho, alto, peso máximo, orden y marca de caja por defecto
Precio por caja	`ShippingOption.metadata.prices`	Importe en guaraníes por código de caja
Categorías con tarifa propia	`ShippingOption.metadata.special_categories`	Categoría de producto e importe unitario
Cobertura y plazo	`GeoZone.metadata`	Disponibilidad y horas de entrega por transportista: `mc`, `clx`, `aex`

Reglas de cálculo¶

Resolver la geozona por coincidencia de nombre de ciudad sin distinguir mayúsculas, sobre las geozonas de tipo city.
Descartar la opción de envío cuando la geozona no tiene habilitado el transportista.
Clasificar como especial todo ítem cuya categoría tenga precio propio configurado, y cobrarlo por cantidad.
Cobrar los ítems normales por una sola caja: la más chica cuyas tres dimensiones y peso máximo admitan al producto de mayor volumen del carrito.
Considerar únicamente las cajas con precio configurado, ordenadas por volumen ascendente, y comparar dimensiones ordenadas de mayor a menor.
Convertir las unidades de Medusa antes de comparar: milímetros a centímetros y gramos a kilogramos.
Aplicar la caja marcada por defecto cuando el producto no entra en ninguna caja regular o carece de dimensiones cargadas.
Sumar el precio de la caja y el de los ítems especiales para obtener el total del flete.

Cobertura publicada¶

GET /store/geozones devuelve los 18 departamentos de Paraguay (ISO 3166-2:PY) y el listado de ciudades con su cobertura y plazo por transportista, ordenado alfabéticamente. Alimenta el selector de ciudad del checkout y la promesa de entrega mostrada al cliente.

Criterios de aceptación¶

#	Criterio
1	Devolver un costo de envío distinto para dos carritos de distinto volumen hacia la misma ciudad
2	No ofrecer la opción de envío en una ciudad sin cobertura del transportista
3	Cobrar la tarifa de categoría por unidad en los ítems especiales, sumada a la caja de los normales
4	Aplicar la caja por defecto ante un producto sin dimensiones o mayor que toda caja regular
5	Reflejar en el checkout un cambio de precio de caja realizado en el dashboard, sin desplegar código
6	Listar departamentos y ciudades con su plazo de entrega desde `/store/geozones`

Limitaciones conocidas¶

Cotizar por el producto de mayor volumen y no por el conjunto: dos unidades del mismo producto cotizan igual que una.
Resolver la ciudad por texto y no por código: una discrepancia de nombre entre la dirección y la geozona deja el envío sin cobertura.
Contemplar tres transportistas en la metadata de geozona, pero calcular tarifa únicamente para mc-group; CLX y AEX solo publican disponibilidad y plazo.