feat(bookings): add estimated shipment date handling and validation for binding shipment day

apps/edr-freight-api/src/migrations/1820000000012-AddEstimatedShipmentDate.ts

@@ -0,0 +1,26 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * The booking wizard now captures a NON-BINDING estimated shipment date instead
+ * of the binding scheduledDate. The binding scheduledDate (validated against
+ * open train departures) is set later, at the operation-request step.
+ */
+export class AddEstimatedShipmentDate1820000000012
+  implements MigrationInterface
+{
+  name = 'AddEstimatedShipmentDate1820000000012';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        ADD COLUMN IF NOT EXISTS estimated_shipment_date timestamptz NULL;
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        DROP COLUMN IF EXISTS estimated_shipment_date;
+    `);
+  }
+}

apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts

@@ -795,6 +795,20 @@ export class BookingTransitionService {
       throw new BadRequestException('A valid schedule date is required');
     }
 
+    // The binding shipment day must have at least one OPEN departure on the
+    // route — only schedule-backed days are selectable. The batch engine
+    // assigns the specific train within that (route, day) pool later.
+    const hasDeparture = await this.bookingsService.hasOpenDepartureOnDay(
+      booking.originYardId,
+      booking.destinationYardId,
+      eatDay(date),
+    );
+    if (!hasDeparture) {
+      throw new BadRequestException(
+        'No departures available on the selected day for this route',
+      );
+    }
+
     await this.bookingsRepository.update(bookingId, {
       status: 'OPERATION_REQUEST_PENDING',
       scheduledDate: date,

apps/edr-freight-api/src/modules/bookings/bookings.service.ts

@@ -317,12 +317,14 @@ export class BookingsService {
       ) {
         throw new BadRequestException('Selected schedule is not on the booking route');
       }
-    } else if (!isGeneralContract) {
-      // Day-level pool: the customer picked a DAY — require that the route has at
-      // least one OPEN departure on that EAT day. The batch engine assigns the
-      // train later. General contracts skip this — they have no shipment date at
-      // creation; each drawdown order validates its own day.
-      const day = eatDay(new Date(dto.scheduledDate!));
+    } else if (dto.scheduledDate) {
+      // A real (binding) scheduledDate was supplied (e.g. staff pinning a day
+      // directly). Require that the route has at least one OPEN departure on
+      // that EAT day. The booking wizard does NOT send scheduledDate at creation
+      // — it captures a non-binding estimatedShipmentDate instead, and the
+      // binding day is chosen later at the operation-request step. General
+      // contracts also skip this (each drawdown order validates its own day).
+      const day = eatDay(new Date(dto.scheduledDate));
       const hasDeparture =
         await this.trainSchedulingService.existsOpenScheduleOnRouteDay(
           dto.originYardId,
@@ -428,6 +430,9 @@ export class BookingsService {
       financialTerms: dto.financialTerms,
       bookingType: isGeneralContract ? 'GENERAL_CONTRACT' : 'ONE_TIME',
       scheduledDate: dto.scheduledDate ? new Date(dto.scheduledDate) : null,
+      estimatedShipmentDate: dto.estimatedShipmentDate
+        ? new Date(dto.estimatedShipmentDate)
+        : null,
       startDate: dto.startDate ? new Date(dto.startDate) : undefined,
       endDate: dto.endDate ? new Date(dto.endDate) : undefined,
       status: 'DRAFT',
@@ -621,6 +626,8 @@ export class BookingsService {
         );
     }
     if (dto.scheduledDate) updates.scheduledDate = new Date(dto.scheduledDate);
+    if (dto.estimatedShipmentDate)
+      updates.estimatedShipmentDate = new Date(dto.estimatedShipmentDate);
     if (dto.startDate) updates.startDate = new Date(dto.startDate);
     if (dto.endDate) updates.endDate = new Date(dto.endDate);
     delete updates.containers;
@@ -696,6 +703,23 @@ export class BookingsService {
   }
 
   /** Return a paginated list of bookings matching the filter. */
+  /**
+   * Whether a route has at least one OPEN train departure on the given EAT day.
+   * Used to validate the binding shipment day chosen at the operation-request
+   * step (only days with a schedule are selectable).
+   */
+  async hasOpenDepartureOnDay(
+    originYardId: string,
+    destinationYardId: string,
+    day: string,
+  ): Promise<boolean> {
+    return this.trainSchedulingService.existsOpenScheduleOnRouteDay(
+      originYardId,
+      destinationYardId,
+      day,
+    );
+  }
+
   async findAll(
     filter: FilterBookingDto,
     forceCompanyId?: string,

apps/edr-freight-api/src/modules/bookings/dto/create-booking.dto.ts

@@ -155,14 +155,24 @@ export class CreateBookingDto {
   bookingType?: string;
 
   /**
-   * The day the customer wants to ship (the pool day key). Required for one-time
-   * bookings; omitted for general contracts, which pick the date per order.
+   * The BINDING shipment day (the pool day key), validated against open train
+   * departures. Set later at the operation-request step — NOT at booking
+   * creation. Optional here; staff may still pin it directly.
    */
   @ApiPropertyOptional({ example: '2026-06-15T00:00:00.000Z' })
-  @ValidateIf((o) => o.bookingType !== 'GENERAL_CONTRACT')
+  @IsOptional()
   @IsDateString()
   scheduledDate?: string;
 
+  /**
+   * Non-binding shipment-date estimate captured in the booking wizard. Purely
+   * informational — NOT validated against train departures.
+   */
+  @ApiPropertyOptional({ example: '2026-06-15T00:00:00.000Z' })
+  @IsOptional()
+  @IsDateString()
+  estimatedShipmentDate?: string;
+
   @ApiProperty({ enum: CONTRACT_TYPES })
   @IsIn([...CONTRACT_TYPES])
   contractType!: string;

apps/edr-freight-api/src/modules/bookings/entities/booking.entity.ts

@@ -155,10 +155,23 @@ export class Booking extends BaseEntity {
   /**
    * Nullable: general contracts have no shipment date at creation — the date is
    * chosen per drawdown order. One-time bookings always set this (the pool day key).
+   *
+   * NOTE: this is the BINDING shipment day, validated against actual open train
+   * departures. It is set later, when the customer requests the operation — NOT
+   * at booking creation. See estimatedShipmentDate for the non-binding estimate
+   * captured in the booking wizard.
    */
   @Column({ name: 'scheduled_date', type: 'timestamptz', nullable: true })
   scheduledDate?: Date | null;
 
+  /**
+   * Non-binding shipment-date estimate captured in the booking wizard. Purely
+   * informational — NOT validated against train departures. The binding
+   * scheduledDate is chosen later at the operation-request step.
+   */
+  @Column({ name: 'estimated_shipment_date', type: 'timestamptz', nullable: true })
+  estimatedShipmentDate?: Date | null;
+
   /**
    * General contracts only: when the ordering window closes, computed from the
    * global CONTRACT_PERIOD_MONTHS setting at activation. Null for one-time