feat(train-scheduling): load returned empties onto an export train

Empties had no way onto a departure: the return record could name a train
but nothing seated it on a wagon. Export schedules now expose a loading
action that packs selected returns onto free wagons at one 40ft or two 20ft
each, enforced both in the picker and in the API (existing empties on the
schedule count against their wagon).

Adds container_size, train_schedule_id and wagon_sequence_no to
freight.empty_container_returns.

apps/edr-freight-api/src/migrations/3540000000000-EmptyReturnTrainLoad.ts

@@ -0,0 +1,35 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Empty containers ride an export departure back to Djibouti, so a return now
+ * records which train schedule carries it and on which wagon slot. Size is
+ * captured too: the wagon rule is one 40ft OR two 20ft per wagon, which cannot
+ * be enforced without knowing the box size.
+ */
+export class EmptyReturnTrainLoad3540000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.empty_container_returns
+        ADD COLUMN IF NOT EXISTS container_size character varying(10),
+        ADD COLUMN IF NOT EXISTS train_schedule_id uuid,
+        ADD COLUMN IF NOT EXISTS wagon_sequence_no integer
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_empty_container_returns_train_schedule_id
+        ON freight.empty_container_returns (train_schedule_id)
+        WHERE train_schedule_id IS NOT NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      DROP INDEX IF EXISTS freight.idx_empty_container_returns_train_schedule_id
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.empty_container_returns
+        DROP COLUMN IF EXISTS container_size,
+        DROP COLUMN IF EXISTS train_schedule_id,
+        DROP COLUMN IF EXISTS wagon_sequence_no
+    `);
+  }
+}

apps/edr-freight-api/src/modules/import-operations/dto/import-operations.dto.ts

@@ -1,5 +1,17 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsArray, IsDateString, IsIn, IsOptional, IsString, IsUUID } from 'class-validator';
+import { Type } from 'class-transformer';
+import {
+  ArrayNotEmpty,
+  IsArray,
+  IsDateString,
+  IsIn,
+  IsInt,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Min,
+  ValidateNested,
+} from 'class-validator';
 
 import { DJIBOUTI_INCIDENT_TYPES, type DjiboutiIncidentType } from '../entities/djibouti-incident.entity';
 import {
@@ -120,6 +132,9 @@ export class ImportOperationActionDto {
   notes?: string;
 }
 
+export const EMPTY_CONTAINER_SIZES = ['20', '40'] as const;
+export type EmptyContainerSize = (typeof EMPTY_CONTAINER_SIZES)[number];
+
 export class CreateEmptyContainerReturnDto {
   @ApiProperty()
   @IsString()
@@ -140,6 +155,11 @@ export class CreateEmptyContainerReturnDto {
   @IsDateString()
   returnDate?: string;
 
+  @ApiPropertyOptional({ enum: EMPTY_CONTAINER_SIZES })
+  @IsOptional()
+  @IsIn(EMPTY_CONTAINER_SIZES)
+  containerSize?: EmptyContainerSize;
+
   @ApiPropertyOptional()
   @IsOptional()
   @IsString()
@@ -176,6 +196,39 @@ export class CreateEmptyContainerReturnDto {
   returnedBy?: 'EDR' | 'CUSTOMER';
 }
 
+export class LoadEmptyContainerItemDto {
+  @ApiProperty({ format: 'uuid' })
+  @IsUUID()
+  id!: string;
+
+  @ApiProperty({ enum: EMPTY_CONTAINER_SIZES })
+  @IsIn(EMPTY_CONTAINER_SIZES)
+  containerSize!: EmptyContainerSize;
+
+  @ApiProperty()
+  @IsInt()
+  @Min(1)
+  wagonSequenceNo!: number;
+}
+
+export class LoadEmptyContainersOnTrainDto extends ImportOperationActionDto {
+  @ApiProperty({ format: 'uuid' })
+  @IsUUID()
+  trainScheduleId!: string;
+
+  @ApiPropertyOptional({ description: 'Run number shown on the return record.' })
+  @IsOptional()
+  @IsString()
+  trainNumber?: string;
+
+  @ApiProperty({ type: [LoadEmptyContainerItemDto] })
+  @IsArray()
+  @ArrayNotEmpty()
+  @ValidateNested({ each: true })
+  @Type(() => LoadEmptyContainerItemDto)
+  items!: LoadEmptyContainerItemDto[];
+}
+
 export class UpdateEmptyContainerReturnStatusDto extends ImportOperationActionDto {
   @ApiProperty({ enum: EMPTY_CONTAINER_RETURN_STATUSES })
   @IsIn(EMPTY_CONTAINER_RETURN_STATUSES)

apps/edr-freight-api/src/modules/import-operations/empty-container-wagon.util.spec.ts

@@ -0,0 +1,23 @@
+import { assertWagonLoad } from './empty-container-wagon.util';
+
+describe('assertWagonLoad', () => {
+  it('accepts one 40ft or two 20ft per wagon', () => {
+    expect(() =>
+      assertWagonLoad(
+        new Map([
+          [1, ['40']],
+          [2, ['20', '20']],
+          [3, ['20']],
+        ]),
+      ),
+    ).not.toThrow();
+  });
+
+  it('rejects a 40ft sharing a wagon', () => {
+    expect(() => assertWagonLoad(new Map([[4, ['40', '20']]]))).toThrow(/Wagon 4/);
+  });
+
+  it('rejects three containers on a wagon', () => {
+    expect(() => assertWagonLoad(new Map([[5, ['20', '20', '20']]]))).toThrow(/Wagon 5/);
+  });
+});

apps/edr-freight-api/src/modules/import-operations/empty-container-wagon.util.ts

@@ -0,0 +1,16 @@
+import { BadRequestException } from '@nestjs/common';
+
+/**
+ * A wagon carries ONE 40ft OR TWO 20ft empties — never a mix, never three.
+ * Throws on the first wagon that breaks the rule.
+ */
+export function assertWagonLoad(sizesByWagon: Map<number, string[]>): void {
+  for (const [wagon, sizes] of sizesByWagon) {
+    const has40 = sizes.some((size) => size === '40');
+    if ((has40 && sizes.length > 1) || sizes.length > 2) {
+      throw new BadRequestException(
+        `Wagon ${wagon} takes one 40ft or two 20ft containers — got ${sizes.join('ft + ')}ft`,
+      );
+    }
+  }
+}

apps/edr-freight-api/src/modules/import-operations/entities/empty-container-return.entity.ts

@@ -51,6 +51,17 @@ export class EmptyContainerReturn extends BaseEntity {
   @Column({ name: 'wagon_allocation_reference', type: 'varchar', length: 120, nullable: true })
   wagonAllocationReference?: string | null;
 
+  /** '20' or '40' — drives the one-40ft-or-two-20ft-per-wagon loading rule. */
+  @Column({ name: 'container_size', type: 'varchar', length: 10, nullable: true })
+  containerSize?: string | null;
+
+  /** Export departure carrying this empty back to Djibouti. */
+  @Column({ name: 'train_schedule_id', type: 'uuid', nullable: true })
+  trainScheduleId?: string | null;
+
+  @Column({ name: 'wagon_sequence_no', type: 'int', nullable: true })
+  wagonSequenceNo?: number | null;
+
   @Column({ name: 'performed_by', type: 'varchar', length: 120, nullable: true })
   performedBy?: string | null;
 

apps/edr-freight-api/src/modules/import-operations/import-operations.controller.ts

@@ -8,6 +8,7 @@ import {
   CreateDjiboutiIncidentDto,
   CreateEmptyContainerReturnDto,
   ImportOperationActionDto,
+  LoadEmptyContainersOnTrainDto,
   RecordDeclarationDto,
   UpdateEmptyContainerReturnStatusDto,
   UploadImportCustomsDocumentDto,
@@ -104,6 +105,14 @@ export class ImportOperationsController {
     return this.service.createEmptyReturn(dto);
   }
 
+  @Post('empty-container-returns/load-on-train')
+  @ApiOperation({
+    summary: 'Load returned empties onto an export train (1×40ft or 2×20ft per wagon)',
+  })
+  loadEmptyReturnsOnTrain(@Body() dto: LoadEmptyContainersOnTrainDto) {
+    return this.service.loadEmptyReturnsOnTrain(dto);
+  }
+
   @Post('empty-container-returns/:id/status')
   @ApiOperation({ summary: 'Batch 16: advance empty container return workflow' })
   updateEmptyReturnStatus(

apps/edr-freight-api/src/modules/import-operations/import-operations.service.ts

@@ -1,11 +1,12 @@
 import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { Repository } from 'typeorm';
+import { In, Repository } from 'typeorm';
 
 import {
   CreateDjiboutiIncidentDto,
   CreateEmptyContainerReturnDto,
   ImportOperationActionDto,
+  LoadEmptyContainersOnTrainDto,
   RecordDeclarationDto,
   AssignCustomsRiskDto,
   UpdateEmptyContainerReturnStatusDto,
@@ -15,6 +16,7 @@ import {
   DjiboutiIncident,
   type DjiboutiIncidentType,
 } from './entities/djibouti-incident.entity';
+import { assertWagonLoad } from './empty-container-wagon.util';
 import { EmptyContainerReturn } from './entities/empty-container-return.entity';
 import {
   ImportCustomsFinalization,
@@ -156,6 +158,7 @@ export class ImportOperationsService {
         bookingId: dto.bookingId ?? null,
         customerId: dto.customerId ?? null,
         returnDate,
+        containerSize: dto.containerSize ?? null,
         facility: dto.facility ?? null,
         yard: dto.yard ?? null,
         zone: dto.zone ?? null,
@@ -170,6 +173,63 @@ export class ImportOperationsService {
     );
   }
 
+  /**
+   * Load returned empties onto an export departure. A wagon takes ONE 40ft or
+   * TWO 20ft — never a mix, never three. Empties already sitting on a wagon of
+   * the same schedule count against that wagon, so incremental loads cannot
+   * quietly double-book a slot.
+   *
+   * ponytail: does not check the wagon is free of cargo bookings — the loading
+   * UI picks only unallocated wagons from the schedule's plan. Cross-check here
+   * if empties ever get loaded from another client.
+   */
+  async loadEmptyReturnsOnTrain(dto: LoadEmptyContainersOnTrainDto) {
+    const ids = dto.items.map((item) => item.id);
+    const rows = await this.emptyReturns.find({ where: { id: In(ids) } });
+    const missing = ids.filter((id) => !rows.some((row) => row.id === id));
+    if (missing.length) {
+      throw new NotFoundException(`Empty container return(s) not found: ${missing.join(', ')}`);
+    }
+
+    const alreadyOnTrain = await this.emptyReturns.find({
+      where: { trainScheduleId: dto.trainScheduleId },
+    });
+    const byWagon = new Map<number, string[]>();
+    for (const row of alreadyOnTrain) {
+      if (row.wagonSequenceNo == null || ids.includes(row.id)) continue;
+      byWagon.set(row.wagonSequenceNo, [
+        ...(byWagon.get(row.wagonSequenceNo) ?? []),
+        row.containerSize ?? '40',
+      ]);
+    }
+    for (const item of dto.items) {
+      byWagon.set(item.wagonSequenceNo, [
+        ...(byWagon.get(item.wagonSequenceNo) ?? []),
+        item.containerSize,
+      ]);
+    }
+    assertWagonLoad(byWagon);
+
+    const changedAt = new Date().toISOString();
+    for (const item of dto.items) {
+      const row = rows.find((candidate) => candidate.id === item.id)!;
+      await this.emptyReturns.update(item.id, {
+        status: 'WAGON_ALLOCATED',
+        containerSize: item.containerSize,
+        trainScheduleId: dto.trainScheduleId,
+        wagonSequenceNo: item.wagonSequenceNo,
+        wagonAllocationReference: dto.trainNumber ?? dto.trainScheduleId,
+        performedBy: dto.performedBy ?? row.performedBy ?? null,
+        statusHistory: [
+          ...(row.statusHistory ?? []),
+          { status: 'WAGON_ALLOCATED' as const, changedAt, performedBy: dto.performedBy ?? null },
+        ],
+      });
+    }
+
+    return this.emptyReturns.find({ where: { trainScheduleId: dto.trainScheduleId } });
+  }
+
   async updateEmptyReturnStatus(id: string, dto: UpdateEmptyContainerReturnStatusDto) {
     const row = await this.emptyReturns.findOne({ where: { id } });
     if (!row) {