Merge branch 'dev' of github.com:Tria-plc/edr-platform into freight/feature/first_mile_invoice

apps/edr-freight-api/src/modules/bookings/booking-list-tabs.config.ts

@@ -28,7 +28,7 @@ export const BOOKING_LIST_TABS: ReadonlyArray<{
   { key: 'payment', statuses: ['FULLY_EXECUTED'] },
   {
     key: 'operations',
-    statuses: ['IN_TRANSIT', 'PAID'],
+    statuses: ['IN_TRANSIT', 'ARRIVED', 'PAID'],
   },
   { key: 'completed', statuses: ['COMPLETED'] },
   { key: 'closed', statuses: ['REJECTED', 'CANCELLED'] },

apps/edr-freight-api/src/modules/bookings/booking-next-step.util.ts

@@ -102,6 +102,7 @@ export function computeNextStep(
         description: 'Mark shipment as in transit',
       };
     case 'IN_TRANSIT':
+    case 'ARRIVED':
       return {
         action: 'COMPLETE',
         description: 'Mark shipment complete',

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

@@ -485,7 +485,7 @@ export class BookingTransitionService {
 
   async complete(bookingId: string): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
-    assertBookingStatus(booking, ["IN_TRANSIT"]);
+    assertBookingStatus(booking, ["IN_TRANSIT", "ARRIVED"]);
 
     const updated = await this.bookingsRepository.update(bookingId, {
       status: "COMPLETED",

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

@@ -435,6 +435,21 @@ export class BookingsController {
     return this.customerTruckService.addTruck(id, dto);
   }
 
+  @Patch(':id/customer-trucks/:assignmentId')
+  @ApiOperation({ summary: 'Edit a not-yet-arrived customer truck (plate/driver/type + containers)' })
+  async updateCustomerTruck(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Param('assignmentId', ParseUUIDPipe) assignmentId: string,
+    @Body() dto: AddCustomerTruckDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    const booking = await this.bookingsService.findById(id);
+    if (!hasFreightPermission(user, FREIGHT_PERMS.bookings.view)) {
+      await this.bookingsService.assertCustomerCanAccessBooking(user?.id, booking);
+    }
+    return this.customerTruckService.updateTruck(id, assignmentId, dto);
+  }
+
   @Delete(':id/customer-trucks/:assignmentId')
   @ApiOperation({ summary: 'Remove a not-yet-arrived customer truck from a booking' })
   async removeCustomerTruck(

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

@@ -116,6 +116,7 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
     BookingPricingService,
     BookingInvoiceService,
     BookingLifecycleNotifierService,
+    ConsolidationService,
     CustomerTruckService,
     ContainerReceiptService,
   ],

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

@@ -272,26 +272,51 @@ export class BookingsRepository extends BaseRepository<Booking> {
   }
 
   /**
-   * Pair two bookings for consolidation. Both return to SUBMITTED so staff can
-   * accept them into the approval chain; the link itself (consolidationPartnerId)
-   * marks them as consolidated in the UI.
+   * Pair two bookings for consolidation. Each returns to its own resume status —
+   * SUBMITTED for a direct customer booking (so staff can accept it into the
+   * approval chain) or the stored consolidationResumeStatus for a contract
+   * drawdown (OPERATION_REQUEST_PENDING / AWAITING_DOCUMENTS). The link itself
+   * (consolidationPartnerId) marks them as consolidated in the UI. The resume
+   * status is cleared once used, so a later un-pair re-parks cleanly.
    */
   async pairConsolidation(bookingId: string, partnerId: string): Promise<void> {
+    const [booking, partner] = await Promise.all([
+      this.repository.findOne({
+        where: { id: bookingId },
+        select: { id: true, consolidationResumeStatus: true },
+      }),
+      this.repository.findOne({
+        where: { id: partnerId },
+        select: { id: true, consolidationResumeStatus: true },
+      }),
+    ]);
+
     await this.repository.update(bookingId, {
       consolidationPartnerId: partnerId,
-      status: 'SUBMITTED',
+      status: booking?.consolidationResumeStatus ?? 'SUBMITTED',
+      consolidationResumeStatus: null,
     } as never);
     await this.repository.update(partnerId, {
       consolidationPartnerId: bookingId,
-      status: 'SUBMITTED',
+      status: partner?.consolidationResumeStatus ?? 'SUBMITTED',
+      consolidationResumeStatus: null,
     } as never);
   }
 
-  /** Park a booking that needs consolidation but has no partner yet. */
-  async parkForConsolidation(bookingId: string): Promise<void> {
+  /**
+   * Park a booking that needs consolidation but has no partner yet. The optional
+   * resumeStatus is where the booking returns once it pairs — pass it for a
+   * contract drawdown so pairing resumes the contract-booking flow rather than
+   * the direct-booking SUBMITTED default.
+   */
+  async parkForConsolidation(
+    bookingId: string,
+    resumeStatus?: string | null,
+  ): Promise<void> {
     await this.repository.update(bookingId, {
       consolidationPartnerId: null,
       status: 'PENDING_CONSOLIDATION',
+      consolidationResumeStatus: resumeStatus ?? null,
     } as never);
   }
 
@@ -1019,6 +1044,81 @@ export class BookingsRepository extends BaseRepository<Booking> {
       .getMany();
   }
 
+  /**
+   * Corridor day pool: ready, not-yet-allocated bookings for one EAT day whose
+   * origin AND destination both lie on the day's corridor stop set — covers
+   * full-route bookings and sub-corridor bookings (Dire→Djibouti on an
+   * Addis→…→Djibouti train). The caller still verifies stop ORDER per train
+   * via the corridor budget; this query only narrows the pool. Same status
+   * rules and ordering as {@link findBatchPool}.
+   */
+  findBatchPoolByCorridorDay(
+    corridorYardIds: string[],
+    day: string,
+  ): Promise<Booking[]> {
+    if (corridorYardIds.length === 0) return Promise.resolve([]);
+    return this.repository
+      .createQueryBuilder('booking')
+      .leftJoinAndSelect('booking.company', 'company')
+      .leftJoinAndSelect('booking.bookingContainers', 'bookingContainer')
+      .leftJoin(TrainScheduleBooking, 'sb', 'sb.booking_id = booking.id')
+      .where('booking.origin_yard_id IN (:...corridorYardIds)', { corridorYardIds })
+      .andWhere('booking.destination_yard_id IN (:...corridorYardIds)', {
+        corridorYardIds,
+      })
+      .andWhere(
+        `DATE(booking.scheduled_date AT TIME ZONE 'Africa/Addis_Ababa') = :day`,
+        { day },
+      )
+      .andWhere('sb.id IS NULL')
+      .andWhere(
+        `((booking.is_government = false AND booking.status = 'FULLY_EXECUTED')
+          OR (booking.is_government = true AND booking.status IN ('APPROVED','PAID')))`,
+      )
+      .orderBy('booking.is_government', 'DESC')
+      .addOrderBy('booking.priority_score', 'DESC')
+      .addOrderBy('booking.fully_executed_at', 'ASC')
+      .addOrderBy('booking.created_at', 'ASC')
+      .getMany();
+  }
+
+  /**
+   * Commercial bookings on the day's corridor whose operation request was NOT
+   * accepted by staff (still pending / changes / price-confirm) and are not yet
+   * linked to a train. These never reached FULLY_EXECUTED, so they never enter the
+   * batch pool; the window's doc-review end sweeps them to EXPIRED. Government
+   * bookings are excluded (they don't go through the customer window).
+   */
+  findUnacceptedForRouteDay(
+    corridorYardIds: string[],
+    day: string,
+  ): Promise<Booking[]> {
+    if (corridorYardIds.length === 0) return Promise.resolve([]);
+    return this.repository
+      .createQueryBuilder('booking')
+      .leftJoinAndSelect('booking.company', 'company')
+      .leftJoin(TrainScheduleBooking, 'sb', 'sb.booking_id = booking.id')
+      .where('booking.origin_yard_id IN (:...corridorYardIds)', { corridorYardIds })
+      .andWhere('booking.destination_yard_id IN (:...corridorYardIds)', {
+        corridorYardIds,
+      })
+      .andWhere(
+        `DATE(booking.scheduled_date AT TIME ZONE 'Africa/Addis_Ababa') = :day`,
+        { day },
+      )
+      .andWhere('sb.id IS NULL')
+      .andWhere('booking.is_government = false')
+      .andWhere(
+        `booking.status IN (
+          'OPERATION_REQUESTED',
+          'OPERATION_REQUEST_PENDING',
+          'OPERATION_CHANGES_REQUESTED',
+          'OPERATION_PRICE_PENDING_CONFIRM'
+        )`,
+      )
+      .getMany();
+  }
+
   /** Every booking that targeted a schedule (any status) — for the batch monitoring board. */
   findAllBySchedule(scheduleId: string): Promise<Booking[]> {
     return this.repository

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

@@ -24,6 +24,7 @@ import {
   RuleEngineService,
 } from '../rule-engine/rule-engine.service';
 import { InjectDataSource } from '@nestjs/typeorm';
+import { EventEmitter2 } from '@nestjs/event-emitter';
 import { DataSource, In } from 'typeorm';
 
 import { deriveTradeDirection } from '../../common/derive-trade-direction.util';
@@ -99,6 +100,7 @@ export class BookingsService {
     private readonly consolidationService: ConsolidationService,
     private readonly vehiclesService: VehiclesService,
     private readonly contractPdfService: ContractPdfService,
+    private readonly events: EventEmitter2,
   ) {}
 
   async assignCustomerTruck(
@@ -493,6 +495,14 @@ export class BookingsService {
       messages.push(
         this.consolidationService.describePaired(partner.reference, slots),
       );
+      // Let deferred owners (e.g. contract drawdowns whose invoice/milestones
+      // were held while the booking waited) finalize now that a whole wagon
+      // exists. Fire-and-forget: a listener failure must not undo the pairing.
+      this.events
+        .emitAsync('booking.consolidation.paired', {
+          bookingIds: [booking.id, partner.id],
+        })
+        .catch(() => undefined);
       return { booking: paired, messages };
     }
 
@@ -605,10 +615,15 @@ export class BookingsService {
       if (schedule.bookingWindowStatus !== 'OPEN') {
         throw new BadRequestException('Selected schedule is no longer accepting bookings');
       }
-      if (
-        schedule.originStationId !== dto.originYardId ||
-        schedule.destinationStationId !== dto.destinationYardId
-      ) {
+      // Corridor-aware: the booking's leg must lie on the schedule's route in
+      // stop order — sub-corridor pins (Dire→Djibouti on an Addis→Djibouti
+      // train) are valid.
+      const stops = await this.trainSchedulingService.stopYardsForSchedule(
+        schedule,
+      );
+      const fromIdx = stops.indexOf(dto.originYardId);
+      const toIdx = stops.indexOf(dto.destinationYardId);
+      if (fromIdx < 0 || toIdx < 0 || fromIdx >= toIdx) {
         throw new BadRequestException('Selected schedule is not on the booking route');
       }
     } else if (dto.scheduledDate) {
@@ -1278,6 +1293,14 @@ export class BookingsService {
   ): Promise<Freight.IBookingTracking> {
     const booking = await this.findById(bookingId);
 
+    const journey = {
+      bookingStatus: booking.status ?? null,
+      bookingOriginYardId: booking.originYardId ?? null,
+      bookingDestinationYardId: booking.destinationYardId ?? null,
+      loadedAt: booking.loadedAt ? new Date(booking.loadedAt).toISOString() : null,
+      arrivedAt: booking.arrivedAt ? new Date(booking.arrivedAt).toISOString() : null,
+    };
+
     const empty: Freight.IBookingTracking = {
       bookingId: booking.id,
       bookingReference: booking.reference,
@@ -1295,6 +1318,7 @@ export class BookingsService {
       actualArrivalAt: null,
       scheduledDepartureAt: null,
       scheduledArrivalAt: null,
+      ...journey,
     };
 
     if (!booking.trainScheduleId) {
@@ -1331,6 +1355,7 @@ export class BookingsService {
       actualArrivalAt: track.actualArrivalAt,
       scheduledDepartureAt: track.scheduledDepartureAt,
       scheduledArrivalAt: track.scheduledArrivalAt,
+      ...journey,
     };
   }
 
@@ -1399,6 +1424,20 @@ export class BookingsService {
         schedule?.status ?? null;
     }
 
+    // A generated-but-unsigned SELF_HAUL handover means the customer must approve
+    // delivery from the portal (booking-based, one per booking). EDR last-mile
+    // handovers are per delivering truck and signed by the receiver at the door,
+    // so they never surface the portal "Approve delivery" action.
+    const [pendingHandover] = await this.dataSource.query(
+      `SELECT 1 FROM freight.booking_handovers
+        WHERE booking_id = $1 AND signed_at IS NULL AND deleted_at IS NULL
+          AND mile_type = 'SELF_HAUL'
+        LIMIT 1`,
+      [id],
+    );
+    (booking as Booking & { handoverAwaitingSignature?: boolean }).handoverAwaitingSignature =
+      Boolean(pendingHandover);
+
     return booking;
   }
 
@@ -1607,7 +1646,7 @@ export class BookingsService {
     if (!booking.isGovernment) {
       throw new BadRequestException('Only government bookings can be expedited');
     }
-    const blocked = ['PAID', 'IN_TRANSIT', 'COMPLETED', 'CANCELLED', 'REJECTED'];
+    const blocked = ['PAID', 'IN_TRANSIT', 'ARRIVED', 'COMPLETED', 'CANCELLED', 'REJECTED'];
     if (blocked.includes(booking.status)) {
       throw new BadRequestException(`Cannot expedite booking in status ${booking.status}`);
     }

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

@@ -42,21 +42,30 @@ export class CustomerTruckService {
     const booking = await this.loadBookingGuard(bookingId);
     this.assertSelfHaulPaid(booking);
 
-    const isExport = booking.tradeDirection === 'EXPORT';
     const requested = (dto.containerNumbers ?? []).map((n) => n.trim().toUpperCase());
 
-    // EXPORT: the truck delivers 1–2 known containers. IMPORT: containers are
-    // not pre-specified — they are registered + weighed when the truck leaves.
-    if (isExport) {
-      if (requested.length < 1 || requested.length > 2) {
-        throw new BadRequestException('An export truck must carry 1 or 2 of the booking containers');
-      }
-    } else if (requested.length > 2) {
+    // Both import and export specify the containers each truck carries. Capacity
+    // is size-based: a 40ft container fills the truck (max 1); two 20ft containers
+    // fit (max 2), no size mixing. #trucks <= #containers follows naturally since
+    // each container is assigned to exactly one truck.
+    if (requested.length < 1) {
+      throw new BadRequestException('Select at least one container for this truck');
+    }
+    if (requested.length > 2) {
       throw new BadRequestException('A truck carries at most 2 containers');
     }
 
     if (requested.length) {
       const bookingNumbers = await this.bookingContainerNumbers(bookingId);
+      // Never assign more trucks than the booking has containers.
+      const existingTrucks = await this.dataSource
+        .getRepository(CustomerTruckAssignment)
+        .count({ where: { bookingId } });
+      if (existingTrucks + 1 > bookingNumbers.length) {
+        throw new BadRequestException(
+          `Cannot assign more trucks than containers — this booking has ${bookingNumbers.length} container(s) and ${existingTrucks} truck(s) already assigned.`,
+        );
+      }
       for (const n of requested) {
         if (!bookingNumbers.includes(n)) {
           throw new BadRequestException(`Container ${n} is not one of this booking's containers`);
@@ -68,6 +77,13 @@ export class CustomerTruckService {
           throw new ConflictException(`Container ${n} is already loaded onto another truck`);
         }
       }
+      // Size cap: a 40ft container fills the truck.
+      const sizes = await this.containerSizes(bookingId, requested);
+      if (sizes.some((s) => s.includes('40')) && requested.length > 1) {
+        throw new BadRequestException(
+          'A 40ft container fills the truck — assign only 1 container to this truck',
+        );
+      }
     }
 
     await this.dataSource.transaction(async (manager) => {
@@ -133,6 +149,76 @@ export class CustomerTruckService {
     return this.listTrucks(bookingId);
   }
 
+  /**
+   * Edit a truck assignment — plate/driver/type and the containers it carries.
+   * Allowed only until the truck has arrived (same guard as removal). Container
+   * rules mirror {@link addTruck}: 1–2 of the booking's containers, none already
+   * on another truck, and a 40ft container fills the truck (max 1).
+   */
+  async updateTruck(
+    bookingId: string,
+    assignmentId: string,
+    dto: AddCustomerTruckDto,
+  ): Promise<CustomerTruckAssignment[]> {
+    const booking = await this.loadBookingGuard(bookingId);
+    this.assertSelfHaulPaid(booking);
+
+    const assignment = await this.assignments.findByIdWithContainers(assignmentId);
+    if (!assignment || assignment.bookingId !== bookingId) {
+      throw new NotFoundException('Truck assignment not found for this booking');
+    }
+    if (assignment.arrivedAt) {
+      throw new ConflictException('Cannot edit a truck that has already arrived');
+    }
+
+    const requested = (dto.containerNumbers ?? []).map((n) => n.trim().toUpperCase());
+    if (requested.length < 1) {
+      throw new BadRequestException('Select at least one container for this truck');
+    }
+    if (requested.length > 2) {
+      throw new BadRequestException('A truck carries at most 2 containers');
+    }
+    const bookingNumbers = await this.bookingContainerNumbers(bookingId);
+    for (const n of requested) {
+      if (!bookingNumbers.includes(n)) {
+        throw new BadRequestException(`Container ${n} is not one of this booking's containers`);
+      }
+    }
+    // Exclude THIS truck's own containers so re-saving the same set is allowed.
+    const assignedElsewhere = await this.assignedContainerNumbersExcept(bookingId, assignmentId);
+    for (const n of requested) {
+      if (assignedElsewhere.includes(n)) {
+        throw new ConflictException(`Container ${n} is already loaded onto another truck`);
+      }
+    }
+    const sizes = await this.containerSizes(bookingId, requested);
+    if (sizes.some((s) => s.includes('40')) && requested.length > 1) {
+      throw new BadRequestException(
+        'A 40ft container fills the truck — assign only 1 container to this truck',
+      );
+    }
+
+    await this.dataSource.transaction(async (manager) => {
+      await manager.getRepository(CustomerTruckAssignment).update(assignmentId, {
+        plateNumber: dto.truckPlateNumber.trim().toUpperCase(),
+        driverName: dto.driverName.trim(),
+        truckType: dto.truckType.trim(),
+      });
+      await manager.getRepository(CustomerTruckContainer).softDelete({ assignmentId });
+      await manager.getRepository(CustomerTruckContainer).save(
+        requested.map((containerNumber) =>
+          manager.getRepository(CustomerTruckContainer).create({
+            assignmentId,
+            bookingId,
+            containerNumber,
+          }),
+        ),
+      );
+    });
+
+    return this.listTrucks(bookingId);
+  }
+
   /**
    * Register an IMPORT self-haul truck leaving the port: the containers it
    * actually loaded (replacing any provisional list) and its weighed gross.
@@ -226,6 +312,13 @@ export class CustomerTruckService {
     if (assignment.departedAt) {
       throw new ConflictException('This truck has already left — its load is locked');
     }
+    // Containers can only be loaded after the truck has physically arrived at the
+    // warehouse (arrival weighing recorded). Assignment alone is just planning.
+    if (!assignment.arrivedAt) {
+      throw new BadRequestException(
+        'Record the truck arrival before loading — containers can only be loaded onto an arrived truck',
+      );
+    }
 
     const requested = (dto.containerNumbers ?? []).map((n) => n.trim().toUpperCase());
     if (!requested.length) {
@@ -244,30 +337,35 @@ export class CustomerTruckService {
       }
     }
 
-    const grossKg = await this.vgmKgForContainers(bookingId, requested);
+    const grossTons = await this.vgmTonsForContainers(bookingId, requested);
     await this.dataSource.transaction(async (manager) => {
       await manager.getRepository(CustomerTruckContainer).softDelete({ assignmentId });
+      // Operator loading the truck: stamp loaded_at so these containers move to
+      // the LOADED stage (customer assignment alone leaves loaded_at null).
+      const loadedAt = new Date();
       await manager.getRepository(CustomerTruckContainer).save(
         requested.map((containerNumber) =>
           manager.getRepository(CustomerTruckContainer).create({
             assignmentId,
             bookingId,
             containerNumber,
+            loadedAt,
           }),
         ),
       );
-      // Provisional gross from the loaded containers' VGM — overridden by the
-      // weighed gross on departure.
+      // Provisional gross (tonnes) from the loaded containers' VGM — overridden
+      // by the weighed gross on departure. (Column is *_kg but holds tonnes.)
       await manager.getRepository(CustomerTruckAssignment).update(assignmentId, {
-        grossWeightKg: grossKg,
+        grossWeightKg: grossTons,
       });
     });
     return this.listTrucks(bookingId);
   }
 
-  private async vgmKgForContainers(bookingId: string, numbers: string[]): Promise<number> {
-    const [row]: Array<{ kg: string }> = await this.dataSource.query(
-      `SELECT COALESCE(SUM(bcu.vgm_tons), 0) * 1000 AS kg
+  /** Summed VGM (tonnes) of the given containers — provisional truck gross. */
+  private async vgmTonsForContainers(bookingId: string, numbers: string[]): Promise<number> {
+    const [row]: Array<{ tons: string }> = await this.dataSource.query(
+      `SELECT COALESCE(SUM(bcu.vgm_tons), 0) AS tons
          FROM freight.booking_container_units bcu
          JOIN freight.booking_container bc
            ON bc.id = bcu.booking_container_id AND bc.deleted_at IS NULL
@@ -276,7 +374,7 @@ export class CustomerTruckService {
           AND bcu.deleted_at IS NULL`,
       [bookingId, numbers],
     );
-    return Number(row?.kg ?? 0);
+    return Number(row?.tons ?? 0);
   }
 
   /**
@@ -399,4 +497,20 @@ export class CustomerTruckService {
     );
     return rows.map((r) => r.containerNumber.trim().toUpperCase());
   }
+
+  /** Contract container sizes (e.g. "20ft" / "40ft") for the given container numbers. */
+  private async containerSizes(bookingId: string, numbers: string[]): Promise<string[]> {
+    if (!numbers.length) return [];
+    const rows: Array<{ size: string | null }> = await this.dataSource.query(
+      `SELECT bc.container_size AS "size"
+         FROM freight.booking_container_units bcu
+         JOIN freight.booking_container bc
+           ON bc.id = bcu.booking_container_id AND bc.deleted_at IS NULL
+        WHERE bc.booking_id = $1
+          AND UPPER(bcu.container_number) = ANY($2)
+          AND bcu.deleted_at IS NULL`,
+      [bookingId, numbers],
+    );
+    return rows.map((r) => (r.size ?? '').trim());
+  }
 }

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

@@ -37,6 +37,7 @@ export const BOOKING_STATUSES = [
   'PAYMENT_VERIFICATION_IN_PROGRESS',
   'PAID',
   'IN_TRANSIT',
+  'ARRIVED',
   'COMPLETED',
   'REJECTED',
   'CANCELLED',
@@ -430,6 +431,14 @@ export class Booking extends BaseEntity {
   @JoinColumn({ name: 'consolidation_partner_id' })
   consolidationPartner?: Booking | null;
 
+  // Status a booking parked in PENDING_CONSOLIDATION returns to once it pairs.
+  // Null for direct customer bookings (they resume to SUBMITTED, the historical
+  // default); contract-drawdown bookings set it to the status createUnderContract
+  // would otherwise have used (OPERATION_REQUEST_PENDING / AWAITING_DOCUMENTS), so
+  // pairing resumes them into the right flow instead of the direct-booking one.
+  @Column({ name: 'consolidation_resume_status', type: 'varchar', length: 40, nullable: true })
+  consolidationResumeStatus?: string | null;
+
   @Column({ name: 'wagons_required', type: 'numeric', precision: 6, scale: 2, nullable: true })
   wagonsRequired?: number | null;
 
@@ -458,6 +467,24 @@ export class Booking extends BaseEntity {
   @Column({ name: 'train_schedule_id', type: 'uuid', nullable: true })
   trainScheduleId?: string | null;
 
+  // ── Per-booking journey (segment corridor bookings) ────────────────────────
+  // A booking rides only its own origin→destination leg of the train's route,
+  // so dispatch/arrival are per-booking facts, not train facts. Clearance gates
+  // read arrivedAt (booking arrival), never the schedule's actualArrivalAt.
+  /** Operator confirmed cargo loaded at the booking's origin yard (per-booking dispatch). */
+  @Column({ name: 'loaded_at', type: 'timestamptz', nullable: true })
+  loadedAt?: Date | null;
+
+  @Column({ name: 'loaded_by_user_id', type: 'uuid', nullable: true })
+  loadedByUserId?: string | null;
+
+  /** Operator confirmed cargo unloaded at the booking's destination yard (per-booking arrival). */
+  @Column({ name: 'arrived_at', type: 'timestamptz', nullable: true })
+  arrivedAt?: Date | null;
+
+  @Column({ name: 'arrived_by_user_id', type: 'uuid', nullable: true })
+  arrivedByUserId?: string | null;
+
   /** End of the pay window once the booking is SELECTED_FOR_BATCH. */
   @Column({ name: 'payment_deadline', type: 'timestamptz', nullable: true })
   paymentDeadline?: Date | null;

apps/edr-freight-api/src/modules/bookings/entities/customer-truck-container.entity.ts

@@ -23,4 +23,12 @@ export class CustomerTruckContainer extends BaseEntity {
 
   @Column({ name: 'container_number', type: 'varchar', length: 64 })
   containerNumber!: string;
+
+  /**
+   * When the container was actually loaded onto the truck by the operator.
+   * Null = customer-assigned (planned) but not yet loaded. Stage LOADED requires
+   * this to be set, so customer assignment alone does not mark a container loaded.
+   */
+  @Column({ name: 'loaded_at', type: 'timestamptz', nullable: true })
+  loadedAt?: Date | null;
 }