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/entities/contract-rate-snapshot.entity.ts

@@ -44,4 +44,11 @@ export class ContractRateSnapshot extends BaseEntity {
   /** is_hazardous | is_reefer when this is a conditional surcharge. */
   @Column({ name: 'conditional_on', type: 'varchar', length: 32, nullable: true })
   conditionalOn?: string | null;
+
+  /**
+   * Customs clearance service fee line — billed up front via a clearance
+   * invoice, excluded from shipment booking totals.
+   */
+  @Column({ name: 'is_clearance', type: 'boolean', default: false })
+  isClearance!: boolean;
 }

apps/edr-freight-api/src/modules/contracts/entities/contract.entity.ts

@@ -25,6 +25,7 @@ export const CONTRACT_STATUSES = [
   'SIGNED_CUSTOMER',
   'FULLY_EXECUTED',
   'CONTRACT_ACTIVE',
+  'AWAITING_CLEARANCE_PAYMENT', // Path B — clearance fee invoiced, unpaid
   'AWAITING_CLEARANCE_DOCUMENTS',
   'CLEARANCE_UNDER_REVIEW',
   'CLEARANCE_READY_FOR_BOOKING',
@@ -84,6 +85,7 @@ export type ContractKindValue = (typeof CONTRACT_KINDS)[number];
 
 export const CONTRACT_CLEARANCE_STATUSES = [
   'NOT_APPLICABLE',
+  'AWAITING_PAYMENT', // Path B — clearance service fee must be paid first
   'AWAITING_DOCUMENTS',
   'DOCUMENTS_UNDER_REVIEW',
   'CLEARANCE_READY_FOR_BOOKING', // Path B — GL may create the booking
@@ -215,6 +217,10 @@ export class Contract extends BaseEntity {
   @Column({ name: 'clearance_cycle_number', type: 'int', default: 0 })
   clearanceCycleNumber!: number;
 
+  /** When the prepaid customs clearance service fee settled (Path B ONE_TIME). */
+  @Column({ name: 'clearance_fee_paid_at', type: 'timestamptz', nullable: true })
+  clearanceFeePaidAt?: Date | null;
+
   @Column({ name: 'pricing_breakdown', type: 'jsonb', nullable: true })
   pricingBreakdown?: Record<string, unknown> | null;