feat: implement document clearance workflow for bookings

- Added ClearanceCard component to display and manage clearance documents in ReadonlyBookingView.
- Introduced new API endpoints for clearance operations: getClearance, submitClearanceDocuments, and proceedToOperation.
- Created BookingDocumentReview entity and migration for document review status tracking.
- Developed GlClearancePage for Global Logistics to review and manage document submissions.
- Implemented utility functions for determining clearance setting codes based on trade direction and freight type.
- Added tests for booking transition clearance logic and clearance utility functions.

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

@@ -19,6 +19,7 @@ import { FileRecord } from '../files/entities/file.entity';
 import { BookingsRepository } from './bookings.repository';
 import { Booking } from './entities/booking.entity';
 import { assertBookingStatus } from './booking-status.util';
+import { clearanceSettingCode } from './clearance.util';
 import { ContractViewDto } from './dto/contract-view.dto';
 import { SignContractDto } from './dto/sign-contract.dto';
 import { ContractSignerRole } from './entities/booking-contract-signature.entity';
@@ -222,19 +223,31 @@ export class BookingContractService {
 
     const updates: Record<string, unknown> = {};
 
+    // Whether a document-clearance gate applies (IMPORT/EXPORT bookings). When it
+    // does, the counter-signed booking goes to AWAITING_DOCUMENTS for the customer
+    // to upload clearance documents instead of straight into the batch pipeline.
+    const includesCustoms = booking.serviceType?.includesCustoms ?? false;
+    const clearanceCode = clearanceSettingCode(
+      booking.tradeDirection,
+      booking.freightType,
+      includesCustoms,
+    );
+
     if (role === 'CUSTOMER') {
       updates.status = 'SIGNED_CUSTOMER';
       updates.customerSignedAt = now;
     } else {
-      updates.status = 'FULLY_EXECUTED';
       updates.fullyExecutedAt = now;
       updates.marketingApprovedAt = now;
       updates.marketingApprovedById = options.signerUserId ?? null;
       updates.lockedAt = now;
+      updates.status = clearanceCode ? 'AWAITING_DOCUMENTS' : 'FULLY_EXECUTED';
     }
 
     const updated = await this.bookingsRepository.update(bookingId, updates as never);
-    if (role === 'STAFF' && updated?.trainScheduleId) {
+    // Only the non-clearance (legacy/domestic) path enters the batch pipeline now;
+    // clearance bookings enter operations after the GL document gate.
+    if (role === 'STAFF' && !clearanceCode && updated?.trainScheduleId) {
       this.bookingBatchService.enqueueScheduleProcessing(updated.trainScheduleId);
     }
     try {

apps/edr-freight-api/src/modules/bookings/booking-next-step.util.ts

@@ -57,6 +57,26 @@ export function computeNextStep(
         action: 'AWAIT_PAYMENT',
         description: 'Awaiting customer payment',
       };
+    case 'AWAITING_DOCUMENTS':
+      return {
+        action: 'UPLOAD_DOCUMENTS',
+        description: 'Upload the clearance documents for your shipment',
+      };
+    case 'DOCUMENTS_UNDER_REVIEW':
+      return {
+        action: 'AWAIT_DOCUMENT_REVIEW',
+        description: 'Global Logistics is reviewing your documents',
+      };
+    case 'CLEARANCE_READY':
+      return {
+        action: 'PROCEED_TO_OPERATION',
+        description: 'Clearance is ready — proceed to operation',
+      };
+    case 'OPERATION_REQUESTED':
+      return {
+        action: 'AWAIT_OPERATION',
+        description: 'Operation requested; an operator will take it forward',
+      };
     case 'PAID':
       return {
         action: 'START_TRANSIT',

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

@@ -0,0 +1,76 @@
+import { BadRequestException } from '@nestjs/common';
+import { BookingTransitionService } from './booking-transition.service';
+
+/**
+ * Focused tests for the clearance 100%-approved gate in finalizeClearance.
+ * Uses minimal stubs for the service's collaborators.
+ */
+describe('BookingTransitionService — finalizeClearance gate', () => {
+  const booking = {
+    id: 'b-1',
+    status: 'DOCUMENTS_UNDER_REVIEW',
+    tradeDirection: 'IMPORT',
+    freightType: 'CONTAINER',
+    serviceType: { includesCustoms: false }, // no output set → only the input gate
+  };
+
+  // Input set has two required docs.
+  const inputSetting = {
+    code: 'clearance_import_container_without_customs',
+    fields: [
+      { fileKey: 'commercial_invoice', isRequired: true },
+      { fileKey: 'packing_list', isRequired: true },
+    ],
+  };
+
+  function makeService(reviews: Array<{ settingCode: string; fileKey: string; status: string }>) {
+    const bookingsRepository = {
+      findDocumentReviews: jest.fn().mockResolvedValue(reviews),
+      update: jest.fn().mockResolvedValue({ id: 'b-1' }),
+    };
+    const bookingsService = {
+      findById: jest.fn().mockResolvedValue(booking),
+    };
+    const fileUploadSettingsService = {
+      getByCode: jest.fn().mockResolvedValue(inputSetting),
+    };
+    const filesService = { findByResource: jest.fn().mockResolvedValue([]) };
+
+    const service = new BookingTransitionService(
+      bookingsRepository as never,
+      {} as never, // ruleEngineService
+      {} as never, // pricingService
+      {} as never, // contractService
+      filesService as never,
+      fileUploadSettingsService as never,
+      bookingsService as never,
+    );
+    return { service, bookingsRepository };
+  }
+
+  it('rejects when a required document is not APPROVED', async () => {
+    const { service } = makeService([
+      {
+        settingCode: inputSetting.code,
+        fileKey: 'commercial_invoice',
+        status: 'APPROVED',
+      },
+      // packing_list is still PENDING (missing approval)
+    ]);
+    await expect(service.finalizeClearance('b-1')).rejects.toBeInstanceOf(
+      BadRequestException,
+    );
+  });
+
+  it('moves to CLEARANCE_READY when all required documents are APPROVED', async () => {
+    const { service, bookingsRepository } = makeService([
+      { settingCode: inputSetting.code, fileKey: 'commercial_invoice', status: 'APPROVED' },
+      { settingCode: inputSetting.code, fileKey: 'packing_list', status: 'APPROVED' },
+    ]);
+    await service.finalizeClearance('b-1');
+    expect(bookingsRepository.update).toHaveBeenCalledWith(
+      'b-1',
+      expect.objectContaining({ status: 'CLEARANCE_READY' }),
+    );
+  });
+});

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

@@ -8,10 +8,13 @@ import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/curre
 
 import { assertCanApproveBookingStep } from '../../common/freight-permission.util';
 import { RuleEngineService } from '../rule-engine/rule-engine.service';
+import { FilesService } from '../files/files.service';
+import { FileUploadSettingsService } from '../file-upload-settings/file-upload-settings.service';
 import { BookingContractService } from './booking-contract.service';
 import { BookingPricingService } from './booking-pricing.service';
 import { BookingsRepository } from './bookings.repository';
 import { assertBookingStatus } from './booking-status.util';
+import { clearanceCodesForBooking } from './clearance.util';
 import { computeNextStep, type BookingNextStep } from './booking-next-step.util';
 import { SubmitBookingResponseDto } from './dto/submit-booking-response.dto';
 import { PriceLineItemDto } from './dto/generate-price-response.dto';
@@ -25,6 +28,8 @@ export class BookingTransitionService {
     private readonly ruleEngineService: RuleEngineService,
     private readonly pricingService: BookingPricingService,
     private readonly contractService: BookingContractService,
+    private readonly filesService: FilesService,
+    private readonly fileUploadSettingsService: FileUploadSettingsService,
     @Inject(forwardRef(() => BookingsService))
     private readonly bookingsService: BookingsService,
   ) {}
@@ -446,6 +451,289 @@ export class BookingTransitionService {
     return this.bookingsService.findById(updated!.id);
   }
 
+  // ── Document clearance gate (post counter-sign) ───────────────────────────
+
+  /**
+   * The clearance document grid for a booking: each required field from the
+   * resolved customer-input set (and the GL-output set for customs) with its
+   * uploaded file and GL review status. Drives both portals' clearance UI.
+   */
+  async getClearanceView(bookingId: string): Promise<{
+    status: string;
+    includesCustoms: boolean;
+    inputCode: string | null;
+    outputCode: string | null;
+    documents: Array<{
+      fileKey: string;
+      label: string;
+      required: boolean;
+      uploadedBy: 'customer' | 'gl';
+      settingCode: string;
+      file: { id: string; name: string; url: string } | null;
+      reviewStatus: 'PENDING' | 'APPROVED' | 'QUERIED' | null;
+      note: string | null;
+    }>;
+    allApproved: boolean;
+  }> {
+    const booking = await this.bookingsService.findById(bookingId);
+    const { inputCode, outputCode, includesCustoms } =
+      clearanceCodesForBooking(booking);
+
+    const files = await this.filesService.findByResource(bookingId, 'bookings');
+    const fileByCode = new Map(files.map((f) => [f.code, f]));
+    const reviews = await this.bookingsRepository.findDocumentReviews(bookingId);
+    const reviewByKey = new Map(
+      reviews.map((r) => [`${r.settingCode}:${r.fileKey}`, r]),
+    );
+
+    const documents: Awaited<
+      ReturnType<BookingTransitionService['getClearanceView']>
+    >['documents'] = [];
+
+    const pushSetting = async (
+      code: string | null,
+      uploadedBy: 'customer' | 'gl',
+    ) => {
+      if (!code) return;
+      let setting;
+      try {
+        setting = await this.fileUploadSettingsService.getByCode(code);
+      } catch {
+        return; // setting not seeded — skip gracefully
+      }
+      for (const field of setting.fields ?? []) {
+        const file = fileByCode.get(field.fileKey) ?? null;
+        const review = reviewByKey.get(`${code}:${field.fileKey}`) ?? null;
+        documents.push({
+          fileKey: field.fileKey,
+          label: field.fileLabel,
+          required: field.isRequired,
+          uploadedBy,
+          settingCode: code,
+          file: file
+            ? { id: file.id, name: file.name, url: file.url }
+            : null,
+          reviewStatus: review?.status ?? null,
+          note: review?.note ?? null,
+        });
+      }
+    };
+
+    await pushSetting(inputCode, 'customer');
+    await pushSetting(outputCode, 'gl');
+
+    // Ad-hoc / unknown documents (code custom_*) appear alongside the seeded set.
+    for (const f of files) {
+      if (!f.code?.startsWith('custom_')) continue;
+      const review = reviewByKey.get(`custom:${f.code}`) ?? null;
+      documents.push({
+        fileKey: f.code,
+        label: f.name,
+        required: false,
+        uploadedBy: 'customer',
+        settingCode: 'custom',
+        file: { id: f.id, name: f.name, url: f.url },
+        reviewStatus: review?.status ?? null,
+        note: review?.note ?? null,
+      });
+    }
+
+    const allApproved = await this.isClearanceFullyApproved(booking);
+
+    return {
+      status: booking.status,
+      includesCustoms,
+      inputCode,
+      outputCode,
+      documents,
+      allApproved,
+    };
+  }
+
+  /**
+   * True when every REQUIRED field of the booking's customer-input clearance set
+   * has an APPROVED review row. The 100% gate before clearance can be finalized.
+   */
+  private async isClearanceFullyApproved(booking: Booking): Promise<boolean> {
+    const { inputCode } = clearanceCodesForBooking(booking);
+    if (!inputCode) return true; // no gate applies (e.g. domestic)
+    let setting;
+    try {
+      setting = await this.fileUploadSettingsService.getByCode(inputCode);
+    } catch {
+      return false;
+    }
+    const required = (setting.fields ?? []).filter((f) => f.isRequired);
+    if (required.length === 0) return true;
+    const reviews = await this.bookingsRepository.findDocumentReviews(booking.id);
+    return required.every((field) =>
+      reviews.some(
+        (r) =>
+          r.settingCode === inputCode &&
+          r.fileKey === field.fileKey &&
+          r.status === 'APPROVED',
+      ),
+    );
+  }
+
+  /**
+   * Customer uploads clearance documents. Each multipart file's fieldname is the
+   * field's fileKey (or custom_<n> for ad-hoc). Saves FileRecords, refreshes the
+   * per-document review rows to PENDING, and moves the booking into review.
+   */
+  async submitClearanceDocuments(
+    bookingId: string,
+    files: Express.Multer.File[],
+  ): Promise<Booking> {
+    const booking = await this.bookingsService.findById(bookingId);
+    assertBookingStatus(booking, ['AWAITING_DOCUMENTS', 'DOCUMENTS_UNDER_REVIEW']);
+    const { inputCode } = clearanceCodesForBooking(booking);
+    if (!inputCode) {
+      throw new BadRequestException('This booking has no document-clearance step');
+    }
+    if (files.length === 0) {
+      throw new BadRequestException('No documents uploaded');
+    }
+
+    for (const file of files) {
+      const record = await this.filesService.upsertByCode({
+        resourceId: bookingId,
+        resource: 'bookings',
+        code: file.fieldname,
+        file,
+      });
+      // Ad-hoc docs (custom_*) are not part of the required gate; still tracked.
+      const settingCode = file.fieldname.startsWith('custom_')
+        ? 'custom'
+        : inputCode;
+      await this.bookingsRepository.upsertDocumentReviewPending({
+        bookingId,
+        settingCode,
+        fileKey: file.fieldname,
+        fileRecordId: record.id,
+      });
+    }
+
+    await this.bookingsRepository.update(bookingId, {
+      status: 'DOCUMENTS_UNDER_REVIEW',
+    } as never);
+    return this.bookingsService.findById(bookingId);
+  }
+
+  /** GL reviews a single document: APPROVED or QUERIED (with a note). */
+  async reviewDocument(
+    bookingId: string,
+    fileKey: string,
+    status: 'APPROVED' | 'QUERIED',
+    staffId: string,
+    note?: string,
+  ): Promise<Booking> {
+    const booking = await this.bookingsService.findById(bookingId);
+    assertBookingStatus(booking, ['DOCUMENTS_UNDER_REVIEW']);
+    const { inputCode, outputCode } = clearanceCodesForBooking(booking);
+
+    const existing = await this.bookingsRepository.findDocumentReviews(bookingId);
+    const match = existing.find((r) => r.fileKey === fileKey);
+    const settingCode =
+      match?.settingCode ??
+      (fileKey.startsWith('custom_') ? 'custom' : (inputCode ?? outputCode ?? 'custom'));
+
+    if (status === 'QUERIED' && !note?.trim()) {
+      throw new BadRequestException('A note is required when querying a document');
+    }
+
+    await this.bookingsRepository.setDocumentReviewStatus(
+      bookingId,
+      settingCode,
+      fileKey,
+      status,
+      staffId,
+      note,
+    );
+    if (status === 'QUERIED') {
+      await this.bookingsRepository.createReviewNote(
+        bookingId,
+        `Document "${fileKey}" queried: ${note}`,
+        'CHANGES_REQUESTED',
+        staffId,
+      );
+    }
+    return this.bookingsService.findById(bookingId);
+  }
+
+  /** GL uploads the customs output documents (IM4/IM5/EX3/etc.). */
+  async uploadClearanceOutputDocuments(
+    bookingId: string,
+    files: Express.Multer.File[],
+  ): Promise<Booking> {
+    const booking = await this.bookingsService.findById(bookingId);
+    assertBookingStatus(booking, ['DOCUMENTS_UNDER_REVIEW']);
+    const { outputCode } = clearanceCodesForBooking(booking);
+    if (!outputCode) {
+      throw new BadRequestException('This booking has no customs output documents');
+    }
+    if (files.length === 0) {
+      throw new BadRequestException('No documents uploaded');
+    }
+    for (const file of files) {
+      await this.filesService.upsertByCode({
+        resourceId: bookingId,
+        resource: 'bookings',
+        code: file.fieldname,
+        file,
+      });
+    }
+    return this.bookingsService.findById(bookingId);
+  }
+
+  /**
+   * GL confirms clearance: requires every customer document APPROVED (100% gate)
+   * and, for customs, the required output documents present → CLEARANCE_READY.
+   */
+  async finalizeClearance(bookingId: string): Promise<Booking> {
+    const booking = await this.bookingsService.findById(bookingId);
+    assertBookingStatus(booking, ['DOCUMENTS_UNDER_REVIEW']);
+
+    const approved = await this.isClearanceFullyApproved(booking);
+    if (!approved) {
+      throw new BadRequestException(
+        'All required documents must be approved before clearance can be finalized',
+      );
+    }
+
+    const { outputCode } = clearanceCodesForBooking(booking);
+    if (outputCode) {
+      const setting = await this.fileUploadSettingsService.getByCode(outputCode);
+      const files = await this.filesService.findByResource(bookingId, 'bookings');
+      const uploaded = new Set(files.map((f) => f.code));
+      const missing = (setting.fields ?? []).filter(
+        (f) => f.isRequired && !uploaded.has(f.fileKey),
+      );
+      if (missing.length > 0) {
+        throw new BadRequestException(
+          `Upload all required customs output documents first: ${missing
+            .map((m) => m.fileLabel)
+            .join(', ')}`,
+        );
+      }
+    }
+
+    await this.bookingsRepository.update(bookingId, {
+      status: 'CLEARANCE_READY',
+    } as never);
+    return this.bookingsService.findById(bookingId);
+  }
+
+  /** Customer proceeds to operation once clearance is ready → OPERATION_REQUESTED. */
+  async requestOperation(bookingId: string): Promise<Booking> {
+    const booking = await this.bookingsService.findById(bookingId);
+    assertBookingStatus(booking, ['CLEARANCE_READY']);
+    await this.bookingsRepository.update(bookingId, {
+      status: 'OPERATION_REQUESTED',
+    } as never);
+    return this.bookingsService.findById(bookingId);
+  }
+
   async enrichBookingResponse(booking: Booking): Promise<Booking & {
     latestChangeRequestNote?: string | null;
     contractSummary?: string | null;

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

@@ -47,6 +47,7 @@ import {
   RejectBookingDto,
   RejectStepDto,
   RequestChangesDto,
+  ReviewDocumentDto,
   StaffRejectDto,
 } from './dto/request-changes.dto';
 import { ContractViewDto } from './dto/contract-view.dto';
@@ -328,6 +329,86 @@ export class BookingsController {
     return this.transitionService.enrichBookingResponse(booking);
   }
 
+  // ── Document clearance (post counter-sign) ────────────────────────────────
+
+  @Get(':id/clearance')
+  @ApiOperation({
+    summary: 'Document-clearance grid (required docs + upload + GL review status)',
+  })
+  getClearance(@Param('id', ParseUUIDPipe) id: string) {
+    return this.transitionService.getClearanceView(id);
+  }
+
+  @Post(':id/clearance/documents')
+  @UseInterceptors(AnyFilesInterceptor())
+  @ApiConsumes('multipart/form-data')
+  @ApiOperation({
+    summary: 'Customer uploads clearance documents (fieldname = document key)',
+  })
+  async submitClearanceDocuments(
+    @Param('id', ParseUUIDPipe) id: string,
+    @UploadedFiles() files: Express.Multer.File[],
+  ) {
+    const booking = await this.transitionService.submitClearanceDocuments(
+      id,
+      files ?? [],
+    );
+    return this.transitionService.enrichBookingResponse(booking);
+  }
+
+  @Post(':id/clearance/proceed')
+  @ApiOperation({
+    summary: 'Customer proceeds to operation (CLEARANCE_READY → OPERATION_REQUESTED)',
+  })
+  async proceedToOperation(@Param('id', ParseUUIDPipe) id: string) {
+    const booking = await this.transitionService.requestOperation(id);
+    return this.transitionService.enrichBookingResponse(booking);
+  }
+
+  @Post(':id/clearance/review')
+  @BookingStaff(FREIGHT_PERMS.bookings.reviewDocuments)
+  @ApiOperation({ summary: 'GL reviews a clearance document (Approve | Query)' })
+  async reviewClearanceDocument(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: ReviewDocumentDto,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    const booking = await this.transitionService.reviewDocument(
+      id,
+      dto.fileKey,
+      dto.status,
+      resolveAuthUserId(user),
+      dto.note,
+    );
+    return this.transitionService.enrichBookingResponse(booking);
+  }
+
+  @Post(':id/clearance/output-documents')
+  @BookingStaff(FREIGHT_PERMS.bookings.uploadClearanceOutput)
+  @UseInterceptors(AnyFilesInterceptor())
+  @ApiConsumes('multipart/form-data')
+  @ApiOperation({ summary: 'GL uploads customs output documents (IM4/EX3/…)' })
+  async uploadClearanceOutput(
+    @Param('id', ParseUUIDPipe) id: string,
+    @UploadedFiles() files: Express.Multer.File[],
+  ) {
+    const booking = await this.transitionService.uploadClearanceOutputDocuments(
+      id,
+      files ?? [],
+    );
+    return this.transitionService.enrichBookingResponse(booking);
+  }
+
+  @Post(':id/clearance/finalize')
+  @BookingStaff(FREIGHT_PERMS.bookings.finalizeClearance)
+  @ApiOperation({
+    summary: 'GL finalizes clearance (requires 100% approved) → CLEARANCE_READY',
+  })
+  async finalizeClearance(@Param('id', ParseUUIDPipe) id: string) {
+    const booking = await this.transitionService.finalizeClearance(id);
+    return this.transitionService.enrichBookingResponse(booking);
+  }
+
   @Post(':id/staff/request-changes')
   @BookingStaff(FREIGHT_PERMS.bookings.requestChanges)
   @ApiOperation({ summary: 'Staff return booking for customer updates' })

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

@@ -8,6 +8,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 { FileUploadSettingsModule } from '../file-upload-settings/file-upload-settings.module';
 import { SignaturesModule } from '../signatures/signatures.module';
 import { BookingContractService } from './booking-contract.service';
 import { BookingPaymentService } from './booking-payment.service';
@@ -21,6 +22,7 @@ import { ConsolidationService } from './consolidation.service';
 import { BookingsService } from './bookings.service';
 import { BookingApprovalStep } from './entities/booking-approval-step.entity';
 import { BookingCargoModifier } from './entities/booking-cargo-modifier.entity';
+import { BookingDocumentReview } from './entities/booking-document-review.entity';
 import { BookingContainer } from './entities/booking-container.entity';
 import { BookingRateSnapshot } from './entities/booking-rate-snapshot.entity';
 import { BookingContractSignature } from './entities/booking-contract-signature.entity';
@@ -41,6 +43,7 @@ import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.modu
       BookingContainer,
       BookingCargoModifier,
       BookingApprovalStep,
+      BookingDocumentReview,
       BookingRateSnapshot,
       BookingReviewNote,
       BookingContractSignature,
@@ -52,6 +55,7 @@ import { TrainSchedulingModule } from '../train-scheduling/train-scheduling.modu
     CompaniesModule,
     // CustomersModule,
     RuleEngineModule,
+    FileUploadSettingsModule,
     SignaturesModule,
     ExchangeModule.forRootAsync({
       inject: [ConfigService],

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

@@ -7,6 +7,10 @@ import { DataSource, EntityManager, FindOptionsWhere, In, Repository, SelectQuer
 import { ContainerType } from '../rule-engine/entities/container-type.entity';
 import { BookingApprovalStep } from './entities/booking-approval-step.entity';
 import { BookingCargoModifier } from './entities/booking-cargo-modifier.entity';
+import {
+  BookingDocumentReview,
+  DocumentReviewStatus,
+} from './entities/booking-document-review.entity';
 import { BookingContainer } from './entities/booking-container.entity';
 import { BookingRateSnapshot } from './entities/booking-rate-snapshot.entity';
 import { BookingReviewNote, ReviewNoteType } from './entities/booking-review-note.entity';
@@ -313,6 +317,82 @@ export class BookingsRepository extends BaseRepository<Booking> {
     return pending === 0;
   }
 
+  // ── Clearance document reviews ────────────────────────────────────────────
+
+  findDocumentReviews(bookingId: string): Promise<BookingDocumentReview[]> {
+    return this.dataSource.getRepository(BookingDocumentReview).find({
+      where: { bookingId },
+      order: { createdAt: 'ASC' },
+    });
+  }
+
+  findDocumentReview(
+    bookingId: string,
+    settingCode: string,
+    fileKey: string,
+  ): Promise<BookingDocumentReview | null> {
+    return this.dataSource.getRepository(BookingDocumentReview).findOne({
+      where: { bookingId, settingCode, fileKey },
+    });
+  }
+
+  /**
+   * Upsert a document-review row to PENDING for a freshly uploaded file. Resets
+   * any prior QUERIED/APPROVED state so the GL re-reviews the new upload.
+   */
+  async upsertDocumentReviewPending(input: {
+    bookingId: string;
+    settingCode: string;
+    fileKey: string;
+    fileRecordId: string;
+  }): Promise<void> {
+    const repo = this.dataSource.getRepository(BookingDocumentReview);
+    const existing = await repo.findOne({
+      where: {
+        bookingId: input.bookingId,
+        settingCode: input.settingCode,
+        fileKey: input.fileKey,
+      },
+    });
+    if (existing) {
+      await repo.update(existing.id, {
+        fileRecordId: input.fileRecordId,
+        status: 'PENDING',
+        note: null,
+        reviewedByStaffId: null,
+        reviewedAt: null,
+      });
+      return;
+    }
+    await repo.save(repo.create({ ...input, status: 'PENDING' }));
+  }
+
+  /** GL marks a document APPROVED or QUERIED (with an optional note). */
+  async setDocumentReviewStatus(
+    bookingId: string,
+    settingCode: string,
+    fileKey: string,
+    status: DocumentReviewStatus,
+    staffId: string,
+    note?: string,
+  ): Promise<void> {
+    const repo = this.dataSource.getRepository(BookingDocumentReview);
+    const existing = await repo.findOne({
+      where: { bookingId, settingCode, fileKey },
+    });
+    const patch = {
+      status,
+      note: note ?? null,
+      reviewedByStaffId: staffId,
+      reviewedAt: new Date(),
+    };
+    if (existing) {
+      await repo.update(existing.id, patch);
+      return;
+    }
+    await repo.save(repo.create({ bookingId, settingCode, fileKey, ...patch }));
+  }
+
   /** Persist cargo modifiers linked to rate snapshots. */
   async createCargoModifiers(
     rows: Array<{

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

@@ -0,0 +1,49 @@
+import {
+  clearanceSettingCode,
+  clearanceOutputSettingCode,
+} from './clearance.util';
+
+describe('clearance.util — clearanceSettingCode', () => {
+  it('resolves import container with/without customs', () => {
+    expect(clearanceSettingCode('IMPORT', 'CONTAINER', true)).toBe(
+      'clearance_import_container_with_customs',
+    );
+    expect(clearanceSettingCode('IMPORT', 'CONTAINER', false)).toBe(
+      'clearance_import_container_without_customs',
+    );
+  });
+
+  it('resolves export bulk with/without customs', () => {
+    expect(clearanceSettingCode('EXPORT', 'BULK', true)).toBe(
+      'clearance_export_bulk_with_customs',
+    );
+    expect(clearanceSettingCode('EXPORT', 'BULK', false)).toBe(
+      'clearance_export_bulk_without_customs',
+    );
+  });
+
+  it('returns null for DOMESTIC (no clearance gate)', () => {
+    expect(clearanceSettingCode('DOMESTIC', 'CONTAINER', true)).toBeNull();
+    expect(clearanceSettingCode('DOMESTIC', 'BULK', false)).toBeNull();
+  });
+});
+
+describe('clearance.util — clearanceOutputSettingCode', () => {
+  it('returns a container output code only for customs container bookings', () => {
+    expect(clearanceOutputSettingCode('IMPORT', 'CONTAINER', true)).toBe(
+      'clearance_output_import_container',
+    );
+    expect(clearanceOutputSettingCode('EXPORT', 'CONTAINER', true)).toBe(
+      'clearance_output_export_container',
+    );
+  });
+
+  it('returns null without customs', () => {
+    expect(clearanceOutputSettingCode('IMPORT', 'CONTAINER', false)).toBeNull();
+  });
+
+  it('returns null for bulk (no container output set) and domestic', () => {
+    expect(clearanceOutputSettingCode('IMPORT', 'BULK', true)).toBeNull();
+    expect(clearanceOutputSettingCode('DOMESTIC', 'CONTAINER', true)).toBeNull();
+  });
+});

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

@@ -0,0 +1,70 @@
+import { Booking } from './entities/booking.entity';
+
+/**
+ * Resolves which seeded clearance FileUploadSetting applies to a booking, from
+ * its trade direction, freight type and whether its service includes customs.
+ * Mirrors the codes seeded in file-upload-settings.seeder.ts.
+ */
+
+type Op = 'import' | 'export';
+type Freight = 'container' | 'bulk';
+
+/** Trade direction → clearance operation. DOMESTIC has no customs clearance. */
+function operationFor(tradeDirection: string): Op | null {
+  if (tradeDirection === 'IMPORT') return 'import';
+  if (tradeDirection === 'EXPORT') return 'export';
+  return null; // DOMESTIC / intercity — no clearance gate
+}
+
+function freightFor(freightType: string): Freight {
+  return freightType === 'BULK' ? 'bulk' : 'container';
+}
+
+/** The customer-input clearance setting code, or null when no gate applies. */
+export function clearanceSettingCode(
+  tradeDirection: string,
+  freightType: string,
+  includesCustoms: boolean,
+): string | null {
+  const op = operationFor(tradeDirection);
+  if (!op) return null;
+  const freight = freightFor(freightType);
+  const customs = includesCustoms ? 'with_customs' : 'without_customs';
+  return `clearance_${op}_${freight}_${customs}`;
+}
+
+/** The GL-output (customs output) setting code; only container customs sets exist. */
+export function clearanceOutputSettingCode(
+  tradeDirection: string,
+  freightType: string,
+  includesCustoms: boolean,
+): string | null {
+  if (!includesCustoms) return null;
+  const op = operationFor(tradeDirection);
+  if (!op) return null;
+  // Only container customs output sets are seeded for this phase.
+  if (freightFor(freightType) !== 'container') return null;
+  return `clearance_output_${op}_container`;
+}
+
+/** Convenience: resolve both codes for a loaded booking (with its serviceType). */
+export function clearanceCodesForBooking(booking: Booking): {
+  inputCode: string | null;
+  outputCode: string | null;
+  includesCustoms: boolean;
+} {
+  const includesCustoms = booking.serviceType?.includesCustoms ?? false;
+  return {
+    inputCode: clearanceSettingCode(
+      booking.tradeDirection,
+      booking.freightType,
+      includesCustoms,
+    ),
+    outputCode: clearanceOutputSettingCode(
+      booking.tradeDirection,
+      booking.freightType,
+      includesCustoms,
+    ),
+    includesCustoms,
+  };
+}

apps/edr-freight-api/src/modules/bookings/dto/request-changes.dto.ts

@@ -1,5 +1,5 @@
 import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsOptional, IsString, MinLength } from 'class-validator';
+import { IsIn, IsOptional, IsString, MinLength } from 'class-validator';
 
 export class RequestChangesDto {
   @ApiProperty({ description: 'Staff note explaining what the customer must fix' })
@@ -43,3 +43,19 @@ export class RejectBookingDto {
   @IsString()
   reason?: string;
 }
+
+export class ReviewDocumentDto {
+  @ApiProperty({ description: 'The document fileKey being reviewed' })
+  @IsString()
+  @MinLength(1)
+  fileKey!: string;
+
+  @ApiProperty({ enum: ['APPROVED', 'QUERIED'] })
+  @IsIn(['APPROVED', 'QUERIED'])
+  status!: 'APPROVED' | 'QUERIED';
+
+  @ApiPropertyOptional({ description: 'Required when querying a document' })
+  @IsOptional()
+  @IsString()
+  note?: string;
+}

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

@@ -0,0 +1,51 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+import { Booking } from './booking.entity';
+
+export const DOCUMENT_REVIEW_STATUSES = ['PENDING', 'APPROVED', 'QUERIED'] as const;
+export type DocumentReviewStatus = (typeof DOCUMENT_REVIEW_STATUSES)[number];
+
+/**
+ * Per-document GL review for the post-counter-sign clearance gate. One row per
+ * required clearance document (keyed by fileKey within a setting). GL marks each
+ * APPROVED or QUERIED (with a note); the booking can only proceed once every
+ * required customer document is APPROVED. A QUERIED row returns to PENDING when
+ * the customer re-uploads that file.
+ */
+@Entity({ schema: 'freight', name: 'booking_document_review' })
+@Index(['bookingId'])
+@Index(['status'])
+@Index(['bookingId', 'settingCode', 'fileKey'], { unique: true })
+export class BookingDocumentReview extends BaseEntity {
+  @Column({ name: 'booking_id', type: 'uuid' })
+  bookingId!: string;
+
+  @ManyToOne(() => Booking, { onDelete: 'CASCADE' })
+  @JoinColumn({ name: 'booking_id' })
+  booking?: Booking;
+
+  /** The clearance setting this document belongs to (e.g. clearance_import_container_with_customs). */
+  @Column({ name: 'setting_code', type: 'varchar', length: 128 })
+  settingCode!: string;
+
+  /** The required document's stable key within the setting (e.g. commercial_invoice). */
+  @Column({ name: 'file_key', type: 'varchar', length: 128 })
+  fileKey!: string;
+
+  /** The uploaded FileRecord backing this review row (null until uploaded). */
+  @Column({ name: 'file_record_id', type: 'uuid', nullable: true })
+  fileRecordId?: string | null;
+
+  @Column({ name: 'status', type: 'varchar', length: 20, default: 'PENDING' })
+  status!: DocumentReviewStatus;
+
+  /** GL note explaining a QUERIED status. */
+  @Column({ name: 'note', type: 'text', nullable: true })
+  note?: string | null;
+
+  @Column({ name: 'reviewed_by_staff_id', type: 'uuid', nullable: true })
+  reviewedByStaffId?: string | null;
+
+  @Column({ name: 'reviewed_at', type: 'timestamptz', nullable: true })
+  reviewedAt?: Date | null;
+}

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

@@ -43,6 +43,11 @@ export const BOOKING_STATUSES = [
   'CONSOLIDATED',
   'CONTRACT_ACTIVE',
   'CONTRACT_CLOSED',
+  // Post counter-sign document-clearance gate (GL workflow).
+  'AWAITING_DOCUMENTS',
+  'DOCUMENTS_UNDER_REVIEW',
+  'CLEARANCE_READY',
+  'OPERATION_REQUESTED',
 ] as const;
 
 export type BookingStatus = (typeof BOOKING_STATUSES)[number];