fix(warehouses): detention groups by canonical truck type

Join truck_types via vehicles.truck_type_id (normalized legacy
vehicle_type only as fallback) so type renames can't unmatch detention
rules and FK-less vehicles keep billing.

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

@@ -85,6 +85,24 @@ export class CustomerTruckService {
     if (isBulk) {
       const { totalTons, remainingTons } = await remainingBulkTons(this.dataSource, bookingId);
       assertBulkTonnageRemains(totalTons, remainingTons);
+
+      // Assignment-time drawdown: planned tonnage across live trucks (weighed
+      // net once departed, planned before) may not exceed the declared total.
+      if (totalTons > 0) {
+        const [p]: Array<{ planned: string | null }> = await this.dataSource.query(
+          `SELECT SUM(COALESCE(a.net_weight_tons, a.planned_tons, 0)) AS planned
+             FROM freight.customer_truck_assignments a
+            WHERE a.booking_id = $1 AND a.deleted_at IS NULL`,
+          [bookingId],
+        );
+        const alreadyPlanned = Number(p?.planned ?? 0);
+        const requestedTons = Number(dto.plannedTons ?? 0);
+        if (requestedTons > 0 && alreadyPlanned + requestedTons > totalTons + 0.001) {
+          throw new BadRequestException(
+            `Planned tonnage exceeds the booking: ${alreadyPlanned} t already assigned of ${totalTons} t — at most ${Math.max(0, totalTons - alreadyPlanned)} t left for this truck`,
+          );
+        }
+      }
     }
 
     if (requested.length) {
@@ -108,6 +126,8 @@ export class CustomerTruckService {
           plateNumber: dto.truckPlateNumber.trim().toUpperCase(),
           driverName: dto.driverName.trim(),
           truckType: dto.truckType.trim(),
+          plannedTons: isBulk ? (dto.plannedTons ?? null) : null,
+          plannedQuantity: isBulk ? (dto.plannedQuantity ?? null) : null,
         }),
       );
       await manager.getRepository(CustomerTruckContainer).save(
@@ -186,23 +206,52 @@ export class CustomerTruckService {
       throw new ConflictException('Cannot edit a truck that has already arrived');
     }
 
-    const requested = (dto.containerNumbers ?? []).map((n) => n.trim().toUpperCase());
-    if (requested.length < 1) {
+    // Bulk trucks carry loose tonnage, not containers — planned tonnage is
+    // editable instead, capped by what the other trucks haven't claimed.
+    const isBulk = booking.freightType === 'BULK';
+    const requested = isBulk
+      ? []
+      : (dto.containerNumbers ?? []).map((n) => n.trim().toUpperCase());
+    if (!isBulk && requested.length < 1) {
       throw new BadRequestException('Select at least one container for this truck');
     }
-    assertTruckLoad({
-      containers: requested,
-      bookingContainers: await this.bookingContainerNumbers(bookingId),
-      sizes: await bookingContainerSizes(this.dataSource, bookingId, requested),
-      // Exclude THIS truck's own containers so re-saving the same set is allowed.
-      assignedElsewhere: await this.assignedContainerNumbersExcept(bookingId, assignmentId),
-    });
+    if (!isBulk) {
+      assertTruckLoad({
+        containers: requested,
+        bookingContainers: await this.bookingContainerNumbers(bookingId),
+        sizes: await bookingContainerSizes(this.dataSource, bookingId, requested),
+        // Exclude THIS truck's own containers so re-saving the same set is allowed.
+        assignedElsewhere: await this.assignedContainerNumbersExcept(bookingId, assignmentId),
+      });
+    } else if (dto.plannedTons != null) {
+      const { totalTons } = await remainingBulkTons(this.dataSource, bookingId);
+      if (totalTons > 0) {
+        const [p]: Array<{ planned: string | null }> = await this.dataSource.query(
+          `SELECT SUM(COALESCE(a.net_weight_tons, a.planned_tons, 0)) AS planned
+             FROM freight.customer_truck_assignments a
+            WHERE a.booking_id = $1 AND a.deleted_at IS NULL AND a.id <> $2`,
+          [bookingId, assignmentId],
+        );
+        const others = Number(p?.planned ?? 0);
+        if (others + Number(dto.plannedTons) > totalTons + 0.001) {
+          throw new BadRequestException(
+            `Planned tonnage exceeds the booking: ${others} t on other trucks of ${totalTons} t — at most ${Math.max(0, totalTons - others)} t left for this truck`,
+          );
+        }
+      }
+    }
 
     await this.dataSource.transaction(async (manager) => {
       await manager.getRepository(CustomerTruckAssignment).update(assignmentId, {
         plateNumber: dto.truckPlateNumber.trim().toUpperCase(),
         driverName: dto.driverName.trim(),
         truckType: dto.truckType.trim(),
+        ...(isBulk
+          ? {
+              plannedTons: dto.plannedTons ?? null,
+              plannedQuantity: dto.plannedQuantity ?? null,
+            }
+          : {}),
       });
       await manager.getRepository(CustomerTruckContainer).softDelete({ assignmentId });
       await manager.getRepository(CustomerTruckContainer).save(

apps/edr-freight-api/src/modules/bookings/dto/add-customer-truck.dto.ts

@@ -4,10 +4,12 @@ import {
   IsArray,
   IsIn,
   IsNotEmpty,
+  IsNumber,
   IsOptional,
   IsString,
   Matches,
   MaxLength,
+  Min,
 } from 'class-validator';
 
 import { CUSTOMER_TRUCK_TYPES } from './customer-truck-assignment.dto';
@@ -44,4 +46,16 @@ export class AddCustomerTruckDto {
     message: 'each container number must match ISO container format, e.g. ABCD1234567',
   })
   containerNumbers?: string[];
+
+  /** Bulk: planned tonnage this truck hauls — draws down the booking total at assignment. */
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  plannedTons?: number;
+
+  /** Bulk: optional item/piece count on this truck. */
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  plannedQuantity?: number;
 }

apps/edr-freight-api/src/modules/bookings/entities/customer-truck-assignment.entity.ts

@@ -51,6 +51,14 @@ export class CustomerTruckAssignment extends BaseEntity {
   @Column({ name: 'net_weight_tons', type: 'numeric', precision: 14, scale: 3, nullable: true })
   netWeightTons?: number | null;
 
+  /** Bulk: planned tonnage at assignment — draws down the booking before weigh-out. */
+  @Column({ name: 'planned_tons', type: 'numeric', precision: 14, scale: 3, nullable: true })
+  plannedTons?: number | null;
+
+  /** Bulk: optional item/piece count planned on this truck. */
+  @Column({ name: 'planned_quantity', type: 'integer', nullable: true })
+  plannedQuantity?: number | null;
+
   @Column({ name: 'departed_at', type: 'timestamptz', nullable: true })
   departedAt?: Date | null;
 

apps/edr-freight-api/src/modules/first-mile/dto/set-vehicles.dto.ts

@@ -1,4 +1,4 @@
-import { IsArray, IsOptional, IsString, IsUUID, ValidateNested } from 'class-validator';
+import { IsArray, IsNumber, IsOptional, IsString, IsUUID, Min, ValidateNested } from 'class-validator';
 import { Type } from 'class-transformer';
 
 export class FirstMileVehicleInput {
@@ -8,6 +8,18 @@ export class FirstMileVehicleInput {
   @IsOptional()
   @IsString()
   containerNumber?: string;
+
+  /** Bulk: tonnage this truck hauls. */
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  tons?: number;
+
+  /** Bulk: optional item/piece count. */
+  @IsOptional()
+  @IsNumber()
+  @Min(0)
+  quantity?: number;
 }
 
 /** Replace the full set of vehicles (with their container numbers) on a pickup. */

apps/edr-freight-api/src/modules/first-mile/entities/first-mile-vehicle-assignment.entity.ts

@@ -36,4 +36,12 @@ export class FirstMileVehicleAssignment extends BaseEntity {
   /** Actual distance driven by this truck (km), entered per vehicle. */
   @Column({ name: 'distance_km', type: 'numeric', precision: 10, scale: 2, nullable: true })
   distanceKm?: number | null;
+
+  /** Bulk: tonnage this truck hauls — assigned tonnage draws down the booking total. */
+  @Column({ name: 'tons', type: 'numeric', precision: 14, scale: 3, nullable: true })
+  tons?: number | null;
+
+  /** Bulk: optional item/piece count on this truck. */
+  @Column({ name: 'quantity', type: 'integer', nullable: true })
+  quantity?: number | null;
 }

apps/edr-freight-api/src/modules/first-mile/first-mile.service.ts

@@ -532,17 +532,47 @@ export class FirstMileService {
    */
   async setVehicles(
     id: string,
-    inputs: Array<{ vehicleId: string; containerNumber?: string | null }>,
+    inputs: Array<{
+      vehicleId: string;
+      containerNumber?: string | null;
+      tons?: number | null;
+      quantity?: number | null;
+    }>,
   ): Promise<FirstMile> {
     const existing = await this.findById(id);
-    // Dedupe by vehicleId, keeping the container number; preserve order.
-    const desiredMap = new Map<string, string | null>();
+    // Dedupe by vehicleId, keeping the load details; preserve order.
+    const desiredMap = new Map<
+      string,
+      { containerNumber: string | null; tons: number | null; quantity: number | null }
+    >();
     for (const inp of inputs) {
-      if (inp.vehicleId) desiredMap.set(inp.vehicleId, inp.containerNumber ?? null);
+      if (inp.vehicleId) {
+        desiredMap.set(inp.vehicleId, {
+          containerNumber: inp.containerNumber ?? null,
+          tons: inp.tons ?? null,
+          quantity: inp.quantity ?? null,
+        });
+      }
     }
     const desired = [...desiredMap.keys()];
     const desiredSet = new Set(desired);
 
+    // Bulk drawdown: assigned tonnage may not exceed what the booking declares.
+    const totalTons = [...desiredMap.values()].reduce((s, v) => s + (Number(v.tons) || 0), 0);
+    if (totalTons > 0 && existing.bookingId) {
+      const [b]: Array<{ vgm: string | null }> = await this.dataSource.query(
+        `SELECT cargo_total_weight_vgm AS vgm FROM freight.bookings
+          WHERE id = $1 AND deleted_at IS NULL`,
+        [existing.bookingId],
+      );
+      const declared = Number(b?.vgm ?? 0);
+      if (declared > 0 && totalTons > declared + 0.001) {
+        throw new BadRequestException(
+          `Assigned tonnage (${totalTons} t) exceeds the booking's declared ${declared} t`,
+        );
+      }
+    }
+
     const manager = this.dataSource.manager;
     const current = await manager.find(FirstMileVehicleAssignment, {
       where: { firstMileId: id },
@@ -555,12 +585,16 @@ export class FirstMileService {
     )];
     const added = desired.filter((v) => !junctionSet.has(v));
     const removed = releaseIds.filter((v) => !desiredSet.has(v));
-    // Vehicles that stay but whose container number changed.
-    const changed = current.filter(
-      (a) =>
-        desiredMap.has(a.vehicleId) &&
-        (a.containerNumber ?? null) !== (desiredMap.get(a.vehicleId) ?? null),
-    );
+    // Vehicles that stay but whose load details changed.
+    const changed = current.filter((a) => {
+      const want = desiredMap.get(a.vehicleId);
+      if (!want) return false;
+      return (
+        (a.containerNumber ?? null) !== want.containerNumber ||
+        (a.tons == null ? null : Number(a.tons)) !== want.tons ||
+        (a.quantity ?? null) !== want.quantity
+      );
+    });
 
     await this.dataSource.transaction(async (tx) => {
       if (removed.length) {
@@ -570,17 +604,25 @@ export class FirstMileService {
         });
       }
       for (const vehicleId of added) {
+        const want = desiredMap.get(vehicleId);
         await tx.insert(FirstMileVehicleAssignment, {
           firstMileId: id,
           vehicleId,
-          containerNumber: desiredMap.get(vehicleId) ?? null,
+          containerNumber: want?.containerNumber ?? null,
+          tons: want?.tons ?? null,
+          quantity: want?.quantity ?? null,
         });
       }
       for (const row of changed) {
+        const want = desiredMap.get(row.vehicleId);
         await tx.update(
           FirstMileVehicleAssignment,
           { firstMileId: id, vehicleId: row.vehicleId },
-          { containerNumber: desiredMap.get(row.vehicleId) ?? null },
+          {
+            containerNumber: want?.containerNumber ?? null,
+            tons: want?.tons ?? null,
+            quantity: want?.quantity ?? null,
+          },
         );
       }
     });

apps/edr-freight-api/src/modules/truck-types/dto/create-truck-type.dto.ts

@@ -0,0 +1,55 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Transform } from 'class-transformer';
+import { IsBoolean, IsNumber, IsOptional, IsString, MaxLength, Min } from 'class-validator';
+
+const toNumber = ({ value }: { value: unknown }) =>
+  value === '' || value == null ? value : Number(value);
+
+const toBoolean = ({ value }: { value: unknown }) => {
+  if (typeof value === 'boolean') return value;
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  return value;
+};
+
+export class CreateTruckTypeDto {
+  @ApiProperty({ maxLength: 32, example: 'CASONI' })
+  @IsString()
+  @MaxLength(32)
+  code!: string;
+
+  @ApiProperty({ maxLength: 100, example: 'Casoni (rigid, no trailer)' })
+  @IsString()
+  @MaxLength(100)
+  name!: string;
+
+  @ApiPropertyOptional({
+    description: 'Payload capacity in metric tons — pre-fills a vehicle registered against this type',
+    example: 30,
+  })
+  @IsOptional()
+  @Transform(toNumber)
+  @IsNumber()
+  @Min(0)
+  capacityTons?: number;
+
+  @ApiPropertyOptional({
+    description: 'Whether this configuration pulls a trailer. False (e.g. Casoni) forbids a trailer plate.',
+    default: false,
+  })
+  @IsOptional()
+  @Transform(toBoolean)
+  @IsBoolean()
+  hasTrailer?: boolean;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  description?: string;
+
+  @ApiPropertyOptional({ default: true })
+  @IsOptional()
+  @Transform(toBoolean)
+  @IsBoolean()
+  isActive?: boolean;
+}

apps/edr-freight-api/src/modules/truck-types/dto/update-truck-type.dto.ts

@@ -0,0 +1,5 @@
+import { PartialType } from '@nestjs/mapped-types';
+
+import { CreateTruckTypeDto } from './create-truck-type.dto';
+
+export class UpdateTruckTypeDto extends PartialType(CreateTruckTypeDto) {}

apps/edr-freight-api/src/modules/truck-types/entities/truck-type.entity.ts

@@ -0,0 +1,40 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index } from 'typeorm';
+
+/**
+ * A truck configuration EDR registers vehicles against — back-office managed so
+ * new configurations arrive without a code change.
+ *
+ * Two fields drive vehicle registration:
+ * - `capacityTons` pre-fills a vehicle's capacity (capacity belongs to the type,
+ *   not to each individual truck).
+ * - `hasTrailer` decides whether a trailer plate applies at all. A rigid truck
+ *   (e.g. Casoni) has none, and registering one with a trailer plate is rejected.
+ */
+@Entity({ schema: 'freight', name: 'truck_types' })
+@Index(['code'])
+@Index(['isActive'])
+export class TruckType extends BaseEntity {
+  /**
+   * Matching key, upper-case. Denormalised onto `vehicles.vehicle_type`, which
+   * truck-detention billing groups and matches fee rules by — so a code change
+   * here is a billing-visible change.
+   */
+  @Column({ name: 'code', type: 'varchar', length: 32, unique: true })
+  code!: string;
+
+  @Column({ name: 'name', type: 'varchar', length: 100 })
+  name!: string;
+
+  @Column({ name: 'capacity_tons', type: 'numeric', precision: 10, scale: 3, nullable: true })
+  capacityTons?: number | null;
+
+  @Column({ name: 'has_trailer', type: 'boolean', default: false })
+  hasTrailer!: boolean;
+
+  @Column({ name: 'description', type: 'text', nullable: true })
+  description?: string | null;
+
+  @Column({ name: 'is_active', type: 'boolean', default: true })
+  isActive!: boolean;
+}

apps/edr-freight-api/src/modules/truck-types/truck-types.controller.ts

@@ -0,0 +1,74 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Param,
+  ParseUUIDPipe,
+  Patch,
+  Post,
+  Query,
+} from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
+
+import { RuleEngineManage, RuleEngineView } from '../../common/rule-engine-guards';
+
+import { CreateTruckTypeDto } from './dto/create-truck-type.dto';
+import { UpdateTruckTypeDto } from './dto/update-truck-type.dto';
+import { TruckTypesService } from './truck-types.service';
+
+@ApiTags('truck-types')
+@Controller('truck-types')
+@ApiBearerAuth()
+export class TruckTypesController {
+  constructor(private readonly truckTypesService: TruckTypesService) {}
+
+  @Get()
+  @RuleEngineView('truck-types')
+  @ApiOperation({ summary: 'List truck types' })
+  findAll(@Query() query: Record<string, string | undefined>) {
+    return this.truckTypesService.findAll({
+      isActive:
+        query.isActive === 'all'
+          ? undefined
+          : query.isActive !== undefined
+            ? query.isActive === 'true'
+            : true,
+      page: query.page ? parseInt(query.page, 10) : undefined,
+      pageSize: query.pageSize ? parseInt(query.pageSize, 10) : undefined,
+      sortBy: query.sortBy,
+      sortOrder: query.sortOrder,
+    });
+  }
+
+  @Get(':id')
+  @RuleEngineView('truck-types')
+  @ApiOperation({ summary: 'Get a truck type by ID' })
+  findOne(@Param('id', ParseUUIDPipe) id: string) {
+    return this.truckTypesService.findById(id);
+  }
+
+  @Post()
+  @RuleEngineManage('truck-types')
+  @ApiOperation({ summary: 'Create a truck type' })
+  create(@Body() dto: CreateTruckTypeDto) {
+    return this.truckTypesService.create(dto);
+  }
+
+  @Patch(':id')
+  @RuleEngineManage('truck-types')
+  @ApiOperation({ summary: 'Update a truck type' })
+  update(@Param('id', ParseUUIDPipe) id: string, @Body() dto: UpdateTruckTypeDto) {
+    return this.truckTypesService.update(id, dto);
+  }
+
+  @Delete(':id')
+  @RuleEngineManage('truck-types')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  @ApiOperation({ summary: 'Soft-delete a truck type' })
+  remove(@Param('id', ParseUUIDPipe) id: string) {
+    return this.truckTypesService.remove(id);
+  }
+}

apps/edr-freight-api/src/modules/truck-types/truck-types.module.ts

@@ -0,0 +1,15 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { TruckType } from './entities/truck-type.entity';
+import { TruckTypesController } from './truck-types.controller';
+import { TruckTypesRepository } from './truck-types.repository';
+import { TruckTypesService } from './truck-types.service';
+
+@Module({
+  imports: [TypeOrmModule.forFeature([TruckType])],
+  controllers: [TruckTypesController],
+  providers: [TruckTypesRepository, TruckTypesService],
+  exports: [TruckTypesRepository, TruckTypesService],
+})
+export class TruckTypesModule {}

apps/edr-freight-api/src/modules/truck-types/truck-types.repository.ts

@@ -0,0 +1,20 @@
+import { BaseRepository } from '@edr/api-common';
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { TruckType } from './entities/truck-type.entity';
+
+@Injectable()
+export class TruckTypesRepository extends BaseRepository<TruckType> {
+  constructor(
+    @InjectRepository(TruckType)
+    repository: Repository<TruckType>,
+  ) {
+    super(repository);
+  }
+
+  findByCode(code: string): Promise<TruckType | null> {
+    return this.repository.findOne({ where: { code } });
+  }
+}

apps/edr-freight-api/src/modules/truck-types/truck-types.service.ts

@@ -0,0 +1,116 @@
+import { ConflictException, Injectable, NotFoundException } from '@nestjs/common';
+import { FindOptionsOrder } from 'typeorm';
+
+import { CreateTruckTypeDto } from './dto/create-truck-type.dto';
+import { UpdateTruckTypeDto } from './dto/update-truck-type.dto';
+import { TruckType } from './entities/truck-type.entity';
+import { TruckTypesRepository } from './truck-types.repository';
+
+type TruckTypeListFilter = {
+  isActive?: boolean;
+  page?: number;
+  pageSize?: number;
+  sortBy?: string;
+  sortOrder?: string;
+};
+
+@Injectable()
+export class TruckTypesService {
+  constructor(private readonly truckTypesRepository: TruckTypesRepository) {}
+
+  async findAll(filter: TruckTypeListFilter = {}): Promise<{
+    data: TruckType[];
+    meta: { total: number; page: number; pageSize: number; totalPages: number };
+  }> {
+    const page = filter.page ?? 1;
+    const pageSize = filter.pageSize ?? 500;
+    const sortBy = ['code', 'name', 'capacityTons', 'hasTrailer', 'isActive'].includes(
+      filter.sortBy ?? '',
+    )
+      ? (filter.sortBy as keyof TruckType)
+      : 'code';
+    const sortOrder = filter.sortOrder?.toUpperCase() === 'DESC' ? 'DESC' : 'ASC';
+
+    const [data, total] = await this.truckTypesRepository.findAndCount({
+      where: filter.isActive === undefined ? {} : { isActive: filter.isActive },
+      order: { [sortBy]: sortOrder } as FindOptionsOrder<TruckType>,
+      skip: (page - 1) * pageSize,
+      take: pageSize,
+    });
+
+    return {
+      data,
+      meta: {
+        total,
+        page,
+        pageSize,
+        totalPages: Math.max(1, Math.ceil(total / pageSize)),
+      },
+    };
+  }
+
+  async findById(id: string): Promise<TruckType> {
+    const truckType = await this.truckTypesRepository.findById(id);
+
+    if (!truckType) {
+      throw new NotFoundException(`Truck type ${id} not found`);
+    }
+
+    return truckType;
+  }
+
+  async findByCode(code: string): Promise<TruckType> {
+    const truckType = await this.truckTypesRepository.findByCode(code);
+    if (!truckType) {
+      throw new NotFoundException(`Truck type ${code} not found`);
+    }
+    return truckType;
+  }
+
+  async create(dto: CreateTruckTypeDto): Promise<TruckType> {
+    const code = dto.code.trim().toUpperCase();
+    const existing = await this.truckTypesRepository.findByCode(code);
+
+    if (existing) {
+      throw new ConflictException(`Truck type code "${code}" already exists`);
+    }
+
+    return this.truckTypesRepository.create({
+      code,
+      name: dto.name.trim(),
+      capacityTons: dto.capacityTons ?? null,
+      hasTrailer: dto.hasTrailer ?? false,
+      description: dto.description?.trim() ?? null,
+      isActive: dto.isActive ?? true,
+    });
+  }
+
+  async update(id: string, dto: UpdateTruckTypeDto): Promise<TruckType> {
+    const truckType = await this.findById(id);
+    const nextCode = dto.code?.trim().toUpperCase();
+
+    if (nextCode && nextCode !== truckType.code) {
+      const existing = await this.truckTypesRepository.findByCode(nextCode);
+      if (existing) {
+        throw new ConflictException(`Truck type code "${nextCode}" already exists`);
+      }
+    }
+
+    const updated = await this.truckTypesRepository.update(id, {
+      ...dto,
+      ...(nextCode ? { code: nextCode } : {}),
+      ...(dto.name ? { name: dto.name.trim() } : {}),
+    });
+
+    if (!updated) {
+      throw new NotFoundException(`Truck type ${id} not found`);
+    }
+
+    return updated;
+  }
+
+  async remove(id: string): Promise<void> {
+    await this.findById(id);
+    await this.truckTypesRepository.softDelete(id);
+  }
+}

apps/edr-freight-api/src/modules/vehicles/dto/create-vehicle.dto.ts

@@ -1,6 +1,11 @@
 import { IsString, IsEnum, IsNumber, IsOptional, IsUUID, Matches } from 'class-validator';
 import { Transform } from 'class-transformer';
-import { VehicleType, FuelType, VehicleStatus, VehicleAvailability } from '../entities/vehicle.entity';
+import {
+  FuelType,
+  VehicleAvailability,
+  VehicleOwnership,
+  VehicleStatus,
+} from '../entities/vehicle.entity';
 
 /**
  * A vehicle plate is two or three letters, a hyphen, then two to six digits —
@@ -28,8 +33,9 @@ export class CreateVehicleDto {
   @IsString()
   plateNumber!: string;
 
-  @IsEnum(VehicleType)
-  vehicleType!: VehicleType;
+  /** Truck configuration from `freight.truck_types` — drives capacity and whether a trailer plate applies. */
+  @IsUUID()
+  truckTypeId!: string;
 
   @IsString()
   manufacturer!: string;
@@ -43,8 +49,18 @@ export class CreateVehicleDto {
   @IsEnum(FuelType)
   fuelType!: FuelType;
 
+  /** Defaults to the truck type's capacity when omitted. */
+  @IsOptional()
   @IsNumber()
-  capacity!: number;
+  capacity?: number;
+
+  @IsOptional()
+  @IsString()
+  vin?: string;
+
+  @IsOptional()
+  @IsEnum(VehicleOwnership)
+  ownership?: VehicleOwnership;
 
   @IsEnum(VehicleStatus)
   status!: VehicleStatus;

apps/edr-freight-api/src/modules/vehicles/entities/vehicle.entity.ts

@@ -1,6 +1,17 @@
 import { Entity, Column } from 'typeorm';
 import { BaseEntity } from '@edr/api-common';
 
+/**
+ * Legacy classification. Truck configurations are now back-office data in
+ * `freight.truck_types` — register a vehicle with `truckTypeId`, not this.
+ *
+ * The `vehicle_type` COLUMN survives as a denormalised copy of the truck type's
+ * code because truck-detention billing groups by it in raw SQL and matches it
+ * against `warehouse_fee_rules.vehicle_type`. The service writes it through on
+ * every save; nothing should set it by hand.
+ *
+ * @deprecated use `truckTypeId` / `freight.truck_types`
+ */
 export enum VehicleType {
   TRUCK = 'TRUCK',
   VAN = 'VAN',
@@ -11,6 +22,12 @@ export enum VehicleType {
   FLATBED = 'FLATBED',
 }
 
+/** Who supplies the truck. Supplier selection is deferred until EDR commits to outsourcing. */
+export enum VehicleOwnership {
+  OWNED = 'OWNED',
+  OUTSOURCED = 'OUTSOURCED',
+}
+
 export enum FuelType {
   PETROL = 'PETROL',
   DIESEL = 'DIESEL',
@@ -47,8 +64,12 @@ export class Vehicle extends BaseEntity {
   @Column({ name: 'registration_number', unique: true, nullable: true })
   registrationNumber?: string;
 
+  /** Denormalised `truck_types.code` — written through by the service, never set by hand. */
   @Column({ name: 'vehicle_type', type: 'varchar', nullable: true })
-  vehicleType?: VehicleType;
+  vehicleType?: string;
+
+  @Column({ name: 'truck_type_id', type: 'uuid', nullable: true })
+  truckTypeId?: string | null;
 
   @Column({ nullable: true })
   manufacturer?: string;
@@ -101,7 +122,7 @@ export class Vehicle extends BaseEntity {
   @Column({ name: 'vin', type: 'varchar', nullable: true })
   vin?: string;
 
-  /** Owned | Leased | Rented */
+  /** OWNED | OUTSOURCED — see {@link VehicleOwnership}. */
   @Column({ name: 'ownership', type: 'varchar', nullable: true })
   ownership?: string;
 

apps/edr-freight-api/src/modules/vehicles/vehicles.driver-guard.spec.ts

@@ -11,6 +11,7 @@ describe('VehiclesService driver assignment guard', () => {
     new VehiclesService(
       { findOne, create: jest.fn((x) => x), save: jest.fn(async (x) => x) } as any,
       { record: jest.fn() } as any,
+      { findById: jest.fn(async () => ({ code: 'TRUCK', name: 'Truck', hasTrailer: true })) } as any,
     );
 
   it('rejects create when the driver is on another truck', async () => {
@@ -18,7 +19,7 @@ describe('VehiclesService driver assignment guard', () => {
     const findOne = jest.fn().mockResolvedValueOnce(null).mockResolvedValueOnce(otherTruck);
     const svc = makeService(findOne);
     await expect(
-      svc.create({ plateNumber: '3-22222', vehicleType: 'TRUCK', assignedDriverId: 'd1' } as any),
+      svc.create({ plateNumber: '3-22222', truckTypeId: 'tt1', assignedDriverId: 'd1' } as any),
     ).rejects.toThrow(ConflictException);
   });
 

apps/edr-freight-api/src/modules/vehicles/vehicles.module.ts

@@ -3,9 +3,10 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 import { Vehicle } from './entities/vehicle.entity';
 import { VehiclesService } from './vehicles.service';
 import { VehiclesController } from './vehicles.controller';
+import { TruckTypesModule } from '../truck-types/truck-types.module';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([Vehicle])],
+  imports: [TypeOrmModule.forFeature([Vehicle]), TruckTypesModule],
   providers: [VehiclesService],
   controllers: [VehiclesController],
   exports: [VehiclesService],

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

@@ -1,9 +1,16 @@
-import { Injectable, NotFoundException, ConflictException } from '@nestjs/common';
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  NotFoundException,
+} from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
 import { Not, Repository } from 'typeorm';
 import { CreateVehicleDto } from './dto/create-vehicle.dto';
 import { UpdateVehicleDto } from './dto/update-vehicle.dto';
 import { Vehicle, VehicleAvailability, VehicleStatus } from './entities/vehicle.entity';
+import { TruckType } from '../truck-types/entities/truck-type.entity';
+import { TruckTypesService } from '../truck-types/truck-types.service';
 import { FirstMile, FirstMileStatus } from '../first-mile/entities/first-mile.entity';
 import { FirstMileContainerAllocation } from '../first-mile/entities/first-mile-container-allocation.entity';
 import { LastMile, LastMileStatus } from '../last-mile/entities/last-mile.entity';
@@ -18,8 +25,26 @@ export class VehiclesService {
     @InjectRepository(Vehicle)
     private readonly vehicleRepo: Repository<Vehicle>,
     private readonly history: FleetHistoryService,
+    private readonly truckTypes: TruckTypesService,
   ) {}
 
+  /**
+   * A trailer plate only exists on a configuration that pulls a trailer — a
+   * rigid truck (Casoni) has none. Checked against the RESULTING record, not
+   * just the patch, so switching an articulated truck to a rigid type cannot
+   * leave its old trailer plate stranded on the row.
+   */
+  private assertTrailerPlateAllowed(
+    truckType: TruckType,
+    trailerPlateNo?: string | null,
+  ): void {
+    if (!truckType.hasTrailer && trailerPlateNo) {
+      throw new BadRequestException(
+        `${truckType.name} has no trailer — remove the trailer plate number`,
+      );
+    }
+  }
+
   /**
    * A driver holds one truck at a time — reassignment requires detaching them
    * from their current truck first.
@@ -54,10 +79,17 @@ export class VehiclesService {
       await this.assertDriverUnassigned(dto.assignedDriverId);
     }
 
-    const registrationNumber = `REG-${dto.vehicleType}-${Date.now()}`;
+    const truckType = await this.truckTypes.findById(dto.truckTypeId);
+    this.assertTrailerPlateAllowed(truckType, dto.trailerPlateNo);
+
+    const registrationNumber = `REG-${truckType.code}-${Date.now()}`;
     const vehicle = this.vehicleRepo.create({
       ...dto,
       registrationNumber,
+      // Denormalised for truck-detention billing, which groups on this column.
+      vehicleType: truckType.code,
+      // Capacity belongs to the type; an explicit value still wins for one-offs.
+      capacity: dto.capacity ?? truckType.capacityTons ?? undefined,
     });
 
     const saved = await this.vehicleRepo.save(vehicle);
@@ -148,6 +180,17 @@ export class VehiclesService {
       await this.assertDriverUnassigned(dto.assignedDriverId, id);
     }
 
+    // Re-resolve the truck type whenever the type OR the trailer plate moves —
+    // either edit can produce a rigid truck holding a trailer plate.
+    const nextTruckTypeId = dto.truckTypeId ?? vehicle.truckTypeId;
+    let nextTruckType: TruckType | null = null;
+    if (nextTruckTypeId && (dto.truckTypeId !== undefined || dto.trailerPlateNo !== undefined)) {
+      nextTruckType = await this.truckTypes.findById(nextTruckTypeId);
+      const nextTrailerPlate =
+        dto.trailerPlateNo !== undefined ? dto.trailerPlateNo : vehicle.trailerPlateNo;
+      this.assertTrailerPlateAllowed(nextTruckType, nextTrailerPlate);
+    }
+
     const prev = {
       assignedDriverId: vehicle.assignedDriverId,
       assignedDriverName: vehicle.assignedDriverName,
@@ -156,6 +199,11 @@ export class VehiclesService {
     };
 
     Object.assign(vehicle, dto);
+    // After the patch is applied, so the denormalised billing code always
+    // reflects the type the vehicle actually ends up on.
+    if (nextTruckType) {
+      vehicle.vehicleType = nextTruckType.code;
+    }
     const saved = await this.vehicleRepo.save(vehicle);
 
     // Driver (re)assignment — emit an unassign for the old driver and/or an

apps/edr-freight-api/src/modules/vehicles/vehicles.trailer-plate-guard.spec.ts

@@ -0,0 +1,81 @@
+import { BadRequestException } from '@nestjs/common';
+
+import { VehiclesService } from './vehicles.service';
+
+// A trailer plate only exists on a configuration that pulls a trailer. A rigid
+// truck (Casoni) has none, so registering or editing one into a trailer plate
+// must be refused server-side — the form hiding the field is not enforcement.
+describe('VehiclesService trailer plate guard', () => {
+  const CASONI = { code: 'CASONI', name: 'Casoni (rigid, no trailer)', hasTrailer: false, capacityTons: 30 };
+  const ARTIC = { code: 'TRUCK', name: 'Truck', hasTrailer: true, capacityTons: 40 };
+
+  const makeService = (findOne: jest.Mock, truckType: unknown) => {
+    const save = jest.fn(async (x) => x);
+    const svc = new VehiclesService(
+      { findOne, create: jest.fn((x) => x), save } as any,
+      { record: jest.fn() } as any,
+      { findById: jest.fn(async () => truckType) } as any,
+    );
+    return { svc, save };
+  };
+
+  it('rejects creating a rigid truck that carries a trailer plate', async () => {
+    const findOne = jest.fn().mockResolvedValueOnce(null); // plate is free
+    const { svc } = makeService(findOne, CASONI);
+    await expect(
+      svc.create({ plateNumber: 'ET-9875', truckTypeId: 'tt-casoni', trailerPlateNo: 'ET-1234' } as any),
+    ).rejects.toThrow(BadRequestException);
+  });
+
+  it('accepts a rigid truck with no trailer plate, and takes capacity from the type', async () => {
+    const findOne = jest.fn().mockResolvedValueOnce(null);
+    const { svc } = makeService(findOne, CASONI);
+    const saved = await svc.create({ plateNumber: 'ET-9875', truckTypeId: 'tt-casoni' } as any);
+    expect(saved.capacity).toBe(30);
+    // Denormalised code is what truck-detention billing groups on.
+    expect(saved.vehicleType).toBe('CASONI');
+  });
+
+  it('keeps an explicit capacity over the type default', async () => {
+    const findOne = jest.fn().mockResolvedValueOnce(null);
+    const { svc } = makeService(findOne, CASONI);
+    const saved = await svc.create({
+      plateNumber: 'ET-9875',
+      truckTypeId: 'tt-casoni',
+      capacity: 25,
+    } as any);
+    expect(saved.capacity).toBe(25);
+  });
+
+  it('allows a trailer plate on an articulated type', async () => {
+    const findOne = jest.fn().mockResolvedValueOnce(null);
+    const { svc } = makeService(findOne, ARTIC);
+    await expect(
+      svc.create({ plateNumber: 'ET-9875', truckTypeId: 'tt-truck', trailerPlateNo: 'ET-1234' } as any),
+    ).resolves.toBeDefined();
+  });
+
+  // The regression that motivated validating the RESULT rather than the patch:
+  // switching type alone leaves the stored trailer plate behind.
+  it('rejects switching an existing truck to a rigid type while its trailer plate stands', async () => {
+    const findOne = jest
+      .fn()
+      .mockResolvedValueOnce({ id: 'v1', plateNumber: 'ET-9875', trailerPlateNo: 'ET-1234' });
+    const { svc } = makeService(findOne, CASONI);
+    await expect(svc.update('v1', { truckTypeId: 'tt-casoni' } as any)).rejects.toThrow(
+      BadRequestException,
+    );
+  });
+
+  it('allows the switch when the trailer plate is cleared in the same edit', async () => {
+    const findOne = jest
+      .fn()
+      .mockResolvedValueOnce({ id: 'v1', plateNumber: 'ET-9875', trailerPlateNo: 'ET-1234' });
+    const { svc } = makeService(findOne, CASONI);
+    const saved = await svc.update('v1', {
+      truckTypeId: 'tt-casoni',
+      trailerPlateNo: null,
+    } as any);
+    expect(saved.vehicleType).toBe('CASONI');
+  });
+});

apps/edr-freight-api/src/modules/warehouses/warehouse-fee.service.ts

@@ -791,15 +791,22 @@ export class WarehouseFeeService {
       };
     }
 
-    // Group the leg's vehicles by type so each truck type is billed by its own
-    // matching rule (rates differ by truck type). Falls back to one untyped group.
+    // Group the leg's vehicles by CANONICAL truck type so each type is billed
+    // by its own matching rule (rates differ by truck type). The FK to
+    // truck_types is the source of truth — renaming a type's label no longer
+    // silently unmatches its rule; the normalized legacy vehicle_type code is
+    // only a fallback for vehicles without the FK (LEFT JOIN keeps them billed
+    // instead of dropping them). Falls back to one untyped group.
     const groupRows: Array<{ vehicleType: string | null; truckCount: number | string }> =
       await this.dataSource.query(
-        `SELECT v.vehicle_type AS "vehicleType", count(*)::int AS "truckCount"
+        `SELECT COALESCE(t.code, NULLIF(UPPER(TRIM(v.vehicle_type)), '')) AS "vehicleType",
+                count(*)::int AS "truckCount"
            FROM freight.last_mile_vehicle_assignments va
            JOIN freight.vehicles v ON v.id = va.vehicle_id AND v.deleted_at IS NULL
+           LEFT JOIN freight.truck_types t
+             ON t.id = v.truck_type_id AND t.deleted_at IS NULL
           WHERE va.last_mile_id = $1 AND va.deleted_at IS NULL
-          GROUP BY v.vehicle_type`,
+          GROUP BY 1`,
         [lastMileId],
       );
     const groups = groupRows.length ? groupRows : [{ vehicleType: null, truckCount: 1 }];