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.

packages/types/src/freight/index.ts

@@ -265,6 +265,56 @@ export interface IConsignment extends BaseEntity {
   destinationStation: string;
 }
 
+/** One station along the train's corridor (origin → milestones → destination). */
+export interface ITrackingStation {
+  sequenceNo: number;
+  yardId: string;
+  label: string;
+  code: string;
+}
+
+/** A logged checkpoint as the train passes a station. */
+export interface ITrackingCheckpoint {
+  id: string;
+  sequenceNo: number;
+  yardId: string;
+  label: string | null;
+  kind: TrainCheckpointKind;
+  occurredAt: string;
+  note: string | null;
+}
+
+/**
+ * Customer-facing shipment tracking payload for a single booking, derived from
+ * the train schedule the booking is assigned to and the live checkpoint log.
+ *
+ * `hasSchedule` is false when the booking has not been assigned to a train yet
+ * (still pre-dispatch) — the UI shows a "not on the rails yet" state.
+ */
+export interface IBookingTracking {
+  bookingId: string;
+  bookingReference: string;
+  hasSchedule: boolean;
+  scheduleId: string | null;
+  trainNumber: string | null;
+  /** Operational status of the assigned schedule (DRAFT/SCHEDULED/DISPATCHED/ARRIVED). */
+  scheduleStatus: TrainScheduleStatus | null;
+  direction: string | null;
+  origin: string | null;
+  destination: string | null;
+  /** Ordered stations forming the corridor. */
+  stations: ITrackingStation[];
+  /** Logged checkpoints, ordered by sequence then time. */
+  checkpoints: ITrackingCheckpoint[];
+  /** Highest reached station sequence (−1 = not departed). */
+  currentSequenceNo: number;
+  actualDepartureAt: string | null;
+  actualArrivalAt: string | null;
+  /** Planned departure/arrival from the schedule, used as ETA hints. */
+  scheduledDepartureAt: string | null;
+  scheduledArrivalAt: string | null;
+}
+
 export interface IYard extends BaseEntity {
   code: string;
   label: string;