Merge pull request #182 from Tria-plc/freight_feature/priority

Freight feature/priority

apps/edr-freight-api/package.json

@@ -46,7 +46,9 @@
     "pg": "^8.13.0",
     "puppeteer": "^24.2.0",
     "reflect-metadata": "^0.2.2",
-    "rxjs": "^7.8.1"
+    "rxjs": "^7.8.1",
+    "typeorm": "^0.3.30"
+
   },
   "devDependencies": {
     "@edr/api-common": "workspace:*",
@@ -69,7 +71,6 @@
     "ts-loader": "^9.5.1",
     "ts-node": "^10.9.2",
     "tsconfig-paths": "^4.2.0",
-    "typeorm": "^0.3.30",
     "typescript": "^5.5.4"
   },
   "jest": {

apps/edr-freight-api/src/app.module.ts

@@ -13,6 +13,7 @@ import telebirrConfig from "./config/telebirr.config";
 import rabbitmqConfig from "./config/rabbitmq.config";
 
 import { BookingsModule } from "./modules/bookings/bookings.module";
+import { SignaturesModule } from "./modules/signatures/signatures.module";
 import { FilesModule } from "./modules/files/files.module";
 import { ConsignmentsModule } from "./modules/consignments/consignments.module";
 
@@ -82,6 +83,7 @@ import { OverviewModule } from './modules/overview/overview.module';
       permissions: EDR_FREIGHT_PERMISSIONS,
     }),
     BookingsModule,
+    SignaturesModule,
     FilesModule,
     ConsignmentsModule,
     LocomotivesModule,

apps/edr-freight-api/src/migrations/1784000000000-CreateSavedSignatures.ts

@@ -0,0 +1,22 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class CreateSavedSignatures1784000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE freight.saved_signatures (
+        id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
+        user_id UUID NOT NULL,
+        signer_display_name VARCHAR(200) NOT NULL,
+        signature_file_id UUID NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        deleted_at TIMESTAMPTZ NULL,
+        CONSTRAINT uq_saved_signatures_user_id UNIQUE (user_id)
+      );
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.saved_signatures;`);
+  }
+}

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

@@ -23,6 +23,7 @@ import { ContractViewDto } from './dto/contract-view.dto';
 import { SignContractDto } from './dto/sign-contract.dto';
 import { ContractSignerRole } from './entities/booking-contract-signature.entity';
 import { BookingBatchService } from '../train-scheduling/booking-batch.service';
+import { SignaturesService } from '../signatures/signatures.service';
 
 @Injectable()
 export class BookingContractService {
@@ -38,6 +39,7 @@ export class BookingContractService {
     private readonly pdfService: ContractPdfService,
     @Inject(forwardRef(() => BookingBatchService))
     private readonly bookingBatchService: BookingBatchService,
+    private readonly signaturesService: SignaturesService,
   ) {}
 
   buildContractSummary(booking: Booking): string {
@@ -75,10 +77,16 @@ export class BookingContractService {
     return { summary };
   }
 
-  async getContractView(bookingId: string): Promise<ContractViewDto> {
+  async getContractView(
+    bookingId: string,
+    viewerUserId?: string,
+  ): Promise<ContractViewDto> {
     const { view } = await this.viewModelBuilder.build(bookingId);
     await this.inlineSignatureImages(view.signatures);
     const html = this.renderer.render(view);
+    const savedSignature = viewerUserId
+      ? ((await this.signaturesService.getForUser(viewerUserId)) ?? undefined)
+      : undefined;
     return {
       bookingId: view.bookingId,
       reference: view.reference,
@@ -90,6 +98,7 @@ export class BookingContractService {
       canSignStaff: view.canSignStaff,
       hasContractDocument: view.hasContractDocument,
       signatures: view.signatures,
+      savedSignature,
       pricingSchedule: view.pricing as unknown as Record<string, unknown>,
     };
   }
@@ -194,6 +203,23 @@ export class BookingContractService {
       ipAddress: options.ipAddress ?? null,
     });
 
+    // Persist the just-used signature to the signer's reusable profile so they
+    // don't have to redraw it on the next contract. Best-effort: a failure here
+    // must never block contract execution.
+    if (options.signerUserId) {
+      try {
+        await this.signaturesService.upsertForUser({
+          userId: options.signerUserId,
+          signerDisplayName: dto.signerDisplayName,
+          signatureImageBase64: dto.signatureImageBase64,
+        });
+      } catch (err) {
+        this.logger.warn(
+          `Could not save reusable signature for user ${options.signerUserId}: ${err}`,
+        );
+      }
+    }
+
     const updates: Record<string, unknown> = {};
 
     if (role === 'CUSTOMER') {

apps/edr-freight-api/src/modules/bookings/booking-list-tabs.config.ts

@@ -16,7 +16,7 @@ export const BOOKING_LIST_TABS: ReadonlyArray<{
   statuses: readonly string[] | null;
 }> = [
   { key: 'all', statuses: null },
-  { key: 'intake', statuses: ['SUBMITTED'] },
+  { key: 'intake', statuses: ['SUBMITTED', 'PENDING_CONSOLIDATION'] },
   {
     key: 'in_approval',
     statuses: ['PENDING_APPROVAL', 'APPROVED_PENDING_SIGNATURE'],
@@ -28,7 +28,7 @@ export const BOOKING_LIST_TABS: ReadonlyArray<{
   { key: 'payment', statuses: ['FULLY_EXECUTED'] },
   {
     key: 'operations',
-    statuses: ['IN_TRANSIT', 'PENDING_CONSOLIDATION', 'CONSOLIDATED','PAID'],
+    statuses: ['IN_TRANSIT', 'PAID'],
   },
   { key: 'completed', statuses: ['COMPLETED'] },
   { key: 'closed', statuses: ['REJECTED', 'CANCELLED'] },

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

@@ -1,4 +1,10 @@
-import { BadRequestException, forwardRef, Inject, Injectable } from '@nestjs/common';
+import {
+  BadRequestException,
+  ConflictException,
+  forwardRef,
+  Inject,
+  Injectable,
+} from '@nestjs/common';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
 
 import { assertCanApproveBookingStep } from '../../common/freight-permission.util';
@@ -184,6 +190,16 @@ export class BookingTransitionService {
     const booking = await this.bookingsService.findById(bookingId);
     assertBookingStatus(booking, ['SUBMITTED']);
 
+    // Consolidation gate: a booking whose containers don't fill whole wagons
+    // cannot be accepted until it is paired with a complementary booking.
+    const gate = await this.bookingsService.resolveConsolidationGate(bookingId);
+    if (gate.blocked) {
+      throw new ConflictException(
+        gate.message ??
+          'Booking requires consolidation and cannot be accepted until a partner is found.',
+      );
+    }
+
     await this.ruleEngineService.instantiateApprovalSteps(bookingId, {
       freightType: booking.freightType as 'CONTAINER' | 'BULK',
       cargoTypeId: booking.cargoTypeId,

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

@@ -342,8 +342,12 @@ export class BookingsController {
   @Get(':id/contract/view')
   @ApiOkResponse({ type: ContractViewDto })
   @ApiOperation({ summary: 'Contract HTML view for portal and backoffice' })
-  getContractView(@Param('id', ParseUUIDPipe) id: string) {
-    return this.contractService.getContractView(id);
+  getContractView(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Request() req: { user?: { id?: string; sub?: string } },
+  ) {
+    const userId = req.user?.id ?? req.user?.sub;
+    return this.contractService.getContractView(id, userId);
   }
 
   @Get(':id/contract/document')

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

@@ -6,6 +6,7 @@ import { CompaniesModule } from '../companies/companies.module';
 import { FilesModule } from '../files/files.module';
 import { MinioModule } from '../minio/minio.module';
 import { RuleEngineModule } from '../rule-engine/rule-engine.module';
+import { SignaturesModule } from '../signatures/signatures.module';
 import { BookingContractService } from './booking-contract.service';
 import { BookingPaymentService } from './booking-payment.service';
 import { BookingPricingService } from './booking-pricing.service';
@@ -50,6 +51,7 @@ import { CbeExchangeService } from '../cbe-exchange/cbe-exchange.service';
     CompaniesModule,
     // CustomersModule,
     RuleEngineModule,
+    SignaturesModule,
   ],
   controllers: [BookingsController, PayController],
   providers: [

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

@@ -93,6 +93,7 @@ export class BookingsRepository extends BaseRepository<Booking> {
       .leftJoinAndSelect('booking.rateSnapshots', 'snapshots')
       .leftJoinAndSelect('booking.cargoModifiers', 'modifiers')
       .leftJoinAndSelect('booking.reviewNotes', 'reviewNotes')
+      .leftJoinAndSelect('booking.consolidationPartner', 'consolidationPartner')
       .where('booking.id = :id', { id })
       .leftJoinAndMapMany(
         'booking.files',
@@ -177,7 +178,7 @@ export class BookingsRepository extends BaseRepository<Booking> {
       .andWhere('b.allowConsolidation = true')
       .andWhere('b.consolidationPartnerId IS NULL')
       .andWhere('b.status IN (:...statuses)', {
-        statuses: ['DRAFT', 'PENDING_CONSOLIDATION'],
+        statuses: ['DRAFT', 'SUBMITTED', 'PENDING_CONSOLIDATION'],
       })
       .andWhere('b.originYardId = :originYardId', {
         originYardId: booking.originYardId,
@@ -214,15 +215,27 @@ export class BookingsRepository extends BaseRepository<Booking> {
     return null;
   }
 
-  /** Pair two bookings for consolidation. */
+  /**
+   * Pair two bookings for consolidation. Both return to SUBMITTED so staff can
+   * accept them into the approval chain; the link itself (consolidationPartnerId)
+   * marks them as consolidated in the UI.
+   */
   async pairConsolidation(bookingId: string, partnerId: string): Promise<void> {
     await this.repository.update(bookingId, {
       consolidationPartnerId: partnerId,
-      status: 'CONSOLIDATED',
+      status: 'SUBMITTED',
     } as never);
     await this.repository.update(partnerId, {
       consolidationPartnerId: bookingId,
-      status: 'CONSOLIDATED',
+      status: 'SUBMITTED',
+    } as never);
+  }
+
+  /** Park a booking that needs consolidation but has no partner yet. */
+  async parkForConsolidation(bookingId: string): Promise<void> {
+    await this.repository.update(bookingId, {
+      consolidationPartnerId: null,
+      status: 'PENDING_CONSOLIDATION',
     } as never);
   }
 
@@ -429,6 +442,7 @@ export class BookingsRepository extends BaseRepository<Booking> {
       .leftJoinAndSelect('booking.destinationYard', 'destinationYard')
       .leftJoinAndSelect('booking.serviceType', 'serviceType')
       .leftJoinAndSelect('booking.approvalSteps', 'approvalSteps')
+      .leftJoinAndSelect('booking.consolidationPartner', 'consolidationPartner')
       .where('booking.deleted_at IS NULL');
 
     this.applyListFilters(qb, options);

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

@@ -204,6 +204,48 @@ export class BookingsService {
     return { booking: pending, messages };
   }
 
+  /**
+   * Consolidation gate used at staff-accept time. Returns the (possibly newly
+   * paired) booking plus whether it still needs a consolidation partner.
+   * When a booking needs consolidation and none is found, it is parked in
+   * PENDING_CONSOLIDATION and `blocked` is true so the caller refuses the accept.
+   */
+  async resolveConsolidationGate(bookingId: string): Promise<{
+    booking: Booking;
+    blocked: boolean;
+    message?: string;
+  }> {
+    let booking = await this.findById(bookingId);
+
+    // Already paired — passes the gate.
+    if (booking.consolidationPartnerId) {
+      return { booking, blocked: false };
+    }
+
+    const needs =
+      await this.consolidationService.needsConsolidationFromBooking(booking);
+    if (!needs) {
+      return { booking, blocked: false };
+    }
+
+    // A partner may have appeared since submission — try to pair now.
+    const result = await this.tryAutoConsolidate(booking);
+    booking = result.booking;
+    if (booking.consolidationPartnerId) {
+      return { booking, blocked: false, message: result.messages.join(' ') };
+    }
+
+    // Still no partner — park it and block the accept.
+    await this.bookingsRepository.parkForConsolidation(booking.id);
+    booking = await this.findById(booking.id);
+    const slots = await this.consolidationService.slotsFromBooking(booking);
+    return {
+      booking,
+      blocked: true,
+      message: this.consolidationService.describePending(booking, slots),
+    };
+  }
+
   /** Create a new freight booking. */
   async create(
     dto: CreateBookingDto,

apps/edr-freight-api/src/modules/bookings/dto/contract-view.dto.ts

@@ -14,6 +14,14 @@ export class ContractSignatureDto {
   signatureImageUrl?: string | null;
 }
 
+export class SavedSignatureViewDto {
+  @ApiProperty()
+  signerDisplayName!: string;
+
+  @ApiPropertyOptional()
+  signatureImageUrl?: string | null;
+}
+
 export class ContractViewDto {
   @ApiProperty()
   bookingId!: string;
@@ -45,6 +53,9 @@ export class ContractViewDto {
   @ApiProperty({ type: [ContractSignatureDto] })
   signatures!: ContractSignatureDto[];
 
+  @ApiPropertyOptional({ type: SavedSignatureViewDto })
+  savedSignature?: SavedSignatureViewDto;
+
   @ApiPropertyOptional()
   pricingSchedule?: Record<string, unknown>;
 }

apps/edr-freight-api/src/modules/signatures/dto/save-signature.dto.ts

@@ -0,0 +1,24 @@
+import { ApiProperty } from '@nestjs/swagger';
+import { IsString, MinLength } from 'class-validator';
+
+export class SaveSignatureDto {
+  @ApiProperty()
+  @IsString()
+  @MinLength(1)
+  signerDisplayName!: string;
+
+  @ApiProperty({
+    description: 'PNG signature image as base64 (with or without data URL prefix)',
+  })
+  @IsString()
+  @MinLength(20)
+  signatureImageBase64!: string;
+}
+
+export class SavedSignatureDto {
+  @ApiProperty()
+  signerDisplayName!: string;
+
+  @ApiProperty({ nullable: true })
+  signatureImageUrl!: string | null;
+}

apps/edr-freight-api/src/modules/signatures/entities/saved-signature.entity.ts

@@ -0,0 +1,25 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+import { FileRecord } from '../../files/entities/file.entity';
+
+/**
+ * A reusable signature that belongs to a single user (customer or staff).
+ * Captured once and applied to many booking contracts so the signer does not
+ * have to redraw it every time. One active saved signature per user.
+ */
+@Entity({ schema: 'freight', name: 'saved_signatures' })
+@Index(['userId'], { unique: true })
+export class SavedSignature extends BaseEntity {
+  @Column({ name: 'user_id', type: 'uuid' })
+  userId!: string;
+
+  @Column({ name: 'signer_display_name', type: 'varchar', length: 200 })
+  signerDisplayName!: string;
+
+  @Column({ name: 'signature_file_id', type: 'uuid', nullable: true })
+  signatureFileId?: string | null;
+
+  @ManyToOne(() => FileRecord, { nullable: true })
+  @JoinColumn({ name: 'signature_file_id' })
+  signatureFile?: FileRecord | null;
+}

apps/edr-freight-api/src/modules/signatures/signatures.controller.ts

@@ -0,0 +1,39 @@
+import { Body, Controller, Get, Put, Request } from '@nestjs/common';
+import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+
+import { SignaturesService } from './signatures.service';
+import { SaveSignatureDto, SavedSignatureDto } from './dto/save-signature.dto';
+
+@ApiTags('Signatures')
+@Controller('me/signature')
+export class SignaturesController {
+  constructor(private readonly signaturesService: SignaturesService) {}
+
+  @Get()
+  @ApiOkResponse({ type: SavedSignatureDto })
+  @ApiOperation({ summary: "Current user's reusable saved signature" })
+  getMySignature(
+    @Request() req: { user?: { id?: string; sub?: string } },
+  ): Promise<SavedSignatureDto | null> {
+    const userId = req.user?.id ?? req.user?.sub;
+    if (!userId) return Promise.resolve(null);
+    return this.signaturesService.getForUser(userId);
+  }
+
+  @Put()
+  @ApiOkResponse({ type: SavedSignatureDto })
+  @ApiOperation({ summary: 'Create or update the reusable saved signature' })
+  async saveMySignature(
+    @Body() dto: SaveSignatureDto,
+    @Request() req: { user?: { id?: string; sub?: string } },
+  ): Promise<SavedSignatureDto | null> {
+    const userId = req.user?.id ?? req.user?.sub;
+    if (!userId) return null;
+    await this.signaturesService.upsertForUser({
+      userId,
+      signerDisplayName: dto.signerDisplayName,
+      signatureImageBase64: dto.signatureImageBase64,
+    });
+    return this.signaturesService.getForUser(userId);
+  }
+}

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

@@ -0,0 +1,21 @@
+import { Module } from '@nestjs/common';
+import { TypeOrmModule } from '@nestjs/typeorm';
+
+import { FilesModule } from '../files/files.module';
+import { MinioModule } from '../minio/minio.module';
+import { SignaturesController } from './signatures.controller';
+import { SignaturesService } from './signatures.service';
+import { SignaturesRepository } from './signatures.repository';
+import { SavedSignature } from './entities/saved-signature.entity';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([SavedSignature]),
+    FilesModule,
+    MinioModule,
+  ],
+  controllers: [SignaturesController],
+  providers: [SignaturesService, SignaturesRepository],
+  exports: [SignaturesService],
+})
+export class SignaturesModule {}

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

@@ -0,0 +1,34 @@
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+import { BaseRepository } from '@edr/api-common';
+import { SavedSignature } from './entities/saved-signature.entity';
+
+@Injectable()
+export class SignaturesRepository extends BaseRepository<SavedSignature> {
+  constructor(
+    @InjectRepository(SavedSignature)
+    repo: Repository<SavedSignature>,
+  ) {
+    super(repo);
+  }
+
+  findByUserId(userId: string): Promise<SavedSignature | null> {
+    return this.repository.findOne({
+      where: { userId } as never,
+      relations: ['signatureFile'],
+    });
+  }
+
+  /** Insert or update the single saved signature for a user. */
+  async upsert(data: Partial<SavedSignature>): Promise<SavedSignature> {
+    const existing = await this.repository.findOne({
+      where: { userId: data.userId! } as never,
+    });
+    if (existing) {
+      Object.assign(existing, data);
+      return this.repository.save(existing);
+    }
+    return this.repository.save(this.repository.create(data));
+  }
+}

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

@@ -0,0 +1,94 @@
+import { Injectable } from '@nestjs/common';
+import { Readable } from 'stream';
+
+import { FilesService } from '../files/files.service';
+import { MinioService } from '../minio/minio.service';
+import { SignaturesRepository } from './signatures.repository';
+import { SavedSignature } from './entities/saved-signature.entity';
+import { SavedSignatureDto } from './dto/save-signature.dto';
+
+export interface UpsertSignatureInput {
+  userId: string;
+  signerDisplayName: string;
+  signatureImageBase64: string;
+}
+
+@Injectable()
+export class SignaturesService {
+  constructor(
+    private readonly signaturesRepository: SignaturesRepository,
+    private readonly filesService: FilesService,
+    private readonly minioService: MinioService,
+  ) {}
+
+  /** Saved signature for a user, with the image inlined as a data URL (or null). */
+  async getForUser(userId: string): Promise<SavedSignatureDto | null> {
+    const saved = await this.signaturesRepository.findByUserId(userId);
+    if (!saved) return null;
+    return {
+      signerDisplayName: saved.signerDisplayName,
+      signatureImageUrl: await this.inlineImageUrl(saved.signatureFile?.url),
+    };
+  }
+
+  /** Insert or update the user's reusable signature, storing the image in MinIO. */
+  async upsertForUser(input: UpsertSignatureInput): Promise<SavedSignature> {
+    const buffer = this.decodeSignatureImage(input.signatureImageBase64);
+    const file: Express.Multer.File = {
+      fieldname: 'signature',
+      originalname: `signature-${input.userId}.png`,
+      encoding: '7bit',
+      mimetype: 'image/png',
+      size: buffer.length,
+      buffer,
+      stream: Readable.from(buffer),
+      destination: '',
+      filename: '',
+      path: '',
+    };
+
+    const fileRecord = await this.filesService.upsertByCode({
+      resourceId: input.userId,
+      resource: 'saved_signatures',
+      code: 'signature',
+      file,
+    });
+
+    return this.signaturesRepository.upsert({
+      userId: input.userId,
+      signerDisplayName: input.signerDisplayName,
+      signatureFileId: fileRecord.id,
+    });
+  }
+
+  private async inlineImageUrl(
+    url?: string | null,
+  ): Promise<string | null> {
+    if (!url) return null;
+    if (url.startsWith('data:')) return url;
+    try {
+      const objectName = this.minioService.getObjectNameFromUrl(url);
+      const stream = await this.minioService.getFileStream(objectName);
+      const buffer = await this.streamToBuffer(stream);
+      return `data:image/png;base64,${buffer.toString('base64')}`;
+    } catch {
+      return url;
+    }
+  }
+
+  private decodeSignatureImage(base64: string): Buffer {
+    const raw = base64.includes(',') ? base64.split(',')[1]! : base64;
+    return Buffer.from(raw, 'base64');
+  }
+
+  private streamToBuffer(stream: Readable): Promise<Buffer> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      stream.on('data', (chunk: Buffer | string) => {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      });
+      stream.on('error', reject);
+      stream.on('end', () => resolve(Buffer.concat(chunks)));
+    });
+  }
+}