Merge branch 'dev' into freight/nati-2

# Conflicts:
#	apps/edr-freight-api/src/app.module.ts
#	apps/edr-freight-api/src/seed/freight-permissions.registry.ts
#	apps/edr-freight-web/backoffice/src/components/layout/sidebar-sections.tsx
#	apps/edr-freight-web/backoffice/src/constants/URLS.ts
#	apps/edr-freight-web/backoffice/src/lib/permissions.ts

packages/types/src/freight/index.ts

@@ -188,6 +188,11 @@ export enum InvoiceSource {
   LastMile = "lastmile",
   /** Customs clearance service fee — billed on the booking invoice with the freight. */
   Clearance = "clearance",
+  /**
+   * Post-finalization clearance charge (port charges / miscellaneous) billed
+   * to the customer as its own payable invoice. `sourceId` is the charge id.
+   */
+  ClearanceCharge = "clearance_charge",
   /**
    * A batch of shipping-line credits billed together. Unlike every other
    * source, `sourceId` is the shipping line's id rather than a single record's:
@@ -802,6 +807,65 @@ export interface PricingBreakdown {
 
 export type DocumentReviewStatus = "PENDING" | "APPROVED" | "QUERIED";
 
+// ── Clearance history (per-booking action trail, History tab) ───────────────
+
+/** One recorded clearance action — review, workflow step, or charge. */
+export interface ClearanceHistoryEvent {
+  id: string;
+  /** Stable machine code, e.g. DOC_APPROVED, DECLARATION_UPLOADED. */
+  action: string;
+  /** Human sentence, frozen at write time. */
+  label: string;
+  actorType: "STAFF" | "CUSTOMER" | "SYSTEM";
+  actorName: string | null;
+  metadata: Record<string, unknown> | null;
+  at: string;
+}
+
+// ── Clearance charges (post-finalization customer billing) ──────────────────
+
+export type ClearanceChargeType = "PORT_CHARGES" | "MISCELLANEOUS";
+
+/**
+ * DOC_UPLOADED: GL Djibouti uploaded the supporting document (port charges).
+ * BILLED: GL Ethiopia set amount + currency. SENT: invoice issued to the
+ * customer (ETB pays via gateway, other currencies via Finance's manual
+ * settlement). PAID: the invoice settled.
+ */
+export type ClearanceChargeStatus =
+  | "DOC_UPLOADED"
+  | "BILLED"
+  | "SENT"
+  | "PAID";
+
+/** One clearance charge level on a booking — at most one per type. */
+export interface ClearanceCharge {
+  id: string;
+  bookingId: string;
+  type: ClearanceChargeType;
+  status: ClearanceChargeStatus;
+  file: { id: string; name: string; url: string } | null;
+  amount: number | null;
+  currency: string | null;
+  invoiceId: string | null;
+  invoiceNumber: string | null;
+  uploadedByName: string | null;
+  uploadedAt: string | null;
+  billedByName: string | null;
+  billedAt: string | null;
+  paidAt: string | null;
+}
+
+/** One entry of a clearance document's audit trail, oldest first. */
+export interface ClearanceDocumentEvent {
+  type: "UPLOADED" | "RESUBMITTED" | "QUERIED" | "APPROVED";
+  at: string;
+  /** Actor display name (staff for reviews; null = the customer/unknown). */
+  byName: string | null;
+  /** Query reason, for QUERIED events. */
+  note: string | null;
+}
+
 /** One row of the clearance document grid (a required doc + its file + review). */
 export interface ClearanceDocument {
   fileKey: string;
@@ -813,6 +877,14 @@ export interface ClearanceDocument {
   file: { id: string; name: string; url: string } | null;
   reviewStatus: DocumentReviewStatus | null;
   note: string | null;
+  /** When the current file version was uploaded — a re-upload (query response) refreshes it. */
+  uploadedAt?: string | null;
+  /** When the latest review decision (approve/query) was recorded. */
+  reviewedAt?: string | null;
+  /** Display name of the staff member who recorded the decision. */
+  reviewedByName?: string | null;
+  /** Full audit trail: uploads, re-submissions, queries, approval. */
+  history?: ClearanceDocumentEvent[];
 }
 
 /**
@@ -852,6 +924,12 @@ export interface ClearanceView {
   documents: ClearanceDocument[];
   /** True once every required customer document is APPROVED (the 100% gate). */
   allApproved: boolean;
+  /**
+   * True while the customer may still attach documents and GL may still
+   * approve or query them — open until the shipment is paid, not merely until
+   * clearance is finalized.
+   */
+  documentsOpen?: boolean;
   /** Phased clearance (GENERAL + customs per-booking). */
   phase?: ContractDocPhase | null;
   milestones?: IClearanceMilestone[];