Smart Truck

Inspiració

Cada matí al magatzem DDI Mollet de DAMM, els planificadors de ruta donen al conductor una "Hoja de Carga" i una "Hoja de Ruta" en paper: desenes de palets, més de 18 parades, finestres de lliurament estretes i una columna Descarga al full de càrrega que es deixa en blanc. El conductor descobreix sobre la marxa quins palets baixen a quin bar, sovint havent de remenar el remolc perquè l'ordre de càrrega no coincideix amb l'ordre de visita. Els envasos retornables (caixes buides, barrils) tornen igual de caòticament. Vam veure el paperam real de la ruta DR0027 i ens vam adonar que el problema de la ruta i el de la càrrega normalment es resolen per separat. No haurien: una ruta perfecta sobre un camió mal carregat fa tant mal com una bona càrrega sobre una mala ruta. Volíem arreglar les dues coses alhora, sobre el mateix paperam que els conductors ja confien.

Què fa

Smart Truck és una eina de suport a la decisió per a planificadors de magatzem i conductors. A partir de les comandes d'una ruta real produeix:

Una seqüència de parades optimitzada — VRP amb finestres horàries, temps de viatge OSRM i les franges reals de lliurament de Horarios Entrega.
Una càrrega híbrida client-clúster + LIFO — els palets s'agrupen per client i s'apilen de manera que l'última parada es carrega primer. El packer també reserva espai per als retornables que es recullen al llarg de la ruta.
Un PDF Smart Hoja Carga que reprodueix exactament el format DDIDGP actual (mateixes columnes, mateix encapçalament, mateixes tipografies), però omplint la columna Descarga amb una posició concreta de palet que el conductor pot llegir d'un cop d'ull.
Un PDF Smart Hoja Ruta reordenat segons la seqüència optimitzada perquè els dos fulls quedin coherents.
Un bessó digital 3D del camió (react-three-fiber) que mostra la descàrrega de palets parada a parada, una maqueta mòbil per al conductor i un panell de KPIs que compara el pla optimitzat amb el paperam as-is (km estalviats, temps estalviat, retornables recuperats, reordenacions manuals evitades).

Tot s'executa amb una sola comanda — python -m smart_truck.demo — que reconstrueix la línia base a partir dels PDFs originals i emet tots els artefactes del pitch llestos per imprimir.

Com ho hem construït

Backend: FastAPI per a l'API, OR-Tools per al VRP, PuLP per al MILP d'assignació client-palet dins del packer de càrrega, ReportLab per emetre el paperam Smart, i pdfplumber per parsejar els fulls DDIDGP originals i fer que la nostra sortida quadri columna a columna. Pandas + parquet a la capa de dades, Nominatim per al geocoding (amb cache en disc) i OSRM per a les matrius de distància i temps per carretera.
Frontend: Next.js 14 + Tailwind. Leaflet per al mapa de ruta, react-three-fiber + Three.js per al bessó 3D del camió, i un panell de KPIs petit que fa el diff entre la línia base i el pla optimitzat. Pàgines: dashboard del planificador, vista mòbil del conductor, pick-list i bessó del camió.
Dades: hem treballat directament sobre artefactes reals de DAMM — Hoja Carga.pdf, Hoja Ruta.pdf, Horarios Entrega.XLSX, ZM040.XLSX i el layout del magatzem de Mollet. La reconstrucció de la línia base parseja el paperam d'avui, així cada KPI que ensenyem està ancorat a l'as-is real.
Pipeline: comandes → geocoding → matrius distància/temps → VRP (route.py) → planificador de retornables (returns.py) → packer LIFO+clúster (load.py) → emissor que dibuixa els PDFs Smart sobre les plantilles originals.

Quins reptes vam trobar

Geocodificar adreces de bars. Molts punts de lliurament són bars petits de pobles catalans (Sant Julià de Vilatorta, Calldetenes, Folgueroles) que Nominatim només troba amb cadenes d'adreça netejades amb cura. Vam construir un normalitzador + cache per no tornar a colpejar l'API i perquè la demo sigui reproduïble offline.
Parsejar el paperam original. El PDF de la "Hoja de Carga" DDIDGP és un informe amb layout fix, no un PDF amb tags — els límits de columna s'han d'inferir per clústers de coordenades, i la columna Descarga ve buida a l'origen, així que vam haver d'inventar un esquema de posicions que encara encaixés dins el marc visual existent.
La ruta i la càrrega estan acoblades. Una càrrega LIFO només té sentit donat un ordre de parades, però l'ordre òptim depèn en part del que cap a on dins el camió (retornables, palets fràgils, etc). Vam acabar amb un bucle de dues fases: primer ruta, després pack amb consciència de clústers, després re-cost.
Envasos retornables. Es recullen al moment del lliurament i ocupen l'espai que acabem d'alliberar. Modelar-ho correctament (en lloc d'ignorar-ho com fa de facto el procés as-is) era la diferència entre una "demo d'optimització maca" i una cosa que un conductor podria fer servir de debò.
Pressió de temps real. Construir backend, optimitzador, emissor de PDFs, bessó 3D i panell de KPIs dins la finestra del hackathon va voler dir scoping despietat — vam fixar la demo a una sola ruta real (DR0027, 2026-05-08) perquè cada artefacte es pogués validar contra la veritat de camp.

Què ens enorgulleix especialment

La nostra Smart Hoja Carga és visualment indistingible de la que DAMM imprimeix avui — només que la columna Descarga ara sí que està plena. Un planificador la pot adoptar sense reentrenament.
Optimització conjunta de ruta + càrrega, no dos models desconnectats.
Demo end-to-end amb una sola comanda (python -m smart_truck.demo) que produeix tots els artefactes del pitch de manera determinista.
Un bessó 3D real i animat del camió que ensenya per què importa l'ordre de càrrega — molt més convincent que un full de càlcul.

Què hem après

El VRP amb finestres horàries és la part fàcil; el packing sota LIFO + retornables és on viu el dolor operatiu real.
Els operaris confien en el paper. El camí més ràpid cap a l'adopció no és una UI nova llampant, sinó el mateix full que ja saben llegir, amb una columna més plena.
Les dades reals de logística són brutes en maneres interessants — normalització d'adreces, codificacions barrejades als exports d'Excel i convencions tàcites amagades en l'ordre de les columnes. Construir una capa neta de parsing + línia base s'ha amortitzat moltes vegades.
Un bessó 3D val per deu diapositives quan s'ha d'explicar la càrrega LIFO a un públic no tècnic.
KPIs calculats contra la línia base real parsejada dels PDFs originals, no contra un benchmark sintètic.

Què hem après

El VRP amb finestres horàries és la part fàcil; el packing sota LIFO + retornables és on viu el dolor operatiu real.
Els operaris confien en el paper. El camí més ràpid cap a l'adopció no és una UI nova llampant, sinó el mateix full que ja saben llegir, amb una columna més plena.
Les dades reals de logística són brutes en maneres interessants — normalització d'adreces, codificacions barrejades als exports d'Excel i convencions tàcites amagades en l'ordre de les columnes. Construir una capa neta de parsing + línia base s'ha amortitzat moltes vegades.
Un bessó 3D val per deu diapositives quan s'ha d'explicar la càrrega LIFO a un públic no tècnic.

Què ve després per a Smart Truck

Pilot en una ruta en viu a DDI Mollet, amb el conductor portant la Smart Hoja Carga al costat de l'original durant una setmana per fer un A/B del temps estalviat.
App per al conductor: convertir la maqueta mòbil en una PWA real amb suport offline, escaneig de codis de barres a cada parada i captura de retornables en directe.
Planificació multi-camió: estendre de l'optimització d'una sola ruta a la planificació diària de la flota a tot DDI Mollet, incloent-hi restriccions de torns dels conductors.
Re-optimització en viu: incorporar trànsit en temps real des d'OSRM i deixar que el planificador re-costegi una ruta a mig dia quan una parada s'endarrereix.
*Tancar el cercle al magatzem: alimentar el pla de posicions de palet de tornada al moll de càrrega perquè el camió es carregui *físicament en l'ordre òptim — tancant el bucle entre el layout del magatzem (Layout Mollet.xlsx) i la carretera.
Generalitzar més enllà de begudes: el patró clúster + LIFO + retornables s'aplica a qualsevol distribució multi-parada amb logística inversa (bombones de gas, barrils, palets, devolucions de retail).

Construït amb

python · typescript · fastapi · or-tools · pulp · pandas · pyarrow · pdfplumber · reportlab · osrm · nominatim · pydantic · uvicorn · next.js · react · tailwindcss · leaflet · react-leaflet · three.js · react-three-fiber · @react-three/drei