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/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,