Merge pull request #1063 from Tria-plc/freight_feature/usermanagement

Freight feature/usermanagement

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

@@ -16,7 +16,7 @@ import {
   containersPerWagonForSize,
   wagonsPerUnitForSize,
 } from '../rule-engine/container-type.util';
-import { bulkItemWagonsRequired } from '../train-scheduling/train-capacity.util';
+import { bulkItemWagonsForAllowedTypes } from '../train-scheduling/train-capacity.util';
 import { BookingsRepository } from './bookings.repository';
 import { wagonRemainder } from './consolidation.service';
 import { GeneratePriceResponseDto, PriceLineItemDto } from './dto/generate-price-response.dto';
@@ -1188,8 +1188,9 @@ export class BookingPricingService {
       );
       if (!(capacity > 0)) return null;
       // Break-bulk (PER_ITEM): `tons` above is the item count; size by
-      // indivisible items instead of pretending the count is tonnage.
-      const byItems = bulkItemWagonsRequired(booking, capacity);
+      // indivisible items instead of pretending the count is tonnage. Best
+      // count across allowed wagon types, each capped by its items-fit.
+      const byItems = bulkItemWagonsForAllowedTypes(booking, cargo, capacity);
       if (byItems > 0) return byItems;
       return Math.max(1, Math.ceil(tons / capacity));
     } catch {

apps/edr-freight-api/src/modules/rule-engine/dto/create-cargo-type.dto.ts

@@ -1,6 +1,6 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
 import { CargoUnitOfMeasure } from '@edr/types';
-import { IsArray, IsBoolean, IsEnum, IsInt, IsOptional, IsString, IsUUID, MaxLength, Min } from 'class-validator';
+import { IsArray, IsBoolean, IsEnum, IsInt, IsObject, IsOptional, IsString, IsUUID, MaxLength, Min } from 'class-validator';
 
 export class CreateCargoTypeDto {
   @ApiProperty({ description: 'Cargo type display name', maxLength: 255 })
@@ -32,6 +32,18 @@ export class CreateCargoTypeDto {
   @IsUUID('4', { each: true })
   wagonTypeIds?: string[];
 
+  @ApiPropertyOptional({
+    description:
+      'PER_ITEM cargo only: items that physically fit one wagon, keyed by wagon-type id ' +
+      '(e.g. { "<nw5-id>": 4, "<nw7-id>": 6 }). Required for every wagonTypeId when ' +
+      'unitOfMeasure is PER_ITEM.',
+    type: 'object',
+    additionalProperties: { type: 'integer', minimum: 1 },
+  })
+  @IsOptional()
+  @IsObject()
+  itemsPerWagonMap?: Record<string, number> | null;
+
   @ApiPropertyOptional({ default: false })
   @IsOptional()
   @IsBoolean()

apps/edr-freight-api/src/modules/rule-engine/entities/cargo-type.entity.ts

@@ -50,6 +50,16 @@ export class CargoType extends BaseEntity {
   })
   wagonTypes?: WagonType[];
 
+  /**
+   * PER_ITEM (break-bulk) only: how many whole items physically fit each
+   * allowed wagon type, keyed by wagon-type id (e.g. cars → { NW5: 4, NW7: 6 }).
+   * Allocation loads min(this fit, floor(capacityTons / perItemTons)) per
+   * wagon — floor space and rated tonnage bind independently. Keys are kept a
+   * subset of the wagonTypes join rows by the cargo-types service.
+   */
+  @Column({ name: 'items_per_wagon_map', type: 'jsonb', nullable: true })
+  itemsPerWagonMap?: Record<string, number> | null;
+
   @Column({ name: 'requires_director_approval', type: 'boolean', default: false })
   requiresDirectorApproval!: boolean;
 

apps/edr-freight-api/src/modules/rule-engine/interfaces/rates.repository.interface.ts

@@ -28,6 +28,13 @@ export interface IRatesRepository {
   create(data: Partial<Rate>): Promise<Rate>;
   update(id: string, data: Partial<Rate>): Promise<Rate | null>;
   softDelete(id: string): Promise<void>;
+  /**
+   * Flip a commodity's PER_TON↔PER_ITEM rates to match its unit of measure.
+   * Both units bill the same stored quantity — only the name differs — so a
+   * uom change must rename the units or bookings keep quoting "per ton" for
+   * counted cargo. Returns the number of rates flipped.
+   */
+  syncBulkQuantityUnit(cargoTypeId: string, unitOfMeasure: 'PER_TON' | 'PER_ITEM'): Promise<number>;
 }
 
 export const RATES_REPOSITORY = Symbol('RATES_REPOSITORY');

apps/edr-freight-api/src/modules/rule-engine/repositories/rates.repository.ts

@@ -177,4 +177,16 @@ export class RatesRepository implements IRatesRepository {
   async softDelete(id: string): Promise<void> {
     await this.repo.softDelete(id);
   }
+
+  async syncBulkQuantityUnit(
+    cargoTypeId: string,
+    unitOfMeasure: 'PER_TON' | 'PER_ITEM',
+  ): Promise<number> {
+    const from = unitOfMeasure === 'PER_ITEM' ? 'PER_TON' : 'PER_ITEM';
+    const result = await this.repo.update(
+      { cargoTypeId, rateUnit: from },
+      { rateUnit: unitOfMeasure },
+    );
+    return result.affected ?? 0;
+  }
 }

apps/edr-freight-api/src/modules/rule-engine/services/cargo-types.service.ts

@@ -1,5 +1,11 @@
-import { PaginatedResponse } from '@edr/types';
-import { ConflictException, Inject, Injectable, NotFoundException } from '@nestjs/common';
+import { CargoUnitOfMeasure, PaginatedResponse } from '@edr/types';
+import {
+  BadRequestException,
+  ConflictException,
+  Inject,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
 import { generateCode } from '../../../common/utils/generate-code.util';
 import { CreateCargoTypeDto } from '../dto/create-cargo-type.dto';
 import { ListCargoTypesQueryDto } from '../dto/list-rule-engine-query.dto';
@@ -11,6 +17,7 @@ import {
   CARGO_TYPES_REPOSITORY,
   ICargoTypesRepository,
 } from '../interfaces/cargo-types.repository.interface';
+import { IRatesRepository, RATES_REPOSITORY } from '../interfaces/rates.repository.interface';
 import { DisplayOrderService } from './display-order.service';
 
 @Injectable()
@@ -18,6 +25,8 @@ export class CargoTypesService {
   constructor(
     @Inject(CARGO_TYPES_REPOSITORY)
     private readonly repository: ICargoTypesRepository,
+    @Inject(RATES_REPOSITORY)
+    private readonly ratesRepository: IRatesRepository,
     private readonly displayOrder: DisplayOrderService,
   ) {}
 
@@ -38,6 +47,34 @@ export class CargoTypesService {
     return this.repository.findByCode(code);
   }
 
+  /**
+   * PER_ITEM (break-bulk) cargo must carry a whole-items-fit for EVERY allowed
+   * wagon type — allocation caps each wagon at min(fit, tonnage) and a missing
+   * fit would silently fall back to tonnage-only loading. Returns the map
+   * trimmed to the allowed ids (stale keys from a removed wagon type drop out);
+   * null when the cargo is not PER_ITEM or has no wagon types.
+   */
+  private resolveItemsPerWagonMap(input: {
+    unitOfMeasure?: CargoUnitOfMeasure | null;
+    wagonTypeIds: string[];
+    itemsPerWagonMap?: Record<string, number> | null;
+  }): Record<string, number> | null {
+    if (input.unitOfMeasure !== CargoUnitOfMeasure.PerItem || !input.wagonTypeIds.length) {
+      return null;
+    }
+    const map: Record<string, number> = {};
+    for (const wagonTypeId of input.wagonTypeIds) {
+      const fit = Number(input.itemsPerWagonMap?.[wagonTypeId]);
+      if (!Number.isInteger(fit) || fit < 1) {
+        throw new BadRequestException(
+          `itemsPerWagonMap must define how many items fit wagon type ${wagonTypeId} (integer >= 1) for PER_ITEM cargo`,
+        );
+      }
+      map[wagonTypeId] = fit;
+    }
+    return map;
+  }
+
   /** Create a new cargo type. */
   async create(dto: CreateCargoTypeDto): Promise<CargoType> {
     const code = generateCode(dto.cargoTypeName);
@@ -62,26 +99,58 @@ export class CargoTypesService {
       unitOfMeasure: dto.unitOfMeasure ?? null,
       // Join rows are written by the save (RESTRICT FK rejects unknown ids).
       wagonTypes: (dto.wagonTypeIds ?? []).map((id) => ({ id }) as WagonType),
+      itemsPerWagonMap: this.resolveItemsPerWagonMap({
+        unitOfMeasure: dto.unitOfMeasure ?? null,
+        wagonTypeIds: dto.wagonTypeIds ?? [],
+        itemsPerWagonMap: dto.itemsPerWagonMap,
+      }),
       displayOrder,
     });
   }
 
   /** Update an existing cargo type. */
   async update(id: string, dto: UpdateCargoTypeDto): Promise<CargoType> {
-    await this.findById(id);
+    const existing = await this.findById(id);
     if (dto.parentGroupId) {
       if (dto.parentGroupId === id) throw new ConflictException('A cargo type cannot be its own parent');
       const parent = await this.repository.findById(dto.parentGroupId);
       if (!parent) throw new NotFoundException(`Parent cargo type ${dto.parentGroupId} not found`);
     }
-    const { wagonTypeIds, insertAfterId: _insertAfterId, ...columns } = dto;
+    const { wagonTypeIds, itemsPerWagonMap, insertAfterId: _insertAfterId, ...columns } = dto;
+    // Re-validate the fit map whenever anything it depends on moves — a partial
+    // update merges with the stored values so e.g. adding a wagon type without
+    // its fit still 400s. Untouched fields leave the stored map alone.
+    const touchesItemsFit =
+      wagonTypeIds !== undefined || itemsPerWagonMap !== undefined || dto.unitOfMeasure !== undefined;
     const updated = await this.repository.update(id, {
       ...columns,
       ...(wagonTypeIds
         ? { wagonTypes: wagonTypeIds.map((wagonTypeId) => ({ id: wagonTypeId }) as WagonType) }
         : {}),
+      ...(touchesItemsFit
+        ? {
+            itemsPerWagonMap: this.resolveItemsPerWagonMap({
+              unitOfMeasure:
+                dto.unitOfMeasure !== undefined ? dto.unitOfMeasure : existing.unitOfMeasure,
+              wagonTypeIds: wagonTypeIds ?? (existing.wagonTypes ?? []).map((wt) => wt.id),
+              itemsPerWagonMap:
+                itemsPerWagonMap !== undefined ? itemsPerWagonMap : existing.itemsPerWagonMap,
+            }),
+          }
+        : {}),
     });
     if (!updated) throw new NotFoundException(`Cargo type ${id} not found`);
+    // A uom flip renames how existing rates bill (PER_TON ↔ PER_ITEM name the
+    // same stored quantity) — sync them or bookings keep quoting "per ton" for
+    // counted cargo.
+    if (
+      dto.unitOfMeasure !== undefined &&
+      dto.unitOfMeasure !== existing.unitOfMeasure &&
+      (dto.unitOfMeasure === CargoUnitOfMeasure.PerTon ||
+        dto.unitOfMeasure === CargoUnitOfMeasure.PerItem)
+    ) {
+      await this.ratesRepository.syncBulkQuantityUnit(id, dto.unitOfMeasure);
+    }
     return updated;
   }
 

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

@@ -69,6 +69,7 @@ import {
   LocomotiveLimits,
   WagonTypeDimensions,
   bookingCargoTons,
+  bulkItemsFitFor,
   bulkItemWagonsRequired,
   bookingGrossWeightTons,
   deriveTrainCapacityFromLocomotive,
@@ -4060,7 +4061,13 @@ export class BookingBatchService implements OnModuleInit {
 
     // Break-bulk (PER_ITEM): indivisible items can need more wagons than raw
     // tonnage suggests (floor items-per-wagon loses the fractional capacity).
-    const byItems = bulkItemWagonsRequired(booking, capacityTons);
+    // `dimsFor` resolved dims from the first allowed wagon type, so charge that
+    // same type's configured items-fit alongside its capacity.
+    const byItems = bulkItemWagonsRequired(
+      booking,
+      capacityTons,
+      bulkItemsFitFor(booking.cargoType, booking.cargoType?.wagonTypes?.[0]?.id),
+    );
 
     return Math.max(DEFAULT_WAGONS_PER_BOOKING, stored, byLength, byWeight, byItems);
   }

apps/edr-freight-api/src/modules/train-scheduling/fleet-plan.util.ts

@@ -1,4 +1,4 @@
-import { bookingCargoTons, bulkItemWagonsRequired } from './train-capacity.util';
+import { bookingCargoTons, bulkItemWagonsForAllowedTypes } from './train-capacity.util';
 import type { Booking } from '../bookings/entities/booking.entity';
 import type { WagonType } from '../wagon-types/entities/wagon-type.entity';
 import {
@@ -53,8 +53,10 @@ export function wagonsRequiredForBooking(booking: Booking, bulkWagonCapacity?: n
   if (booking.freightType === 'BULK') {
     const capacity = bulkWagonCapacity && bulkWagonCapacity > 0 ? bulkWagonCapacity : 1;
     // Break-bulk (PER_ITEM) sizes by indivisible items; `cargoTotalWeightVgm`
-    // holds the item count there, not tons.
-    const byItems = bulkItemWagonsRequired(booking, capacity);
+    // holds the item count there, not tons. No wagon type is fixed yet, so use
+    // the best count across the cargo's allowed types (per-type items-fit
+    // respected); falls back to `capacity` when the relation isn't loaded.
+    const byItems = bulkItemWagonsForAllowedTypes(booking, booking.cargoType, capacity);
     if (byItems > 0) return byItems;
     const weight = Number(booking.cargoTotalWeightVgm ?? 0);
     return Math.max(1, Math.ceil(weight / capacity));

apps/edr-freight-api/src/modules/train-scheduling/train-capacity.util.spec.ts

@@ -2,6 +2,7 @@ import {
   bookingCargoTons,
   bookingGrossWeightTons,
   bookingTrainLengthMeters,
+  bulkItemWagonsForAllowedTypes,
   bulkItemWagonsRequired,
   consistUsage,
   consistViolations,
@@ -76,6 +77,62 @@ describe('train-capacity.util', () => {
       expect(bulkItemWagonsRequired(breakBulk(0, 800), 69)).toBe(0);
       expect(bulkItemWagonsRequired(breakBulk(400, 0), 69)).toBe(0);
     });
+
+    describe('configured items-fit (floor space vs tonnage)', () => {
+      it('weight binds: 50 cars × 20T on a 70T wagon that fits 4 → 3 per wagon → 17', () => {
+        // floor(70/20) = 3 by tonnage < 4 by floor space.
+        expect(bulkItemWagonsRequired(breakBulk(50, 1000), 70, 4)).toBe(17);
+      });
+
+      it('floor space binds: 50 cars × 10T on a 70T wagon that fits 4 → 4 per wagon → 13', () => {
+        // floor(70/10) = 7 by tonnage, but only 4 fit physically.
+        expect(bulkItemWagonsRequired(breakBulk(50, 500), 70, 4)).toBe(13);
+      });
+
+      it('ignores an absent/invalid fit (legacy cargo types): tonnage-only', () => {
+        expect(bulkItemWagonsRequired(breakBulk(50, 1000), 70, null)).toBe(17);
+        expect(bulkItemWagonsRequired(breakBulk(50, 1000), 70, 0)).toBe(17);
+        // floor(70/10) = 7 per wagon → ceil(50/7) = 8 wagons.
+        expect(bulkItemWagonsRequired(breakBulk(50, 500), 70)).toBe(8);
+      });
+    });
+  });
+
+  describe('bulkItemWagonsForAllowedTypes', () => {
+    const breakBulk = (quantity: number, weightTons: number) => ({
+      freightType: 'BULK',
+      cargoTotalWeightVgm: quantity,
+      bulkTotalWeightTons: weightTons,
+    });
+
+    it('picks the fewest-wagon allowed type, each capped by its own fit', () => {
+      const cargoType = {
+        wagonTypes: [
+          { id: 'nw5', capacityTons: 70 },
+          { id: 'nw7', capacityTons: 80 },
+        ],
+        itemsPerWagonMap: { nw5: 4, nw7: 6 },
+      };
+      // 50 cars × 20T: NW5 → min(4, floor(70/20)=3) = 3/wagon = 17 wagons;
+      // NW7 → min(6, floor(80/20)=4) = 4/wagon = 13 wagons. Best = 13.
+      expect(bulkItemWagonsForAllowedTypes(breakBulk(50, 1000), cargoType, 70)).toBe(13);
+    });
+
+    it('equals the old max-capacity estimate when no fits are configured', () => {
+      const cargoType = {
+        wagonTypes: [
+          { id: 'a', capacityTons: 50 },
+          { id: 'b', capacityTons: 70 },
+        ],
+      };
+      // Tonnage-only best = biggest wagon: floor(70/20) = 3/wagon → 17.
+      expect(bulkItemWagonsForAllowedTypes(breakBulk(50, 1000), cargoType, 1)).toBe(17);
+    });
+
+    it('falls back to the given capacity when the relation is missing', () => {
+      expect(bulkItemWagonsForAllowedTypes(breakBulk(50, 1000), null, 70)).toBe(17);
+      expect(bulkItemWagonsForAllowedTypes(breakBulk(50, 1000), { wagonTypes: [] }, 70)).toBe(17);
+    });
   });
 
   describe('bookingCargoTons (break-bulk weight preference)', () => {

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

@@ -120,6 +120,12 @@ export function bookingCargoTons(booking: {
  * 400 items / 800T on 69T wagons → 2T per item → 34 items per wagon → 12 wagons.
  * Returns 0 when the booking is not item-counted (PER_TON bulk, containers) —
  * callers then fall back to the pooled-tonnage math.
+ *
+ * `itemsFit` is the wagon type's PHYSICAL item capacity (floor space — from
+ * cargoType.itemsPerWagonMap). It binds independently of tonnage: a 70T wagon
+ * that fits 4 cars takes 3 cars of 20T (weight binds) but only 4 cars of 10T
+ * (floor binds, 30T of rated capacity ride empty). Absent/invalid fit falls
+ * back to tonnage-only (legacy cargo types without a configured fit).
  */
 export function bulkItemWagonsRequired(
   booking: {
@@ -128,6 +134,7 @@ export function bulkItemWagonsRequired(
     bulkTotalWeightTons?: number | string | null;
   },
   capacityTons: number,
+  itemsFit?: number | null,
 ): number {
   if (booking.freightType !== 'BULK' || !(capacityTons > 0)) return 0;
   const quantity = num(booking.cargoTotalWeightVgm);
@@ -136,10 +143,56 @@ export function bulkItemWagonsRequired(
   const perItemTons = totalWeightTons / quantity;
   // ponytail: an item heavier than a whole wagon still charges 1 wagon per
   // item; reject such bookings at creation time if the case turns real.
-  const itemsPerWagon = Math.max(1, Math.floor(capacityTons / perItemTons));
+  const byTonnage = Math.max(1, Math.floor(capacityTons / perItemTons));
+  const byFloor = num(itemsFit) >= 1 ? Math.floor(num(itemsFit)) : Infinity;
+  const itemsPerWagon = Math.min(byTonnage, byFloor);
   return Math.max(1, Math.ceil(quantity / itemsPerWagon));
 }
 
+type ItemFitCargoType = {
+  wagonTypes?: Array<{ id: string; capacityTons?: number | string | null }> | null;
+  itemsPerWagonMap?: Record<string, number> | null;
+} | null;
+
+/** Configured whole-items fit of one wagon type for a cargo type; null if unset. */
+export function bulkItemsFitFor(
+  cargoType: ItemFitCargoType | undefined,
+  wagonTypeId: string | null | undefined,
+): number | null {
+  const fit = wagonTypeId ? Number(cargoType?.itemsPerWagonMap?.[wagonTypeId]) : NaN;
+  return Number.isFinite(fit) && fit >= 1 ? fit : null;
+}
+
+/**
+ * Break-bulk wagon count when no single wagon type is fixed yet: the best
+ * (fewest-wagon) count across the cargo type's allowed wagon types, each
+ * respecting its own items-fit. With no fits configured this equals the old
+ * max-capacity estimate; with no allowed types it degrades to
+ * `fallbackCapacityTons` tonnage-only.
+ */
+export function bulkItemWagonsForAllowedTypes(
+  booking: {
+    freightType?: string | null;
+    cargoTotalWeightVgm?: number | string | null;
+    bulkTotalWeightTons?: number | string | null;
+  },
+  cargoType: ItemFitCargoType | undefined,
+  fallbackCapacityTons: number,
+): number {
+  const allowed = (cargoType?.wagonTypes ?? []).filter((wt) => num(wt.capacityTons) > 0);
+  if (!allowed.length) return bulkItemWagonsRequired(booking, fallbackCapacityTons);
+  let best = 0;
+  for (const wagonType of allowed) {
+    const wagons = bulkItemWagonsRequired(
+      booking,
+      num(wagonType.capacityTons),
+      bulkItemsFitFor(cargoType, wagonType.id),
+    );
+    if (wagons > 0 && (best === 0 || wagons < best)) best = wagons;
+  }
+  return best;
+}
+
 /** Gross weight of one loaded wagon: it hauls itself plus its cargo. */
 export function grossWagonWeightTons(slot: Pick<ConsistSlot, 'tareWeightTons' | 'cargoTons'>): number {
   return num(slot.tareWeightTons) + num(slot.cargoTons);

apps/edr-freight-api/src/modules/train-scheduling/wagon-plan.util.ts

@@ -3,7 +3,12 @@ import { AllocationLoadType } from '@edr/types';
 import { Booking } from '../bookings/entities/booking.entity';
 import { containersPerWagonForSize, wagonsPerUnitForSize } from '../rule-engine/container-type.util';
 import { WagonType } from '../wagon-types/entities/wagon-type.entity';
-import { bookingCargoTons, bulkItemWagonsRequired, consistViolations } from './train-capacity.util';
+import {
+  bookingCargoTons,
+  bulkItemsFitFor,
+  bulkItemWagonsRequired,
+  consistViolations,
+} from './train-capacity.util';
 
 export const MAX_TRAIN_WEIGHT_TONS = 3500;
 export const MAX_TRAIN_LENGTH_METERS = 760;
@@ -175,7 +180,11 @@ export function buildBulkWagonPlan(
   // Break-bulk (PER_ITEM) bookings size by indivisible items per booking —
   // their tonnage must NOT pool with PER_TON cargo (an item can't split
   // across wagons the way loose tonnage can).
-  const itemSlotsByBooking = bookings.map((b) => bulkItemWagonsRequired(b, capacity));
+  const itemSlotsByBooking = bookings.map((b) =>
+    // The plan fixed THIS wagon type, so its configured items-fit binds — not
+    // the best fit across the cargo's allowed types.
+    bulkItemWagonsRequired(b, capacity, bulkItemsFitFor(b.cargoType, wagonType.id)),
+  );
   const itemSlots = itemSlotsByBooking.reduce((sum, n) => sum + n, 0);
   const totalWeight = roundTons(
     bookings.reduce(