CEP Distribuição Otimizador: dónde instalar un CD desde un CSV de códigos postales

TL;DR

• Subes un CSV de códigos postales brasileños, con volumen por pedido opcional, y la herramienta responde en segundos en qué ciudades están los mejores centros de distribución — para reducir distancia y, por consecuencia, tiempo y coste de envío.
• La geocodificación de código postal a municipio, con latitud y longitud reales, es offline desde una base integrada, así que cien mil pedidos no son cien mil llamadas a una API.
• La recomendación es una heurística voraz de k-median (o p-median): elige las ciudades que minimizan la distancia total ponderada por la demanda, no las ciudades con más pedidos.
• Corre en local, gratis y offline, y entrega un mapa PNG estático más un mapa HTML interactivo.

Qué es y para quién

CEP Distribuição Otimizador es una CLI en Node.js para la pregunta que toda operación de comercio electrónico hace una vez al año: con pedidos repartidos por el país, ¿en qué ciudades un centro de distribución reduce de verdad la distancia de envío?

Es para quien cuida operaciones y logística, tiene el CSV de pedidos y la hoja de cálculo, y para el analista al que le preguntaron "cuántos centros necesitamos" y prefiere responder con una curva antes que con una opinión.

Qué hace

• Geocodificación offline de código postal a municipio, con latitud y longitud reales, instantánea y escalable a cientos de miles de pedidos.
• Recomienda ciudades reales para centros de distribución, eligiendo las que minimizan la distancia total ponderada por la demanda, con heurística voraz de k-median o p-median.
• Curva "¿cuántos centros?", mostrando el rendimiento decreciente de abrir uno, dos, tres centros y sugiriendo un número razonable.
• Ponderación por volumen cuando el CSV tiene cantidad, peso o facturación por línea, así la recomendación la mueve la demanda real y no la cuenta de códigos postales.
• Mapas: PNG estático con contornos reales de Brasil, offline, más HTML interactivo con Leaflet y OpenStreetMap para presentar.

La ponderación es lo que cambia la respuesta: mil pedidos en una ciudad y un pedido en otra son dos filas por conteo y nada por volumen, y la herramienta lee las dos.

Instalación y uso

Requiere Node.js 18+, porque usa fetch nativo. El paquete canvas compila bibliotecas nativas durante la instalación.

git clone https://github.com/artificialguybr/cep-distribuicao-otimizador.git
cd cep-distribuicao-otimizador
npm install
npm run build

# recomendar las mejores ciudades para CD (número sugerido automáticamente)
node dist/cli.js centers examples/pedidos_exemplo.csv -o mapa

# forzar exactamente 3 centros y generar los mapas
node dist/cli.js centers examples/pedidos_exemplo.csv -n 3 -o mapa

Eso escribe mapa.png (estático) y mapa.html (interactivo), e imprime la curva de rendimientos decrecientes y la lista de ciudades recomendadas.

Cuándo usarla, cuándo no

Úsala cuando tienes un CSV de códigos postales y necesitas una respuesta defendible sobre dónde abrir un centro de distribución, cuando quieres la pregunta "cuántos" respondida con una curva en vez de con una meta, o cuando quieres probar la premisa antes de firmar un contrato de nave.

No la uses como sustituto de un estudio de red. El README describe una heurística voraz que minimiza distancia ponderada, que es una buena primera respuesta y no un modelo de coste completo — tarifa de envío, alquiler de nave, mano de obra y nivel de servicio quedan fuera. Y no la uses con un CSV de códigos postales sucio: la precisión de la geocodificación es la entrada de todo lo que viene después.

Sources

1. CEP Distribuição Otimizador — repositorio — funciones, geocodificación offline, heurística k-median, mapas, instalación y uso citados arriba.
2. README.md — comandos de instalación y uso, formato del archivo de entrada, requisitos.

Página del proyecto: CEP Distribuição Otimizador

FAQ

¿Llama a una API por cada código postal? No. La geocodificación de código postal a municipio usa una base integrada, así que es offline y no depende de miles de llamadas externas.

¿Qué algoritmo elige las ciudades? Heurística voraz de k-median o p-median que minimiza la distancia total ponderada por la demanda.

¿Puedo forzar un número de centros? Sí, con la opción -n, que fuerza exactamente ese número; sin ella, la herramienta sugiere un número a partir de la curva de rendimientos decrecientes.

¿Considera el volumen de pedidos? Sí, cuando el CSV tiene columna de cantidad, peso o facturación, la recomendación la mueve la demanda real en vez del conteo de códigos postales.