Cost Model

The cost model feeds TripAnalysis.costBreakdown — a per-segment breakdown used to compute the internal cost, margin, and ProfitabilityIndicator displayed in the back-office. None of the cost components are directly added to the client-facing price; they exist for profitability analysis only.

CostBreakdown Structure

interface CostBreakdown {
  fuel:          FuelCostComponent;
  tolls:         TollCostComponent;
  wear:          WearCostComponent;
  driver:        DriverCostComponent;
  parking:       ParkingCostComponent;
  zoneSurcharges?: ZoneSurcharges;
  tco?:          TcoCostComponent;  // TCO if vehicle data available
  total:         number;
}

total = fuel + tolls + wear + driver + parking. Zone surcharges and TCO are additive when present.

Fuel Cost

Fuel price resolution chain

The engine resolves the price per liter in this order, stopping at the first available result:

Default fuel prices:

CollectAPI timeout: 4 000 ms (REALTIME_API_TIMEOUT_MS). A cache hit with less than 48 hours of age satisfies the request without an API call. The per-request in-memory cache (TTL 60 s) prevents duplicate calls within a single pricing calculation for multi-waypoint excursions.

Fuel consumption resolution chain

The liters-per-100-km figure resolves via a separate four-level chain:

Fuel cost formula

litersUsed = (distanceKm / 100) × consumptionL100km
fuelCost   = litersUsed × pricePerLiter

Toll Cost

Toll resolution chain

Toll results are cached in the TollCalculationCache table for 24 hours (keyed on coordinate hash to 4 decimal places ≈ 11 m precision). TollCostComponent.isFromCache flags cache hits.

For ELECTRIC fuel type, the engine remaps to GASOLINE for the Google Routes API (which may not return toll data for electric vehicles).

Toll cost formula (fallback only)

tollCost = distanceKm × tollCostPerKm

Wear Cost

Vehicle mechanical wear modeled as a flat rate per km:

wearCost = distanceKm × wearCostPerKm

Default: 0.10 €/km (DEFAULT_COST_PARAMETERS.wearCostPerKm). Overridden by OrganizationPricingSettings.wearCostPerKm.

Driver Cost

Driver time valued at an hourly rate:

driverCost = (durationMinutes / 60) × driverHourlyCost

Default: 25.00 €/h (DEFAULT_COST_PARAMETERS.driverHourlyCost). Overridden by OrganizationPricingSettings.driverHourlyCost.

For HEAVY vehicles with RSE mandatory breaks, the extra break minutes are included in the totalDurationMinutes fed into the driver cost calculation.

TCO (Total Cost of Ownership)

When full vehicle and category TCO data is available, a TcoCostComponent is added:

interface TcoCostComponent {
  amount: number;
  distanceKm: number;
  depreciation: { amount: number; ratePerKm: number; method: "LINEAR" | "DECLINING_BALANCE" };
  maintenance:  { amount: number; ratePerKm: number };
  insurance:    { amount: number; ratePerKm: number };
  totalRatePerKm: number;
  source: "VEHICLE" | "CATEGORY";
}

TCO complements the wear cost; when TCO is present, tco.total provides a more accurate amortisation figure than the flat wearCostPerKm rate.

Zone Surcharges

Fixed surcharges defined per zone are collected after route resolution:

interface ZoneSurcharges {
  pickup:  ZoneSurchargeComponent | null;
  dropoff: ZoneSurchargeComponent | null;
  total:   number;
}

Each ZoneSurchargeComponent aggregates parkingSurcharge + accessFee for the zone. If pickup and dropoff resolve to the same zone, the surcharge is counted only once.

RSE Compliance Staffing Costs

When integrateComplianceIntoPricing() detects a long-distance or multi-day mission, it attaches a CompliancePlan to TripAnalysis:

The staffing plan selection policy is configurable (OrganizationPricingSettings.staffingSelectionPolicy):

Staffing costs inflate TripAnalysis.totalInternalCost but are not added to the client price. They affect the profitability indicator.

Profitability Indicator

type ProfitabilityIndicator = "green" | "orange" | "red";

// Thresholds (configurable):
//   green:  marginPercent ≥ greenMarginThreshold  (default 20 %)
//   orange: marginPercent ≥ orangeMarginThreshold (default 0 %)
//   red:    marginPercent < orangeMarginThreshold

marginPercent = ((price - internalCost) / price) × 100

Both greenMarginThreshold and orangeMarginThreshold are configurable in OrganizationPricingSettings.

Short-trip pricing

Below shortTripThresholdKm (configurable), the engine applies a shortTripMultiplier to offset the fixed overhead costs per trip. A minimumTripPriceHt floor can also be set to guarantee a minimum revenue.

See also

• Modes — FIXED_GRID vs DYNAMIC and bidirectional pricing
• Hierarchical Algorithm — Zone resolution and grid matching
• Shadow Calculation — Segments A / B / C and availability overlap
• Configuration → Behaviour — OrganizationPricingSettings field map