feat: enhance contract clearance process with linked booking details

- Added  and  to  for better visibility of GL-created shipment bookings.
- Implemented  method in  to fetch the latest clearance phase for contracts, improving list responses.
- Introduced  property in the  entity to store the latest clearance cycle's phase.
- Updated  to surface linked booking information in the clearance view.
- Created  component to display detailed container information in booking details.
- Refactored booking actions to remove contract-related actions from the booking request page.
- Enhanced the  component to reflect the current phase of clearance actions.
- Updated UI components to provide clearer messaging regarding the status of clearance and linked bookings.
- Adjusted action handling in  to include duty payment actions.
- Improved the  to show hints for each phase of the clearance process.

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

@@ -90,6 +90,7 @@ export class BookingsRepository extends BaseRepository<Booking> {
       .createQueryBuilder('booking')
       .leftJoinAndSelect('booking.bookingContainers', 'bc')
       .leftJoinAndSelect('bc.containerType', 'ct')
+      .leftJoinAndSelect('bc.units', 'bcu')
       .leftJoinAndSelect('booking.company', 'company')
       // .leftJoinAndSelect('booking.customer', 'customer')
       .leftJoinAndSelect('booking.train', 'train')
@@ -104,6 +105,7 @@ export class BookingsRepository extends BaseRepository<Booking> {
       .leftJoinAndSelect('booking.reviewNotes', 'reviewNotes')
       .leftJoinAndSelect('booking.consolidationPartner', 'consolidationPartner')
       .where('booking.id = :id', { id })
+      .addOrderBy('bcu.sort_order', 'ASC')
       .leftJoinAndMapMany(
         'booking.files',
         FileRecord,

apps/edr-freight-api/src/modules/bookings/entities/booking-container.entity.ts

@@ -1,8 +1,9 @@
 import { BaseEntity } from '@edr/api-common';
-import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+import { Column, Entity, Index, JoinColumn, ManyToOne, OneToMany } from 'typeorm';
 import { ContainerType } from '../../rule-engine/entities/container-type.entity';
 import { WeightLimitRule } from '../../rule-engine/entities/weight-limit-rule.entity';
 import { Booking } from './booking.entity';
+import { BookingContainerUnit } from './booking-container-unit.entity';
 
 @Entity({ schema: 'freight', name: 'booking_container' })
 @Index(['bookingId'])
@@ -61,4 +62,8 @@ export class BookingContainer extends BaseEntity {
 
   @Column({ name: 'overweight_excess_tons', type: 'numeric', precision: 10, scale: 3, nullable: true })
   overweightExcessTons?: number | null;
+
+  /** The physical containers under this line — each with its own number + VGM. */
+  @OneToMany(() => BookingContainerUnit, (u) => u.bookingContainer)
+  units?: BookingContainerUnit[];
 }

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

@@ -334,15 +334,19 @@ export class CompaniesController {
     @Param("companyId", ParseUUIDPipe) companyId: string,
   ) {
     const files = await this.filesService.findByResource(companyId, "companies");
-    return files.map((f) => ({
-      id: f.id,
-      name: f.name,
-      code: f.code,
-      mimeType: f.mimeType,
-      size: f.size,
-      uploadedAt: f.createdAt,
-      url: f.url,
-    }));
+    return Promise.all(
+      files.map(async (f) => ({
+        id: f.id,
+        name: f.name,
+        code: f.code,
+        mimeType: f.mimeType,
+        size: f.size,
+        uploadedAt: f.createdAt,
+        // Raw `f.url` is an un-signed MinIO path the browser can't open — sign
+        // it so the file previews/downloads in the client.
+        url: f.url ? await this.filesService.signUrl(f.url) : f.url,
+      })),
+    );
   }
 
   @Post(":companyId/documents")

apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts

@@ -77,6 +77,9 @@ export interface ContractClearanceView {
   /** Export post-booking clearance finalized (transit permit uploaded + GL confirmed). */
   exportClearanceFinalized?: boolean;
   linkedBookingId?: string | null;
+  /** Reference + status of the GL-created shipment booking, once it exists. */
+  linkedBookingReference?: string | null;
+  linkedBookingStatus?: string | null;
   dutyAdvice?: {
     amount: number;
     currency: string;
@@ -284,13 +287,22 @@ export class ContractClearanceService {
     );
 
     let nextAction = this.workflowService.computeNextAction(contract, cycle, milestones);
-    if (cycle?.bookingId && contract.tradeDirection === 'EXPORT') {
+    // Once GL creates the shipment booking, surface its reference + status so the
+    // customer sees the concrete booking instead of a stale "will be created
+    // shortly" message. Reuse the export booking load; fetch for import too.
+    let linkedBookingReference: string | null = null;
+    let linkedBookingStatus: string | null = null;
+    if (cycle?.bookingId) {
       const booking = await this.bookingsService.findById(cycle.bookingId);
       if (booking) {
-        nextAction = this.workflowService.computeNextActionForBooking(
-          booking,
-          bookingMilestones,
-        );
+        linkedBookingReference = booking.reference ?? null;
+        linkedBookingStatus = booking.status ?? null;
+        if (contract.tradeDirection === 'EXPORT') {
+          nextAction = this.workflowService.computeNextActionForBooking(
+            booking,
+            bookingMilestones,
+          );
+        }
       }
     }
 
@@ -326,6 +338,8 @@ export class ContractClearanceService {
       preClearanceFinalized: Boolean(cycle?.preClearanceFinalizedAt),
       exportClearanceFinalized: Boolean(cycle?.completedAt),
       linkedBookingId: cycle?.bookingId ?? null,
+      linkedBookingReference,
+      linkedBookingStatus,
       dutyAdvice,
       workflowFiles,
       t1,

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

@@ -135,6 +135,7 @@ export class ContractsRepository extends BaseRepository<Contract> {
     // Attach the generated contract PDF to each row so list/home can offer a
     // direct download. Loaded separately to keep pagination counts correct.
     await this.attachContractFiles(items);
+    await this.attachClearancePhases(items);
 
     const totalPages = pageSize > 0 ? Math.ceil(total / pageSize) : 0;
     return {
@@ -173,6 +174,30 @@ export class ContractsRepository extends BaseRepository<Contract> {
     }
   }
 
+  /**
+   * Attach each contract's persisted clearance phase (latest cycle's
+   * current_phase) so list consumers can show step-accurate customer actions
+   * ("Pay duty & upload slip" vs generic "Update clearance") without a
+   * per-contract clearance-view request. One query per page, like
+   * `attachContractFiles`.
+   */
+  private async attachClearancePhases(contracts: Contract[]): Promise<void> {
+    if (contracts.length === 0) return;
+    const ids = contracts.map((c) => c.id);
+    const rows: Array<{ contract_id: string; current_phase: string | null }> =
+      await this.dataSource.query(
+        `SELECT DISTINCT ON (contract_id) contract_id, current_phase
+           FROM freight.contract_clearance_cycles
+          WHERE contract_id = ANY($1)
+          ORDER BY contract_id, cycle_number DESC`,
+        [ids],
+      );
+    const byContract = new Map(rows.map((r) => [r.contract_id, r.current_phase]));
+    for (const contract of contracts) {
+      contract.clearancePhase = byContract.get(contract.id) ?? null;
+    }
+  }
+
   async getStatusCounts(): Promise<Record<string, number>> {
     const rows = await this.repository
       .createQueryBuilder('contract')

apps/edr-freight-api/src/modules/contracts/entities/contract.entity.ts

@@ -254,4 +254,10 @@ export class Contract extends BaseEntity {
     createForeignKeyConstraints: false,
   })
   files?: FileRecord[];
+
+  /**
+   * Latest clearance cycle's current_phase, attached by
+   * ContractsRepository.attachClearancePhases for list responses. Not a column.
+   */
+  clearancePhase?: string | null;
 }

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

@@ -123,6 +123,16 @@ export class FilesService {
     return this.filesRepository.findByResource(resourceId, resource);
   }
 
+  /**
+   * Short-lived signed URL for a stored file's raw MinIO URL. The persisted
+   * `url` is an un-signed object path that a browser cannot fetch directly;
+   * callers that expose files for preview/download must sign them first.
+   */
+  async signUrl(rawUrl: string, expirySeconds = 300): Promise<string> {
+    const objectName = this.minioService.getObjectNameFromUrl(rawUrl);
+    return this.minioService.getSignedUrl(objectName, expirySeconds);
+  }
+
   async findByCode(
     resourceId: string,
     resource: string,