feat: implement 20ft container weight-pairing validation

- Added ContainerValidationService to handle 20ft weight-pairing logic.
- Introduced validate20ftWeightPairing utility function to check weight differences.
- Updated BookingPricingService to include overweight line details and pairing errors in price response.
- Enhanced BookingTransitionService to reject submissions with unpairable 20ft containers.
- Created ShipmentValidation interface for pre-submit validation of container contracts.
- Integrated shipment validation into the contract booking process, providing warnings for overweight containers and hard blocks for pairing errors.
- Updated front-end components to display validation results and prevent submission when errors are present.

apps/edr-freight-web/portal/src/services/api.ts

@@ -24,6 +24,7 @@ import {
   ContractDocuments,
   GenerateContractPriceResponse,
   SubmitContractResponse,
+  ShipmentValidation,
 } from "./contracts.service";
 import type { BookingDocuments } from "@/pages/bookings/new-booking-form/schema";
 import {
@@ -462,6 +463,13 @@ export const api = {
       contractsService.createBookingUnderContract(id, dto),
     ),
 
+    validateShipment: endpoint<
+      { id: string; dto: Freight.CreateBookingUnderContractDto },
+      ShipmentValidation
+    >("contracts", "validateShipment", ({ id, dto }) =>
+      contractsService.validateShipment(id, dto),
+    ),
+
     getContractMilestones: endpoint<
       { id: string },
       Freight.IClearanceMilestone[]

apps/edr-freight-web/portal/src/services/contracts.service.ts

@@ -33,6 +33,25 @@ export interface SubmitContractResponse {
   message?: string;
 }
 
+/** A container line whose total VGM exceeds the weight-limit rule. */
+export interface OverweightLine {
+  containerTypeCode: string;
+  totalVgmTons: number;
+  maxAllowedTons: number;
+  excessTons: number;
+}
+
+/**
+ * Pre-submit validation for a shipment booking under a CONTAINER contract.
+ * `overweightLines` are WARNINGS only (an overweight surcharge applies — the
+ * customer may still submit); `pairingErrors` are HARD BLOCKS (20ft containers
+ * that cannot be balanced onto wagons) and must prevent booking.
+ */
+export interface ShipmentValidation {
+  overweightLines: OverweightLine[];
+  pairingErrors: string[];
+}
+
 export interface ContractListFilter {
   status?: string;
   statuses?: string;
@@ -285,6 +304,20 @@ export const contractsService = {
     return data.data.booking ?? data.data;
   },
 
+  /**
+   * Pre-submit validation of a shipment booking (same DTO as
+   * `createBookingUnderContract`). Returns overweight warnings and hard-block
+   * 20ft wagon-pairing errors so the customer can be warned/blocked before the
+   * booking is created.
+   */
+  validateShipment: async (
+    id: string,
+    dto: Freight.CreateBookingUnderContractDto,
+  ): Promise<ShipmentValidation> => {
+    const { data } = await client.post(C.VALIDATE_SHIPMENT(id), dto);
+    return data.data ?? data;
+  },
+
   // ── Milestones ──
   getContractMilestones: async (
     id: string,