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

Freight feature/usermanagement

apps/edr-freight-api/src/modules/bookings/booking-transition.accept.spec.ts

@@ -37,7 +37,7 @@ describe('BookingTransitionService — acceptIntake validity window', () => {
       {} as never, // fileUploadSettingsService
       {} as never, // bookingBatchService
       bookingsService as never,
-      { isPhasedGeneralCustomsBooking: () => false } as never,
+      { isPhasedCustomsBooking: () => false } as never,
       {} as never, // workflowService
       {} as never, // invoiceService
       { validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
@@ -59,6 +59,7 @@ describe('BookingTransitionService — acceptIntake validity window', () => {
         clearanceDocsUploadedToStaff: jest.fn(),
         dutySlipUploadedToStaff: jest.fn(),
       } as never, // notifier
+      { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository, ruleEngineService, contractService };
   }

apps/edr-freight-api/src/modules/bookings/booking-transition.clearance.spec.ts

@@ -46,7 +46,7 @@ describe('BookingTransitionService — finalizeClearance gate', () => {
       fileUploadSettingsService as never,
       {} as never, // bookingBatchService
       bookingsService as never,
-      { isPhasedGeneralCustomsBooking: () => false } as never,
+      { isPhasedCustomsBooking: () => false } as never,
       {} as never, // workflowService
       {} as never, // invoiceService
       { validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
@@ -68,6 +68,7 @@ describe('BookingTransitionService — finalizeClearance gate', () => {
         clearanceDocsUploadedToStaff: jest.fn(),
         dutySlipUploadedToStaff: jest.fn(),
       } as never, // notifier
+      { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository };
   }
@@ -149,7 +150,7 @@ describe('BookingTransitionService — finalizeClearance customs output gate', (
       fileUploadSettingsService as never,
       {} as never, // bookingBatchService
       bookingsService as never,
-      { isPhasedGeneralCustomsBooking: () => false } as never,
+      { isPhasedCustomsBooking: () => false } as never,
       {} as never, // workflowService
       {} as never, // invoiceService
       { validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
@@ -171,6 +172,7 @@ describe('BookingTransitionService — finalizeClearance customs output gate', (
         clearanceDocsUploadedToStaff: jest.fn(),
         dutySlipUploadedToStaff: jest.fn(),
       } as never, // notifier
+      { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository };
   }
@@ -238,7 +240,7 @@ describe('BookingTransitionService — submitClearanceDocuments required-fields
       fileUploadSettingsService as never,
       {} as never, // bookingBatchService
       bookingsService as never,
-      { isPhasedGeneralCustomsBooking: () => false } as never,
+      { isPhasedCustomsBooking: () => false } as never,
       {} as never, // workflowService
       {} as never, // invoiceService
       { validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
@@ -260,6 +262,7 @@ describe('BookingTransitionService — submitClearanceDocuments required-fields
         clearanceDocsUploadedToStaff: jest.fn(),
         dutySlipUploadedToStaff: jest.fn(),
       } as never, // notifier
+      { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository, filesService };
   }

apps/edr-freight-api/src/modules/bookings/booking-transition.operation.spec.ts

@@ -48,7 +48,7 @@ describe('BookingTransitionService — operation review', () => {
       {} as never, // fileUploadSettingsService
       bookingBatchService as never,
       bookingsService as never,
-      { isPhasedGeneralCustomsBooking: () => false } as never,
+      { isPhasedCustomsBooking: () => false } as never,
       {} as never, // workflowService
       invoiceService as never,
       { validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
@@ -70,6 +70,7 @@ describe('BookingTransitionService — operation review', () => {
         clearanceDocsUploadedToStaff: jest.fn(),
         dutySlipUploadedToStaff: jest.fn(),
       } as never, // notifier
+      { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository, bookingBatchService, invoiceService };
   }
@@ -164,11 +165,12 @@ describe('BookingTransitionService — requestOperation export space gate', () =
       {} as never, // fileUploadSettingsService
       bookingBatchService as never,
       bookingsService as never,
-      { isPhasedGeneralCustomsBooking: () => false } as never,
+      { isPhasedCustomsBooking: () => false } as never,
       {} as never, // workflowService
       {} as never, // invoiceService
       { validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
       notifier as never,
+      { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository, bookingBatchService };
   }

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

@@ -7,7 +7,7 @@ import {
   Logger,
   Optional,
 } from "@nestjs/common";
-import { OnEvent } from "@nestjs/event-emitter";
+import { EventEmitter2, OnEvent } from "@nestjs/event-emitter";
 
 import { BookingBatchService } from '../train-scheduling/booking-batch.service';
 import { eatDay } from '../train-scheduling/batch-window.util';
@@ -56,11 +56,12 @@ export class BookingTransitionService {
         private readonly invoiceService: BookingInvoiceService,
     private readonly containerValidationService: ContainerValidationService,
     private readonly notifier: BookingLifecycleNotifierService,
+    private readonly events: EventEmitter2,
     @Optional() private readonly milestoneService?: ClearanceMilestoneService,
   ) {}
 
-  private isPhasedGeneralCustoms(booking: Booking): boolean {
-    return this.bookingClearanceService.isPhasedGeneralCustomsBooking(booking);
+  private isPhasedCustoms(booking: Booking): boolean {
+    return this.bookingClearanceService.isPhasedCustomsBooking(booking);
   }
 
   /** Reject submit when the booking's 20ft containers can't be balanced onto wagons. */
@@ -376,6 +377,8 @@ export class BookingTransitionService {
     } as never);
     const fresh = await this.bookingsService.findById(updated!.id);
     this.notifier.completed(fresh);
+    // A ONE_TIME contract closes on its single shipment being delivered.
+    this.events.emit('booking.completed', { bookingId });
     // Customer tracking: close out the tail milestones so a finished shipment
     // never shows a forever-pending timeline. EXIT_NOTE/PROCESS_COMPLETED are
     // implied by delivery; a storage invoice that was never raised is skipped
@@ -491,7 +494,7 @@ export class BookingTransitionService {
     operationReady?: boolean;
   }> {
     const booking = await this.bookingsService.findById(bookingId);
-    if (this.isPhasedGeneralCustoms(booking)) {
+    if (this.isPhasedCustoms(booking)) {
       return this.bookingClearanceService.getClearanceView(bookingId);
     }
     const { inputCode, outputCode, includesCustoms } =
@@ -650,7 +653,7 @@ export class BookingTransitionService {
       status: "DOCUMENTS_UNDER_REVIEW",
     } as never);
 
-    if (this.isPhasedGeneralCustoms(booking)) {
+    if (this.isPhasedCustoms(booking)) {
       await this.workflowService.onCustomerDocsUploadedForBooking(
         bookingId,
         booking.tradeDirection ?? 'IMPORT',
@@ -732,7 +735,7 @@ export class BookingTransitionService {
     }
     if (
       status === 'QUERIED' &&
-      this.isPhasedGeneralCustoms(booking) &&
+      this.isPhasedCustoms(booking) &&
       booking.preClearanceFinalizedAt
     ) {
       throw new BadRequestException(
@@ -755,7 +758,7 @@ export class BookingTransitionService {
         "CHANGES_REQUESTED",
         staffId,
       );
-      if (this.isPhasedGeneralCustoms(booking)) {
+      if (this.isPhasedCustoms(booking)) {
         await this.workflowService.onDocumentReviewReopenedForBooking(bookingId);
         await this.bookingsRepository.update(bookingId, {
           clearanceCurrentPhase: ContractDocPhase.GlEtReview,
@@ -767,7 +770,7 @@ export class BookingTransitionService {
     if (status === "QUERIED") {
       this.notifier.documentQueried(updated, fileKey, note ?? '');
     }
-    if (this.isPhasedGeneralCustoms(updated)) {
+    if (this.isPhasedCustoms(updated)) {
       const allApproved = await this.isClearanceFullyApproved(updated);
       if (allApproved) {
         await this.workflowService.onAllDocsApprovedForBooking(bookingId);
@@ -817,7 +820,7 @@ export class BookingTransitionService {
    */
   async finalizeClearance(bookingId: string): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
-    if (this.isPhasedGeneralCustoms(booking)) {
+    if (this.isPhasedCustoms(booking)) {
       throw new BadRequestException(
         'General customs bookings use phased clearance — complete milestones via the phased actions instead of finalize.',
       );

apps/edr-freight-api/src/modules/bookings/bookings.repository.ts

@@ -1,8 +1,16 @@
 import { BaseRepository } from '@edr/api-common';
 import { SchedulingStatus } from '@edr/types';
-import { Injectable } from '@nestjs/common';
+import { ConflictException, Injectable } from '@nestjs/common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { DataSource, EntityManager, FindOptionsWhere, In, Repository, SelectQueryBuilder } from 'typeorm';
+import {
+  DataSource,
+  DeepPartial,
+  EntityManager,
+  FindOptionsWhere,
+  In,
+  Repository,
+  SelectQueryBuilder,
+} from 'typeorm';
 
 import { wagonsPerUnitForSize } from '../rule-engine/container-type.util';
 import { ContainerType } from '../rule-engine/entities/container-type.entity';
@@ -26,6 +34,22 @@ import {
 import { FileRecord } from '../files/entities/file.entity';
 import { ContainerWeightResult } from '../rule-engine/rule-engine.service';
 
+/** A booking is ready for a batch: commercial = signed, government = approved/paid. */
+const BATCH_POOL_READY = `((booking.is_government = false AND booking.status = 'FULLY_EXECUTED')
+  OR (booking.is_government = true AND booking.status IN ('APPROVED','PAID')))`;
+
+/**
+ * Suspending a contract freezes its bookings, so they drop out of every
+ * scheduling pool. Filtering here (rather than letting the write guard throw)
+ * keeps the batch crons quiet — a frozen contract simply stops being a
+ * candidate until the suspension is lifted.
+ */
+const NOT_ON_SUSPENDED_CONTRACT = `(booking.contract_id IS NULL
+  OR NOT EXISTS (
+    SELECT 1 FROM freight.contracts c
+    WHERE c.id = booking.contract_id AND c.status = 'SUSPENDED'
+  ))`;
+
 export interface BookingListFilterOptions {
   statuses?: string[];
   status?: string;
@@ -68,6 +92,42 @@ export class BookingsRepository extends BaseRepository<Booking> {
     return this.repository.findOne({ where: { reference } });
   }
 
+  /**
+   * Suspending a contract freezes its bookings too, so the single write path
+   * every booking mutation funnels through is the place to enforce it — one
+   * guard instead of one per transition method.
+   *
+   * The batch/scheduling pools filter suspended contracts out up front
+   * (see {@link excludeSuspendedContract}), so the engine and its crons never
+   * reach a frozen booking and this only ever fires on a user-initiated action.
+   *
+   * ponytail: the seven `manager.getRepository(Booking)` writes inside
+   * train-scheduling transactions bypass this — they only run on bookings the
+   * pool already handed out, which the filter above has excluded. Move them onto
+   * this repository if that ever stops holding.
+   */
+  private async assertContractNotSuspended(id: string): Promise<void> {
+    const row = await this.repository
+      .createQueryBuilder('booking')
+      .select('contract.status', 'status')
+      .innerJoin(Contract, 'contract', 'contract.id = booking.contract_id')
+      .where('booking.id = :id', { id })
+      .getRawOne<{ status: string }>();
+    if (row?.status === 'SUSPENDED') {
+      throw new ConflictException(
+        'This shipment belongs to a suspended contract. EDR must lift the suspension before it can move.',
+      );
+    }
+  }
+
+  override async update(
+    id: string,
+    data: DeepPartial<Booking>,
+  ): Promise<Booking | null> {
+    await this.assertContractNotSuspended(id);
+    return super.update(id, data);
+  }
+
   /**
    * Highest NNNNNN sequence already issued for `BK-<year>-…` references.
    * Includes soft-deleted bookings so the next number clears references that
@@ -1032,7 +1092,8 @@ export class BookingsRepository extends BaseRepository<Booking> {
         'scheduleBooking.booking_id = booking.id',
       )
       .where('booking.status = :paidStatus', { paidStatus: 'PAID' })
-      .andWhere('scheduleBooking.id IS NULL');
+      .andWhere('scheduleBooking.id IS NULL')
+      .andWhere(NOT_ON_SUSPENDED_CONTRACT);
 
     // Day-level pooling: customers no longer set train_schedule_id, so the wizard
     // surfaces the whole (route, EAT day) pool. Fall back to the legacy
@@ -1091,10 +1152,8 @@ export class BookingsRepository extends BaseRepository<Booking> {
       .leftJoin(TrainScheduleBooking, 'sb', 'sb.booking_id = booking.id')
       .where('booking.train_schedule_id = :scheduleId', { scheduleId })
       .andWhere('sb.id IS NULL')
-      .andWhere(
-        `((booking.is_government = false AND booking.status = 'FULLY_EXECUTED')
-          OR (booking.is_government = true AND booking.status IN ('APPROVED','PAID')))`,
-      )
+      .andWhere(BATCH_POOL_READY)
+      .andWhere(NOT_ON_SUSPENDED_CONTRACT)
       .orderBy('booking.is_government', 'DESC')
       .addOrderBy('booking.priority_score', 'DESC')
       .addOrderBy('booking.fully_executed_at', 'ASC')
@@ -1130,10 +1189,8 @@ export class BookingsRepository extends BaseRepository<Booking> {
         { day },
       )
       .andWhere('sb.id IS NULL')
-      .andWhere(
-        `((booking.is_government = false AND booking.status = 'FULLY_EXECUTED')
-          OR (booking.is_government = true AND booking.status IN ('APPROVED','PAID')))`,
-      )
+      .andWhere(BATCH_POOL_READY)
+      .andWhere(NOT_ON_SUSPENDED_CONTRACT)
       .orderBy('booking.is_government', 'DESC')
       .addOrderBy('booking.priority_score', 'DESC')
       .addOrderBy('booking.fully_executed_at', 'ASC')
@@ -1170,10 +1227,8 @@ export class BookingsRepository extends BaseRepository<Booking> {
         { day },
       )
       .andWhere('sb.id IS NULL')
-      .andWhere(
-        `((booking.is_government = false AND booking.status = 'FULLY_EXECUTED')
-          OR (booking.is_government = true AND booking.status IN ('APPROVED','PAID')))`,
-      )
+      .andWhere(BATCH_POOL_READY)
+      .andWhere(NOT_ON_SUSPENDED_CONTRACT)
       .orderBy('booking.is_government', 'DESC')
       .addOrderBy('booking.priority_score', 'DESC')
       .addOrderBy('booking.fully_executed_at', 'ASC')

apps/edr-freight-api/src/modules/bookings/clearance.util.spec.ts

@@ -62,13 +62,15 @@ describe('clearance.util — clearanceCodesForBooking (intercity)', () => {
     expect(direct.inputCode).toBe(INTERCITY_DOCUMENTS_SETTING_CODE);
   });
 
-  it('ONE_TIME contract drawdowns skip the per-booking set (contract collected it)', () => {
+  it('ONE_TIME contract shipments carry the same per-booking set', () => {
+    // Contracts no longer collect clearance documents — every shipment does,
+    // whatever kind of contract it draws on.
     const drawdown = clearanceCodesForBooking({
       ...base,
       contractId: 'c1',
       contractKind: 'ONE_TIME',
     } as unknown as Booking);
-    expect(drawdown.inputCode).toBeNull();
+    expect(drawdown.inputCode).toBe(INTERCITY_DOCUMENTS_SETTING_CODE);
     expect(drawdown.outputCode).toBeNull();
   });
 });

apps/edr-freight-api/src/modules/bookings/clearance.util.ts

@@ -11,9 +11,8 @@ type Freight = 'container' | 'bulk';
 
 /**
  * The single (admin-configured) document set intercity shipments upload.
- * DOMESTIC has no customs, so one shared set serves contracts and bookings:
- * ONE_TIME collects it at contract level, GENERAL per booking — Operations
- * reviews either way.
+ * DOMESTIC has no customs, so one shared set serves every intercity booking —
+ * ONE_TIME and GENERAL alike, collected per booking and reviewed by Operations.
  */
 export const INTERCITY_DOCUMENTS_SETTING_CODE = 'intercity_documents';
 
@@ -77,16 +76,6 @@ export function clearanceCodesForBooking(booking: Booking): {
   const includesCustoms =
     Boolean(booking.serviceType?.includesCustoms) ||
     Boolean(booking.customsClearingEnabled);
-  // Intercity drawdowns under a ONE_TIME contract already cleared the intercity
-  // document set on the CONTRACT (post-signature); only GENERAL drawdowns and
-  // direct (contract-less) bookings carry the per-booking set.
-  if (
-    booking.tradeDirection === 'DOMESTIC' &&
-    booking.contractId &&
-    booking.contractKind === 'ONE_TIME'
-  ) {
-    return { inputCode: null, outputCode: null, includesCustoms: false };
-  }
   return {
     inputCode: clearanceSettingCode(
       booking.tradeDirection,