feat: add shipment tracking feature with live updates

- Implemented tracking functionality for bookings, allowing users to track their shipments in real-time.
- Added new API endpoints for fetching tracking data.
- Created a ShipmentTrackingModal component to display tracking information, including current status, checkpoints, and estimated arrival times.
- Enhanced the booking detail view to include tracking options for eligible bookings.
- Updated the train scheduling service to include scheduled departure and arrival times in the response.
- Introduced utility functions for managing tracking stages and statuses.

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

@@ -213,6 +213,28 @@ export class BookingsController {
     return this.transitionService.enrichBookingResponse(booking);
   }
 
+  @Get(':id/tracking')
+  @ApiOperation({
+    summary: 'Shipment tracking timeline for a booking',
+    description:
+      "Returns the booking's consignment (once dispatched) and its ordered " +
+      'tracking events. Scoped to the customer\'s own company.',
+  })
+  async findTracking(
+    @Param('id', ParseUUIDPipe) id: string,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    const booking = await this.bookingsService.findById(id);
+    // Staff see any booking; customers only their own company's.
+    if (!hasFreightPermission(user, FREIGHT_PERMS.bookings.view)) {
+      await this.bookingsService.assertCustomerCanAccessBooking(
+        user?.id,
+        booking,
+      );
+    }
+    return this.bookingsService.getBookingTracking(id);
+  }
+
   @Delete(':id')
   @HttpCode(204)
   @ApiOperation({ summary: 'Soft-delete DRAFT booking' })

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

@@ -2,12 +2,15 @@ import {
   BadRequestException,
   ConflictException,
   ForbiddenException,
+  forwardRef,
+  Inject,
   Injectable,
   NotFoundException,
 } from '@nestjs/common';
-import { SchedulingStatus } from '@edr/types';
+import { Freight, SchedulingStatus } from '@edr/types';
 // import { CustomersService } from '../customers/customers.service';
 import { CompaniesService } from '../companies/companies.service';
+import { TrainSchedulingService } from '../train-scheduling/train-scheduling.service';
 import { FilesService } from '../files/files.service';
 import { MinioService } from '../minio/minio.service';
 import { ContainerTypesService } from '../rule-engine/services/container-types.service';
@@ -53,6 +56,8 @@ export class BookingsService {
     private readonly minioService: MinioService,
     // private readonly customersService: CustomersService,
     private readonly companiesService: CompaniesService,
+    @Inject(forwardRef(() => TrainSchedulingService))
+    private readonly trainSchedulingService: TrainSchedulingService,
     private readonly ruleEngineService: RuleEngineService,
     private readonly containerTypesService: ContainerTypesService,
     private readonly consolidationService: ConsolidationService,
@@ -669,6 +674,75 @@ export class BookingsService {
     }
   }
 
+  /**
+   * Build the customer-facing shipment tracking payload for a booking from the
+   * train schedule it is assigned to and the live checkpoint log. The caller is
+   * responsible for authorizing access to the booking first.
+   *
+   * When the booking has not been assigned to a train yet, returns a valid
+   * "no schedule" payload so the UI can show a pre-dispatch state.
+   */
+  async getBookingTracking(
+    bookingId: string,
+  ): Promise<Freight.IBookingTracking> {
+    const booking = await this.findById(bookingId);
+
+    const empty: Freight.IBookingTracking = {
+      bookingId: booking.id,
+      bookingReference: booking.reference,
+      hasSchedule: false,
+      scheduleId: null,
+      trainNumber: null,
+      scheduleStatus: null,
+      direction: null,
+      origin: null,
+      destination: null,
+      stations: [],
+      checkpoints: [],
+      currentSequenceNo: -1,
+      actualDepartureAt: null,
+      actualArrivalAt: null,
+      scheduledDepartureAt: null,
+      scheduledArrivalAt: null,
+    };
+
+    if (!booking.trainScheduleId) {
+      return empty;
+    }
+
+    // Pull the live corridor + checkpoints for the assigned schedule. If the
+    // schedule was removed, fall back to the pre-dispatch state rather than 500.
+    let track: Awaited<
+      ReturnType<TrainSchedulingService['getScheduleCheckpoints']>
+    >;
+    try {
+      track = await this.trainSchedulingService.getScheduleCheckpoints(
+        booking.trainScheduleId,
+      );
+    } catch {
+      return empty;
+    }
+
+    return {
+      bookingId: booking.id,
+      bookingReference: booking.reference,
+      hasSchedule: true,
+      scheduleId: track.scheduleId,
+      trainNumber: track.trainNumber,
+      scheduleStatus: track.status as Freight.TrainScheduleStatus,
+      direction: track.direction,
+      origin: track.origin,
+      destination: track.destination,
+      stations: track.stations,
+      checkpoints: track.checkpoints as Freight.ITrackingCheckpoint[],
+      currentSequenceNo: track.currentSequenceNo,
+      actualDepartureAt: track.actualDepartureAt,
+      actualArrivalAt: track.actualArrivalAt,
+      scheduledDepartureAt: track.scheduledDepartureAt,
+      scheduledArrivalAt: track.scheduledArrivalAt,
+    };
+  }
+
   /** Aggregate metrics and tab counts for the backoffice booking list. */
   async getListSummary(filter: FilterBookingDto): Promise<BookingListSummaryDto> {
     const page = filter.page ?? 1;

apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts

@@ -790,6 +790,12 @@ export class TrainSchedulingService {
       actualArrivalAt: schedule.actualArrivalAt
         ? schedule.actualArrivalAt.toISOString()
         : null,
+      scheduledDepartureAt: schedule.scheduledDepartureDate
+        ? schedule.scheduledDepartureDate.toISOString()
+        : null,
+      scheduledArrivalAt: schedule.scheduledArrivalDate
+        ? schedule.scheduledArrivalDate.toISOString()
+        : null,
       origin: stations[0]?.label ?? null,
       destination: stations[stations.length - 1]?.label ?? null,
       stations,