feat: enhance train scheduling and contract management features

- Added StationWorkControls to manage loading/unloading phases in TrainScheduleV2DetailPage.
- Implemented API endpoints for recording station work and managing wagon detach requests.
- Updated contract templates to include Ethiopian customs handling options.
- Enhanced shipment forms to collect customs clearing agent details for without-customs bookings.
- Introduced NUMBER_OF_WAGONS as a unit of measure for bulk cargo, allowing customers to specify wagon counts.
- Improved validation for customs clearing agent information in shipment forms.
- Updated various components and services to accommodate new features and ensure data integrity.

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

@@ -156,7 +156,7 @@ import {
   bookingCargoTons,
   bulkItemsFitFor,
   bulkItemWagonsRequired,
-  bulkTonsPerWagon,
+  bulkTonsPerWagonFor,
   consistViolations,
   deriveTrainCapacityFromLocomotive,
   combinedLocomotiveLimits,
@@ -2884,6 +2884,25 @@ export class TrainSchedulingService {
         schedule = reloaded;
       }
     }
+    // Loading is tracked per station: dispatching with cargo still to board at
+    // the origin marks it loaded (checklist + auto-load below), so the origin's
+    // loading time window must have been started first — same gate the
+    // per-booking load endpoint enforces.
+    const originBoarders = await this.unloadedOriginBoarderIds(
+      scheduleId,
+      schedule.originStationId,
+    );
+    const boardersToLoad = dto.loadedBookingIds
+      ? originBoarders.filter((id) => new Set(dto.loadedBookingIds).has(id))
+      : originBoarders;
+    if (
+      boardersToLoad.length &&
+      !schedule.stationWorkLogs?.[schedule.originStationId]?.loading?.startedAt
+    ) {
+      throw new BadRequestException(
+        'Start loading at the origin station before dispatching with cargo to load',
+      );
+    }
     // Staff may record the departure after the fact — past is fine, future is not.
     const now = dto.actualDepartureAt ? new Date(dto.actualDepartureAt) : new Date();
     this.assertNotFuture(now, 'Departure time');
@@ -4436,6 +4455,9 @@ export class TrainSchedulingService {
       origin: stations[0]?.label ?? null,
       destination: stations[stations.length - 1]?.label ?? null,
       stations,
+      // Per-yard loading/unloading time windows for the track page's
+      // start/end buttons and elapsed-time display.
+      stationWorkLogs: schedule.stationWorkLogs ?? {},
       currentSequenceNo,
       checkpoints: events.map((e) => ({
         id: e.id,
@@ -4852,6 +4874,23 @@ export class TrainSchedulingService {
     if (schedule.status !== TrainScheduleStatusEnum.Dispatched) {
       throw new BadRequestException('Only DISPATCHED trains can arrive');
     }
+    // Arrival bulk-marks every booking destined for the final yard as arrived
+    // (autoArriveAtFinalYard) — unloading is tracked per station, so the
+    // destination's unloading time window must be started before that sweep
+    // may run. Skipped when nothing on the train alights at the final yard.
+    const alightsAtFinal = (schedule.scheduleBookings ?? []).some(
+      (sb) =>
+        sb.booking?.destinationYardId === schedule.destinationStationId &&
+        sb.booking?.status === 'IN_TRANSIT',
+    );
+    if (
+      alightsAtFinal &&
+      !schedule.stationWorkLogs?.[schedule.destinationStationId]?.unloading?.startedAt
+    ) {
+      throw new BadRequestException(
+        'Start unloading at the destination station before marking the train arrived',
+      );
+    }
 
     // The arrival clock: the operator's entered time when arriving via the final
     // checkpoint (already order/future-checked there), else now.
@@ -9362,6 +9401,8 @@ export class TrainSchedulingService {
       Booking,
       | 'freightType'
       | 'cargoTotalWeightVgm'
+      | 'bulkTotalWeightTons'
+      | 'bulkRequestedWagons'
       | 'wagonsRequired'
       | 'bookingContainers'
       | 'cargoType'
@@ -9392,7 +9433,7 @@ export class TrainSchedulingService {
     const byLength = containerWagonsForLines(booking.bookingContainers ?? []);
     // PER_TON cargo may cap tons per wagon below the rating (sugar 50T on a 70T
     // wagon) — more wagons for the same cargo, so more tare to pull.
-    const tonsPerWagon = bulkTonsPerWagon(booking.cargoType, wagonTypeId, dims.capacityTons);
+    const tonsPerWagon = bulkTonsPerWagonFor(booking, booking.cargoType, wagonTypeId, dims.capacityTons);
     const byWeight = cargo > 0 && tonsPerWagon > 0 ? Math.ceil(cargo / tonsPerWagon) : 0;
     // Break-bulk (PER_ITEM): indivisible items occupy more wagons than raw
     // tonnage suggests — their tare must be pulled too (batch dimsFor parity).
@@ -9877,6 +9918,10 @@ export class TrainSchedulingService {
       // Ordered corridor stops (route milestones; falls back to the two
       // endpoints) — lets the UI draw per-segment occupancy and label legs.
       stops: this.mapScheduleStops(schedule),
+      // Per-yard loading/unloading time windows (start/end clicks) — the
+      // detail page shows the origin's loading window; dispatch requires it
+      // started when cargo boards there.
+      stationWorkLogs: schedule.stationWorkLogs ?? {},
       // Gross ceiling the validator holds each leg to: the set's weakest
       // locomotive pull limit plus its overage tolerance. Booking weightTons
       // above are gross too, so the strip can sum them per leg against this.