implement update train details feature: add DTO, service method, and UI modal for editing train name and run numbers

apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts

@@ -1,4 +1,4 @@
-import { Injectable } from '@nestjs/common';
+import { Injectable, UnprocessableEntityException } from '@nestjs/common';
 
 import { RatesService } from '../rule-engine/services/rates.service';
 import { ContainerTypesService } from '../rule-engine/services/container-types.service';
@@ -15,6 +15,11 @@ export interface ContractUnitRateLineItem {
   containerSize?: string | null;
   conditionalOn?: string | null;
   cargoTypeCode?: string | null;
+  /**
+   * Customs clearance service fee — billed separately in advance (before the
+   * clearance document step), never part of shipment booking totals.
+   */
+  isClearance?: boolean;
 }
 
 /** The contract `pricing_breakdown` shape (doc §9.1). */
@@ -184,6 +189,31 @@ export class ContractPricingService {
       }
     }
 
+    // Customs clearance service fee (Path B) — a FLAT prepaid fee, shown on the
+    // contract and billed via its own clearance invoice: after counter-sign for
+    // ONE_TIME, per shipment request for GENERAL. Excluded from booking totals.
+    // A customs contract may not proceed without a configured live rate.
+    if (contract.customsClearingEnabled) {
+      const clearance = liveRates.find(
+        (r) => r.rateType === 'CUSTOMS_CLEARANCE' && r.currency === 'USD',
+      );
+      if (!clearance || Number(clearance.rateValue) <= 0) {
+        throw new UnprocessableEntityException(
+          'No customs clearance service fee is configured. Ask the rates team to set a live CUSTOMS_CLEARANCE rate before submitting customs contracts.',
+        );
+      }
+      lineItems.push({
+        code: 'CUSTOMS_CLEARANCE',
+        label:
+          contract.contractKind === 'GENERAL'
+            ? 'Customs clearance service fee (per shipment request, prepaid)'
+            : 'Customs clearance service fee (prepaid)',
+        unit: toContractUnit(clearance.rateUnit),
+        unitPrice: convert(Number(clearance.rateValue)),
+        isClearance: true,
+      });
+    }
+
     return {
       displayMode: 'UNIT_RATES',
       currency,
@@ -229,6 +259,7 @@ export class ContractPricingService {
         containerSize: line.containerSize ?? null,
         isSurcharge: !!line.conditionalOn,
         conditionalOn: line.conditionalOn ?? null,
+        isClearance: !!line.isClearance,
       });
     }
   }