changes

apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts

@@ -67,6 +67,12 @@ export interface BookingEvaluationInput {
   isGovernment?: boolean;
   allowConsolidation?: boolean;
   shippingLineId?: string | null;
+  /**
+   * The booking's rail leg. Import overweight derives its per-ton price from
+   * this route's own container freight rate, so the engine needs the yards.
+   */
+  originYardId?: string | null;
+  destinationYardId?: string | null;
   /**
    * Booking's cargo type needs EDR-provided lashing/securing (cargoType
    * hasLashing = true). Fires the flat LASHING surcharge. Resolved by the
@@ -91,6 +97,15 @@ export interface AppliedCargoModifier {
   triggerValue: number | null;
   calculatedAmount: number;
   currency: string;
+  /**
+   * Effective per-unit USD price when it differs from the rate row's own value
+   * — set by derived charges (import overweight: base freight ÷ 2×limit) so
+   * the breakdown shows the real per-ton figure, not the base container price.
+   * Any modifier carrying it also bypasses frozen contract snapshots.
+   */
+  unitPriceUsd?: number | null;
+  /** Display unit for a unitPriceUsd modifier (e.g. PER_TON for overweight). */
+  billingUnit?: string;
 }
 
 export interface ContainerWeightResult {
@@ -165,12 +180,16 @@ export class RuleEngineService {
       ...(await this.capacityViolations(input.containers, input.tradeDirection)),
     );
 
+    // Per-container-line weight limit (maxVgmTons), index-aligned with
+    // containerWeightResults — the derived import overweight divides by it.
+    const lineMaxVgmTons: Array<number | null> = [];
     for (const container of input.containers) {
       const rules = await this.weightLimitRulesRepo.findActiveByContainerTypeId(
         container.containerTypeId,
         input.tradeDirection,
       );
       const rule = rules[0];
+      lineMaxVgmTons.push(rule ? Number(rule.maxVgmTons) : null);
       let isOverweight = container.isOverweight ?? false;
       let excess = container.overweightExcessTons ?? null;
 
@@ -273,13 +292,6 @@ export class RuleEngineService {
           input.containers.some((c) => Number(c.reeferQuantity ?? 0) > 0),
         label: 'refrigerated (reefer) cargo',
       },
-      {
-        trigger: 'WITH_RETURN',
-        wanted:
-          truthy(input.withReturn) ||
-          input.containers.some((c) => Number(c.returnQuantity ?? 0) > 0),
-        label: 'empty-container return',
-      },
     ];
     for (const svc of requestedServices) {
       if (svc.wanted && !surchargeRates.some((r) => r.trigger === svc.trigger)) {
@@ -292,6 +304,14 @@ export class RuleEngineService {
     }
 
     for (const rate of surchargeRates) {
+      // Import overweight never bills the configured rate — its per-ton price
+      // derives from the route's base container freight (see below).
+      if (rate.trigger === 'OVERWEIGHT' && input.tradeDirection === 'IMPORT') {
+        continue;
+      }
+      // Empty-container return is sold per route + container type — billed by
+      // the route-matched block below, never by this route-agnostic loop.
+      if (rate.trigger === 'WITH_RETURN') continue;
       const triggered = this.matchesTrigger(rate.trigger, {
         isHazardous: input.isHazardous,
         hasReefer,
@@ -384,6 +404,21 @@ export class RuleEngineService {
       });
     }
 
+    if (input.tradeDirection === 'IMPORT') {
+      appliedModifiers.push(
+        ...this.derivedImportOverweight(
+          input,
+          containerWeightResults,
+          lineMaxVgmTons,
+          liveRates,
+        ),
+      );
+    }
+
+    const withReturn = this.withReturnCharges(input, liveRates);
+    appliedModifiers.push(...withReturn.modifiers);
+    hardBlocked.push(...withReturn.blocked);
+
     return {
       priorityScore,
       appliedModifiers,
@@ -394,6 +429,132 @@ export class RuleEngineService {
     };
   }
 
+  /**
+   * Import overweight — derived, never configured. Each overweight container
+   * line bills its excess tons at (its own base import freight on the booking's
+   * route) ÷ (2 × its weight limit): 20ft at 1000 USD with a 20 t limit →
+   * 25 USD per excess ton. Export keeps the configured OVERWEIGHT rate.
+   * Note: derives from the LIVE route rate even for frozen-rate contract
+   * bookings — the frozen snapshot has no route-scoped container price to
+   * divide.
+   */
+  private derivedImportOverweight(
+    input: BookingEvaluationInput,
+    weightResults: ContainerWeightResult[],
+    lineMaxVgmTons: Array<number | null>,
+    liveRates: Rate[],
+  ): AppliedCargoModifier[] {
+    const modifiers: AppliedCargoModifier[] = [];
+    if (!input.originYardId || !input.destinationYardId) return modifiers;
+
+    for (let i = 0; i < weightResults.length; i++) {
+      const wr = weightResults[i];
+      const excess = Number(wr?.overweightExcessTons ?? 0);
+      const maxVgm = Number(lineMaxVgmTons[i] ?? 0);
+      if (!wr?.isOverweight || !(excess > 0) || !(maxVgm > 0)) continue;
+
+      // Same precedence as base freight pricing: the rate scoped to this
+      // container type wins over the route's catch-all rate.
+      const onLeg = liveRates.filter(
+        (r) =>
+          r.rateType === 'CONTAINER_IMPORT' &&
+          r.currency === 'USD' &&
+          r.originYardId === input.originYardId &&
+          r.destinationYardId === input.destinationYardId,
+      );
+      const base =
+        onLeg.find((r) => r.containerTypeId === wr.containerTypeId) ??
+        onLeg.find((r) => !r.containerTypeId);
+      // No base rate → the base-freight line hard-blocks this booking anyway.
+      if (!base) continue;
+
+      const perTon = Number(base.rateValue) / (2 * maxVgm);
+      const amount = excess * perTon;
+      if (!(amount > 0)) continue;
+
+      modifiers.push({
+        rateId: base.id,
+        surchargeCode: 'OVERWEIGHT_PER_TON',
+        triggerValue: excess,
+        calculatedAmount: amount,
+        currency: base.currency,
+        unitPriceUsd: perTon,
+        billingUnit: 'PER_TON',
+      });
+    }
+    return modifiers;
+  }
+
+  /**
+   * Empty-container return — sold per direction + route + container type, like
+   * base freight. Each container line that opted in (returnQuantity, or every
+   * container when only the legacy booking-level flag is set) bills the
+   * route-matched WITH_RETURN rate for its own container type; a line with no
+   * matching rate hard-blocks the booking instead of shipping the service for
+   * free. Rates are import-only for now, so an export booking that asks for
+   * return blocks too.
+   * ponytail: bills the LIVE route rate, not a frozen contract snapshot — one
+   * RETURN_SURCHARGE snapshot code can't hold per-size route prices.
+   */
+  private withReturnCharges(
+    input: BookingEvaluationInput,
+    liveRates: Rate[],
+  ): { modifiers: AppliedCargoModifier[]; blocked: string[] } {
+    const modifiers: AppliedCargoModifier[] = [];
+    const blocked: string[] = [];
+    const bookingLevel = truthy(input.withReturn);
+    const wanted =
+      bookingLevel || input.containers.some((c) => Number(c.returnQuantity ?? 0) > 0);
+    if (!wanted) return { modifiers, blocked };
+
+    const onLeg = liveRates.filter(
+      (r) =>
+        r.trigger === 'WITH_RETURN' &&
+        r.currency === 'USD' &&
+        r.tradeDirection === input.tradeDirection &&
+        r.originYardId === input.originYardId &&
+        r.destinationYardId === input.destinationYardId,
+    );
+
+    for (const container of input.containers) {
+      const qty =
+        Number(container.returnQuantity ?? 0) > 0
+          ? Number(container.returnQuantity)
+          : bookingLevel
+            ? Number(container.quantity || 0)
+            : 0;
+      if (!(qty > 0)) continue;
+
+      const rate =
+        onLeg.find((r) => r.containerTypeId === container.containerTypeId) ??
+        onLeg.find((r) => !r.containerTypeId);
+      if (!rate) {
+        blocked.push(
+          'No empty-container return rate is configured for this container ' +
+            'type on this route (return is import-only) — remove the return ' +
+            'option or ask EDR to configure its rate for this origin → destination.',
+        );
+        continue;
+      }
+
+      const rateValue = Number(rate.rateValue);
+      const amount = rate.rateUnit === 'FLAT' ? rateValue : qty * rateValue;
+      if (!(amount > 0)) continue;
+      modifiers.push({
+        rateId: rate.id,
+        surchargeCode: this.surchargeCode(rate),
+        triggerValue: qty,
+        calculatedAmount: amount,
+        currency: rate.currency,
+        unitPriceUsd: rateValue,
+        billingUnit: rate.rateUnit,
+      });
+    }
+
+    // Same block deduplicated — several lines missing the rate is one problem.
+    return { modifiers, blocked: [...new Set(blocked)] };
+  }
+
   /**
    * Messages for container lines whose total weight exceeds the hard capacity
    * ceiling (weight_limit_rules.max_capacity_tons). Non-empty ⇒ the booking