feat: Implement general contract booking orders functionality

- Add DTOs for creating booking orders and viewing contract quantities.
- Create entities for booking orders and booking order lines.
- Implement service for managing general contract operations, including activation after payment and retrieving quantity lines.
- Develop UI components for contract detail and list pages, including order placement dialog.
- Integrate API service for booking orders, enabling listing and creating orders against contracts.
- Enhance contract status display and quantity pool visualization in the UI.

packages/types/src/freight/index.ts

@@ -42,6 +42,26 @@ export enum FreightType {
   Bulk = "BULK",
 }
 
+/**
+ * Distinguishes a normal one-time booking from a general contract — an umbrella
+ * commitment that is signed and paid once, then drawn down by many orders over
+ * its period. Stored on the booking row.
+ */
+export enum BookingType {
+  OneTime = "ONE_TIME",
+  GeneralContract = "GENERAL_CONTRACT",
+}
+
+/**
+ * How a cargo type's quantity is measured. Bulk cargo is weighed in tons,
+ * break-bulk is counted per item. Containerised freight is always counted by
+ * container and carries no unit-of-measure.
+ */
+export enum CargoUnitOfMeasure {
+  PerTon = "PER_TON",
+  PerItem = "PER_ITEM",
+}
+
 export enum BookingStatus {
   Draft = "DRAFT",
   Submitted = "SUBMITTED",
@@ -68,6 +88,10 @@ export enum BookingStatus {
   Cancelled = "CANCELLED",
   PendingConsolidation = "PENDING_CONSOLIDATION",
   Consolidated = "CONSOLIDATED",
+  /** General contract: paid umbrella contract that is accepting drawdown orders. */
+  ContractActive = "CONTRACT_ACTIVE",
+  /** General contract: closed because its quantity was exhausted (or period elapsed). */
+  ContractClosed = "CONTRACT_CLOSED",
 }
 
 export enum ConsignmentStatus {
@@ -329,6 +353,11 @@ export interface IBooking extends BaseEntity {
   customerId: string;
   trainId?: string | null;
   status: BookingStatus;
+  /** ONE_TIME for normal bookings; GENERAL_CONTRACT for umbrella contracts. */
+  bookingType?: BookingType;
+  /** General contracts only: when ordering closes (null until active / for one-time). */
+  expiresAt?: string | null;
+  /** Null for general contracts at creation — the date is chosen per order. */
   scheduledDate: string;
   totalAmount: number;
   paymentStatus: PaymentStatus;
@@ -474,6 +503,8 @@ export interface BookingReferenceCargoTypeChild {
   name: string;
   code: string;
   show_free_text_box: boolean;
+  /** How this cargo is measured (PER_TON / PER_ITEM); null when unset. */
+  unit_of_measure?: CargoUnitOfMeasure | null;
 }
 
 export interface BookingReferenceCargoTypeGroup {
@@ -554,7 +585,10 @@ export interface CreateBookingDto {
   companyId?: string | undefined;
   trainId?: string | undefined;
   trainScheduleId?: string | undefined;
-  scheduledDate: string;
+  /** Optional for general contracts — they pick the date per order, not at creation. */
+  scheduledDate?: string | undefined;
+  /** Defaults to ONE_TIME. GENERAL_CONTRACT creates an umbrella contract. */
+  bookingType?: BookingType | undefined;
   contractType: string;
   previousContractId?: string | undefined;
   serviceTypeId: string;
@@ -578,3 +612,73 @@ export interface CreateBookingDto {
   containers?: CreateBookingContainerDto[];
   allowConsolidation?: boolean;
 }
+
+// ── General Contracts & Booking Orders ──────────────────────────────────────────
+
+/**
+ * A line of contracted quantity. For CONTAINER contracts there is one line per
+ * container type (each its own drawdown pool); for BULK/BREAK_BULK a single line
+ * with a null containerTypeId carries the total tons/items.
+ */
+export interface ContractQuantityLine {
+  containerTypeId: string | null;
+  containerTypeName?: string | null;
+  /** PER_TON / PER_ITEM for bulk-style lines; null for container lines. */
+  unitOfMeasure?: CargoUnitOfMeasure | null;
+  /** Total contracted units on this line (containers, tons, or items). */
+  contractedQuantity: number;
+  /** Units already drawn down by non-cancelled orders. */
+  orderedQuantity: number;
+  /** contractedQuantity − orderedQuantity. */
+  remainingQuantity: number;
+}
+
+/**
+ * Customer-facing view of a general contract (a Booking with
+ * bookingType = GENERAL_CONTRACT) and its remaining drawdown pool.
+ */
+export interface IGeneralContract extends IBooking {
+  bookingType: BookingType;
+  /** When the contract becomes ACTIVE; when ordering closes. Null until active. */
+  expiresAt?: string | null;
+  /** Per-line contracted / ordered / remaining quantities. */
+  quantityLines: ContractQuantityLine[];
+}
+
+export interface CreateBookingOrderLineDto {
+  /** Null for bulk/break-bulk; the container type id for container contracts. */
+  containerTypeId?: string | null;
+  quantity: number;
+}
+
+export interface CreateBookingOrderDto {
+  /** The general contract (booking) this order draws down from. */
+  contractBookingId: string;
+  /** The shipment day the customer wants for this order. */
+  scheduledDate: string;
+  lines: CreateBookingOrderLineDto[];
+}
+
+export interface IBookingOrderLine {
+  id: string;
+  containerTypeId?: string | null;
+  containerTypeName?: string | null;
+  quantity: number;
+}
+
+export interface IBookingOrder {
+  id: string;
+  reference: string;
+  contractBookingId: string;
+  /** The child shipment booking spawned for this order (enters scheduling). */
+  bookingId?: string | null;
+  bookingReference?: string | null;
+  companyId?: string | null;
+  scheduledDate: string;
+  status: BookingStatus;
+  schedulingStatus: SchedulingStatus;
+  trainScheduleId?: string | null;
+  lines: IBookingOrderLine[];
+  createdAt: string;
+  updatedAt: string;
+}