Order Consolidation System

A pair of orders comes in with pre-computed pairing metrics: distanceKm between the two destinations, deliveryWindowDifferenceHours, availableCarrierCapacity, and the individual orderWeight1 and orderWeight2, plus the full orders array and carrierDetails for reference. The priority table works entirely off the three pairing metrics.

Consolidation priority falls out of three factors read together under a first hit policy: distanceKm, deliveryWindowDifferenceHours, and availableCarrierCapacity. Destinations under 50km apart with windows within 48 hours and capacity above 3 rate 'high'; two 'medium' rows relax either the time gap (up to 72 hours) or the distance (up to 100km); under 100km with up to 72 hours and capacity above 1 still earns 'low', and the blank catch-all returns 'none' with the explanation that orders cannot be consolidated. Each row also emits a plain-language explanation field.

The graduated relaxation is the realistic part: consolidation only pays when the detour between drops is small relative to the line-haul, so distance gets the tightest bounds, while a 72-hour window difference is workable because one customer can usually be nudged a day. Requiring spare carrier capacity above a floor keeps the combined load from bumping other committed freight; the specific 50/100km and 48/72-hour cutoffs are business tuning rather than any industry standard.

Pair-level metrics get computed before routing: canConsolidate is simply consolidationPriority != 'none', consolidationWeight sums orderWeight1 + orderWeight2, and the savings estimates scale with distance, expectedFuelSavings at distanceKm * 0.15 and costSavingEstimate at distanceKm * 0.25 + 15. Computing these once here lets every priority branch reuse the same baseline and just discount it.

Four branches fan out on consolidationPriority: 'high', 'medium', and 'low' each get their own processing expression, and the default branch handles 'none'. Splitting the flow this way keeps each branch's action, schedule shape, and savings discount independent, so changing how low-priority pairs are handled cannot affect the automatic high-priority path.

High-priority pairs are processed without friction: consolidationAction is 'immediate_consolidation', the deliverySchedule is typed 'consolidated' with notificationRequired false, and the costSavingsReport passes expectedFuelSavings and costSavingEstimate through at full value. No customer touchpoint is needed because both the distance and window checks were already at their tightest.

Medium pairs move to 'scheduled_consolidation' with a twist on notification: customerConfirmationRequired flips true only when deliveryWindowDifferenceHours > 24, meaning a customer is asked before their delivery shifts by more than a day. The savings report is haircut to 90% of expectedFuelSavings and 80% of costSavingEstimate to reflect the extra coordination these pairs need.

Low-priority pairs become 'optional_consolidation' with additionalReview set to 'required' and customerConfirmationRequired always true; the deliverySchedule is typed 'potential_consolidation' and brackets the range between requestedDeliveryDate1 and requestedDeliveryDate2 rather than committing to a slot. Savings drop to 70% and 60% of the fuel and labor baselines, acknowledging that marginal pairings often lose part of the theoretical gain in execution.

When no consolidation is possible the fallback keeps both orders independent: consolidationAction is 'no_consolidation', the deliverySchedule is typed 'separate' with each order keeping its own delivery time, and the costSavingsReport zeroes out fuelSavings, laborSavings, and totalSavings. Returning an explicit zero report instead of omitting it keeps the response shape uniform for downstream reporting.