[18.0][NEW] TMS Route Optimization Suite

[mileo]

TMS Route Optimization Suite

Overview

This pull request introduces three integrated modules that provide a route optimization solution for the Transport Management System (TMS) in Odoo. These modules work together to enable intelligent route planning with capacity constraints, cost minimization, and multi-stop delivery management.

Modules Included

1. TMS Delivery Stops (tms_delivery_stops)

Extends the TMS module to support multiple delivery stops per TMS order, enabling businesses to manage complex delivery routes with multiple destinations.

Key Features

• Multiple Delivery Stops: Add multiple delivery stops to a single TMS order
• Weight and Volume Tracking: Track weight and volume for each delivery stop with support for Units of Measure (UoM)
• Geolocation Support: Automatic geolocation from partner addresses for route optimization
• Stop Sequencing: Order stops in a sequence to define delivery route order
• Unloading Time: Configure minimum unloading time per stop for better time estimation
• State Management: Track stop states (Draft, Scheduled, Delivered, Skipped)
• Map Integration: Integration with Leaflet map view for visual route planning
• Total Calculations: Automatic calculation of total weight, volume, and stops per order

---

2. TMS Vehicle Capacity (tms_vehicle_capacity)

Extends the TMS and Fleet modules to manage vehicle types with capacity and cost information, providing a foundation for route optimization.

Key Features

• Vehicle Types: Define vehicle types (Van, VUC, Toco, Truck, Bitrem, etc.) with default capacities and costs
• Weight Capacity: Configure weight capacity per vehicle with Units of Measure support
• Volume Capacity: Configure volume capacity per vehicle with Units of Measure support
• Cost Management: Define cost per kilometer and minimum trip cost per vehicle
• Team Integration: Link vehicle types to TMS teams for route optimization
• Depot Locations: Configure default depot/starting point per vehicle
• Automatic Population: Vehicle type defaults automatically populate vehicle fields

---

3. TMS Route Optimizer (tms_route_optimizer)

Provides route optimization functionality for TMS using Google OR-Tools. It solves Vehicle Routing Problems (VRP) to find optimal routes for multiple delivery stops, considering vehicle capacity constraints, distances, and costs.

Key Features

• Route Optimization: Uses Google OR-Tools to solve VRP problems
• Multi-Vehicle Support: Distributes stops across multiple vehicles
• Capacity Constraints: Considers weight and volume capacity of vehicles
• Distance Calculation: Uses Haversine formula to calculate distances between locations
• Cost Optimization: Minimizes total cost considering distance and vehicle costs
• Automatic Order Creation: Creates TMS orders from optimized routes
• Visualization: Provides Google Maps and Waze URLs for each route
• Performance Metrics: Shows utilization rates, distances, and costs per route

---

Integration Architecture

The three modules work together in an integrated workflow:

┌─────────────────────┐
│ tms_delivery_stops  │
│                     │
│ - Delivery stops    │
│ - Geolocation       │
│ - Weight/Volume     │
└──────────┬──────────┘
           │
           │ provides data
           │
           ▼
┌─────────────────────┐
│ tms_route_optimizer │
│                     │
│ - VRP Solver        │
│ - Route Planning    │
│ - Cost Optimization │
└──────────┬──────────┘
           │
           │ uses constraints
           │
           ▼
┌─────────────────────┐
│ tms_vehicle_capacity│
│                     │
│ - Vehicle types     │
│ - Capacities        │
│ - Costs             │
└─────────────────────┘

Integration Points

1. tms_delivery_stops → tms_route_optimizer

   • Finds stops in Draft state within date range
   • Uses stop weight/volume for capacity constraints
   • Uses stop geolocation for distance calculation
   • Updates stops to Scheduled state when orders are created

2. tms_vehicle_capacity → tms_route_optimizer

   • Uses vehicle weight/volume capacity as constraints
   • Uses vehicle cost per KM and minimum trip cost
   • Filters vehicles by team's allowed vehicle types
   • Uses team's default depot location

3. tms_route_optimizer → TMS Orders

   • Creates one TMS order per optimized route
   • Adds stops in optimized order
   • Links vehicles to orders
   • Updates stop states automatically

---

Use Cases

• Multi-stop delivery routes: Plan and optimize routes with multiple delivery destinations
• Route optimization: Minimize transportation costs and distances
• Capacity planning: Ensure deliveries fit within vehicle capacity constraints
• Cost optimization: Reduce operational costs through intelligent route planning
• Multi-vehicle operations: Efficiently distribute stops across multiple vehicles
• Visual route planning: Use map integration for route verification

---

Technical Details

Algorithm

• Solver: Google OR-Tools Vehicle Routing Problem (VRP) solver
• Distance Calculation: Haversine formula for great-circle distances
• Constraints:
  • Weight capacity per vehicle
  • Volume capacity per vehicle
  • Vehicle availability
  • Vehicle type restrictions
• Objective Function:

  Total Cost = Σ (Minimum Trip Cost + Distance × Cost per KM)
  

Optimization Process

1. Input: Delivery stops in Draft state within date range
2. Validation: Verify geolocation, capacities, and vehicle availability
3. Distance Matrix: Calculate distances between depot and all stops
4. VRP Solving: Use OR-Tools to find optimal routes
5. Output: Optimized routes with assigned vehicles and stop sequences
6. Order Creation: Generate TMS orders from optimized routes

---

Configuration Requirements

Prerequisites

1. Install OR-Tools:

   pip install ortools

2. Configure TMS Teams:

   • Set default depot location (must have geolocation)
   • Configure allowed vehicle types

3. Configure Vehicles:

   • Assign vehicle types
   • Set weight and volume capacities
   • Configure cost per KM and minimum trip cost
   • Link vehicles to TMS teams

4. Configure Delivery Partners:

   • Ensure all partners have geolocation coordinates
   • Use base_geolocalize module for automatic geocoding

5. Create Delivery Stops:

   • Create TMS orders with delivery stops
   • Set stops to Draft state
   • Fill in weight, volume, and scheduled dates

System Parameters (Optional)

• tms.route_optimizer.max_time_seconds: Maximum optimization time (default: 300 seconds)
• tms.route_optimizer.max_deliveries: Maximum number of deliveries (default: 100)

---

Features Highlights

Route Optimization Features

• ✅ Multi-vehicle route optimization
• ✅ Capacity constraint handling (weight & volume)
• ✅ Cost minimization
• ✅ Distance-based optimization
• ✅ Automatic TMS order generation
• ✅ Google Maps & Waze integration
• ✅ Performance metrics and utilization tracking

Delivery Stop Management

• ✅ Multiple stops per order
• ✅ Stop sequencing and reordering
• ✅ State workflow management
• ✅ Geolocation integration
• ✅ Weight/volume tracking with UoM
• ✅ Unloading time estimation
• ✅ Map visualization

Vehicle Management

• ✅ Vehicle type definitions
• ✅ Capacity management (weight & volume)
• ✅ Cost configuration
• ✅ Team-based vehicle assignment
• ✅ Depot location configuration
• ✅ Automatic field population

---

[pedrobaeza]

Oh, this is such a coincidence, as we have developed an almost identical feature, but independent from any other vertical, called route_planning, using OR Tools for the route planning itself.

We can connect through glue modules to other parts. For example, we have already developed route_planning_stock for auto-creating what we call route checkpoints for deliveries/receipts from pickings.

We are going to do the PRs over a new repo soon.

[pedrobaeza]

FYI @carlos-lopez-tecnativa