feat(bookings): two-level clearance charges (port + misc) billed to customer with invoices

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

@@ -1,4 +1,5 @@
 import {
+  BadRequestException,
   Body,
   Controller,
   Delete,
@@ -38,6 +39,8 @@ import {
 } from "@nestjs/swagger";
 import type { Response } from "express";
 
+import { BookingClearanceChargeService } from './booking-clearance-charge.service';
+import { BillClearanceChargeDto } from './dto/clearance-charge.dto';
 import { BookingContractService } from './booking-contract.service';
 import { BookingPricingService } from './booking-pricing.service';
 import { BookingTransitionService } from './booking-transition.service';
@@ -170,6 +173,7 @@ export class BookingsController {
     private readonly userTradeAccessService: UserTradeAccessService,
     private readonly wagonCancellationService: BookingWagonCancellationService,
     private readonly consolidationApprovalService: ConsolidationApprovalService,
+    private readonly clearanceChargeService: BookingClearanceChargeService,
   ) {}
 
   @Post()
@@ -1073,6 +1077,96 @@ export class BookingsController {
     return this.transitionService.enrichBookingResponse(booking);
   }
 
+  // ── Clearance charges (post-finalization customer billing) ────────────────
+
+  @Get(":id/clearance/charges")
+  @BookingStaff([
+    FREIGHT_PERMS.contracts.clearanceEtActions,
+    FREIGHT_PERMS.contracts.clearanceDjActions,
+  ])
+  @ApiOperation({
+    summary: "Clearance charges billed to the customer (port + miscellaneous)",
+  })
+  getClearanceCharges(@Param("id", ParseUUIDPipe) id: string) {
+    return this.clearanceChargeService.list(id);
+  }
+
+  @Post(":id/clearance/charges/port-document")
+  @BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
+  @UseInterceptors(FileInterceptor("file"))
+  @ApiConsumes("multipart/form-data")
+  @ApiOperation({
+    summary: "GL Djibouti uploads (or replaces, until billed) the port-charges document",
+  })
+  uploadPortChargeDocument(
+    @Param("id", ParseUUIDPipe) id: string,
+    @UploadedFile() file: Express.Multer.File,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    if (!file) throw new BadRequestException("A document file is required");
+    return this.clearanceChargeService.uploadPortDocument(
+      id,
+      file,
+      resolveAuthUserId(user),
+    );
+  }
+
+  @Patch(":id/clearance/charges/:chargeId/bill")
+  @BookingStaff(FREIGHT_PERMS.contracts.clearanceEtActions)
+  @ApiOperation({
+    summary:
+      "GL Ethiopia sets or revises the charge's amount + currency (revising a sent charge cancels its unpaid invoice)",
+  })
+  billClearanceCharge(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Param("chargeId", ParseUUIDPipe) chargeId: string,
+    @Body() dto: BillClearanceChargeDto,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    return this.clearanceChargeService.billCharge(
+      id,
+      chargeId,
+      dto,
+      resolveAuthUserId(user),
+    );
+  }
+
+  @Post(":id/clearance/charges/:chargeId/send")
+  @BookingStaff(FREIGHT_PERMS.contracts.clearanceEtActions)
+  @ApiOperation({
+    summary:
+      "GL Ethiopia issues the charge's payable invoice to the customer (ETB pays via gateway, other currencies via manual settlement)",
+  })
+  sendClearanceCharge(
+    @Param("id", ParseUUIDPipe) id: string,
+    @Param("chargeId", ParseUUIDPipe) chargeId: string,
+  ) {
+    return this.clearanceChargeService.sendCharge(id, chargeId);
+  }
+
+  @Post(":id/clearance/charges/miscellaneous")
+  @BookingStaff(FREIGHT_PERMS.contracts.clearanceEtActions)
+  @UseInterceptors(FileInterceptor("file"))
+  @ApiConsumes("multipart/form-data")
+  @ApiOperation({
+    summary:
+      "GL Ethiopia creates the miscellaneous charge (document + amount + currency); unlocked once the port charge is paid",
+  })
+  createMiscellaneousCharge(
+    @Param("id", ParseUUIDPipe) id: string,
+    @UploadedFile() file: Express.Multer.File,
+    @Body() dto: BillClearanceChargeDto,
+    @CurrentUser() user: AuthUserPayload,
+  ) {
+    if (!file) throw new BadRequestException("A document file is required");
+    return this.clearanceChargeService.createMiscellaneous(
+      id,
+      file,
+      dto,
+      resolveAuthUserId(user),
+    );
+  }
+
   @Post(":id/clearance/output-documents")
   @BookingStaff(FREIGHT_PERMS.bookings.uploadClearanceOutput)
   @UseInterceptors(AnyFilesInterceptor())