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/utils/wagon-plan.util.ts

@@ -7,7 +7,7 @@ import {
   bookingCargoTons,
   bulkItemsFitFor,
   bulkItemWagonsRequired,
-  bulkTonsPerWagon,
+  bulkTonsPerWagonFor,
   bulkTonWagonsRequired,
   consistViolations,
 } from '../train-capacity.util';
@@ -193,8 +193,11 @@ export function buildBulkWagonPlan(
   // pool with uncapped tonnage either: its wagons stop at the cap, so 200T needs
   // 4 wagons and pooling it at 70T would plan 3. Capped bookings are sized on
   // their own cap; only genuinely uncapped tonnage pools at rated capacity.
+  // A NUMBER_OF_WAGONS booking is "capped" at its even share (tons ÷ requested),
+  // so it plans exactly the requested count.
   const cappedTonSlotsByBooking = bookings.map((b, i) =>
-    itemSlotsByBooking[i] > 0 || bulkTonsPerWagon(b.cargoType, wagonType.id, capacity) >= capacity
+    itemSlotsByBooking[i] > 0 ||
+    bulkTonsPerWagonFor(b, b.cargoType, wagonType.id, capacity) >= capacity
       ? 0
       : bulkTonWagonsRequired(b, b.cargoType, wagonType.id, capacity),
   );
@@ -330,6 +333,7 @@ function allocateBookingsToSlots(
     // bookings that column is an item COUNT, not tons.
     remainingWeightTons: roundTons(bookingCargoTons(booking)),
     cargoType: booking.cargoType,
+    booking,
   }));
 
   let bookingIndex = 0;
@@ -343,10 +347,17 @@ function allocateBookingsToSlots(
       const booking = remaining[bookingIndex];
       // A PER_TON loading cap (sugar 50T on a 70T wagon) binds the FILL as well
       // as the wagon count — the plan reserved a wagon per capped chunk, so
-      // pouring rated capacity into it would leave the last wagon empty.
+      // pouring rated capacity into it would leave the last wagon empty. A
+      // NUMBER_OF_WAGONS booking fills each wagon its even share (tons ÷
+      // requested) for the same reason.
       const takeCap = Math.min(
         wagonRemaining,
-        bulkTonsPerWagon(booking.cargoType, slot.wagonTypeId, slot.capacityTons),
+        bulkTonsPerWagonFor(
+          booking.booking,
+          booking.cargoType,
+          slot.wagonTypeId,
+          slot.capacityTons,
+        ),
       );
       const allocatedWeightTons = roundTons(
         Math.min(takeCap, booking.remainingWeightTons),