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. Cache keys must include route coordinates plus the vehicle-class metadata (tollClass, vehicleHeightCm, axleCount) so a light sedan never reuses a coach toll estimate. 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).

Approach and empty-return legs are priced with the same toll pipeline as the client service leg when those legs have route geometry. If Google/HERE/TollGuru cannot return a route, the engine falls back to the Haversine estimate rather than dropping the cost component.

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, same-day, relay, double-crew, or multi-day requirement, it attaches a CompliancePlan to TripAnalysis:

The engine now resolves staffing through a single computeStaffing() path parameterized by an RSE mode profile:

The staffing plan selection policy is configurable (OrganizationPricingSettings.staffingSelectionPolicy) and operator choices can override the automatic plan when the cockpit sends a staffingOverride:

Staffing costs inflate TripAnalysis.totalInternalCost and are also folded into the recommended quote price when the returned plan carries an additionalCost. The cost breakdown itself remains operator-internal; agency responses receive only reduced feasibility/crew information.

Relay plans use a frozen sharePercent split. The default comes from OrganizationLicenseRule.defaultRelaySharePercent, and explicit operator overrides are clamped to an exclusive 1–99 percent range. Accepted quotes persist the split into StaffingPlan / StaffingAssignment so dispatch does not recompute it.

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