feat: backend de optimización OpenRoute con motor VRP, métricas e IA local

[juandmg020407]

Resumen

Integración a main del backend de optimización completo de OpenRoute, desarrollado principalmente por @samuelparraechague (8 commits) + 3 commits de ajuste post-review por @juandmg020407 (migración LLM, limpieza personal, limpieza de PDFs) + merge commit con resolución de conflictos.

Por qué este PR usa una rama derivada de main

La rama original feature/openroute-backend se creó como historia git independiente y GitHub no permitía el PR directo ("main and feature/openroute-backend are entirely different commit histories"). Para no perder los commits de Samuel ni la atribución, se ha creado esta nueva rama feat/backend-optimization derivada de main con un merge --allow-unrelated-histories. El resultado es funcionalmente idéntico: trae todo el backend al main actual.

Lo que entra en main

Motor VRP (carpeta src/)

• optimizer.py — solver dual con patrón Strategy: heurística propia (clustering K-Means + VMC ponderado) y Google OR-Tools (CVRPTW industrial). Fallback automático.
• data_processor.py — limpieza, validación y matrices Haversine ajustadas (×1.3 para callejero urbano).
• metrics.py — simulador baseline manual con 3 heurísticas humanas + cálculo de ahorros.
• ai_assistant.py — generador de informes en lenguaje natural con Ollama local (mismo modelo que el frontend) + fallback de plantillas heurísticas dinámicas.
• test_optimizer.py, test_run.py — suite de tests unitarios y test end-to-end.

Datos (carpeta data/)

• pedidos_ejemplo.csv — 30 pedidos reales en Elche + Alicante con coords precisas.
• vehiculos_config.json — 3 furgonetas (eléctrica, diésel, apoyo) con capacidad y coste/km.

Módulos reutilizables (carpeta skills/)

• 1_data_cleaning/clean_orders.py
• 2_eda/eda_report.py
• 3_models/route_optimizer_skill.py

Documentación

• docs/BACKEND_INTEGRATION.md — guía técnica de 3 pasos para consumir el motor desde Streamlit, FastAPI o cualquier otra app Python.

requirements.txt actualizado

Inventario completo: numpy, pandas, ortools, streamlit, folium, streamlit-folium, requests.

Impacto medido sobre 30 pedidos en Elche+Alicante con 3 furgonetas

Métrica	Manual (baseline)	OpenRoute	Ahorro
Distancia	373.51 km	172.39 km	−53.8%
Coste €	88.39	44.94	−49.2%
CO2 kg	82.17	37.93	−53.8%
Tiempo h	25.12	18.45	−26.6%

Cambios añadidos antes del merge (sobre los commits originales de Samuel)

1. Migración Gemini API → Ollama local (commit f27fa5f)

ai_assistant.py ahora usa el mismo LLM open source local (llama3.1:8b) que el frontend. Sin GEMINI_API_KEY, sin internet, sin coste. Coherente con "IA Responsable y Abierta" del hackathon.

2. Fix en plantilla de respaldo (commit f27fa5f)

• Eliminada la referencia personal "Recomendación de Impacto para Samuel Parra" en _generate_local_explanation.
• Sustituidos valores hardcodeados (VAN-01, VAN-02, 12.50 €, 32%) por cálculo dinámico desde data['vehiculos'].

3. Limpieza del README de la rama (commit dd8d34e)

• El README.md antiguo mezclaba info personal con guía técnica.
• Guía técnica útil → docs/BACKEND_INTEGRATION.md (actualizada al nuevo API de AIAssistant).
• El README principal de main (ampliado en PR Feat/llm chatbot frontend #3) cubre el proyecto completo.

4. Limpieza de archivos personales (commit 65dbcbd)

• Eliminado .cloudecode_rules (reglas personales del autor para su IDE).
• Eliminada carpeta OpenRoute/ con PDFs de SEDIA (copyright de la organización) y PDFs internos del equipo (quedan en historial git).

Cómo probarlo

# 1. Modelo Ollama (una sola vez, ~5GB)
ollama pull llama3.1:8b

# 2. Dependencias Python
pip install -r requirements.txt

# 3. Tests unitarios
cd src && python -m unittest test_optimizer.py -v

# 4. Test end-to-end con reporte comparativo
python src/test_run.py

cc: @echeguate @giulianpeter

Co-authored-by: Samuel Parra parrasamuel453@gmail.com