Skip to content

Transport Capacity Management

Jump to bottom
Agilasoft Cloud Technologies edited this page Jan 20, 2026 · 3 revisions

Capacity Management Design and Implementation Plan

Transport Module

Table of Contents

  1. Executive Summary
  2. Current State Analysis
  3. Objectives and Requirements
  4. System Architecture
  5. Data Models
  6. Core Functionality
  7. Integration Points
  8. User Interface Design
  9. Implementation Plan
  10. Testing Strategy
  11. Future Enhancements

Executive Summary

This document outlines the design and implementation plan for a comprehensive Capacity Management System within the Transport module. The system will enable real-time tracking, planning, and optimization of vehicle capacity utilization across transport operations, ensuring efficient resource allocation and preventing over-capacity assignments.

Key Benefits

  • Real-time Capacity Visibility: Track available and utilized capacity across all vehicles
  • Intelligent Assignment: Automatically match transport jobs to vehicles based on capacity constraints
  • Optimization: Maximize vehicle utilization while preventing over-capacity scenarios
  • Planning Support: Forecast capacity needs and identify bottlenecks
  • Compliance: Ensure regulatory weight/volume limits are respected

Current State Analysis

Existing Capacity Fields

Transport Vehicle

  • capacity_weight (Float) - Maximum weight capacity
  • capacity_volume (Float) - Maximum volume capacity (m³)
  • capacity_pallets (Float) - Maximum pallet capacity
  • max_container_count (Float) - Maximum container count
  • container_types (Table MultiSelect) - Supported container types

Transport Job Package

  • weight (Float) - Package weight
  • volume (Float) - Package volume (m³)
  • no_of_packs (Float) - Number of packages
  • quantity (Float) - Quantity
  • Dimensions: length, widht, height

Current Capacity Validation

Run Sheet (run_sheet.py)

  • Basic validation method validate_capacity() exists
  • Checks total weight, volume, and pallets against vehicle capacity
  • Limitations:
    • Only validates on Run Sheet save
    • No real-time capacity tracking
    • No capacity reservation system
    • No multi-dimensional capacity optimization

Transport Plan (transport_plan.py)

  • _find_vehicle_for_trip() checks capacity during planning
  • _find_candidate_vehicle() filters vehicles by capacity
  • Limitations:
    • Capacity checks are basic (weight/volume/pallets)
    • No capacity reservation during planning
    • No capacity utilization tracking over time
    • No capacity forecasting

Gaps Identified

  1. No Centralized Capacity Manager: No unified system to manage capacity across all transport operations
  2. No Capacity Reservation: Capacity is not reserved when jobs are assigned, leading to double-booking risks
  3. No Real-time Tracking: No dashboard or view showing current capacity utilization
  4. No Capacity Forecasting: Cannot predict future capacity needs
  5. No Multi-dimensional Optimization: Does not optimize for multiple capacity dimensions simultaneously
  6. No Capacity Alerts: No notifications when capacity thresholds are reached
  7. No Historical Utilization: No tracking of capacity utilization trends
  8. Limited Integration: Capacity checks are scattered across different modules

Objectives and Requirements

Functional Requirements

FR1: Capacity Definition and Configuration

  • Support multiple capacity dimensions (weight, volume, pallets, containers)
  • Allow capacity configuration per vehicle type
  • Support capacity overrides for specific vehicles
  • Define capacity units and conversion factors

FR2: Real-time Capacity Tracking

  • Track available capacity for each vehicle in real-time
  • Calculate utilized capacity from assigned jobs/legs
  • Display capacity utilization percentage
  • Support capacity tracking across multiple time periods

FR3: Capacity Reservation System

  • Reserve capacity when jobs are assigned to vehicles
  • Release capacity when jobs are cancelled or completed
  • Support partial capacity reservations (for multi-stop routes)
  • Handle capacity conflicts and overrides

FR4: Intelligent Vehicle Assignment

  • Automatically suggest vehicles based on capacity requirements
  • Consider multiple capacity dimensions simultaneously
  • Prioritize vehicles with optimal capacity fit
  • Support capacity-based filtering in vehicle selection

FR5: Capacity Validation

  • Validate capacity before job assignment
  • Prevent over-capacity assignments
  • Warn when approaching capacity limits
  • Support capacity override with authorization

FR6: Capacity Planning and Forecasting

  • Forecast capacity needs based on scheduled jobs
  • Identify capacity bottlenecks
  • Suggest optimal vehicle allocation
  • Support capacity planning for future dates

FR7: Capacity Reporting and Analytics

  • Capacity utilization reports
  • Historical capacity trends
  • Vehicle utilization statistics
  • Capacity efficiency metrics

Non-Functional Requirements

NFR1: Performance

  • Capacity calculations must complete within 2 seconds for 1000 vehicles
  • Real-time capacity updates must be reflected within 5 seconds
  • Support concurrent capacity reservations

NFR2: Scalability

  • Support 10,000+ vehicles
  • Handle 100,000+ transport jobs per month
  • Efficient database queries with proper indexing

NFR3: Reliability

  • Ensure data consistency in capacity reservations
  • Handle concurrent updates gracefully
  • Maintain capacity accuracy during system failures

NFR4: Usability

  • Intuitive UI for capacity visualization
  • Clear capacity warnings and alerts
  • Easy capacity override process

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Transport Module                          │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌──────────────────┐         ┌──────────────────┐          │
│  │  Capacity Manager│◄────────┤  Capacity API   │          │
│  │  (Core Engine)   │         │  (Public API)   │          │
│  └────────┬─────────┘         └──────────────────┘          │
│           │                                                    │
│           ├──────────┬────────────┬──────────────┐           │
│           │          │            │              │           │
│  ┌────────▼──┐  ┌───▼────┐  ┌───▼────┐  ┌─────▼────┐      │
│  │ Capacity  │  │Capacity │  │Capacity│  │ Capacity │      │
│  │ Tracker   │  │Reserver │  │Validator│  │ Planner │      │
│  └───────────┘  └─────────┘  └────────┘  └──────────┘      │
│                                                               │
│  ┌──────────────────────────────────────────────────────┐   │
│  │           Capacity Data Models                        │   │
│  │  - Vehicle Capacity                                   │   │
│  │  - Capacity Reservation                               │   │
│  │  - Capacity Utilization                              │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                               │
└─────────────────────────────────────────────────────────────┘
           │                    │                    │
           ▼                    ▼                    ▼
    ┌──────────┐         ┌──────────┐         ┌──────────┐
    │Transport │         │ Run Sheet│         │Transport │
    │   Job    │         │          │         │  Plan    │
    └──────────┘         └──────────┘         └──────────┘

Component Design

1. Capacity Manager (Core Engine)

Location: logistics/transport/capacity/capacity_manager.py

Responsibilities:

  • Centralized capacity management logic
  • Coordinate between capacity components
  • Maintain capacity state consistency
  • Provide unified API for capacity operations

Key Methods:

class CapacityManager:
    def get_available_capacity(vehicle, date, time_slot=None)
    def reserve_capacity(vehicle, job, capacity_requirements)
    def release_capacity(vehicle, job)
    def check_capacity_sufficient(vehicle, requirements)
    def get_capacity_utilization(vehicle, date_range)
    def find_suitable_vehicles(requirements, filters)
    def forecast_capacity(date_range, vehicle_type=None)

2. Capacity Tracker

Location: logistics/transport/capacity/capacity_tracker.py

Responsibilities:

  • Track real-time capacity utilization
  • Calculate available capacity
  • Maintain capacity snapshots
  • Update capacity in real-time

3. Capacity Reserver

Location: logistics/transport/capacity/capacity_reserver.py

Responsibilities:

  • Reserve capacity for jobs/legs
  • Release capacity when jobs complete
  • Handle capacity conflicts
  • Support partial reservations

4. Capacity Validator

Location: logistics/transport/capacity/capacity_validator.py

Responsibilities:

  • Validate capacity before assignments
  • Check capacity constraints
  • Generate capacity warnings
  • Support capacity overrides

5. Capacity Planner

Location: logistics/transport/capacity/capacity_planner.py

Responsibilities:

  • Forecast future capacity needs
  • Identify capacity bottlenecks
  • Suggest optimal vehicle allocation
  • Support capacity planning queries

6. Vehicle Type Capacity Helper

Location: logistics/transport/capacity/vehicle_type_capacity.py

Responsibilities:

  • Get capacity information for vehicle types (aggregated from vehicles)
  • Calculate average/minimum/maximum capacity for vehicle type
  • Support capacity validation at vehicle type level (before specific vehicle assignment)

Key Methods:

def get_vehicle_type_capacity_info(vehicle_type):
    """Get aggregated capacity information for a vehicle type"""
    # Returns: {
    #   'max_weight': max capacity weight,
    #   'max_volume': max capacity volume,
    #   'max_pallets': max capacity pallets,
    #   'avg_weight': average capacity weight,
    #   'min_weight': minimum capacity weight,
    #   'vehicle_count': number of vehicles of this type,
    #   'weight_uom': standard weight UOM,
    #   'volume_uom': standard volume UOM
    # }

def check_vehicle_type_capacity(vehicle_type, requirements):
    """Check if vehicle type can accommodate requirements"""
    # Returns: {
    #   'sufficient': bool,
    #   'available_vehicles': list of vehicles with sufficient capacity,
    #   'warnings': list of warning messages
    # }

7. UOM Conversion Helper

Location: logistics/transport/capacity/uom_conversion.py

Responsibilities:

  • Convert weight, volume, and dimensions between different UOMs
  • Calculate volume from dimensions with UOM conversion
  • Standardize capacity values to default UOMs for calculations
  • Handle UOM conversion errors gracefully

Key Methods:

def convert_weight(value, from_uom, to_uom=None, company=None):
    """Convert weight from one UOM to another"""
    # Uses default weight UOM from settings if to_uom not provided
    # Returns converted value in target UOM

def convert_volume(value, from_uom, to_uom=None, company=None):
    """Convert volume from one UOM to another"""
    # Uses default volume UOM from settings if to_uom not provided
    # Returns converted value in target UOM

def convert_dimension(value, from_uom, to_uom=None, company=None):
    """Convert dimension (length/width/height) from one UOM to another"""
    # Uses default dimension UOM from settings if to_uom not provided
    # Returns converted value in target UOM

def calculate_volume_from_dimensions(length, width, height, 
                                     dimension_uom=None, 
                                     volume_uom=None,
                                     company=None):
    """Calculate volume from dimensions with UOM conversion"""
    # Converts dimensions to standard UOM
    # Calculates volume: length × width × height
    # Converts result to target volume UOM
    # Reuses logic from logistics.warehousing.utils.volume_conversion

def standardize_capacity_value(value, uom, capacity_type, company=None):
    """Convert capacity value to standard UOM for calculations"""
    # capacity_type: 'weight', 'volume', or 'dimension'
    # Returns value in standard UOM (from settings)

Data Models

1. Capacity Reservation (New DocType)

Purpose: Track capacity reservations for transport jobs/legs

Fields:

{
  "doctype": "Capacity Reservation",
  "fields": [
    {
      "fieldname": "vehicle",
      "fieldtype": "Link",
      "options": "Transport Vehicle",
      "reqd": 1
    },
    {
      "fieldname": "reservation_date",
      "fieldtype": "Date",
      "reqd": 1
    },
    {
      "fieldname": "reservation_start_time",
      "fieldtype": "Time"
    },
    {
      "fieldname": "reservation_end_time",
      "fieldtype": "Time"
    },
    {
      "fieldname": "reserved_weight",
      "fieldtype": "Float",
      "label": "Reserved Weight"
    },
    {
      "fieldname": "reserved_weight_uom",
      "fieldtype": "Link",
      "label": "Reserved Weight UOM",
      "options": "UOM",
      "default": "KG"
    },
    {
      "fieldname": "reserved_volume",
      "fieldtype": "Float",
      "label": "Reserved Volume"
    },
    {
      "fieldname": "reserved_volume_uom",
      "fieldtype": "Link",
      "label": "Reserved Volume UOM",
      "options": "UOM",
      "default": "CBM"
    },
    {
      "fieldname": "reserved_pallets",
      "fieldtype": "Float",
      "label": "Reserved Pallets"
    },
    {
      "fieldname": "reserved_containers",
      "fieldtype": "Float",
      "label": "Reserved Containers"
    },
    {
      "fieldname": "transport_job",
      "fieldtype": "Link",
      "options": "Transport Job"
    },
    {
      "fieldname": "transport_leg",
      "fieldtype": "Link",
      "options": "Transport Leg"
    },
    {
      "fieldname": "run_sheet",
      "fieldtype": "Link",
      "options": "Run Sheet"
    },
    {
      "fieldname": "status",
      "fieldtype": "Select",
      "options": "Reserved\nActive\nReleased\nCancelled",
      "default": "Reserved"
    },
    {
      "fieldname": "reserved_by",
      "fieldtype": "Link",
      "options": "User"
    },
    {
      "fieldname": "released_at",
      "fieldtype": "Datetime"
    }
  ]
}

2. Capacity Utilization Snapshot (New DocType)

Purpose: Store historical capacity utilization snapshots for reporting

Fields:

{
  "doctype": "Capacity Utilization Snapshot",
  "fields": [
    {
      "fieldname": "snapshot_date",
      "fieldtype": "Date",
      "reqd": 1
    },
    {
      "fieldname": "snapshot_time",
      "fieldtype": "Time",
      "reqd": 1
    },
    {
      "fieldname": "vehicle",
      "fieldtype": "Link",
      "options": "Transport Vehicle",
      "reqd": 1
    },
    {
      "fieldname": "total_capacity_weight",
      "fieldtype": "Float"
    },
    {
      "fieldname": "capacity_weight_uom",
      "fieldtype": "Link",
      "label": "Weight Capacity UOM",
      "options": "UOM",
      "default": "KG"
    },
    {
      "fieldname": "utilized_weight",
      "fieldtype": "Float"
    },
    {
      "fieldname": "available_weight",
      "fieldtype": "Float"
    },
    {
      "fieldname": "weight_utilization_percent",
      "fieldtype": "Percent"
    },
    {
      "fieldname": "total_capacity_volume",
      "fieldtype": "Float"
    },
    {
      "fieldname": "capacity_volume_uom",
      "fieldtype": "Link",
      "label": "Volume Capacity UOM",
      "options": "UOM",
      "default": "CBM"
    },
    {
      "fieldname": "utilized_volume",
      "fieldtype": "Float"
    },
    {
      "fieldname": "available_volume",
      "fieldtype": "Float"
    },
    {
      "fieldname": "volume_utilization_percent",
      "fieldtype": "Percent"
    },
    {
      "fieldname": "total_capacity_pallets",
      "fieldtype": "Float"
    },
    {
      "fieldname": "utilized_pallets",
      "fieldtype": "Float"
    },
    {
      "fieldname": "available_pallets",
      "fieldtype": "Float"
    },
    {
      "fieldname": "pallets_utilization_percent",
      "fieldtype": "Percent"
    }
  ]
}

3. Enhanced Transport Vehicle

Additional Fields:

{
  "fieldname": "capacity_management_tab",
  "fieldtype": "Tab Break",
  "label": "Capacity Management"
},
{
  "fieldname": "capacity_weight_uom",
  "fieldtype": "Link",
  "label": "Capacity Weight UOM",
  "options": "UOM",
  "description": "Unit of measure for weight capacity (default from settings)",
  "default": "KG"
},
{
  "fieldname": "capacity_volume_uom",
  "fieldtype": "Link",
  "label": "Capacity Volume UOM",
  "options": "UOM",
  "description": "Unit of measure for volume capacity (default from settings)",
  "default": "CBM"
},
{
  "fieldname": "capacity_override_enabled",
  "fieldtype": "Check",
  "label": "Allow Capacity Override",
  "default": 0
},
{
  "fieldname": "max_capacity_override_percent",
  "fieldtype": "Percent",
  "label": "Max Override %",
  "description": "Maximum percentage capacity can be overridden"
},
{
  "fieldname": "capacity_buffer_percent",
  "fieldtype": "Percent",
  "label": "Capacity Buffer %",
  "default": 10,
  "description": "Recommended buffer to maintain"
},
{
  "fieldname": "capacity_alert_threshold",
  "fieldtype": "Percent",
  "label": "Alert Threshold %",
  "default": 80,
  "description": "Alert when utilization exceeds this percentage"
}

4. Enhanced Sales Quote

Additional Fields:

{
  "fieldname": "capacity_info_section",
  "fieldtype": "Section Break",
  "label": "Capacity Information",
  "depends_on": "eval:doc.vehicle_type && doc.is_transport"
},
{
  "fieldname": "vehicle_type_capacity_weight",
  "fieldtype": "Float",
  "label": "Vehicle Type Max Weight",
  "read_only": 1,
  "description": "Maximum weight capacity for selected vehicle type"
},
{
  "fieldname": "vehicle_type_capacity_weight_uom",
  "fieldtype": "Link",
  "label": "Weight Capacity UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "vehicle_type_capacity_volume",
  "fieldtype": "Float",
  "label": "Vehicle Type Max Volume",
  "read_only": 1,
  "description": "Maximum volume capacity for selected vehicle type"
},
{
  "fieldname": "vehicle_type_capacity_volume_uom",
  "fieldtype": "Link",
  "label": "Volume Capacity UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "capacity_status",
  "fieldtype": "Select",
  "options": "Available\nWarning\nExceeded",
  "label": "Capacity Status",
  "read_only": 1
},
{
  "fieldname": "capacity_warning",
  "fieldtype": "Small Text",
  "label": "Capacity Warning",
  "read_only": 1
}

Note: Sales Quote already has weight_uom and volume_uom fields. These will be used for capacity validation.

5. Enhanced Transport Order

Additional Fields:

{
  "fieldname": "capacity_tab",
  "fieldtype": "Tab Break",
  "label": "Capacity"
},
{
  "fieldname": "total_required_weight",
  "fieldtype": "Float",
  "label": "Total Required Weight",
  "read_only": 1
},
{
  "fieldname": "total_required_weight_uom",
  "fieldtype": "Link",
  "label": "Required Weight UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "total_required_volume",
  "fieldtype": "Float",
  "label": "Total Required Volume",
  "read_only": 1
},
{
  "fieldname": "total_required_volume_uom",
  "fieldtype": "Link",
  "label": "Required Volume UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "total_required_pallets",
  "fieldtype": "Float",
  "label": "Total Required Pallets",
  "read_only": 1
},
{
  "fieldname": "vehicle_type_capacity_weight",
  "fieldtype": "Float",
  "label": "Vehicle Type Max Weight",
  "read_only": 1
},
{
  "fieldname": "vehicle_type_capacity_weight_uom",
  "fieldtype": "Link",
  "label": "Weight Capacity UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "vehicle_type_capacity_volume",
  "fieldtype": "Float",
  "label": "Vehicle Type Max Volume",
  "read_only": 1
},
{
  "fieldname": "vehicle_type_capacity_volume_uom",
  "fieldtype": "Link",
  "label": "Volume Capacity UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "vehicle_type_capacity_pallets",
  "fieldtype": "Float",
  "label": "Vehicle Type Max Pallets",
  "read_only": 1
},
{
  "fieldname": "capacity_status",
  "fieldtype": "Select",
  "options": "Available\nWarning\nExceeded",
  "label": "Capacity Status",
  "read_only": 1
}

Note: Transport Order Package already has uom field. This will be used for quantity/package UOM.

6. Enhanced Transport Job

Additional Fields (in addition to existing capacity-related fields):

{
  "fieldname": "vehicle_type_capacity_weight",
  "fieldtype": "Float",
  "label": "Vehicle Type Max Weight",
  "read_only": 1,
  "description": "Maximum weight capacity for selected vehicle type"
},
{
  "fieldname": "vehicle_type_capacity_weight_uom",
  "fieldtype": "Link",
  "label": "Weight Capacity UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "vehicle_type_capacity_volume",
  "fieldtype": "Float",
  "label": "Vehicle Type Max Volume",
  "read_only": 1
},
{
  "fieldname": "vehicle_type_capacity_volume_uom",
  "fieldtype": "Link",
  "label": "Volume Capacity UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "vehicle_type_capacity_pallets",
  "fieldtype": "Float",
  "label": "Vehicle Type Max Pallets",
  "read_only": 1
},
{
  "fieldname": "capacity_validation_status",
  "fieldtype": "Select",
  "options": "Not Validated\nValid\nWarning\nExceeded",
  "label": "Capacity Validation Status",
  "read_only": 1
}

Note: Transport Job Package already has uom field for quantity/package UOM.

6.1. Enhanced Transport Job Package

Additional Fields:

{
  "fieldname": "weight_uom",
  "fieldtype": "Link",
  "label": "Weight UOM",
  "options": "UOM",
  "description": "Unit of measure for weight (default from settings)"
},
{
  "fieldname": "volume_uom",
  "fieldtype": "Link",
  "label": "Volume UOM",
  "options": "UOM",
  "description": "Unit of measure for volume (default from settings)"
},
{
  "fieldname": "dimension_uom",
  "fieldtype": "Link",
  "label": "Dimension UOM",
  "options": "UOM",
  "description": "Unit of measure for length, width, height (default from settings)"
}

6.2. Enhanced Transport Order Package

Additional Fields:

{
  "fieldname": "weight_uom",
  "fieldtype": "Link",
  "label": "Weight UOM",
  "options": "UOM",
  "description": "Unit of measure for weight (default from settings)"
},
{
  "fieldname": "volume_uom",
  "fieldtype": "Link",
  "label": "Volume UOM",
  "options": "UOM",
  "description": "Unit of measure for volume (default from settings)"
},
{
  "fieldname": "dimension_uom",
  "fieldtype": "Link",
  "label": "Dimension UOM",
  "options": "UOM",
  "description": "Unit of measure for length, width, height (default from settings)"
}

Note: Transport Order Package already has uom field for quantity/package UOM.

7. Enhanced Transport Leg

Additional Fields:

{
  "fieldname": "vehicle_type_capacity_weight",
  "fieldtype": "Float",
  "label": "Vehicle Type Max Weight (kg)",
  "read_only": 1
},
{
  "fieldname": "capacity_status",
  "fieldtype": "Select",
  "options": "Available\nWarning\nExceeded",
  "label": "Capacity Status",
  "read_only": 1
}

8. Enhanced Run Sheet

Additional Fields:

{
  "fieldname": "capacity_tab",
  "fieldtype": "Tab Break",
  "label": "Capacity"
},
{
  "fieldname": "total_required_weight",
  "fieldtype": "Float",
  "label": "Total Required Weight",
  "read_only": 1
},
{
  "fieldname": "total_required_weight_uom",
  "fieldtype": "Link",
  "label": "Required Weight UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "total_required_volume",
  "fieldtype": "Float",
  "label": "Total Required Volume",
  "read_only": 1
},
{
  "fieldname": "total_required_volume_uom",
  "fieldtype": "Link",
  "label": "Required Volume UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "total_required_pallets",
  "fieldtype": "Float",
  "label": "Total Required Pallets",
  "read_only": 1
},
{
  "fieldname": "vehicle_capacity_weight",
  "fieldtype": "Float",
  "label": "Vehicle Capacity Weight",
  "read_only": 1
},
{
  "fieldname": "vehicle_capacity_weight_uom",
  "fieldtype": "Link",
  "label": "Vehicle Weight Capacity UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "vehicle_capacity_volume",
  "fieldtype": "Float",
  "label": "Vehicle Capacity Volume",
  "read_only": 1
},
{
  "fieldname": "vehicle_capacity_volume_uom",
  "fieldtype": "Link",
  "label": "Vehicle Volume Capacity UOM",
  "options": "UOM",
  "read_only": 1
},
{
  "fieldname": "vehicle_capacity_pallets",
  "fieldtype": "Float",
  "label": "Vehicle Capacity Pallets",
  "read_only": 1
},
{
  "fieldname": "weight_utilization_percent",
  "fieldtype": "Percent",
  "label": "Weight Utilization %",
  "read_only": 1
},
{
  "fieldname": "volume_utilization_percent",
  "fieldtype": "Percent",
  "label": "Volume Utilization %",
  "read_only": 1
},
{
  "fieldname": "pallets_utilization_percent",
  "fieldtype": "Percent",
  "label": "Pallets Utilization %",
  "read_only": 1
},
{
  "fieldname": "capacity_status",
  "fieldtype": "Select",
  "options": "Available\nWarning\nExceeded\nOverridden",
  "label": "Capacity Status",
  "read_only": 1
}

9. Capacity Settings (New DocType)

Purpose: System-wide capacity management settings

Fields:

{
  "doctype": "Transport Capacity Settings",
  "is_single": 1,
  "fields": [
    {
      "fieldname": "enable_capacity_management",
      "fieldtype": "Check",
      "label": "Enable Capacity Management",
      "default": 1
    },
    {
      "fieldname": "enable_capacity_reservation",
      "fieldtype": "Check",
      "label": "Enable Capacity Reservation",
      "default": 1
    },
    {
      "fieldname": "auto_reserve_capacity",
      "fieldtype": "Check",
      "label": "Auto Reserve Capacity on Assignment",
      "default": 1
    },
    {
      "fieldname": "capacity_validation_strict",
      "fieldtype": "Check",
      "label": "Strict Capacity Validation",
      "description": "Prevent assignments exceeding capacity",
      "default": 1
    },
    {
      "fieldname": "default_capacity_buffer",
      "fieldtype": "Percent",
      "label": "Default Capacity Buffer %",
      "default": 10
    },
    {
      "fieldname": "capacity_alert_threshold",
      "fieldtype": "Percent",
      "label": "Default Alert Threshold %",
      "default": 80
    },
    {
      "fieldname": "snapshot_frequency",
      "fieldtype": "Select",
      "options": "Hourly\nDaily\nWeekly",
      "label": "Utilization Snapshot Frequency",
      "default": "Daily"
    },
    {
      "fieldname": "retention_days",
      "fieldtype": "Int",
      "label": "Snapshot Retention (days)",
      "default": 90
    },
    {
      "fieldname": "uom_section",
      "fieldtype": "Section Break",
      "label": "Default Units of Measure"
    },
    {
      "fieldname": "default_dimension_uom",
      "fieldtype": "Link",
      "label": "Default Dimension UOM",
      "options": "UOM",
      "description": "Default unit for length, width, height (e.g., CM, M, FT)",
      "default": "CM"
    },
    {
      "fieldname": "default_volume_uom",
      "fieldtype": "Link",
      "label": "Default Volume UOM",
      "options": "UOM",
      "description": "Default unit for volume (e.g., CBM, CFT, L)",
      "default": "CBM"
    },
    {
      "fieldname": "default_weight_uom",
      "fieldtype": "Link",
      "label": "Default Weight UOM",
      "options": "UOM",
      "description": "Default unit for weight (e.g., KG, TON, LB)",
      "default": "KG"
    },
    {
      "fieldname": "column_break_uom",
      "fieldtype": "Column Break"
    },
    {
      "fieldname": "enable_uom_conversion",
      "fieldtype": "Check",
      "label": "Enable UOM Conversion",
      "description": "Automatically convert between different UOMs in capacity calculations",
      "default": 1
    },
    {
      "fieldname": "require_uom_for_capacity",
      "fieldtype": "Check",
      "label": "Require UOM for Capacity Fields",
      "description": "Require UOM to be specified for all capacity-related fields",
      "default": 0
    }
  ]
}

Note: Default UOMs can also be added to existing Transport Settings DocType as an alternative approach.

Core Functionality

1. Capacity Calculation

Available Capacity Formula

Available Capacity = Total Capacity - Reserved Capacity - Utilized Capacity

Utilization Percentage

Utilization % = (Reserved + Utilized) / Total Capacity × 100

1.1. UOM Conversion for Capacity Calculations

Purpose: Ensure all capacity values are in consistent units before calculations

Conversion Requirements:

  1. Weight Conversion: Convert all weight values to standard UOM (default: KG)
  2. Volume Conversion: Convert all volume values to standard UOM (default: CBM)
  3. Dimension Conversion: Convert dimensions to standard UOM before volume calculation (default: CM or M)

Standard UOMs for Capacity:

  • Weight: Always stored and compared in KG (or configured default)
  • Volume: Always stored and compared in CBM (or configured default)
  • Dimensions: Converted to standard dimension UOM before volume calculation

Conversion Flow:

1. Input values with source UOMs
   ↓
2. Convert to standard UOMs (using conversion factors)
   ↓
3. Perform capacity calculations
   ↓
4. Display results in standard or preferred UOMs

Conversion Functions:

def convert_weight(value, from_uom, to_uom="KG"):
    """Convert weight from one UOM to another"""
    # Uses UOM conversion factors from Frappe UOM table
    # Falls back to standard conversions (KG, TON, LB, etc.)

def convert_volume(value, from_uom, to_uom="CBM"):
    """Convert volume from one UOM to another"""
    # Uses UOM conversion factors
    # Handles: CBM, CFT, L, ML, etc.

def convert_dimension(value, from_uom, to_uom="CM"):
    """Convert dimension (length/width/height) from one UOM to another"""
    # Uses UOM conversion factors
    # Handles: CM, M, MM, FT, IN, etc.

def calculate_volume_from_dimensions(length, width, height, 
                                     dimension_uom=None, volume_uom="CBM"):
    """Calculate volume from dimensions with UOM conversion"""
    # Converts dimensions to standard UOM
    # Calculates volume: length × width × height
    # Converts result to target volume UOM
    # Reuses logic from logistics.warehousing.utils.volume_conversion

UOM Conversion Sources:

  1. Frappe UOM Conversion Table: Standard Frappe UOM conversions
  2. Dimension Volume UOM Conversion: Custom conversions for dimension-to-volume (e.g., CM³ to CBM)
  3. Transport Capacity UOM Conversion: Custom conversions specific to transport capacity (if needed)

2. Capacity Reservation Flow

1. Job/Leg Assignment to Vehicle
   ↓
2. Calculate Capacity Requirements
   ↓
3. Check Available Capacity
   ↓
4. Reserve Capacity (if sufficient)
   ↓
5. Create Capacity Reservation Record
   ↓
6. Update Vehicle Capacity Status

3. Capacity Release Flow

1. Job/Leg Completion/Cancellation
   ↓
2. Identify Capacity Reservations
   ↓
3. Release Reserved Capacity
   ↓
4. Update Reservation Status to "Released"
   ↓
5. Update Vehicle Capacity Status

4. Vehicle Selection Algorithm

def find_suitable_vehicles(requirements, filters):
    """
    Find vehicles that can accommodate the capacity requirements.
    
    Algorithm:
    1. Filter vehicles by type, availability, and other filters
    2. For each vehicle, calculate available capacity
    3. Check if available capacity >= required capacity (with buffer)
    4. Rank vehicles by:
       - Capacity fit (closest match without exceeding)
       - Current utilization (prefer less utilized)
       - Cost efficiency
    5. Return ranked list of suitable vehicles
    """

5. Vehicle Type Capacity Validation

Purpose: Validate capacity at vehicle type level before specific vehicle assignment

Use Cases:

  • Sales Quote: Validate when vehicle_type is selected
  • Transport Order: Validate when vehicle_type is assigned
  • Transport Job: Validate when vehicle_type is assigned
  • Transport Leg: Validate when vehicle_type is fetched from job or manually set

Validation Logic:

def validate_vehicle_type_capacity(vehicle_type, requirements):
    """
    Validate if vehicle type can accommodate requirements.
    
    Algorithm:
    1. Get aggregated capacity info for vehicle type (max/avg/min from all vehicles)
    2. Compare requirements against vehicle type capacity
    3. Return validation result with warnings if needed
    
    Returns:
        {
            'valid': bool,
            'status': 'Available' | 'Warning' | 'Exceeded',
            'warnings': list,
            'available_vehicles': int  # Count of vehicles with sufficient capacity
        }
    """

Capacity Aggregation Methods:

  • Maximum: Use maximum capacity from all vehicles of this type (most permissive)
  • Average: Use average capacity from all vehicles of this type (balanced)
  • Minimum: Use minimum capacity from all vehicles of this type (most restrictive)
  • Recommended: Use 75th percentile capacity (allows for most vehicles while being realistic)

6. Capacity Validation Rules

  1. Strict Mode: Prevent any assignment exceeding capacity
  2. Warning Mode: Allow assignment but show warning if >80% utilization
  3. Override Mode: Allow override with authorization if configured
  4. Buffer Check: Consider capacity buffer in calculations
  5. Vehicle Type Validation: Check capacity at vehicle type level before vehicle assignment
  6. UOM Standardization: All capacity values are converted to standard UOMs before comparison

7. UOM Conversion Implementation Details

7.1. Conversion Flow

1. User Input (with source UOMs)
   ↓
2. Get Default UOMs from Transport Capacity Settings
   ↓
3. Convert all values to standard UOMs
   - Weight → Default Weight UOM (e.g., KG)
   - Volume → Default Volume UOM (e.g., CBM)
   - Dimensions → Default Dimension UOM (e.g., CM)
   ↓
4. Perform capacity calculations in standard UOMs
   ↓
5. Display results in standard UOMs (or user-preferred UOMs)

7.2. Conversion Sources Priority

  1. Frappe UOM Conversion Table: Standard Frappe conversions (primary source)
  2. Dimension Volume UOM Conversion: Custom dimension-to-volume conversions
  3. Hardcoded Standard Conversions: Fallback for common conversions (KG, TON, etc.)

7.3. Volume Calculation from Dimensions

Formula:

Volume = Length × Width × Height

With UOM Conversion:

  1. Convert all dimensions to standard dimension UOM (e.g., CM)
  2. Calculate raw volume in cubic dimension UOM (e.g., CM³)
  3. Convert to standard volume UOM (e.g., CBM) using conversion factor

Example:

  • Length: 100 CM, Width: 50 CM, Height: 30 CM
  • Raw Volume: 100 × 50 × 30 = 150,000 CM³
  • Converted to CBM: 150,000 / 1,000,000 = 0.15 CBM

7.4. Error Handling

  • Missing UOM: Use default UOM from settings
  • Missing Conversion Factor:
    • Log warning
    • Use 1.0 (assume same UOM) if values are similar
    • Throw error in strict mode
  • Invalid UOM: Use default UOM and log warning

7.5. Performance Considerations

  • Cache conversion factors in memory
  • Batch convert multiple values together
  • Validate UOMs at form level before calculations
  • Store standardized values in database for faster queries

Integration Points

1. Sales Quote Integration

Location: logistics/pricing_center/doctype/sales_quote/sales_quote.py

Integration Points:

  • Capacity check when vehicle_type is assigned: Validate that vehicle type has sufficient capacity for the quote requirements
  • Calculate capacity requirements from weight, volume, and chargeable fields
  • Check available capacity for the selected vehicle type
  • Display capacity warnings if vehicle type capacity is limited
  • Suggest alternative vehicle types if capacity is insufficient

Methods to Add:

def validate_vehicle_type_capacity(self):
    """Validate vehicle type capacity when vehicle_type is assigned"""
    if not self.vehicle_type:
        return
    
    # Get default UOMs from settings
    from logistics.transport.capacity.uom_conversion import (
        convert_weight, convert_volume, get_default_uoms
    )
    default_uoms = get_default_uoms()
    
    # Calculate capacity requirements from quote
    required_weight = flt(self.weight) or 0
    required_weight_uom = self.weight_uom or default_uoms['weight']
    required_volume = flt(self.volume) or 0
    required_volume_uom = self.volume_uom or default_uoms['volume']
    
    # Convert to standard UOMs for comparison
    required_weight_std = convert_weight(required_weight, required_weight_uom)
    required_volume_std = convert_volume(required_volume, required_volume_uom)
    
    # Get vehicle type capacity (average or minimum from vehicles of this type)
    capacity_info = get_vehicle_type_capacity_info(self.vehicle_type)
    
    # Check if capacity is sufficient (compare in standard UOMs)
    if required_weight_std > 0 and capacity_info.get('max_weight', 0) < required_weight_std:
        frappe.msgprint(_("Warning: Required weight ({0} {1}) may exceed typical capacity for vehicle type {2}").format(
            required_weight, required_weight_uom, self.vehicle_type
        ), indicator='orange')
    
    if required_volume_std > 0 and capacity_info.get('max_volume', 0) < required_volume_std:
        frappe.msgprint(_("Warning: Required volume ({0} {1}) may exceed typical capacity for vehicle type {2}").format(
            required_volume, required_volume_uom, self.vehicle_type
        ), indicator='orange')

UI Enhancements:

  • Show capacity information when vehicle_type is selected
  • Display capacity utilization indicator
  • Warn if capacity requirements exceed typical vehicle type capacity

2. Transport Order Integration

Location: logistics/transport/doctype/transport_order/transport_order.py

Integration Points:

  • Capacity check when vehicle_type is assigned: Validate vehicle type capacity against order requirements
  • Calculate capacity requirements from packages
  • Check available capacity for the selected vehicle type
  • Validate capacity before order submission
  • Reserve capacity when order is converted to Transport Job

Methods to Add:

def validate_vehicle_type_capacity(self):
    """Validate vehicle type capacity when vehicle_type is assigned"""
    if not self.vehicle_type:
        return
    
    # Calculate capacity requirements from packages
    total_weight = sum(flt(pkg.weight) or 0 for pkg in (self.packages or []))
    total_volume = sum(flt(pkg.volume) or 0 for pkg in (self.packages or []))
    total_pallets = sum(flt(pkg.no_of_packs) or 0 for pkg in (self.packages or []))
    
    # Get vehicle type capacity information
    capacity_info = get_vehicle_type_capacity_info(self.vehicle_type)
    
    # Validate capacity
    if total_weight > 0 and capacity_info.get('max_weight', 0) < total_weight:
        frappe.throw(_("Total weight ({0} kg) exceeds typical capacity for vehicle type {1}").format(
            total_weight, self.vehicle_type
        ))
    
    if total_volume > 0 and capacity_info.get('max_volume', 0) < total_volume:
        frappe.throw(_("Total volume ({0} m³) exceeds typical capacity for vehicle type {1}").format(
            total_volume, self.vehicle_type
        ))
    
    if total_pallets > 0 and capacity_info.get('max_pallets', 0) < total_pallets:
        frappe.throw(_("Total pallets ({0}) exceeds typical capacity for vehicle type {1}").format(
            total_pallets, self.vehicle_type
        ))

def calculate_capacity_requirements(self):
    """Calculate total capacity requirements from packages with UOM conversion"""
    from logistics.transport.capacity.uom_conversion import (
        convert_weight, convert_volume, calculate_volume_from_dimensions,
        get_default_uoms
    )
    default_uoms = get_default_uoms()
    
    total_weight = 0
    total_volume = 0
    total_pallets = 0
    weight_uom = default_uoms['weight']
    volume_uom = default_uoms['volume']
    
    for pkg in (self.packages or []):
        # Weight
        pkg_weight = flt(pkg.weight) or 0
        if pkg_weight > 0:
            pkg_weight_uom = getattr(pkg, 'weight_uom', None) or weight_uom
            total_weight += convert_weight(pkg_weight, pkg_weight_uom, weight_uom)
        
        # Volume - prefer direct volume, calculate from dimensions if not available
        pkg_volume = flt(pkg.volume) or 0
        if pkg_volume > 0:
            pkg_volume_uom = getattr(pkg, 'volume_uom', None) or volume_uom
            total_volume += convert_volume(pkg_volume, pkg_volume_uom, volume_uom)
        elif pkg.length and pkg.width and pkg.height:
            # Calculate from dimensions
            dim_uom = getattr(pkg, 'dimension_uom', None) or default_uoms['dimension']
            pkg_volume = calculate_volume_from_dimensions(
                pkg.length, pkg.width, pkg.height,
                dimension_uom=dim_uom,
                volume_uom=volume_uom
            )
            total_volume += pkg_volume
        
        # Pallets
        total_pallets += flt(pkg.no_of_packs) or 0
    
    return {
        'weight': total_weight,
        'weight_uom': weight_uom,
        'volume': total_volume,
        'volume_uom': volume_uom,
        'pallets': total_pallets
    }

UI Enhancements:

  • Display capacity requirements summary
  • Show capacity validation status
  • Highlight capacity warnings

3. Transport Job Integration

Location: logistics/transport/doctype/transport_job/transport_job.py

Integration Points:

  • Capacity check when vehicle_type is assigned: Validate vehicle type capacity against job requirements
  • Calculate total capacity requirements from packages
  • Validate capacity when vehicle is assigned
  • Reserve capacity when job is submitted
  • Release capacity when job is cancelled/completed

Methods to Add:

def validate_vehicle_type_capacity(self):
    """Validate vehicle type capacity when vehicle_type is assigned"""
    if not self.vehicle_type:
        return
    
    # Calculate capacity requirements from packages
    requirements = self.calculate_capacity_requirements()
    
    # Get vehicle type capacity information
    capacity_info = get_vehicle_type_capacity_info(self.vehicle_type)
    
    # Check capacity with buffer
    buffer = get_capacity_buffer()
    
    if requirements['weight'] > 0:
        max_weight = capacity_info.get('max_weight', 0) * (1 - buffer / 100)
        if requirements['weight'] > max_weight:
            frappe.msgprint(_("Warning: Required weight ({0} kg) may exceed capacity for vehicle type {1}").format(
                requirements['weight'], self.vehicle_type
            ), indicator='orange')
    
    if requirements['volume'] > 0:
        max_volume = capacity_info.get('max_volume', 0) * (1 - buffer / 100)
        if requirements['volume'] > max_volume:
            frappe.msgprint(_("Warning: Required volume ({0} m³) may exceed capacity for vehicle type {1}").format(
                requirements['volume'], self.vehicle_type
            ), indicator='orange')
    
    if requirements['pallets'] > 0:
        max_pallets = capacity_info.get('max_pallets', 0) * (1 - buffer / 100)
        if requirements['pallets'] > max_pallets:
            frappe.msgprint(_("Warning: Required pallets ({0}) may exceed capacity for vehicle type {1}").format(
                requirements['pallets'], self.vehicle_type
            ), indicator='orange')

def calculate_capacity_requirements(self):
    """Calculate total weight, volume, pallets from packages"""
    total_weight = sum(flt(pkg.weight) or 0 for pkg in (self.packages or []))
    total_volume = sum(flt(pkg.volume) or 0 for pkg in (self.packages or []))
    total_pallets = sum(flt(pkg.no_of_packs) or 0 for pkg in (self.packages or []))
    
    return {
        'weight': total_weight,
        'volume': total_volume,
        'pallets': total_pallets
    }
    
def validate_capacity(self):
    """Validate capacity if vehicle is assigned"""
    if not self.vehicle:
        return
    
    requirements = self.calculate_capacity_requirements()
    vehicle_doc = frappe.get_doc("Transport Vehicle", self.vehicle)
    
    # Use capacity manager to validate
    from logistics.transport.capacity.capacity_validator import validate_job_capacity
    validate_job_capacity(self, vehicle_doc, requirements)
    
def reserve_capacity(self):
    """Reserve capacity when job is assigned to vehicle"""
    if not self.vehicle or self.docstatus != 1:  # Only for submitted jobs
        return
    
    requirements = self.calculate_capacity_requirements()
    from logistics.transport.capacity.capacity_reserver import reserve_job_capacity
    reserve_job_capacity(self, self.vehicle, requirements)
    
def release_capacity(self):
    """Release capacity when job is completed/cancelled"""
    if not self.vehicle:
        return
    
    from logistics.transport.capacity.capacity_reserver import release_job_capacity
    release_job_capacity(self)

Validation Flow:

  1. When vehicle_type is assigned → Check capacity against vehicle type averages
  2. When vehicle is assigned → Validate against specific vehicle capacity
  3. On job submission → Reserve capacity
  4. On job completion/cancellation → Release capacity

4. Transport Leg Integration

Location: logistics/transport/doctype/transport_leg/transport_leg.py

Integration Points:

  • Capacity check when vehicle_type is assigned: Validate vehicle type capacity for the leg
  • Calculate leg capacity requirements from cargo
  • Validate capacity when leg is added to run sheet
  • Reserve capacity for leg
  • Release capacity when leg is completed

Methods to Add:

def validate_vehicle_type_capacity(self):
    """Validate vehicle type capacity when vehicle_type is assigned or fetched from job"""
    if not self.vehicle_type:
        return
    
    # Calculate leg capacity requirements
    requirements = self.calculate_capacity_requirements()
    
    # Get vehicle type capacity information
    capacity_info = get_vehicle_type_capacity_info(self.vehicle_type)
    
    # Check capacity
    if requirements['weight'] > 0 and capacity_info.get('max_weight', 0) < requirements['weight']:
        frappe.msgprint(_("Warning: Leg weight ({0} kg) may exceed capacity for vehicle type {1}").format(
            requirements['weight'], self.vehicle_type
        ), indicator='orange')
    
    if requirements['volume'] > 0 and capacity_info.get('max_volume', 0) < requirements['volume']:
        frappe.msgprint(_("Warning: Leg volume ({0} m³) may exceed capacity for vehicle type {1}").format(
            requirements['volume'], self.vehicle_type
        ), indicator='orange')

def calculate_capacity_requirements(self):
    """Calculate leg capacity requirements from cargo weight"""
    return {
        'weight': flt(self.cargo_weight_kg) or 0,
        'volume': 0,  # Can be calculated from dimensions if available
        'pallets': 0  # Can be calculated if pallet information is available
    }

def validate_capacity_for_runsheet(self, vehicle):
    """Validate capacity when leg is added to run sheet"""
    if not vehicle:
        return
    
    requirements = self.calculate_capacity_requirements()
    vehicle_doc = frappe.get_doc("Transport Vehicle", vehicle)
    
    from logistics.transport.capacity.capacity_validator import validate_leg_capacity
    validate_leg_capacity(self, vehicle_doc, requirements)

def reserve_capacity(self, vehicle):
    """Reserve capacity for leg when assigned to run sheet"""
    if not vehicle:
        return
    
    requirements = self.calculate_capacity_requirements()
    from logistics.transport.capacity.capacity_reserver import reserve_leg_capacity
    reserve_leg_capacity(self, vehicle, requirements)

def release_capacity(self):
    """Release capacity when leg is completed"""
    from logistics.transport.capacity.capacity_reserver import release_leg_capacity
    release_leg_capacity(self)

Validation Triggers:

  • When vehicle_type is set (from transport_job or manually)
  • When leg is added to a run sheet with a vehicle
  • Before run sheet submission

5. Run Sheet Integration

Location: logistics/transport/doctype/run_sheet/run_sheet.py

Enhancements:

  • Enhance existing validate_capacity() method
  • Add capacity calculation on leg addition
  • Display capacity utilization in UI
  • Reserve capacity for all legs
  • Release capacity on completion

Methods to Enhance:

def calculate_capacity_requirements(self):
    """Calculate total capacity requirements from all legs"""
    
def validate_capacity(self):
    """Enhanced validation with capacity manager"""
    
def reserve_capacity(self):
    """Reserve capacity for all legs"""
    
def update_capacity_display(self):
    """Update capacity fields in UI"""

6. Transport Plan Integration

Location: logistics/transport/doctype/transport_plan/transport_plan.py

Enhancements:

  • Use capacity manager for vehicle selection
  • Consider capacity in optimization algorithms
  • Forecast capacity needs
  • Display capacity constraints in planning

7. Transport Consolidation Integration

Location: logistics/transport/doctype/transport_consolidation/transport_consolidation.py

Integration Points:

  • Validate consolidated capacity
  • Check if consolidation fits vehicle capacity
  • Reserve capacity for consolidation

8. Vehicle Selection UI

Enhancements:

  • Show available capacity in vehicle selector
  • Filter vehicles by capacity
  • Display capacity utilization percentage
  • Warn when capacity is limited

User Interface Design

1. Capacity Dashboard

Location: New page logistics/transport/page/capacity_dashboard/capacity_dashboard

Features:

  • Real-time capacity overview
  • Vehicle capacity utilization chart
  • Capacity alerts and warnings
  • Quick filters (vehicle type, date range, utilization threshold)

Sections:

  • Overview Cards: Total vehicles, average utilization, vehicles at capacity
  • Utilization Chart: Time-series chart showing capacity trends
  • Vehicle List: Table with capacity details
  • Alerts: Capacity warnings and exceeded capacity notifications

2. Sales Quote Capacity View

Enhancement to Sales Quote form:

  • Capacity information section (shown when vehicle_type is selected)
  • Display vehicle type capacity limits
  • Show capacity status (Available/Warning/Exceeded)
  • Capacity warnings when requirements exceed vehicle type capacity

3. Transport Order Capacity View

Enhancement to Transport Order form:

  • New "Capacity" tab
  • Display total capacity requirements from packages
  • Show vehicle type capacity limits
  • Capacity validation status
  • Capacity warnings

4. Vehicle Capacity View

Enhancement to Transport Vehicle form:

  • New "Capacity Management" tab
  • Real-time capacity display
  • Capacity utilization chart
  • Active reservations list
  • Capacity history

5. Run Sheet Capacity View

Enhancement to Run Sheet form:

  • New "Capacity" tab
  • Visual capacity indicators (progress bars)
  • Capacity breakdown by leg
  • Capacity warnings

6. Vehicle Selector Enhancement

Enhancement to vehicle selection dialogs:

  • Show available capacity
  • Filter by capacity
  • Capacity utilization indicator
  • Capacity fit score

7. Capacity Reports

New Reports:

  1. Capacity Utilization Report

    • Vehicle-wise utilization
    • Date range selection
    • Export capabilities

  2. Capacity Forecast Report

    • Future capacity needs
    • Bottleneck identification
    • Recommendations

  3. Capacity Efficiency Report

    • Utilization trends
    • Efficiency metrics
    • Comparison analysis

Implementation Plan

Phase 1: Foundation (Weeks 1-2)

Week 1: Core Infrastructure

  • Create Capacity Manager class
  • Create Capacity Reservation DocType
  • Create Capacity Utilization Snapshot DocType
  • Create Transport Capacity Settings DocType
  • Create UOM Conversion Helper module
  • Add default UOM fields to Transport Capacity Settings
  • Set up database indexes for performance

Week 2: Basic Capacity Tracking and UOM

  • Implement capacity calculation logic
  • Implement UOM conversion functions (weight, volume, dimensions)
  • Implement dimension-to-volume calculation with UOM conversion
  • Integrate UOM conversion in capacity calculations
  • Implement capacity reservation system (with UOM support)
  • Implement capacity release system
  • Add capacity and UOM fields to Transport Vehicle
  • Unit tests for core functionality and UOM conversions

Phase 2: Integration (Weeks 3-5)

Week 3: Sales Quote and Transport Order Integration

  • Create Vehicle Type Capacity Helper
  • Add capacity validation to Sales Quote when vehicle_type is assigned
  • Add capacity validation to Transport Order when vehicle_type is assigned
  • Add capacity calculation methods to Sales Quote
  • Add capacity calculation methods to Transport Order
  • Add capacity display fields to Sales Quote form
  • Add capacity display fields to Transport Order form
  • Unit tests for vehicle type capacity validation

Week 4: Transport Job and Transport Leg Integration

  • Add capacity calculation to Transport Job
  • Add capacity validation to Transport Job when vehicle_type is assigned
  • Add capacity validation to Transport Job when vehicle is assigned
  • Add capacity validation to Transport Leg when vehicle_type is assigned
  • Integrate capacity reservation on job assignment
  • Add capacity fields to Transport Job form
  • Add capacity validation to Transport Leg

Week 5: Run Sheet Integration

  • Enhance Run Sheet capacity validation
  • Add capacity calculation to Run Sheet
  • Add capacity display to Run Sheet UI
  • Integrate capacity reservation for legs

Phase 3: Planning and Selection (Weeks 6-7)

Week 5: Vehicle Selection Enhancement

  • Enhance vehicle selection with capacity filtering
  • Add capacity display to vehicle selector
  • Implement capacity-based vehicle ranking
  • Update Transport Plan integration

Week 6: Capacity Planning

  • Implement capacity forecasting
  • Add capacity planning queries
  • Create capacity bottleneck detection
  • Add capacity planning to Transport Plan

Phase 4: UI and Reporting (Weeks 8-9)

Week 7: Dashboard and UI

  • Create Capacity Dashboard page
  • Enhance Vehicle form with capacity tab
  • Enhance Run Sheet form with capacity tab
  • Add capacity indicators and visualizations

Week 8: Reports and Analytics

  • Create Capacity Utilization Report
  • Create Capacity Forecast Report
  • Create Capacity Efficiency Report
  • Add capacity analytics to existing reports

Phase 5: Testing and Optimization (Weeks 10-11)

Week 9: Testing

  • Integration testing
  • Performance testing
  • User acceptance testing
  • Bug fixes and refinements

Week 11: Documentation and Deployment

  • User documentation
  • API documentation
  • Deployment preparation
  • Training materials

Testing Strategy

Unit Tests

Test Files:

  • logistics/transport/capacity/test_capacity_manager.py
  • logistics/transport/capacity/test_capacity_tracker.py
  • logistics/transport/capacity/test_capacity_reserver.py
  • logistics/transport/capacity/test_capacity_validator.py

Test Cases:

  1. Capacity calculation accuracy
  2. Capacity reservation and release
  3. Capacity validation rules
  4. Vehicle selection algorithm
  5. Capacity conflict handling
  6. Concurrent reservation handling

Integration Tests

Test Scenarios:

  1. Job assignment with capacity reservation
  2. Run Sheet creation with capacity validation
  3. Capacity release on job completion
  4. Capacity forecasting accuracy
  5. Multi-vehicle capacity management

Performance Tests

Metrics:

  • Capacity calculation time for 1000 vehicles
  • Reservation creation time
  • Dashboard load time
  • Report generation time

User Acceptance Tests

Scenarios:

  1. Assign job to vehicle with sufficient capacity
  2. Attempt to assign job exceeding capacity (should warn/block)
  3. View capacity dashboard
  4. Generate capacity reports
  5. Override capacity with authorization

Future Enhancements

Short-term (3-6 months)

  1. Advanced Capacity Optimization

    • Multi-dimensional capacity optimization
    • Load balancing algorithms
    • Capacity-based route optimization

  2. Capacity Analytics

    • Predictive capacity analytics
    • Machine learning for capacity forecasting
    • Capacity trend analysis

  3. Mobile Capacity Tracking

    • Mobile app for capacity updates
    • Real-time capacity notifications
    • Driver capacity reporting

Medium-term (6-12 months)

  1. Dynamic Capacity Adjustment

    • Real-time capacity adjustments
    • Capacity sharing between vehicles
    • Flexible capacity allocation

  2. Capacity Marketplace

    • External capacity sharing
    • Capacity trading platform
    • Third-party capacity integration

  3. AI-Powered Capacity Management

    • AI-based vehicle selection
    • Predictive capacity planning
    • Automated capacity optimization

Long-term (12+ months)

  1. IoT Integration

    • Real-time weight sensors
    • Volume measurement devices
    • Automated capacity tracking

  2. Blockchain Capacity Ledger

    • Immutable capacity records
    • Capacity audit trail
    • Trusted capacity sharing

Technical Specifications

API Endpoints

# Capacity Manager API
GET    /api/method/logistics.transport.capacity.get_available_capacity
POST   /api/method/logistics.transport.capacity.reserve_capacity
POST   /api/method/logistics.transport.capacity.release_capacity
GET    /api/method/logistics.transport.capacity.check_capacity
GET    /api/method/logistics.transport.capacity.find_suitable_vehicles
GET    /api/method/logistics.transport.capacity.forecast_capacity
GET    /api/method/logistics.transport.capacity.get_utilization

Database Indexes

-- Capacity Reservation indexes
CREATE INDEX idx_capacity_reservation_vehicle_date 
ON `tabCapacity Reservation` (vehicle, reservation_date, status);

CREATE INDEX idx_capacity_reservation_job 
ON `tabCapacity Reservation` (transport_job);

CREATE INDEX idx_capacity_reservation_leg 
ON `tabCapacity Reservation` (transport_leg);

-- Capacity Utilization Snapshot indexes
CREATE INDEX idx_capacity_snapshot_vehicle_date 
ON `tabCapacity Utilization Snapshot` (vehicle, snapshot_date);

CREATE INDEX idx_capacity_snapshot_date 
ON `tabCapacity Utilization Snapshot` (snapshot_date);

Performance Considerations

  1. Caching: Cache capacity calculations for frequently accessed vehicles
  2. Batch Processing: Process capacity updates in batches
  3. Async Updates: Use background jobs for capacity snapshots
  4. Database Optimization: Proper indexing and query optimization
  5. Materialized Views: Consider materialized views for complex capacity queries

Risk Assessment

Technical Risks

  1. Performance Impact: Capacity calculations may slow down vehicle selection

    • Mitigation: Implement caching and optimize queries

  2. Data Consistency: Concurrent capacity reservations may cause conflicts

    • Mitigation: Use database transactions and locking mechanisms

  3. Complexity: System may become too complex to maintain

    • Mitigation: Modular design, comprehensive documentation, code reviews

Business Risks

  1. User Adoption: Users may resist new capacity management processes

    • Mitigation: User training, intuitive UI, gradual rollout

  2. Over-constraint: Strict capacity validation may limit flexibility

    • Mitigation: Configurable validation rules, override mechanisms

Success Metrics

Key Performance Indicators (KPIs)

  1. Capacity Utilization Rate: Target 75-85% average utilization
  2. Over-capacity Assignments: < 1% of total assignments
  3. Capacity Calculation Accuracy: 100% accuracy
  4. System Performance: < 2 seconds for capacity queries
  5. User Adoption: 80% of users actively using capacity features

Measurement Methods

  1. Utilization Reports: Track average capacity utilization
  2. Error Logs: Monitor over-capacity assignment attempts
  3. Performance Metrics: Track API response times
  4. User Surveys: Collect user feedback on capacity features
  5. Usage Analytics: Track feature usage statistics

Conclusion

This Capacity Management system will provide comprehensive capacity tracking, planning, and optimization capabilities for the Transport module. The phased implementation approach ensures gradual rollout with continuous testing and refinement. The system is designed to be scalable, performant, and user-friendly while maintaining flexibility for future enhancements.

Appendix

A. Glossary

  • Capacity: Maximum amount (weight/volume/pallets) a vehicle can carry
  • Utilization: Percentage of capacity currently in use
  • Reservation: Temporary hold on capacity for a specific job/leg
  • Available Capacity: Capacity that is not reserved or utilized
  • Capacity Buffer: Recommended unused capacity to maintain flexibility

B. References

  • Transport Vehicle DocType schema
  • Run Sheet capacity validation implementation
  • Transport Plan vehicle selection logic
  • Warehousing Capacity Manager (reference implementation)

C. Related Documents

  • Transport Module Architecture
  • Vehicle Management Design
  • Run Sheet Design
  • Transport Planning Design
  • Warehousing Volume Conversion Utility (reference implementation)

D. UOM Conversion Reference

Existing Utilities:

  • logistics.warehousing.utils.volume_conversion: Dimension-to-volume conversion with UOM support
  • Frappe UOM Conversion: Standard UOM conversions in Frappe framework
  • Dimension Volume UOM Conversion DocType: Custom conversions for dimension-to-volume

Standard UOMs (recommended defaults):

  • Weight: KG (Kilogram), TON (Metric Ton), LB (Pound)
  • Volume: CBM (Cubic Meter), CFT (Cubic Foot), L (Liter)
  • Dimensions: CM (Centimeter), M (Meter), MM (Millimeter), FT (Foot), IN (Inch)

Conversion Examples:

  • 1 TON = 1000 KG
  • 1 CBM = 1,000,000 CM³
  • 1 M = 100 CM
  • 1 FT = 30.48 CM
  • 1 CFT = 0.0283168 CBM

Document Version: 1.1
Last Updated: 2026-01-XX
Author: Transport Module Team
Status: Draft for Review
Changes in v1.1: Added UOM support for dimensions, volume, and weight with conversion logic

Getting Started

Setup and Settings

Sea Freight

Air Freight

Transport

Customs

Warehousing

Pricing Center

Job Management

Sustainability

Intercompany

Special Projects

Pages

Features

Reports

Glossary

Clone this wiki locally