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/trains/dto/wagon-detach-request.dto.ts

@@ -0,0 +1,33 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { IsEnum, IsNotEmpty, IsOptional, IsString, MaxLength } from 'class-validator';
+
+import { WagonDetachRequestAction } from '../entities/wagon-detach-request.entity';
+
+export class CreateWagonDetachRequestDto {
+  @ApiProperty({
+    enum: WagonDetachRequestAction,
+    description: 'What approval is being asked for: a plain detach, or detach + MAINTENANCE.',
+  })
+  @IsEnum(WagonDetachRequestAction)
+  action!: WagonDetachRequestAction;
+
+  @ApiProperty({
+    description: 'Why the wagon must leave the scheduled consist. Shown to the approver.',
+    maxLength: 500,
+  })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(500)
+  reason!: string;
+}
+
+export class DecideWagonDetachRequestDto {
+  @ApiPropertyOptional({
+    description: 'Decision note — required when rejecting, optional when approving.',
+    maxLength: 500,
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  note?: string;
+}

apps/edr-freight-api/src/modules/trains/entities/wagon-detach-request.entity.ts

@@ -0,0 +1,69 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index } from 'typeorm';
+
+export enum WagonDetachRequestAction {
+  Detach = 'DETACH',
+  Maintenance = 'MAINTENANCE',
+}
+
+export enum WagonDetachRequestStatus {
+  Pending = 'PENDING',
+  Approved = 'APPROVED',
+  Rejected = 'REJECTED',
+}
+
+/**
+ * Approval gate for detaching a wagon (or sending it to maintenance) from a
+ * train that is on a SCHEDULED run.
+ *
+ * A draft-schedule or unscheduled train is edited freely; once the run is
+ * SCHEDULED, pulling a wagon out changes a departure customers already booked
+ * against, so it becomes a two-person action: one staffer requests with a
+ * reason, another (holding trains:approve_wagon_detach) approves — approval
+ * executes the detach immediately. Rows are never deleted: decided rows are
+ * the audit trail of who asked, who decided, and why.
+ */
+@Entity({ schema: 'freight', name: 'wagon_detach_requests' })
+@Index(['trainId'])
+@Index(['trainId', 'status'])
+export class WagonDetachRequest extends BaseEntity {
+  @Column({ name: 'train_id', type: 'uuid' })
+  trainId!: string;
+
+  @Column({ name: 'wagon_id', type: 'uuid' })
+  wagonId!: string;
+
+  /** Snapshot — the audit trail must read correctly if the wagon is renumbered or deleted. */
+  @Column({ name: 'wagon_number', type: 'varchar', length: 50 })
+  wagonNumber!: string;
+
+  @Column({ name: 'action', type: 'varchar', length: 20 })
+  action!: WagonDetachRequestAction;
+
+  @Column({ name: 'reason', type: 'varchar', length: 500 })
+  reason!: string;
+
+  @Column({
+    name: 'status',
+    type: 'enum',
+    enum: WagonDetachRequestStatus,
+    enumName: 'wagon_detach_requests_status_enum',
+    default: WagonDetachRequestStatus.Pending,
+  })
+  status!: WagonDetachRequestStatus;
+
+  /** IAM user id of the requester. The approver must be a different person. */
+  @Column({ name: 'requested_by', type: 'uuid', nullable: true })
+  requestedBy?: string | null;
+
+  /** IAM user id of the approver/rejecter; null while pending. */
+  @Column({ name: 'decided_by', type: 'uuid', nullable: true })
+  decidedBy?: string | null;
+
+  @Column({ name: 'decided_at', type: 'timestamptz', nullable: true })
+  decidedAt?: Date | null;
+
+  /** Required on reject, optional on approve. */
+  @Column({ name: 'decision_note', type: 'varchar', length: 500, nullable: true })
+  decisionNote?: string | null;
+}

apps/edr-freight-api/src/modules/trains/train-builder.controller.ts

@@ -25,6 +25,10 @@ import { BuildTrainDto } from './dto/build-train.dto';
 import { ListBuiltTrainsQueryDto } from './dto/list-built-trains-query.dto';
 import { ReorderTrainWagonsDto } from './dto/reorder-train-wagons.dto';
 import { SendWagonToMaintenanceDto } from './dto/send-wagon-to-maintenance.dto';
+import {
+  CreateWagonDetachRequestDto,
+  DecideWagonDetachRequestDto,
+} from './dto/wagon-detach-request.dto';
 import { UpdateTrainDetailsDto } from './dto/update-train-details.dto';
 import { UpdateTrainLocomotivesDto } from './dto/update-train-locomotives.dto';
 import { UpdateTrainYardDto } from './dto/update-train-yard.dto';
@@ -47,6 +51,7 @@ import { TrainBuilderService } from './train-builder.service';
   FREIGHT_PERMS.trains.changeWagonYard,
   FREIGHT_PERMS.trains.toggleActive,
   FREIGHT_PERMS.trains.disband,
+  FREIGHT_PERMS.trains.approveWagonDetach,
 ])
 export class TrainBuilderController {
   constructor(private readonly trainBuilderService: TrainBuilderService) {}
@@ -206,6 +211,74 @@ export class TrainBuilderController {
     );
   }
 
+  @Get(':id/detach-requests')
+  @ApiOperation({
+    summary:
+      'Detach/maintenance approval requests of this train, newest first — pending and decided alike (the audit trail)',
+  })
+  detachRequests(@Param('id', ParseUUIDPipe) id: string) {
+    return this.trainBuilderService.listDetachRequests(id);
+  }
+
+  @Post(':id/wagons/:wagonId/detach-requests')
+  @FleetManage(FREIGHT_PERMS.trains.assignWagons)
+  @ApiOperation({
+    summary:
+      'Request approval to detach a wagon (or send it to maintenance) while the train is on a SCHEDULED run',
+  })
+  createDetachRequest(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Param('wagonId', ParseUUIDPipe) wagonId: string,
+    @Body() dto: CreateWagonDetachRequestDto,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    return this.trainBuilderService.createDetachRequest(
+      id,
+      wagonId,
+      dto,
+      resolveAuthUserId(user),
+    );
+  }
+
+  @Post(':id/detach-requests/:requestId/approve')
+  @FleetManage(FREIGHT_PERMS.trains.approveWagonDetach)
+  @ApiOperation({
+    summary:
+      'Approve a detach/maintenance request — the detach executes immediately; the approver must not be the requester',
+  })
+  approveDetachRequest(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Param('requestId', ParseUUIDPipe) requestId: string,
+    @CurrentUser() user: AuthUserPayload,
+    @Body() dto?: DecideWagonDetachRequestDto,
+  ) {
+    return this.trainBuilderService.decideDetachRequest(
+      id,
+      requestId,
+      'APPROVE',
+      resolveAuthUserId(user),
+      dto?.note,
+    );
+  }
+
+  @Post(':id/detach-requests/:requestId/reject')
+  @FleetManage(FREIGHT_PERMS.trains.approveWagonDetach)
+  @ApiOperation({ summary: 'Reject a detach/maintenance request — a note explaining why is required' })
+  rejectDetachRequest(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Param('requestId', ParseUUIDPipe) requestId: string,
+    @CurrentUser() user: AuthUserPayload,
+    @Body() dto: DecideWagonDetachRequestDto,
+  ) {
+    return this.trainBuilderService.decideDetachRequest(
+      id,
+      requestId,
+      'REJECT',
+      resolveAuthUserId(user),
+      dto.note,
+    );
+  }
+
   @Post(':id/reorder-wagons')
   @FleetManage(FREIGHT_PERMS.trains.assignWagons)
   @ApiOperation({ summary: 'Persist a drag-reorder of the full consist' })

apps/edr-freight-api/src/modules/trains/train-builder.service.ts

@@ -30,8 +30,14 @@ import { ListBuiltTrainsQueryDto } from './dto/list-built-trains-query.dto';
 import { ReorderTrainWagonsDto } from './dto/reorder-train-wagons.dto';
 import { UpdateTrainDetailsDto } from './dto/update-train-details.dto';
 import { UpdateTrainLocomotivesDto } from './dto/update-train-locomotives.dto';
+import { CreateWagonDetachRequestDto } from './dto/wagon-detach-request.dto';
 import { TrainLocomotive } from './entities/train-locomotive.entity';
 import { Train } from './entities/train.entity';
+import {
+  WagonDetachRequest,
+  WagonDetachRequestAction,
+  WagonDetachRequestStatus,
+} from './entities/wagon-detach-request.entity';
 import {
   buildPaginationMeta,
   normalizePagination,
@@ -751,32 +757,43 @@ export class TrainBuilderService {
   /** Detach one wagon and close the sequence gap it leaves. */
   async removeWagon(id: string, wagonId: string, userId?: string | null) {
     const pending = await this.dataSource.transaction(async (manager) => {
-      const train = await this.getEditableTrain(manager, id);
-      const wagon = await manager.getRepository(Wagon).findOne({ where: { id: wagonId } });
-      if (!wagon || wagon.trainId !== train.id) {
-        throw new NotFoundException(`Wagon ${wagonId} is not part of this train`);
-      }
-      await this.assertDetachableAndReleaseStaleSlots(manager, wagon);
-      await manager.getRepository(Wagon).update(wagon.id, {
-        trainId: null,
-        sequenceNumber: null,
-        status: WagonStatus.Available,
-        importTrainNumber: null,
-        exportTrainNumber: null,
-      });
-      await this.resequenceWagons(manager, train.id);
-      return this.syncLiveScheduleAfterConsistChange(
-        manager,
-        train.id,
-        [{ action: 'REMOVE', wagonId: wagon.id, wagonNumber: wagon.wagonNumber }],
-        userId ?? null,
-        wagon.currentYardId ?? train.currentYardId ?? null,
-      );
+      await this.assertDetachNeedsNoApproval(manager, id);
+      return this.removeWagonCore(manager, id, wagonId, userId);
     });
     await this.reconcileWindowAfterConsistChange(pending);
     return this.getComposition(id);
   }
 
+  /** Transactional body of removeWagon — also runs under an approved detach request. */
+  private async removeWagonCore(
+    manager: EntityManager,
+    id: string,
+    wagonId: string,
+    userId?: string | null,
+  ): Promise<PendingWindowCheck | null> {
+    const train = await this.getEditableTrain(manager, id);
+    const wagon = await manager.getRepository(Wagon).findOne({ where: { id: wagonId } });
+    if (!wagon || wagon.trainId !== train.id) {
+      throw new NotFoundException(`Wagon ${wagonId} is not part of this train`);
+    }
+    await this.assertDetachableAndReleaseStaleSlots(manager, wagon);
+    await manager.getRepository(Wagon).update(wagon.id, {
+      trainId: null,
+      sequenceNumber: null,
+      status: WagonStatus.Available,
+      importTrainNumber: null,
+      exportTrainNumber: null,
+    });
+    await this.resequenceWagons(manager, train.id);
+    return this.syncLiveScheduleAfterConsistChange(
+      manager,
+      train.id,
+      [{ action: 'REMOVE', wagonId: wagon.id, wagonNumber: wagon.wagonNumber }],
+      userId ?? null,
+      wagon.currentYardId ?? train.currentYardId ?? null,
+    );
+  }
+
   /**
    * Detach one wagon AND flag it for maintenance: it leaves the consist and
    * moves to MAINTENANCE status (not AVAILABLE), so it is not re-coupled until
@@ -789,6 +806,22 @@ export class TrainBuilderService {
     note?: string | null,
   ) {
     const pending = await this.dataSource.transaction(async (manager) => {
+      await this.assertDetachNeedsNoApproval(manager, id);
+      return this.sendWagonToMaintenanceCore(manager, id, wagonId, userId, note);
+    });
+    await this.reconcileWindowAfterConsistChange(pending);
+    return this.getComposition(id);
+  }
+
+  /** Transactional body of sendWagonToMaintenance — also runs under an approved request. */
+  private async sendWagonToMaintenanceCore(
+    manager: EntityManager,
+    id: string,
+    wagonId: string,
+    userId?: string | null,
+    note?: string | null,
+  ): Promise<PendingWindowCheck | null> {
+    {
       const train = await this.getEditableTrain(manager, id);
       const wagon = await manager.getRepository(Wagon).findOne({ where: { id: wagonId } });
       if (!wagon || wagon.trainId !== train.id) {
@@ -851,6 +884,191 @@ export class TrainBuilderService {
         userId ?? null,
         yardId,
       );
+    }
+  }
+
+  /**
+   * Direct-detach guard: while this train carries a live SCHEDULED run,
+   * removing a wagon changes a departure customers already booked against, so
+   * it is a two-person action — refuse here and point at the request flow.
+   * DRAFT stays freely editable; DISPATCHED is already frozen by
+   * getEditableTrain (the train is IN_SERVICE).
+   */
+  private async assertDetachNeedsNoApproval(
+    manager: EntityManager,
+    trainId: string,
+  ): Promise<void> {
+    const scheduled = await this.findScheduledRun(manager, trainId);
+    if (scheduled) {
+      throw new ConflictException(
+        `Train is on scheduled run ${scheduled.reference ?? scheduled.id} — detaching a wagon needs an approved detach request`,
+      );
+    }
+  }
+
+  private async findScheduledRun(
+    manager: EntityManager,
+    trainId: string,
+  ): Promise<{ id: string; reference: string | null } | null> {
+    const rows: { id: string; reference: string | null }[] = await manager.query(
+      `SELECT ts.id, ts.reference
+         FROM freight.train_schedules ts
+         JOIN freight.train_sets tset ON tset.id = ts.train_set_id
+        WHERE tset.train_id = $1
+          AND ts.status = 'SCHEDULED'
+          AND ts.deleted_at IS NULL
+        LIMIT 1`,
+      [trainId],
+    );
+    return rows[0] ?? null;
+  }
+
+  /**
+   * File a detach/maintenance approval request for a wagon on a SCHEDULED
+   * train. The request carries the reason; a different staffer with
+   * trains:approve_wagon_detach decides it (approval executes the detach).
+   */
+  async createDetachRequest(
+    id: string,
+    wagonId: string,
+    dto: CreateWagonDetachRequestDto,
+    userId?: string | null,
+  ) {
+    return this.dataSource.transaction(async (manager) => {
+      const train = await this.getEditableTrain(manager, id);
+      const wagon = await manager.getRepository(Wagon).findOne({ where: { id: wagonId } });
+      if (!wagon || wagon.trainId !== train.id) {
+        throw new NotFoundException(`Wagon ${wagonId} is not part of this train`);
+      }
+      const scheduled = await this.findScheduledRun(manager, train.id);
+      if (!scheduled) {
+        throw new ConflictException(
+          'This train has no SCHEDULED run — detach the wagon directly, no approval needed',
+        );
+      }
+      // Refuse up front what an approval could never execute (booked
+      // allocations pin the wagon) — but release nothing yet: slots are only
+      // touched when the approved detach actually runs.
+      await this.assertDetachableAndReleaseStaleSlots(manager, wagon, { checkOnly: true });
+      const repo = manager.getRepository(WagonDetachRequest);
+      const open = await repo.findOne({
+        where: { trainId: train.id, wagonId: wagon.id, status: WagonDetachRequestStatus.Pending },
+      });
+      if (open) {
+        throw new ConflictException(
+          `Wagon ${wagon.wagonNumber} already has a pending detach request`,
+        );
+      }
+      return repo.save(
+        repo.create({
+          trainId: train.id,
+          wagonId: wagon.id,
+          wagonNumber: wagon.wagonNumber,
+          action: dto.action,
+          reason: dto.reason.trim(),
+          requestedBy: userId ?? null,
+        }),
+      );
+    });
+  }
+
+  /** All detach/maintenance requests of this train, newest first — the approval audit trail. */
+  async listDetachRequests(trainId: string) {
+    const rows: Array<{
+      id: string;
+      wagonId: string;
+      wagonNumber: string;
+      action: string;
+      reason: string;
+      status: string;
+      requestedById: string | null;
+      requestedBy: string | null;
+      requestedAt: Date;
+      decidedBy: string | null;
+      decidedAt: Date | null;
+      decisionNote: string | null;
+    }> = await this.dataSource.query(
+      `SELECT r.id,
+              r.wagon_id AS "wagonId",
+              r.wagon_number AS "wagonNumber",
+              r.action,
+              r.reason,
+              r.status,
+              r.requested_by AS "requestedById",
+              COALESCE(ru.username, ru.email) AS "requestedBy",
+              r.created_at AS "requestedAt",
+              COALESCE(du.username, du.email) AS "decidedBy",
+              r.decided_at AS "decidedAt",
+              r.decision_note AS "decisionNote"
+         FROM freight.wagon_detach_requests r
+         LEFT JOIN iam.users ru ON ru.id = r.requested_by
+         LEFT JOIN iam.users du ON du.id = r.decided_by
+        WHERE r.train_id = $1
+          AND r.deleted_at IS NULL
+        ORDER BY r.created_at DESC
+        LIMIT 100`,
+      [trainId],
+    );
+    return rows;
+  }
+
+  /**
+   * Decide a pending request. Approve executes the detach (or maintenance
+   * move) in the same transaction that stamps the decision, so an approved row
+   * can never exist without its detach having happened. The requester cannot
+   * approve their own request; a rejection must carry a note.
+   */
+  async decideDetachRequest(
+    id: string,
+    requestId: string,
+    decision: 'APPROVE' | 'REJECT',
+    userId?: string | null,
+    note?: string | null,
+  ) {
+    const pending = await this.dataSource.transaction(async (manager) => {
+      const repo = manager.getRepository(WagonDetachRequest);
+      const request = await repo.findOne({
+        where: { id: requestId, trainId: id },
+        lock: { mode: 'pessimistic_write' },
+      });
+      if (!request) {
+        throw new NotFoundException(`Detach request ${requestId} not found on this train`);
+      }
+      if (request.status !== WagonDetachRequestStatus.Pending) {
+        throw new ConflictException(
+          `This request was already ${request.status.toLowerCase()}`,
+        );
+      }
+      const decisionNote = note?.trim() || null;
+      if (decision === 'REJECT') {
+        if (!decisionNote) {
+          throw new BadRequestException('A note explaining the rejection is required');
+        }
+        await repo.update(request.id, {
+          status: WagonDetachRequestStatus.Rejected,
+          decidedBy: userId ?? null,
+          decidedAt: new Date(),
+          decisionNote,
+        });
+        return null;
+      }
+      // The 4-eyes point of the gate: requester and approver are different people.
+      if (request.requestedBy && userId && request.requestedBy === userId) {
+        throw new ConflictException(
+          'You filed this request — a different staff member must approve it',
+        );
+      }
+      const pendingCheck =
+        request.action === WagonDetachRequestAction.Maintenance
+          ? await this.sendWagonToMaintenanceCore(manager, id, request.wagonId, userId, request.reason)
+          : await this.removeWagonCore(manager, id, request.wagonId, userId);
+      await repo.update(request.id, {
+        status: WagonDetachRequestStatus.Approved,
+        decidedBy: userId ?? null,
+        decidedAt: new Date(),
+        decisionNote,
+      });
+      return pendingCheck;
     });
     await this.reconcileWindowAfterConsistChange(pending);
     return this.getComposition(id);
@@ -893,6 +1111,7 @@ export class TrainBuilderService {
   private async assertDetachableAndReleaseStaleSlots(
     manager: EntityManager,
     wagon: Wagon,
+    opts: { checkOnly?: boolean } = {},
   ): Promise<void> {
     const rows: { id: string; train_set_id: string; status: string; allocs: string }[] =
       await manager.query(
@@ -915,6 +1134,7 @@ export class TrainBuilderService {
         `Wagon ${wagon.wagonNumber} is pinned to an active schedule and cannot be removed`,
       );
     }
+    if (opts.checkOnly) return;
     await manager.getRepository(TrainSetWagon).delete(rows.map((r) => r.id));
     for (const trainSetId of [...new Set(rows.map((r) => r.train_set_id))]) {
       const remaining = await manager.getRepository(TrainSetWagon).find({

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

@@ -4,13 +4,17 @@ import { TypeOrmModule } from '@nestjs/typeorm';
 import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.module';
 import { TrainLocomotive } from './entities/train-locomotive.entity';
 import { Train } from './entities/train.entity';
+import { WagonDetachRequest } from './entities/wagon-detach-request.entity';
 import { TrainBuilderController } from './train-builder.controller';
 import { TrainBuilderService } from './train-builder.service';
 import { TrainsController } from './trains.controller';
 import { TrainsService } from './trains.service';
 
 @Module({
-  imports: [TypeOrmModule.forFeature([Train, TrainLocomotive]), TrainSchedulingModule],
+  imports: [
+    TypeOrmModule.forFeature([Train, TrainLocomotive, WagonDetachRequest]),
+    TrainSchedulingModule,
+  ],
   controllers: [TrainsController, TrainBuilderController],
   providers: [TrainsService, TrainBuilderService],
   exports: [TrainsService, TrainBuilderService],