/gi, '\n')
+ .replace(/<[^>]+>/g, ' ')
+ .replace(/ /gi, ' ')
+ .replace(/&/gi, '&')
+ .replace(/</gi, '<')
+ .replace(/>/gi, '>')
+ .replace(/"/gi, '"')
+ .replace(/'/g, "'")
+ .replace(/[^\x09\x0a\x0d\x20-\x7e]/g, '-')
+ .split('\n')
+ .map((line) => line.replace(/\s+/g, ' ').trim())
+ .filter(Boolean)
+ .join('\n');
+ }
+
+ private wrapLines(text: string, width: number): string[] {
+ const wrapped: string[] = [];
+ for (const rawLine of text.split('\n')) {
+ const words = rawLine.split(' ');
+ let line = '';
+ for (const word of words) {
+ const next = line ? `${line} ${word}` : word;
+ if (next.length > width && line) {
+ wrapped.push(line);
+ line = word;
+ } else {
+ line = next;
+ }
+ }
+ if (line) wrapped.push(line);
+ }
+ return wrapped.length ? wrapped : ['Document'];
+ }
+
+ private escapePdfText(value: string): string {
+ return value.replace(/\\/g, '\\\\').replace(/\(/g, '\\(').replace(/\)/g, '\\)');
+ }
}
diff --git a/apps/edr-freight-api/src/contracts/templates/_partials/article5_pricing.hbs b/apps/edr-freight-api/src/contracts/templates/_partials/article5_pricing.hbs
index cb3440739..64319612a 100644
--- a/apps/edr-freight-api/src/contracts/templates/_partials/article5_pricing.hbs
+++ b/apps/edr-freight-api/src/contracts/templates/_partials/article5_pricing.hbs
@@ -25,6 +25,26 @@
Equipment return: {{pricing.equipmentReturn}}
{{/if}}
+ {{#if pricing.unitRates}}
+ Unit Rate Schedule
+
+ The rates below are the frozen unit prices applicable to this contract. Quantities and the resulting
+ totals are determined per shipment at booking time; no total contract value is fixed at this stage.
+
+
+
+ | Item | Unit price |
|---|
+
+
+ {{#each pricing.unitRates}}
+
+ | {{label}} |
+ {{currency}} {{unitPrice}} / {{unit}} |
+
+ {{/each}}
+
+
+ {{else}}
Charges
+ {{/if}}
Terms of payment
Unless otherwise agreed in writing, the Client shall settle the contract value in
diff --git a/apps/edr-freight-api/src/migrations/1748427600000-AddServiceTypesAndCargoTypes.ts b/apps/edr-freight-api/src/migrations/1748427600000-AddServiceTypesAndCargoTypes.ts
index 65052bad4..08ce634eb 100644
--- a/apps/edr-freight-api/src/migrations/1748427600000-AddServiceTypesAndCargoTypes.ts
+++ b/apps/edr-freight-api/src/migrations/1748427600000-AddServiceTypesAndCargoTypes.ts
@@ -93,20 +93,25 @@ export class AddServiceTypesAndCargoTypes1748427600000 implements MigrationInter
);
// Create indexes for service_types
- await queryRunner.createIndex(
- "freight.service_types",
- new TableIndex({
- name: "IDX_SERVICE_TYPES_IS_ACTIVE",
- columnNames: ["is_active"],
- }),
- );
- await queryRunner.createIndex(
- "freight.service_types",
- new TableIndex({
- name: "IDX_SERVICE_TYPES_DISPLAY_ORDER",
- columnNames: ["display_order"],
- }),
- );
+ const table = await queryRunner.getTable("freight.service_types");
+ if (table && !table.indices.some((idx) => idx.name === "IDX_SERVICE_TYPES_IS_ACTIVE")) {
+ await queryRunner.createIndex(
+ "freight.service_types",
+ new TableIndex({
+ name: "IDX_SERVICE_TYPES_IS_ACTIVE",
+ columnNames: ["is_active"],
+ }),
+ );
+ }
+ if (table && !table.indices.some((idx) => idx.name === "IDX_SERVICE_TYPES_DISPLAY_ORDER")) {
+ await queryRunner.createIndex(
+ "freight.service_types",
+ new TableIndex({
+ name: "IDX_SERVICE_TYPES_DISPLAY_ORDER",
+ columnNames: ["display_order"],
+ }),
+ );
+ }
// Create cargo_types table
if (!(await queryRunner.hasTable("freight.cargo_types"))) await queryRunner.createTable(
diff --git a/apps/edr-freight-api/src/migrations/1790000000000-CreateWarehouseModule.ts b/apps/edr-freight-api/src/migrations/1790000000000-CreateWarehouseModule.ts
index b921a7194..0f9021ff2 100644
--- a/apps/edr-freight-api/src/migrations/1790000000000-CreateWarehouseModule.ts
+++ b/apps/edr-freight-api/src/migrations/1790000000000-CreateWarehouseModule.ts
@@ -78,6 +78,7 @@ export class CreateWarehouseModule1790000000000 implements MigrationInterface {
weight NUMERIC(14,3) NOT NULL DEFAULT 0,
volume NUMERIC(12,3) NULL,
status VARCHAR(32) NOT NULL DEFAULT 'ARRIVED_AT_WAREHOUSE',
+ inspection_status VARCHAR(20) NULL,
arrived_at TIMESTAMPTZ NULL,
inspected_at TIMESTAMPTZ NULL,
ready_for_loading_at TIMESTAMPTZ NULL,
diff --git a/apps/edr-freight-api/src/migrations/1791000000000-AddWarehouseAllocationAndFeeRules.ts b/apps/edr-freight-api/src/migrations/1791000000000-AddWarehouseAllocationAndFeeRules.ts
index fa6087faa..1cad0fe66 100644
--- a/apps/edr-freight-api/src/migrations/1791000000000-AddWarehouseAllocationAndFeeRules.ts
+++ b/apps/edr-freight-api/src/migrations/1791000000000-AddWarehouseAllocationAndFeeRules.ts
@@ -56,6 +56,7 @@ export class AddWarehouseAllocationAndFeeRules1791000000000 implements Migration
{ name: 'zone_id', type: 'uuid', isNullable: true },
{ name: 'free_days', type: 'int', default: 0 },
{ name: 'rate_per_day', type: 'numeric', precision: 14, scale: 2, default: 0 },
+ { name: 'tiers', type: 'jsonb', default: "'[]'" },
{ name: 'currency', type: 'varchar', length: '8', default: "'USD'" },
{ name: 'is_active', type: 'boolean', default: true },
{ name: 'created_at', type: 'timestamptz', default: 'now()' },
diff --git a/apps/edr-freight-api/src/migrations/1791000000005-AddWarehouseInventoryInspectionStatusFix.ts b/apps/edr-freight-api/src/migrations/1791000000005-AddWarehouseInventoryInspectionStatusFix.ts
new file mode 100644
index 000000000..4a59e33b1
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1791000000005-AddWarehouseInventoryInspectionStatusFix.ts
@@ -0,0 +1,24 @@
+import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm';
+
+/**
+ * Fix for fresh deployments: AddWarehouseInspection1750000000003 runs before
+ * the warehouse_inventory table exists, so it cannot add inspection_status.
+ */
+export class AddWarehouseInventoryInspectionStatusFix1791000000005 implements MigrationInterface {
+ private readonly table = 'freight.warehouse_inventory';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ if ((await queryRunner.hasTable(this.table)) && !(await queryRunner.hasColumn(this.table, 'inspection_status'))) {
+ await queryRunner.addColumn(
+ this.table,
+ new TableColumn({ name: 'inspection_status', type: 'varchar', length: '20', isNullable: true }),
+ );
+ }
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ if ((await queryRunner.hasTable(this.table)) && (await queryRunner.hasColumn(this.table, 'inspection_status'))) {
+ await queryRunner.dropColumn(this.table, 'inspection_status');
+ }
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1792000000004-SeedContractValidityPeriods.ts b/apps/edr-freight-api/src/migrations/1792000000004-SeedContractValidityPeriods.ts
new file mode 100644
index 000000000..e635d19c1
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1792000000004-SeedContractValidityPeriods.ts
@@ -0,0 +1,55 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Seeds the admin-configurable "contract validity periods" setting (days). Stored
+ * as a dropdown_settings row whose options each hold a day count in `value`, so
+ * backoffice manages them through the existing Dropdown Settings UI and the
+ * contract staff-accept dialog only offers the configured durations.
+ */
+export class SeedContractValidityPeriods1792000000004
+ implements MigrationInterface
+{
+ name = 'SeedContractValidityPeriods1792000000004';
+ private readonly code = 'contract_validity_periods';
+ private readonly options: Array<{ value: string; label: string }> = [
+ { value: '180', label: '6 months' },
+ { value: '365', label: '1 year' },
+ { value: '730', label: '2 years' },
+ ];
+
+ public async up(queryRunner: QueryRunner): Promise {
+ const existing = await queryRunner.query(
+ `SELECT id FROM freight.dropdown_settings WHERE code = $1 LIMIT 1;`,
+ [this.code],
+ );
+ if (existing.length > 0) return;
+
+ const inserted = await queryRunner.query(
+ `INSERT INTO freight.dropdown_settings (code, label, description, multiple)
+ VALUES ($1, $2, $3, false)
+ RETURNING id;`,
+ [
+ this.code,
+ 'Contract Validity Periods (days)',
+ 'Validity durations (in days) a staff can choose when accepting a submitted contract.',
+ ],
+ );
+ const settingId = inserted[0].id;
+
+ for (let i = 0; i < this.options.length; i++) {
+ const opt = this.options[i];
+ await queryRunner.query(
+ `INSERT INTO freight.dropdown_options (setting_id, value, label, display_order)
+ VALUES ($1, $2, $3, $4);`,
+ [settingId, opt.value, opt.label, i],
+ );
+ }
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `DELETE FROM freight.dropdown_settings WHERE code = $1;`,
+ [this.code],
+ );
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1810000000002-CreateLastMileContainerAllocations.ts b/apps/edr-freight-api/src/migrations/1810000000002-CreateLastMileContainerAllocations.ts
new file mode 100644
index 000000000..b2026b753
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1810000000002-CreateLastMileContainerAllocations.ts
@@ -0,0 +1,78 @@
+import { MigrationInterface, QueryRunner, Table, TableForeignKey } from 'typeorm';
+
+/**
+ * Create the freight.last_mile_container_allocations table β container allocation
+ * records linking last-mile deliveries with containers and vehicles.
+ */
+export class CreateLastMileContainerAllocations1810000000002 implements MigrationInterface {
+ public async up(queryRunner: QueryRunner): Promise {
+ const exists = await queryRunner.hasTable('freight.last_mile_container_allocations');
+ if (exists) return;
+
+ await queryRunner.createTable(
+ new Table({
+ name: 'freight.last_mile_container_allocations',
+ columns: [
+ {
+ name: 'id',
+ type: 'uuid',
+ isPrimary: true,
+ default: 'gen_random_uuid()',
+ },
+ { name: 'last_mile_id', type: 'uuid', isNullable: false },
+ { name: 'container_id', type: 'uuid', isNullable: false },
+ { name: 'vehicle_id', type: 'uuid', isNullable: true },
+ {
+ name: 'container_type',
+ type: 'text',
+ isNullable: false,
+ },
+ {
+ name: 'quantity',
+ type: 'integer',
+ default: 1,
+ isNullable: false,
+ },
+ { name: 'created_at', type: 'timestamptz', default: 'now()' },
+ { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+ { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+ ],
+ }),
+ true,
+ );
+
+ await queryRunner.createForeignKey(
+ 'freight.last_mile_container_allocations',
+ new TableForeignKey({
+ columnNames: ['last_mile_id'],
+ referencedTableName: 'freight.last_mile',
+ referencedColumnNames: ['id'],
+ onDelete: 'CASCADE',
+ }),
+ );
+
+ await queryRunner.createForeignKey(
+ 'freight.last_mile_container_allocations',
+ new TableForeignKey({
+ columnNames: ['vehicle_id'],
+ referencedTableName: 'freight.vehicles',
+ referencedColumnNames: ['id'],
+ onDelete: 'SET NULL',
+ }),
+ );
+
+ await queryRunner.query(
+ `CREATE INDEX "IDX_last_mile_container_allocations_last_mile_id" ON "freight"."last_mile_container_allocations" ("last_mile_id")`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX "IDX_last_mile_container_allocations_vehicle_id" ON "freight"."last_mile_container_allocations" ("vehicle_id")`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ const exists = await queryRunner.hasTable('freight.last_mile_container_allocations');
+ if (exists) {
+ await queryRunner.dropTable('freight.last_mile_container_allocations');
+ }
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1810000000004-AddPostPaymentCompletedColumn.ts b/apps/edr-freight-api/src/migrations/1810000000004-AddPostPaymentCompletedColumn.ts
new file mode 100644
index 000000000..aeedae2b1
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1810000000004-AddPostPaymentCompletedColumn.ts
@@ -0,0 +1,51 @@
+import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm';
+
+export class AddPostPaymentCompletedColumn1810000000004 implements MigrationInterface {
+ name = 'AddPostPaymentCompletedColumn1810000000004';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ const firstMileTable = await queryRunner.hasTable('freight.first_mile_deliveries');
+ if (firstMileTable) {
+ const hasColumn = await queryRunner.hasColumn('freight.first_mile_deliveries', 'is_post_payment_completed');
+ if (!hasColumn) {
+ await queryRunner.addColumn(
+ 'freight.first_mile_deliveries',
+ new TableColumn({
+ name: 'is_post_payment_completed',
+ type: 'boolean',
+ default: false,
+ isNullable: false,
+ })
+ );
+ }
+ }
+
+ const lastMileTable = await queryRunner.hasTable('freight.last_mile_deliveries');
+ if (lastMileTable) {
+ const hasColumn = await queryRunner.hasColumn('freight.last_mile_deliveries', 'is_post_payment_completed');
+ if (!hasColumn) {
+ await queryRunner.addColumn(
+ 'freight.last_mile_deliveries',
+ new TableColumn({
+ name: 'is_post_payment_completed',
+ type: 'boolean',
+ default: false,
+ isNullable: false,
+ })
+ );
+ }
+ }
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ const lastMileTable = await queryRunner.hasTable('freight.last_mile_deliveries');
+ if (lastMileTable) {
+ await queryRunner.dropColumn('freight.last_mile_deliveries', 'is_post_payment_completed');
+ }
+
+ const firstMileTable = await queryRunner.hasTable('freight.first_mile_deliveries');
+ if (firstMileTable) {
+ await queryRunner.dropColumn('freight.first_mile_deliveries', 'is_post_payment_completed');
+ }
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1821000000001-EnsureWarehouseInventoryInspectionStatus.ts b/apps/edr-freight-api/src/migrations/1821000000001-EnsureWarehouseInventoryInspectionStatus.ts
new file mode 100644
index 000000000..523772b39
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1821000000001-EnsureWarehouseInventoryInspectionStatus.ts
@@ -0,0 +1,39 @@
+import { MigrationInterface, QueryRunner, TableColumn } from 'typeorm';
+
+/**
+ * Catch-up for environments where AddWarehouseInspection ran before the
+ * warehouse module table existed. Production needs this column for unload and
+ * inspection flows because the WarehouseInventory entity maps inspectionStatus.
+ */
+export class EnsureWarehouseInventoryInspectionStatus1821000000001 implements MigrationInterface {
+ private readonly table = 'freight.warehouse_inventory';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ if (!(await queryRunner.hasColumn(this.table, 'inspection_status'))) {
+ await queryRunner.addColumn(
+ this.table,
+ new TableColumn({
+ name: 'inspection_status',
+ type: 'varchar',
+ length: '20',
+ isNullable: true,
+ }),
+ );
+ }
+
+ await queryRunner.query(`
+ CREATE INDEX IF NOT EXISTS idx_warehouse_inventory_inspection_status
+ ON freight.warehouse_inventory(inspection_status)
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ DROP INDEX IF EXISTS freight.idx_warehouse_inventory_inspection_status
+ `);
+
+ if (await queryRunner.hasColumn(this.table, 'inspection_status')) {
+ await queryRunner.dropColumn(this.table, 'inspection_status');
+ }
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1821000000002-AddDistanceColumnsToVehicles.ts b/apps/edr-freight-api/src/migrations/1821000000002-AddDistanceColumnsToVehicles.ts
new file mode 100644
index 000000000..98fa8b228
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1821000000002-AddDistanceColumnsToVehicles.ts
@@ -0,0 +1,19 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddDistanceColumnsToVehicles1821000000002 implements MigrationInterface {
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.vehicles
+ ADD COLUMN IF NOT EXISTS estimated_distance_km NUMERIC,
+ ADD COLUMN IF NOT EXISTS actual_distance_km NUMERIC;
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.vehicles
+ DROP COLUMN IF EXISTS estimated_distance_km,
+ DROP COLUMN IF EXISTS actual_distance_km;
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
new file mode 100644
index 000000000..4c2fb5d95
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1821000000002-CreateInvoices.ts
@@ -0,0 +1,185 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Freight billing β `invoices` + `invoice_lines` tables.
+ *
+ * Matches:
+ * - billing/entities/invoice.entity.ts
+ * - billing/entities/invoice-line.entity.ts
+ *
+ * The status enum mirrors `Freight.InvoiceStatus` and uses TypeORM's default
+ * enum-type name (`__enum`) so the entity's `type: "enum"`
+ * column resolves to it without an explicit `enumName`.
+ */
+export class CreateInvoices1821000000002 implements MigrationInterface {
+ name = "CreateInvoices1821000000002";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ const typeExists = await queryRunner.query(
+ `SELECT 1 FROM pg_type WHERE typname = 'invoices_status_enum' AND typnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'freight');`,
+ );
+
+ if (!typeExists.length) {
+ await queryRunner.query(`
+ CREATE TYPE freight.invoices_status_enum AS ENUM (
+ 'DRAFT',
+ 'PENDING',
+ 'PAID',
+ 'OVERDUE',
+ 'CANCELLED',
+ 'REFUNDED'
+ );
+ `);
+ }
+
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.invoices (
+ id uuid NOT NULL DEFAULT uuid_generate_v4(),
+ invoice_number varchar(64) NOT NULL,
+ company_id uuid NOT NULL,
+ company_profile_id uuid NOT NULL,
+ total_amount numeric(14, 2) NOT NULL,
+ currency varchar(8) NOT NULL DEFAULT 'ETB',
+ status freight.invoices_status_enum NOT NULL DEFAULT 'DRAFT',
+ source varchar(255) NOT NULL,
+ source_id varchar(255) NOT NULL,
+ type varchar(255) NOT NULL,
+ issued_at timestamptz,
+ payment_id uuid,
+ due_at timestamptz NOT NULL,
+ created_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now(),
+ deleted_at timestamptz,
+ CONSTRAINT pk_invoices PRIMARY KEY (id),
+ CONSTRAINT uq_invoices_invoice_number UNIQUE (invoice_number),
+ CONSTRAINT fk_invoices_company FOREIGN KEY (company_id)
+ REFERENCES freight.companies (id) ON DELETE RESTRICT,
+ CONSTRAINT fk_invoices_company_profile FOREIGN KEY (company_profile_id)
+ REFERENCES freight.company_profiles (id) ON DELETE RESTRICT,
+ CONSTRAINT fk_invoices_payment FOREIGN KEY (payment_id)
+ REFERENCES freight.payments (id) ON DELETE SET NULL
+ );
+ `);
+
+ await queryRunner.query(
+ `
+ ALTER TABLE freight.invoices
+ ADD COLUMN IF NOT EXISTS id uuid DEFAULT uuid_generate_v4(),
+ ADD COLUMN IF NOT EXISTS invoice_number varchar(64),
+ ADD COLUMN IF NOT EXISTS company_id uuid,
+ ADD COLUMN IF NOT EXISTS company_profile_id uuid,
+ ADD COLUMN IF NOT EXISTS total_amount numeric(14, 2) NOT NULL DEFAULT 0,
+ ADD COLUMN IF NOT EXISTS currency varchar(8) NOT NULL DEFAULT 'ETB',
+ ADD COLUMN IF NOT EXISTS status freight.invoices_status_enum NOT NULL DEFAULT 'DRAFT',
+ ADD COLUMN IF NOT EXISTS source varchar(255),
+ ADD COLUMN IF NOT EXISTS source_id varchar(255),
+ ADD COLUMN IF NOT EXISTS type varchar(255),
+ ADD COLUMN IF NOT EXISTS issued_at timestamptz,
+ ADD COLUMN IF NOT EXISTS payment_id uuid,
+ ADD COLUMN IF NOT EXISTS due_at timestamptz,
+ ADD COLUMN IF NOT EXISTS created_at timestamptz NOT NULL DEFAULT now(),
+ ADD COLUMN IF NOT EXISTS updated_at timestamptz NOT NULL DEFAULT now(),
+ ADD COLUMN IF NOT EXISTS deleted_at timestamptz;
+ `,
+ );
+ await queryRunner.query(`
+ UPDATE freight.invoices
+ SET due_at = COALESCE(due_at, issued_at, created_at, now())
+ WHERE due_at IS NULL;
+ `);
+ await queryRunner.query(`ALTER TABLE freight.invoices ALTER COLUMN due_at SET NOT NULL;`);
+
+ await queryRunner.query(`
+ DO $$
+ BEGIN
+ IF NOT EXISTS (
+ SELECT 1 FROM pg_constraint
+ WHERE contype = 'p'
+ AND conrelid = 'freight.invoices'::regclass
+ ) THEN
+ ALTER TABLE freight.invoices ADD CONSTRAINT pk_invoices PRIMARY KEY (id);
+ END IF;
+
+ IF NOT EXISTS (
+ SELECT 1 FROM pg_constraint
+ WHERE conname = 'uq_invoices_invoice_number'
+ AND conrelid = 'freight.invoices'::regclass
+ ) THEN
+ ALTER TABLE freight.invoices ADD CONSTRAINT uq_invoices_invoice_number UNIQUE (invoice_number);
+ END IF;
+
+ IF NOT EXISTS (
+ SELECT 1 FROM pg_constraint
+ WHERE conname = 'fk_invoices_company'
+ AND conrelid = 'freight.invoices'::regclass
+ ) THEN
+ ALTER TABLE freight.invoices ADD CONSTRAINT fk_invoices_company
+ FOREIGN KEY (company_id) REFERENCES freight.companies (id) ON DELETE RESTRICT;
+ END IF;
+
+ IF NOT EXISTS (
+ SELECT 1 FROM pg_constraint
+ WHERE conname = 'fk_invoices_company_profile'
+ AND conrelid = 'freight.invoices'::regclass
+ ) THEN
+ ALTER TABLE freight.invoices ADD CONSTRAINT fk_invoices_company_profile
+ FOREIGN KEY (company_profile_id) REFERENCES freight.company_profiles (id) ON DELETE RESTRICT;
+ END IF;
+
+ IF NOT EXISTS (
+ SELECT 1 FROM pg_constraint
+ WHERE conname = 'fk_invoices_payment'
+ AND conrelid = 'freight.invoices'::regclass
+ ) THEN
+ ALTER TABLE freight.invoices ADD CONSTRAINT fk_invoices_payment
+ FOREIGN KEY (payment_id) REFERENCES freight.payments (id) ON DELETE SET NULL;
+ END IF;
+ END $$;
+ `);
+
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS idx_invoices_company ON freight.invoices (company_id);`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS idx_invoices_company_profile ON freight.invoices (company_profile_id);`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS idx_invoices_source ON freight.invoices (source, source_id);`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS idx_invoices_status ON freight.invoices (status);`,
+ );
+
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.invoice_lines (
+ id uuid NOT NULL DEFAULT uuid_generate_v4(),
+ invoice_id uuid NOT NULL,
+ charge_type varchar NOT NULL,
+ description varchar(255),
+ quantity numeric(12, 2) NOT NULL DEFAULT 1,
+ unit_rate numeric(14, 2) NOT NULL DEFAULT 0,
+ amount numeric(14, 2) NOT NULL,
+ currency varchar(8) NOT NULL DEFAULT 'ETB',
+ metadata jsonb,
+ created_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now(),
+ deleted_at timestamptz,
+ CONSTRAINT pk_invoice_lines PRIMARY KEY (id),
+ CONSTRAINT fk_invoice_lines_invoice FOREIGN KEY (invoice_id)
+ REFERENCES freight.invoices (id) ON DELETE CASCADE
+ );
+ `);
+
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS idx_invoice_lines_invoice ON freight.invoice_lines (invoice_id);`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.invoice_lines;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.invoices;`);
+ await queryRunner.query(
+ `DROP TYPE IF EXISTS freight.invoices_status_enum;`,
+ );
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1821000000003-AddCompanyKindAndGovBookingLinks.ts b/apps/edr-freight-api/src/migrations/1821000000003-AddCompanyKindAndGovBookingLinks.ts
new file mode 100644
index 000000000..95ea3db1b
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1821000000003-AddCompanyKindAndGovBookingLinks.ts
@@ -0,0 +1,129 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Government bookings now bill to a real seeded government company + an explicit
+ * importer/exporter profile, instead of carrying a null company + free-text
+ * institution. This migration:
+ *
+ * 1. Adds `companies.kind` (commercial | government).
+ * 2. Seeds the Ethiopian government entities + their importer/exporter
+ * profiles (mirrors src/seed/data/gov-companies.data.ts β keep in sync).
+ * 3. Backfills every booking with a NULL company_id / company_profile_id so
+ * the NOT NULL constraints below can be applied:
+ * - NULL company_id β the default government company.
+ * - NULL company_profile_id β the company's profile matching the booking
+ * trade direction; else any profile of the company; else the default
+ * government importer profile.
+ * 4. Enforces NOT NULL on bookings.company_id and bookings.company_profile_id.
+ */
+export class AddCompanyKindAndGovBookingLinks1821000000003
+ implements MigrationInterface
+{
+ name = "AddCompanyKindAndGovBookingLinks1821000000003";
+
+ // Mirrors src/seed/data/gov-companies.data.ts
+ private readonly govCompanies = [
+ { id: "0a1b0001-0000-4000-8000-000000000001", name: "Federal Government of Ethiopia", tin: "0000000001", email: "procurement@gov.et", phone: "+251111000001", im: "0b1c0001-0000-4000-8000-000000000001", ex: "0b1c0001-0000-4000-8000-000000000002", imRef: "IM-90001", exRef: "EX-90001" },
+ { id: "0a1b0002-0000-4000-8000-000000000002", name: "Ministry of National Defense", tin: "0000000002", email: "logistics@mod.gov.et", phone: "+251111000002", im: "0b1c0002-0000-4000-8000-000000000001", ex: "0b1c0002-0000-4000-8000-000000000002", imRef: "IM-90002", exRef: "EX-90002" },
+ { id: "0a1b0003-0000-4000-8000-000000000003", name: "Ethiopian Roads Administration", tin: "0000000003", email: "supply@era.gov.et", phone: "+251111000003", im: "0b1c0003-0000-4000-8000-000000000001", ex: "0b1c0003-0000-4000-8000-000000000002", imRef: "IM-90003", exRef: "EX-90003" },
+ { id: "0a1b0004-0000-4000-8000-000000000004", name: "Ministry of Agriculture", tin: "0000000004", email: "imports@moa.gov.et", phone: "+251111000004", im: "0b1c0004-0000-4000-8000-000000000001", ex: "0b1c0004-0000-4000-8000-000000000002", imRef: "IM-90004", exRef: "EX-90004" },
+ { id: "0a1b0005-0000-4000-8000-000000000005", name: "Ministry of Trade and Regional Integration", tin: "0000000005", email: "trade@motri.gov.et", phone: "+251111000005", im: "0b1c0005-0000-4000-8000-000000000001", ex: "0b1c0005-0000-4000-8000-000000000002", imRef: "IM-90005", exRef: "EX-90005" },
+ { id: "0a1b0006-0000-4000-8000-000000000006", name: "Ethiopian Disaster Risk Management Commission", tin: "0000000006", email: "relief@edrmc.gov.et", phone: "+251111000006", im: "0b1c0006-0000-4000-8000-000000000001", ex: "0b1c0006-0000-4000-8000-000000000002", imRef: "IM-90006", exRef: "EX-90006" },
+ ];
+
+ private get defaultCompanyId(): string {
+ return this.govCompanies[0].id;
+ }
+ private get defaultImporterProfileId(): string {
+ return this.govCompanies[0].im;
+ }
+
+ public async up(queryRunner: QueryRunner): Promise {
+ // 1. kind column
+ await queryRunner.query(
+ `ALTER TABLE "freight"."companies" ADD COLUMN IF NOT EXISTS "kind" varchar(20) NOT NULL DEFAULT 'commercial'`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS "IDX_companies_kind" ON "freight"."companies" ("kind")`,
+ );
+
+ // 2. seed government companies + importer/exporter profiles (idempotent)
+ for (const g of this.govCompanies) {
+ await queryRunner.query(
+ `INSERT INTO "freight"."companies" ("id", "name", "type", "kind", "status", "tin", "country", "email", "phone")
+ VALUES ($1, $2, 'customer', 'government', 'active', $3, 'Ethiopia', $4, $5)
+ ON CONFLICT ("id") DO NOTHING`,
+ [g.id, g.name, g.tin, g.email, g.phone],
+ );
+ await queryRunner.query(
+ `INSERT INTO "freight"."company_profiles" ("id", "company_id", "type", "reference", "status")
+ VALUES ($1, $2, 'importer', $3, 'active'), ($4, $2, 'exporter', $5, 'active')
+ ON CONFLICT ("id") DO NOTHING`,
+ [g.im, g.id, g.imRef, g.ex, g.exRef],
+ );
+ }
+
+ // 3a. backfill NULL company_id β default government company
+ await queryRunner.query(
+ `UPDATE "freight"."bookings" SET "company_id" = $1 WHERE "company_id" IS NULL`,
+ [this.defaultCompanyId],
+ );
+
+ // 3b. backfill NULL company_profile_id β profile matching trade direction
+ await queryRunner.query(
+ `UPDATE "freight"."bookings" b
+ SET "company_profile_id" = cp."id"
+ FROM "freight"."company_profiles" cp
+ WHERE b."company_profile_id" IS NULL
+ AND cp."company_id" = b."company_id"
+ AND cp."deleted_at" IS NULL
+ AND cp."type" = CASE b."trade_direction"
+ WHEN 'IMPORT' THEN 'importer'
+ WHEN 'EXPORT' THEN 'exporter'
+ ELSE NULL END`,
+ );
+
+ // 3c. fallback β any profile of the booking's company
+ await queryRunner.query(
+ `UPDATE "freight"."bookings" b
+ SET "company_profile_id" = (
+ SELECT cp."id" FROM "freight"."company_profiles" cp
+ WHERE cp."company_id" = b."company_id" AND cp."deleted_at" IS NULL
+ ORDER BY cp."created_at" ASC LIMIT 1)
+ WHERE b."company_profile_id" IS NULL
+ AND EXISTS (
+ SELECT 1 FROM "freight"."company_profiles" cp
+ WHERE cp."company_id" = b."company_id" AND cp."deleted_at" IS NULL)`,
+ );
+
+ // 3d. final fallback β default government importer profile
+ await queryRunner.query(
+ `UPDATE "freight"."bookings" SET "company_profile_id" = $1 WHERE "company_profile_id" IS NULL`,
+ [this.defaultImporterProfileId],
+ );
+
+ // 4. enforce NOT NULL
+ await queryRunner.query(
+ `ALTER TABLE "freight"."bookings" ALTER COLUMN "company_id" SET NOT NULL`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE "freight"."bookings" ALTER COLUMN "company_profile_id" SET NOT NULL`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE "freight"."bookings" ALTER COLUMN "company_profile_id" DROP NOT NULL`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE "freight"."bookings" ALTER COLUMN "company_id" DROP NOT NULL`,
+ );
+ await queryRunner.query(
+ `DROP INDEX IF EXISTS "freight"."IDX_companies_kind"`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE "freight"."companies" DROP COLUMN IF EXISTS "kind"`,
+ );
+ // Seeded government rows are intentionally left in place.
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1821000000004-MakePaymentsTypeGeneric.ts b/apps/edr-freight-api/src/migrations/1821000000004-MakePaymentsTypeGeneric.ts
new file mode 100644
index 000000000..9f0e8e7bd
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1821000000004-MakePaymentsTypeGeneric.ts
@@ -0,0 +1,47 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Make the payment projection source-agnostic so any domain (not just bookings)
+ * can own a payment intent.
+ *
+ * - `payments.type` enum `('booking')` β `varchar(50)`. It now stores the
+ * invoice SOURCE (e.g. 'booking', 'demurrage'), supplied by the caller, so a
+ * new domain no longer needs an enum migration to write its intents.
+ * - adds `payments.reference_type varchar(40)` β the gateway reference type
+ * (`PaymentReferenceType`) the intent was opened with, so the reconcile/poll
+ * path can query the provider without hardcoding it.
+ *
+ * Matches payment/entities/payment.entity.ts.
+ */
+export class MakePaymentsTypeGeneric1821000000004 implements MigrationInterface {
+ name = "MakePaymentsTypeGeneric1821000000004";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.payments ALTER COLUMN type TYPE varchar(50) USING type::text;`,
+ );
+ await queryRunner.query(`DROP TYPE IF EXISTS freight.payments_type_enum;`);
+
+ await queryRunner.query(
+ `ALTER TABLE freight.payments ADD COLUMN reference_type varchar(40);`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.payments DROP COLUMN IF EXISTS reference_type;`,
+ );
+
+ // Restore the single-value enum. Any non-'booking' rows would block the cast;
+ // collapse them first so the down migration is safe.
+ await queryRunner.query(
+ `UPDATE freight.payments SET type = 'booking' WHERE type <> 'booking';`,
+ );
+ await queryRunner.query(
+ `CREATE TYPE freight.payments_type_enum AS ENUM ('booking');`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.payments ALTER COLUMN type TYPE freight.payments_type_enum USING type::freight.payments_type_enum;`,
+ );
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1822000000000-CreateContracts.ts b/apps/edr-freight-api/src/migrations/1822000000000-CreateContracts.ts
new file mode 100644
index 000000000..7995e5023
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1822000000000-CreateContracts.ts
@@ -0,0 +1,357 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * ContractβBooking separation (additive phase). Introduces a first-class
+ * `freight.contracts` aggregate that owns the legal/commercial agreement (scope
+ * + unit rates, no quantities) and spawns shipment `bookings` via `contract_id`.
+ *
+ * Purely additive: no legacy columns are dropped here. The data backfill and
+ * legacy-column removal happen in a later cutover migration.
+ *
+ * See docs/new-doc.md Β§5.
+ */
+export class CreateContracts1822000000000 implements MigrationInterface {
+ name = 'CreateContracts1822000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ // ββ contracts βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.contracts (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ reference VARCHAR(64) NOT NULL UNIQUE,
+
+ company_id UUID,
+ company_profile_id UUID,
+ is_government BOOLEAN NOT NULL DEFAULT FALSE,
+ government_institution VARCHAR(255),
+
+ contract_kind VARCHAR(20) NOT NULL,
+ renewal_of_id UUID REFERENCES freight.contracts(id),
+ trade_direction VARCHAR(10) NOT NULL,
+ freight_type VARCHAR(20) NOT NULL,
+
+ service_type_id UUID NOT NULL,
+ payment_currency VARCHAR(5) NOT NULL,
+ customs_clearing_enabled BOOLEAN NOT NULL DEFAULT FALSE,
+ customs_clearing_agent VARCHAR(200),
+ equipment_return VARCHAR(20),
+
+ first_mile_pickup_address TEXT,
+ first_mile_pickup_lat NUMERIC(10,7),
+ first_mile_pickup_lng NUMERIC(10,7),
+ last_mile_delivery_address TEXT,
+ last_mile_delivery_lat NUMERIC(10,7),
+ last_mile_delivery_lng NUMERIC(10,7),
+
+ is_hazardous BOOLEAN NOT NULL DEFAULT FALSE,
+ is_reefer BOOLEAN NOT NULL DEFAULT FALSE,
+
+ estimated_shipment_date TIMESTAMPTZ,
+ contract_validity_days INT,
+ contract_valid_from TIMESTAMPTZ,
+ contract_valid_until TIMESTAMPTZ,
+ expires_at TIMESTAMPTZ,
+
+ status VARCHAR(40) NOT NULL DEFAULT 'DRAFT',
+ clearance_status VARCHAR(40) NOT NULL DEFAULT 'NOT_APPLICABLE',
+ clearance_cycle_number INT NOT NULL DEFAULT 0,
+
+ pricing_breakdown JSONB,
+ pricing_display_mode VARCHAR(20) DEFAULT 'UNIT_RATES',
+
+ contract_type VARCHAR(20),
+ contract_template_key VARCHAR(128),
+ contract_generated_at TIMESTAMPTZ,
+ contract_summary TEXT,
+ version_number INT NOT NULL DEFAULT 1,
+ financial_terms JSONB,
+
+ approved_by_staff_id UUID,
+ approved_by_staff_at TIMESTAMPTZ,
+ signed_by_director_id UUID,
+ signed_by_director_at TIMESTAMPTZ,
+ signed_by_ceo_id UUID,
+ signed_by_ceo_at TIMESTAMPTZ,
+ customer_signed_at TIMESTAMPTZ,
+ fully_executed_at TIMESTAMPTZ,
+ locked_at TIMESTAMPTZ,
+
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ
+ );
+ `);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contracts_company ON freight.contracts(company_id);`);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contracts_status ON freight.contracts(status);`);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contracts_kind ON freight.contracts(contract_kind);`);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contracts_valid_until ON freight.contracts(contract_valid_until);`);
+
+ // ββ contract_routes ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.contract_routes (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ contract_id UUID NOT NULL REFERENCES freight.contracts(id) ON DELETE CASCADE,
+ origin_yard_id UUID NOT NULL,
+ destination_yard_id UUID NOT NULL,
+ km NUMERIC(10,2),
+ sort_order SMALLINT NOT NULL DEFAULT 0,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ,
+ CONSTRAINT uq_contract_route UNIQUE (contract_id, origin_yard_id, destination_yard_id)
+ );
+ `);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contract_routes_contract ON freight.contract_routes(contract_id);`);
+
+ // ββ contract_cargo_scope βββββββββββββββββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.contract_cargo_scope (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ contract_id UUID NOT NULL REFERENCES freight.contracts(id) ON DELETE CASCADE,
+ container_size VARCHAR(10),
+ cargo_type_id UUID,
+ cargo_free_text VARCHAR(200),
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ,
+ CONSTRAINT uq_contract_container_size UNIQUE NULLS NOT DISTINCT (contract_id, container_size)
+ );
+ `);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contract_cargo_scope_contract ON freight.contract_cargo_scope(contract_id);`);
+
+ // ββ contract_signatures ββββββββββββββββββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.contract_signatures (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ contract_id UUID NOT NULL REFERENCES freight.contracts(id) ON DELETE CASCADE,
+ role VARCHAR(20) NOT NULL,
+ signer_display_name VARCHAR(255) NOT NULL,
+ signature_file_id UUID,
+ consent_text TEXT,
+ signed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ
+ );
+ `);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contract_signatures_contract ON freight.contract_signatures(contract_id);`);
+
+ // ββ contract_approval_steps ββββββββββββββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.contract_approval_steps (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ contract_id UUID NOT NULL REFERENCES freight.contracts(id) ON DELETE CASCADE,
+ step_order SMALLINT NOT NULL DEFAULT 0,
+ required_role VARCHAR(40) NOT NULL,
+ blocks_role VARCHAR(40),
+ status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
+ acted_by_staff_id UUID,
+ acted_at TIMESTAMPTZ,
+ note TEXT,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ
+ );
+ `);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contract_approval_steps_contract ON freight.contract_approval_steps(contract_id);`);
+
+ // ββ contract_rate_snapshots ββββββββββββββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.contract_rate_snapshots (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ contract_id UUID NOT NULL REFERENCES freight.contracts(id) ON DELETE CASCADE,
+ rate_id UUID,
+ rate_code VARCHAR(64) NOT NULL,
+ description VARCHAR(255),
+ unit_price NUMERIC(14,2) NOT NULL,
+ unit_of_measure VARCHAR(32) NOT NULL,
+ currency VARCHAR(5) NOT NULL,
+ container_size VARCHAR(10),
+ is_surcharge BOOLEAN DEFAULT FALSE,
+ conditional_on VARCHAR(32),
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ
+ );
+ `);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contract_rate_snapshots_contract ON freight.contract_rate_snapshots(contract_id);`);
+
+ // ββ contract_review_notes ββββββββββββββββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.contract_review_notes (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ contract_id UUID NOT NULL REFERENCES freight.contracts(id) ON DELETE CASCADE,
+ note_type VARCHAR(40) NOT NULL,
+ body TEXT NOT NULL,
+ author_role VARCHAR(20),
+ author_user_id UUID,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ
+ );
+ `);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contract_review_notes_contract ON freight.contract_review_notes(contract_id);`);
+
+ // ββ contract_clearance_cycles ββββββββββββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.contract_clearance_cycles (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ contract_id UUID NOT NULL REFERENCES freight.contracts(id) ON DELETE CASCADE,
+ cycle_number INT NOT NULL,
+ status VARCHAR(40) NOT NULL DEFAULT 'AWAITING_DOCUMENTS',
+ booking_id UUID,
+ started_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ clearance_ready_at TIMESTAMPTZ,
+ completed_at TIMESTAMPTZ,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ,
+ CONSTRAINT uq_contract_clearance_cycle UNIQUE (contract_id, cycle_number)
+ );
+ `);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contract_clearance_cycles_contract ON freight.contract_clearance_cycles(contract_id);`);
+
+ // ββ contract_document_review (pre-booking clearance, Path B) βββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.contract_document_review (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ contract_id UUID NOT NULL REFERENCES freight.contracts(id) ON DELETE CASCADE,
+ clearance_cycle_id UUID REFERENCES freight.contract_clearance_cycles(id),
+ setting_code VARCHAR(128) NOT NULL,
+ file_key VARCHAR(128) NOT NULL,
+ file_record_id UUID,
+ status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
+ note TEXT,
+ uploaded_by_role VARCHAR(20) NOT NULL DEFAULT 'CUSTOMER',
+ reviewed_by_staff_id UUID,
+ reviewed_at TIMESTAMPTZ,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ,
+ CONSTRAINT uq_contract_document_review_doc
+ UNIQUE NULLS NOT DISTINCT (contract_id, clearance_cycle_id, setting_code, file_key)
+ );
+ `);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contract_doc_review_contract ON freight.contract_document_review(contract_id);`);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_contract_doc_review_status ON freight.contract_document_review(status);`);
+
+ // ββ clearance_milestones (GL tracking) βββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.clearance_milestones (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ booking_id UUID REFERENCES freight.bookings(id) ON DELETE CASCADE,
+ contract_id UUID REFERENCES freight.contracts(id) ON DELETE CASCADE,
+ clearance_cycle_id UUID REFERENCES freight.contract_clearance_cycles(id),
+ milestone_code VARCHAR(64) NOT NULL,
+ milestone_label VARCHAR(255) NOT NULL,
+ status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
+ owner_region VARCHAR(5),
+ triggered_by_doc BOOLEAN DEFAULT FALSE,
+ triggered_at TIMESTAMPTZ,
+ triggered_by_user_id UUID,
+ note TEXT,
+ sort_order SMALLINT NOT NULL DEFAULT 0,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ
+ );
+ `);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_clearance_milestones_booking ON freight.clearance_milestones(booking_id);`);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_clearance_milestones_contract ON freight.clearance_milestones(contract_id);`);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_clearance_milestones_region ON freight.clearance_milestones(owner_region, status);`);
+ // booking-scoped and contract-cycle-scoped uniqueness for milestone codes
+ await queryRunner.query(`
+ CREATE UNIQUE INDEX IF NOT EXISTS uq_clearance_milestone_booking
+ ON freight.clearance_milestones(booking_id, milestone_code) WHERE booking_id IS NOT NULL;
+ `);
+ await queryRunner.query(`
+ CREATE UNIQUE INDEX IF NOT EXISTS uq_clearance_milestone_cycle
+ ON freight.clearance_milestones(clearance_cycle_id, milestone_code) WHERE clearance_cycle_id IS NOT NULL;
+ `);
+
+ // ββ booking_container_units (per-unit container detail) ββββββββββββββββββ
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.booking_container_units (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ booking_container_id UUID NOT NULL REFERENCES freight.booking_container(id) ON DELETE CASCADE,
+ container_number VARCHAR(64) NOT NULL,
+ seal_number VARCHAR(64),
+ vgm_tons NUMERIC(10,3) NOT NULL,
+ is_hazardous BOOLEAN DEFAULT FALSE,
+ is_reefer BOOLEAN DEFAULT FALSE,
+ sort_order SMALLINT NOT NULL DEFAULT 0,
+ created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+ deleted_at TIMESTAMPTZ,
+ CONSTRAINT uq_booking_container_unit_number UNIQUE (booking_container_id, container_number)
+ );
+ `);
+
+ // ββ ALTER bookings βββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS contract_id UUID REFERENCES freight.contracts(id);`);
+ await queryRunner.query(`ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS contract_route_id UUID REFERENCES freight.contract_routes(id);`);
+ await queryRunner.query(`ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS created_by_role VARCHAR(20) DEFAULT 'CUSTOMER';`);
+ await queryRunner.query(`ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS created_by_user_id UUID;`);
+ await queryRunner.query(`CREATE INDEX IF NOT EXISTS idx_bookings_contract ON freight.bookings(contract_id);`);
+ // One active booking per ONE_TIME contract. Postgres forbids a subquery in an
+ // index predicate, so we denormalize the contract kind onto the booking and
+ // predicate on that. The column is stamped at booking creation from the
+ // contract; the app layer (ContractBookingService) is the primary guard and
+ // this index is the backstop.
+ await queryRunner.query(`ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS contract_kind VARCHAR(20);`);
+ await queryRunner.query(`
+ CREATE UNIQUE INDEX IF NOT EXISTS uq_one_active_booking_per_one_time_contract
+ ON freight.bookings (contract_id)
+ WHERE status NOT IN ('EXPIRED', 'CANCELLED', 'COMPLETED', 'REJECTED')
+ AND contract_id IS NOT NULL
+ AND contract_kind = 'ONE_TIME';
+ `);
+
+ // ββ ALTER booking_container ββββββββββββββββββββββββββββββββββββββββββββββ
+ await queryRunner.query(`ALTER TABLE freight.booking_container ADD COLUMN IF NOT EXISTS container_size VARCHAR(10);`);
+ await queryRunner.query(`ALTER TABLE freight.booking_container ADD COLUMN IF NOT EXISTS hazardous_quantity SMALLINT DEFAULT 0;`);
+ await queryRunner.query(`ALTER TABLE freight.booking_container ADD COLUMN IF NOT EXISTS reefer_quantity SMALLINT DEFAULT 0;`);
+
+ // ββ ALTER booking_document_review (denormalized contract link) βββββββββββ
+ await queryRunner.query(`ALTER TABLE freight.booking_document_review ADD COLUMN IF NOT EXISTS contract_id UUID REFERENCES freight.contracts(id);`);
+
+ // ββ Extend file_upload_fields with phased GL metadata ββββββββββββββββββββ
+ await queryRunner.query(`ALTER TABLE freight.file_upload_fields ADD COLUMN IF NOT EXISTS phase VARCHAR(40);`);
+ await queryRunner.query(`ALTER TABLE freight.file_upload_fields ADD COLUMN IF NOT EXISTS owner_region VARCHAR(5);`);
+ await queryRunner.query(`ALTER TABLE freight.file_upload_fields ADD COLUMN IF NOT EXISTS trade_direction VARCHAR(10);`);
+ await queryRunner.query(`ALTER TABLE freight.file_upload_fields ADD COLUMN IF NOT EXISTS triggers_milestone_code VARCHAR(64);`);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`ALTER TABLE freight.file_upload_fields DROP COLUMN IF EXISTS triggers_milestone_code;`);
+ await queryRunner.query(`ALTER TABLE freight.file_upload_fields DROP COLUMN IF EXISTS trade_direction;`);
+ await queryRunner.query(`ALTER TABLE freight.file_upload_fields DROP COLUMN IF EXISTS owner_region;`);
+ await queryRunner.query(`ALTER TABLE freight.file_upload_fields DROP COLUMN IF EXISTS phase;`);
+
+ await queryRunner.query(`ALTER TABLE freight.booking_document_review DROP COLUMN IF EXISTS contract_id;`);
+
+ await queryRunner.query(`ALTER TABLE freight.booking_container DROP COLUMN IF EXISTS reefer_quantity;`);
+ await queryRunner.query(`ALTER TABLE freight.booking_container DROP COLUMN IF EXISTS hazardous_quantity;`);
+ await queryRunner.query(`ALTER TABLE freight.booking_container DROP COLUMN IF EXISTS container_size;`);
+
+ await queryRunner.query(`DROP INDEX IF EXISTS freight.uq_one_active_booking_per_one_time_contract;`);
+ await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_bookings_contract;`);
+ await queryRunner.query(`ALTER TABLE freight.bookings DROP COLUMN IF EXISTS contract_kind;`);
+ await queryRunner.query(`ALTER TABLE freight.bookings DROP COLUMN IF EXISTS created_by_user_id;`);
+ await queryRunner.query(`ALTER TABLE freight.bookings DROP COLUMN IF EXISTS created_by_role;`);
+ await queryRunner.query(`ALTER TABLE freight.bookings DROP COLUMN IF EXISTS contract_route_id;`);
+ await queryRunner.query(`ALTER TABLE freight.bookings DROP COLUMN IF EXISTS contract_id;`);
+
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.booking_container_units;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.clearance_milestones;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.contract_document_review;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.contract_clearance_cycles;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.contract_review_notes;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.contract_rate_snapshots;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.contract_approval_steps;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.contract_signatures;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.contract_cargo_scope;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.contract_routes;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.contracts;`);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1822000000000-CreateImportDjiboutiOperations.ts b/apps/edr-freight-api/src/migrations/1822000000000-CreateImportDjiboutiOperations.ts
new file mode 100644
index 000000000..981918f25
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1822000000000-CreateImportDjiboutiOperations.ts
@@ -0,0 +1,53 @@
+import { MigrationInterface, QueryRunner, Table, TableForeignKey, TableIndex } from 'typeorm';
+
+export class CreateImportDjiboutiOperations1822000000000 implements MigrationInterface {
+ name = 'CreateImportDjiboutiOperations1822000000000';
+
+ async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.createTable(
+ new Table({
+ schema: 'freight',
+ name: 'import_djibouti_operations',
+ columns: [
+ { name: 'id', type: 'uuid', isPrimary: true, generationStrategy: 'uuid', default: 'uuid_generate_v4()' },
+ { name: 'train_schedule_id', type: 'uuid', isUnique: true },
+ { name: 'documents', type: 'jsonb', default: "'{}'::jsonb" },
+ { name: 'gatepass_granted_at', type: 'timestamptz', isNullable: true },
+ { name: 'ready_for_loading_at', type: 'timestamptz', isNullable: true },
+ { name: 'loaded_on_train_at', type: 'timestamptz', isNullable: true },
+ { name: 'departed_from_djibouti_at', type: 'timestamptz', isNullable: true },
+ { name: 'load_list_generated_at', type: 'timestamptz', isNullable: true },
+ { name: 'performed_by', type: 'varchar', length: '120', isNullable: true },
+ { name: 'notes', type: 'text', isNullable: true },
+ { name: 'created_at', type: 'timestamptz', default: 'now()' },
+ { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+ { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+ ],
+ }),
+ true,
+ );
+
+ await queryRunner.createIndex(
+ 'freight.import_djibouti_operations',
+ new TableIndex({
+ name: 'idx_import_djibouti_operations_schedule',
+ columnNames: ['train_schedule_id'],
+ }),
+ );
+
+ await queryRunner.createForeignKey(
+ 'freight.import_djibouti_operations',
+ new TableForeignKey({
+ columnNames: ['train_schedule_id'],
+ referencedTableName: 'train_schedules',
+ referencedSchema: 'freight',
+ referencedColumnNames: ['id'],
+ onDelete: 'CASCADE',
+ }),
+ );
+ }
+
+ async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.dropTable('freight.import_djibouti_operations', true);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1823000000000-BackfillContractsFromBookings.ts b/apps/edr-freight-api/src/migrations/1823000000000-BackfillContractsFromBookings.ts
new file mode 100644
index 000000000..552e4affd
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1823000000000-BackfillContractsFromBookings.ts
@@ -0,0 +1,175 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Data backfill for the contractβbooking separation (docs/new-doc.md Β§17).
+ *
+ * For every legacy `booking_type = 'GENERAL_CONTRACT'` booking we synthesise a
+ * `freight.contracts` row from its contract-phase columns, copy its routes
+ * (contract_route_lines β contract_routes, dropping quantity), and point the
+ * contract + every child shipment booking (linked via booking_orders) at it.
+ *
+ * Per Β§19 item 1, historical ONE_TIME bookings that went through the full
+ * contract flow get a contract parent inserted and `contract_id` set on the same
+ * booking row (no row split).
+ *
+ * Idempotent: skips bookings that already have `contract_id` set, and matches a
+ * synthesised contract by a deterministic `CTR-` reference.
+ */
+export class BackfillContractsFromBookings1823000000000
+ implements MigrationInterface
+{
+ name = 'BackfillContractsFromBookings1823000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ // 1. One contract per GENERAL_CONTRACT booking, carrying the contract-phase
+ // columns. Reference is derived from the source booking id so re-runs are
+ // idempotent (ON CONFLICT DO NOTHING on the unique reference).
+ await queryRunner.query(`
+ INSERT INTO freight.contracts (
+ reference, company_id, company_profile_id, is_government, government_institution,
+ contract_kind, trade_direction, freight_type, service_type_id, payment_currency,
+ customs_clearing_enabled, customs_clearing_agent, equipment_return,
+ first_mile_pickup_address, first_mile_pickup_lat, first_mile_pickup_lng,
+ last_mile_delivery_address, last_mile_delivery_lat, last_mile_delivery_lng,
+ is_hazardous, is_reefer, estimated_shipment_date,
+ contract_validity_days, contract_valid_from, contract_valid_until, expires_at,
+ status, clearance_status, clearance_cycle_number,
+ pricing_breakdown, contract_type, contract_template_key, contract_generated_at,
+ contract_summary, version_number,
+ approved_by_staff_id, approved_by_staff_at,
+ signed_by_director_id, signed_by_director_at,
+ signed_by_ceo_id, signed_by_ceo_at, customer_signed_at, fully_executed_at,
+ created_at, updated_at
+ )
+ SELECT
+ 'CTR-' || b.id::text, b.company_id, b.company_profile_id, b.is_government, b.government_institution,
+ 'GENERAL', b.trade_direction, b.freight_type, b.service_type_id, b.payment_currency,
+ b.customs_clearing_enabled, b.customs_clearing_agent, b.equipment_return,
+ b.first_mile_pickup_address, b.first_mile_pickup_lat, b.first_mile_pickup_lng,
+ b.last_mile_delivery_address, b.last_mile_delivery_lat, b.last_mile_delivery_lng,
+ b.is_hazardous, b.is_reefer, b.estimated_shipment_date,
+ b.contract_validity_days, b.contract_valid_from, b.contract_valid_until, b.expires_at,
+ CASE
+ WHEN b.status IN ('CONTRACT_ACTIVE') THEN 'CONTRACT_ACTIVE'
+ WHEN b.status IN ('CONTRACT_CLOSED') THEN 'CONTRACT_CLOSED'
+ WHEN b.status IN ('EXPIRED') THEN 'EXPIRED'
+ WHEN b.status IN ('CANCELLED') THEN 'CANCELLED'
+ WHEN b.status IN ('REJECTED') THEN 'REJECTED'
+ ELSE 'CONTRACT_ACTIVE'
+ END,
+ CASE WHEN b.customs_clearing_enabled THEN 'NOT_APPLICABLE' ELSE 'NOT_APPLICABLE' END,
+ 0,
+ b.pricing_breakdown,
+ b.contract_type, b.contract_template_key, b.contract_generated_at,
+ b.contract_summary, COALESCE(b.version_number, 1),
+ b.approved_by_staff_id, b.approved_by_staff_at,
+ b.signed_by_director_id, b.signed_by_director_at,
+ b.signed_by_ceo_id, b.signed_by_ceo_at, b.customer_signed_at, b.fully_executed_at,
+ b.created_at, b.updated_at
+ FROM freight.bookings b
+ WHERE b.booking_type = 'GENERAL_CONTRACT'
+ ON CONFLICT (reference) DO NOTHING;
+ `);
+
+ // 2. Copy each general contract's route lines into contract_routes (no qty).
+ await queryRunner.query(`
+ INSERT INTO freight.contract_routes (contract_id, origin_yard_id, destination_yard_id, km, sort_order, created_at, updated_at)
+ SELECT c.id, crl.origin_yard_id, crl.destination_yard_id, crl.km, 0, now(), now()
+ FROM freight.contract_route_lines crl
+ JOIN freight.contracts c ON c.reference = 'CTR-' || crl.contract_booking_id::text
+ ON CONFLICT (contract_id, origin_yard_id, destination_yard_id) DO NOTHING;
+ `);
+
+ // 3. Point the general-contract booking itself at its new contract, and stamp
+ // the denormalized contract_kind for the active-booking index.
+ await queryRunner.query(`
+ UPDATE freight.bookings b
+ SET contract_id = c.id, contract_kind = 'GENERAL', created_by_role = 'CUSTOMER'
+ FROM freight.contracts c
+ WHERE c.reference = 'CTR-' || b.id::text
+ AND b.booking_type = 'GENERAL_CONTRACT'
+ AND b.contract_id IS NULL;
+ `);
+
+ // 4. Point each child shipment booking (spawned via booking_orders) at the
+ // same contract as its parent general contract.
+ await queryRunner.query(`
+ UPDATE freight.bookings child
+ SET contract_id = c.id, contract_kind = 'GENERAL', created_by_role = 'CUSTOMER'
+ FROM freight.booking_orders bo
+ JOIN freight.contracts c ON c.reference = 'CTR-' || bo.contract_booking_id::text
+ WHERE child.id = bo.booking_id
+ AND child.contract_id IS NULL;
+ `);
+
+ // 5. Historical ONE_TIME bookings that completed the contract flow: synthesise
+ // a contract parent and point the same booking row at it (no row split).
+ await queryRunner.query(`
+ INSERT INTO freight.contracts (
+ reference, company_id, company_profile_id, is_government, government_institution,
+ contract_kind, trade_direction, freight_type, service_type_id, payment_currency,
+ customs_clearing_enabled, customs_clearing_agent, equipment_return,
+ first_mile_pickup_address, first_mile_pickup_lat, first_mile_pickup_lng,
+ last_mile_delivery_address, last_mile_delivery_lat, last_mile_delivery_lng,
+ is_hazardous, is_reefer, estimated_shipment_date,
+ contract_validity_days, contract_valid_from, contract_valid_until,
+ status, clearance_status, clearance_cycle_number,
+ pricing_breakdown, contract_type, contract_template_key, contract_generated_at,
+ contract_summary, version_number,
+ approved_by_staff_id, approved_by_staff_at,
+ signed_by_director_id, signed_by_director_at,
+ signed_by_ceo_id, signed_by_ceo_at, customer_signed_at, fully_executed_at,
+ created_at, updated_at
+ )
+ SELECT
+ 'CTR-' || b.id::text, b.company_id, b.company_profile_id, b.is_government, b.government_institution,
+ 'ONE_TIME', b.trade_direction, b.freight_type, b.service_type_id, b.payment_currency,
+ b.customs_clearing_enabled, b.customs_clearing_agent, b.equipment_return,
+ b.first_mile_pickup_address, b.first_mile_pickup_lat, b.first_mile_pickup_lng,
+ b.last_mile_delivery_address, b.last_mile_delivery_lat, b.last_mile_delivery_lng,
+ b.is_hazardous, b.is_reefer, b.estimated_shipment_date,
+ b.contract_validity_days, b.contract_valid_from, b.contract_valid_until,
+ 'FULLY_EXECUTED', 'NOT_APPLICABLE', 0,
+ b.pricing_breakdown, b.contract_type, b.contract_template_key, b.contract_generated_at,
+ b.contract_summary, COALESCE(b.version_number, 1),
+ b.approved_by_staff_id, b.approved_by_staff_at,
+ b.signed_by_director_id, b.signed_by_director_at,
+ b.signed_by_ceo_id, b.signed_by_ceo_at, b.customer_signed_at, b.fully_executed_at,
+ b.created_at, b.updated_at
+ FROM freight.bookings b
+ WHERE COALESCE(b.booking_type, 'ONE_TIME') = 'ONE_TIME'
+ AND b.contract_id IS NULL
+ AND b.contract_generated_at IS NOT NULL
+ ON CONFLICT (reference) DO NOTHING;
+ `);
+
+ await queryRunner.query(`
+ UPDATE freight.bookings b
+ SET contract_id = c.id, contract_kind = 'ONE_TIME', created_by_role = 'CUSTOMER'
+ FROM freight.contracts c
+ WHERE c.reference = 'CTR-' || b.id::text
+ AND COALESCE(b.booking_type, 'ONE_TIME') = 'ONE_TIME'
+ AND b.contract_id IS NULL;
+ `);
+
+ // 6. Build a single route per ONE_TIME contract from the booking's own
+ // origin/destination (general contracts already got their routes in step 2).
+ await queryRunner.query(`
+ INSERT INTO freight.contract_routes (contract_id, origin_yard_id, destination_yard_id, sort_order, created_at, updated_at)
+ SELECT c.id, b.origin_yard_id, b.destination_yard_id, 0, now(), now()
+ FROM freight.bookings b
+ JOIN freight.contracts c ON c.id = b.contract_id AND c.contract_kind = 'ONE_TIME'
+ WHERE b.origin_yard_id IS NOT NULL AND b.destination_yard_id IS NOT NULL
+ ON CONFLICT (contract_id, origin_yard_id, destination_yard_id) DO NOTHING;
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ // Unlink bookings and drop the synthesised contracts (and their cascaded routes).
+ await queryRunner.query(`
+ UPDATE freight.bookings SET contract_id = NULL, contract_route_id = NULL
+ WHERE contract_id IN (SELECT id FROM freight.contracts WHERE reference LIKE 'CTR-%');
+ `);
+ await queryRunner.query(`DELETE FROM freight.contracts WHERE reference LIKE 'CTR-%';`);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1823000000000-CreateImportOperationsTables.ts b/apps/edr-freight-api/src/migrations/1823000000000-CreateImportOperationsTables.ts
new file mode 100644
index 000000000..1a198e983
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1823000000000-CreateImportOperationsTables.ts
@@ -0,0 +1,95 @@
+import { MigrationInterface, QueryRunner, Table, TableIndex } from 'typeorm';
+
+export class CreateImportOperationsTables1823000000000 implements MigrationInterface {
+ name = 'CreateImportOperationsTables1823000000000';
+
+ async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.createTable(
+ new Table({
+ schema: 'freight',
+ name: 'djibouti_import_incidents',
+ columns: [
+ { name: 'id', type: 'uuid', isPrimary: true, generationStrategy: 'uuid', default: 'uuid_generate_v4()' },
+ { name: 'booking_id', type: 'uuid' },
+ { name: 'container_number', type: 'varchar', length: '80', isNullable: true },
+ { name: 'cargo_id', type: 'uuid', isNullable: true },
+ { name: 'facility', type: 'varchar', length: '120', isNullable: true },
+ { name: 'station', type: 'varchar', length: '120', isNullable: true },
+ { name: 'incident_type', type: 'varchar', length: '40' },
+ { name: 'description', type: 'text' },
+ { name: 'photos', type: 'jsonb', default: "'[]'::jsonb" },
+ { name: 'reported_by', type: 'varchar', length: '120', isNullable: true },
+ { name: 'reported_at', type: 'timestamptz' },
+ { name: 'created_at', type: 'timestamptz', default: 'now()' },
+ { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+ { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+ ],
+ }),
+ true,
+ );
+ await queryRunner.createIndex('freight.djibouti_import_incidents', new TableIndex({ name: 'idx_djibouti_incidents_booking', columnNames: ['booking_id'] }));
+ await queryRunner.createIndex('freight.djibouti_import_incidents', new TableIndex({ name: 'idx_djibouti_incidents_container', columnNames: ['container_number'] }));
+ await queryRunner.createIndex('freight.djibouti_import_incidents', new TableIndex({ name: 'idx_djibouti_incidents_type', columnNames: ['incident_type'] }));
+
+ await queryRunner.createTable(
+ new Table({
+ schema: 'freight',
+ name: 'import_customs_finalizations',
+ columns: [
+ { name: 'id', type: 'uuid', isPrimary: true, generationStrategy: 'uuid', default: 'uuid_generate_v4()' },
+ { name: 'booking_id', type: 'uuid', isUnique: true },
+ { name: 'documents', type: 'jsonb', default: "'{}'::jsonb" },
+ { name: 'declaration_serial_number', type: 'varchar', length: '120', isNullable: true },
+ { name: 'duties_taxes_notified_at', type: 'timestamptz', isNullable: true },
+ { name: 'duties_taxes_paid_at', type: 'timestamptz', isNullable: true },
+ { name: 'customs_risk', type: 'varchar', length: '12', isNullable: true },
+ { name: 'import_release_permitted_at', type: 'timestamptz', isNullable: true },
+ { name: 'completed_at', type: 'timestamptz', isNullable: true },
+ { name: 'performed_by', type: 'varchar', length: '120', isNullable: true },
+ { name: 'notes', type: 'text', isNullable: true },
+ { name: 'created_at', type: 'timestamptz', default: 'now()' },
+ { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+ { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+ ],
+ }),
+ true,
+ );
+ await queryRunner.createIndex('freight.import_customs_finalizations', new TableIndex({ name: 'idx_import_customs_booking', columnNames: ['booking_id'] }));
+ await queryRunner.createIndex('freight.import_customs_finalizations', new TableIndex({ name: 'idx_import_customs_risk', columnNames: ['customs_risk'] }));
+
+ await queryRunner.createTable(
+ new Table({
+ schema: 'freight',
+ name: 'empty_container_returns',
+ columns: [
+ { name: 'id', type: 'uuid', isPrimary: true, generationStrategy: 'uuid', default: 'uuid_generate_v4()' },
+ { name: 'container_number', type: 'varchar', length: '80' },
+ { name: 'booking_id', type: 'uuid', isNullable: true },
+ { name: 'customer_id', type: 'uuid', isNullable: true },
+ { name: 'return_date', type: 'timestamptz' },
+ { name: 'facility', type: 'varchar', length: '120', isNullable: true },
+ { name: 'yard', type: 'varchar', length: '120', isNullable: true },
+ { name: 'zone', type: 'varchar', length: '120', isNullable: true },
+ { name: 'condition', type: 'text', isNullable: true },
+ { name: 'handover_note', type: 'text', isNullable: true },
+ { name: 'status', type: 'varchar', length: '40', default: "'RETURNED'" },
+ { name: 'wagon_allocation_reference', type: 'varchar', length: '120', isNullable: true },
+ { name: 'performed_by', type: 'varchar', length: '120', isNullable: true },
+ { name: 'created_at', type: 'timestamptz', default: 'now()' },
+ { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+ { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+ ],
+ }),
+ true,
+ );
+ await queryRunner.createIndex('freight.empty_container_returns', new TableIndex({ name: 'idx_empty_returns_container', columnNames: ['container_number'] }));
+ await queryRunner.createIndex('freight.empty_container_returns', new TableIndex({ name: 'idx_empty_returns_booking', columnNames: ['booking_id'] }));
+ await queryRunner.createIndex('freight.empty_container_returns', new TableIndex({ name: 'idx_empty_returns_status', columnNames: ['status'] }));
+ }
+
+ async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.dropTable('freight.empty_container_returns', true);
+ await queryRunner.dropTable('freight.import_customs_finalizations', true);
+ await queryRunner.dropTable('freight.djibouti_import_incidents', true);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1824000000000-DropLegacyContractTables.ts b/apps/edr-freight-api/src/migrations/1824000000000-DropLegacyContractTables.ts
new file mode 100644
index 000000000..06bcff14a
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1824000000000-DropLegacyContractTables.ts
@@ -0,0 +1,41 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Cutover cleanup (docs/new-doc.md Β§17 Phase 4). Runs AFTER the backfill
+ * (1823β¦) so every legacy general contract + drawdown already lives in the
+ * `contracts` aggregate.
+ *
+ * Drops the now-unused booking-as-contract artifacts:
+ * - `bookings.booking_type` (every booking is a real shipment now)
+ * - `bookings.previous_contract_id` (renewal lives on `contracts.renewal_of_id`)
+ * - the `booking_orders` / `booking_order_lines` drawdown ledger
+ * - `contract_route_lines` (superseded by `contract_routes`)
+ *
+ * The shipment/payment/scheduling/allocation columns on `bookings` are kept β
+ * the operational pipeline is unchanged.
+ */
+export class DropLegacyContractTables1824000000000 implements MigrationInterface {
+ name = 'DropLegacyContractTables1824000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ // booking_order_lines references booking_orders β drop child first.
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.booking_order_lines CASCADE;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.booking_orders CASCADE;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.contract_route_lines CASCADE;`);
+
+ await queryRunner.query(`ALTER TABLE freight.bookings DROP COLUMN IF EXISTS booking_type;`);
+ await queryRunner.query(`ALTER TABLE freight.bookings DROP COLUMN IF EXISTS previous_contract_id;`);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ // Re-add the dropped columns (data is not restored β this is a one-way cutover).
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS booking_type VARCHAR(20) DEFAULT 'ONE_TIME';`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS previous_contract_id UUID;`,
+ );
+ // The legacy ledger/route tables are intentionally NOT recreated here; restore
+ // from a backup if a rollback past the cutover is ever required.
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1825000000000-AddGlOperations.ts b/apps/edr-freight-api/src/migrations/1825000000000-AddGlOperations.ts
new file mode 100644
index 000000000..cf0cc51f4
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1825000000000-AddGlOperations.ts
@@ -0,0 +1,65 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Global Logistics Phase-2 operational features (docs/new-doc.md Β§11βΒ§13, gap
+ * matrix #14/#16/#17/#18):
+ * - `clearance_milestones.metadata` β structured payload for RISK_ASSIGNED
+ * (risk level) and DUTY_TAXES_ADVISED (amount, currency, declaration serial)
+ * - `bookings.gl_station_yard_id` / `gl_assigned_staff_id` / `gl_assigned_at`
+ * β station routing + staff binding (GL US-02)
+ * - `freight.clearance_incidents` β cargo exception/damage reports with photos
+ * (GL Import US-07)
+ */
+export class AddGlOperations1825000000000 implements MigrationInterface {
+ name = 'AddGlOperations1825000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.clearance_milestones ADD COLUMN IF NOT EXISTS metadata JSONB;`,
+ );
+
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS gl_station_yard_id UUID;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS gl_assigned_staff_id UUID;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS gl_assigned_at TIMESTAMPTZ;`,
+ );
+
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.clearance_incidents (
+ id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+ booking_id UUID NOT NULL REFERENCES freight.bookings(id) ON DELETE CASCADE,
+ incident_type VARCHAR(32) NOT NULL,
+ description TEXT NOT NULL,
+ photo_file_ids JSONB NOT NULL DEFAULT '[]',
+ reported_by_user_id UUID,
+ reported_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+ deleted_at TIMESTAMPTZ
+ );
+ `);
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS idx_clearance_incidents_booking ON freight.clearance_incidents(booking_id);`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.clearance_incidents CASCADE;`);
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS gl_assigned_at;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS gl_assigned_staff_id;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS gl_station_yard_id;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.clearance_milestones DROP COLUMN IF EXISTS metadata;`,
+ );
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1825000000000-CreateBookingContainerAllocations.ts b/apps/edr-freight-api/src/migrations/1825000000000-CreateBookingContainerAllocations.ts
new file mode 100644
index 000000000..70b0832f5
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1825000000000-CreateBookingContainerAllocations.ts
@@ -0,0 +1,80 @@
+import { MigrationInterface, QueryRunner, Table, TableForeignKey } from 'typeorm';
+
+/**
+ * Create the freight.booking_container_allocations table β container-to-vehicle
+ * allocation mapping for flexible routing of containers across available vehicles.
+ */
+export class CreateBookingContainerAllocations1825000000000 implements MigrationInterface {
+ name = 'CreateBookingContainerAllocations1825000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ const exists = await queryRunner.hasTable('freight.booking_container_allocations');
+ if (exists) return;
+
+ await queryRunner.createTable(
+ new Table({
+ name: 'freight.booking_container_allocations',
+ columns: [
+ {
+ name: 'id',
+ type: 'uuid',
+ isPrimary: true,
+ default: 'gen_random_uuid()',
+ },
+ { name: 'booking_id', type: 'uuid', isNullable: false },
+ { name: 'container_id', type: 'uuid', isNullable: false },
+ { name: 'vehicle_id', type: 'uuid', isNullable: true },
+ {
+ name: 'container_type',
+ type: 'text',
+ isNullable: false,
+ },
+ {
+ name: 'quantity',
+ type: 'integer',
+ default: 1,
+ isNullable: false,
+ },
+ { name: 'created_at', type: 'timestamptz', default: 'now()' },
+ { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+ { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+ ],
+ }),
+ true,
+ );
+
+ await queryRunner.createForeignKey(
+ 'freight.booking_container_allocations',
+ new TableForeignKey({
+ columnNames: ['booking_id'],
+ referencedTableName: 'freight.bookings',
+ referencedColumnNames: ['id'],
+ onDelete: 'CASCADE',
+ }),
+ );
+
+ await queryRunner.createForeignKey(
+ 'freight.booking_container_allocations',
+ new TableForeignKey({
+ columnNames: ['vehicle_id'],
+ referencedTableName: 'freight.vehicles',
+ referencedColumnNames: ['id'],
+ onDelete: 'SET NULL',
+ }),
+ );
+
+ await queryRunner.query(
+ `CREATE INDEX "IDX_booking_container_allocations_booking_id" ON "freight"."booking_container_allocations" ("booking_id")`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX "IDX_booking_container_allocations_vehicle_id" ON "freight"."booking_container_allocations" ("vehicle_id")`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ const exists = await queryRunner.hasTable('freight.booking_container_allocations');
+ if (exists) {
+ await queryRunner.dropTable('freight.booking_container_allocations');
+ }
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1826000000000-AddCargoScopeQuantityCap.ts b/apps/edr-freight-api/src/migrations/1826000000000-AddCargoScopeQuantityCap.ts
new file mode 100644
index 000000000..97428c11b
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1826000000000-AddCargoScopeQuantityCap.ts
@@ -0,0 +1,23 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * GENERAL contracts can be booked repeatedly until a total cargo quantity cap is
+ * reached (e.g. 100 containers across many shipments). `quantity_cap` on each
+ * cargo-scope line holds that ceiling (containers per size, or tons/items for
+ * bulk). NULL = uncapped; always NULL for ONE_TIME (single booking).
+ */
+export class AddCargoScopeQuantityCap1826000000000 implements MigrationInterface {
+ name = 'AddCargoScopeQuantityCap1826000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_cargo_scope ADD COLUMN IF NOT EXISTS quantity_cap NUMERIC(12,2);`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_cargo_scope DROP COLUMN IF EXISTS quantity_cap;`,
+ );
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1827000000000-CreateBookingRequests.ts b/apps/edr-freight-api/src/migrations/1827000000000-CreateBookingRequests.ts
new file mode 100644
index 000000000..e88824e28
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1827000000000-CreateBookingRequests.ts
@@ -0,0 +1,75 @@
+import { MigrationInterface, QueryRunner, Table, TableIndex } from 'typeorm';
+
+/**
+ * Customer shipment requests for GENERAL customs (Path B) contracts. The customer
+ * submits date + quantities; Global Logistics reviews, then creates the booking
+ * on their behalf and per-booking clearance begins. Additive β no change to
+ * existing tables; ONE_TIME contracts are unaffected.
+ */
+export class CreateBookingRequests1827000000000 implements MigrationInterface {
+ name = 'CreateBookingRequests1827000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.createTable(
+ new Table({
+ schema: 'freight',
+ name: 'booking_requests',
+ columns: [
+ { name: 'id', type: 'uuid', isPrimary: true, generationStrategy: 'uuid', default: 'gen_random_uuid()' },
+ { name: 'reference', type: 'varchar', length: '40', default: "''" },
+ { name: 'contract_id', type: 'uuid' },
+ { name: 'requested_by_user_id', type: 'uuid', isNullable: true },
+ { name: 'contract_route_id', type: 'uuid', isNullable: true },
+ { name: 'scheduled_date', type: 'timestamptz', isNullable: true },
+ { name: 'status', type: 'varchar', length: '16', default: "'PENDING'" },
+ { name: 'requested_lines', type: 'jsonb', default: "'{}'::jsonb" },
+ { name: 'notes', type: 'text', isNullable: true },
+ { name: 'created_booking_id', type: 'uuid', isNullable: true },
+ { name: 'reviewed_by_staff_id', type: 'uuid', isNullable: true },
+ { name: 'reviewed_at', type: 'timestamptz', isNullable: true },
+ { name: 'review_note', type: 'text', isNullable: true },
+ { name: 'created_at', type: 'timestamptz', default: 'now()' },
+ { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+ { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+ ],
+ foreignKeys: [
+ {
+ columnNames: ['contract_id'],
+ referencedSchema: 'freight',
+ referencedTableName: 'contracts',
+ referencedColumnNames: ['id'],
+ onDelete: 'CASCADE',
+ },
+ {
+ columnNames: ['created_booking_id'],
+ referencedSchema: 'freight',
+ referencedTableName: 'bookings',
+ referencedColumnNames: ['id'],
+ onDelete: 'SET NULL',
+ },
+ ],
+ }),
+ true,
+ );
+
+ await queryRunner.createIndex(
+ 'freight.booking_requests',
+ new TableIndex({ name: 'idx_booking_requests_contract', columnNames: ['contract_id'] }),
+ );
+ await queryRunner.createIndex(
+ 'freight.booking_requests',
+ new TableIndex({ name: 'idx_booking_requests_status', columnNames: ['status'] }),
+ );
+ await queryRunner.createIndex(
+ 'freight.booking_requests',
+ new TableIndex({
+ name: 'idx_booking_requests_contract_status',
+ columnNames: ['contract_id', 'status'],
+ }),
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.dropTable('freight.booking_requests', true);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1828000000000-AddBulkHazmatReeferQuantity.ts b/apps/edr-freight-api/src/migrations/1828000000000-AddBulkHazmatReeferQuantity.ts
new file mode 100644
index 000000000..cc9437eaf
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1828000000000-AddBulkHazmatReeferQuantity.ts
@@ -0,0 +1,31 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Bulk / break-bulk freight can now declare HOW MUCH of the cargo is hazardous
+ * or refrigerated, in the cargo's own unit of measure (tons for PER_TON, item
+ * count for PER_ITEM). These two columns hold that amount on the booking; they
+ * stay 0 for container freight (which tracks it per line on booking_container)
+ * and for bulk cargo with no hazardous/reefer portion. The existing
+ * is_hazardous / is_reefer booleans remain the surcharge trigger.
+ */
+export class AddBulkHazmatReeferQuantity1828000000000 implements MigrationInterface {
+ name = 'AddBulkHazmatReeferQuantity1828000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS bulk_hazardous_quantity NUMERIC(12,3) NOT NULL DEFAULT 0;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS bulk_reefer_quantity NUMERIC(12,3) NOT NULL DEFAULT 0;`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS bulk_reefer_quantity;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS bulk_hazardous_quantity;`,
+ );
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1828000000000-AddGrnNumberToWarehouseInventory.ts b/apps/edr-freight-api/src/migrations/1828000000000-AddGrnNumberToWarehouseInventory.ts
new file mode 100644
index 000000000..c57a43aaa
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1828000000000-AddGrnNumberToWarehouseInventory.ts
@@ -0,0 +1,34 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddGrnNumberToWarehouseInventory1828000000000 implements MigrationInterface {
+ name = 'AddGrnNumberToWarehouseInventory1828000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.warehouse_inventory
+ ADD COLUMN IF NOT EXISTS grn_number VARCHAR(100) NULL
+ `);
+
+ await queryRunner.query(`
+ UPDATE freight.warehouse_inventory
+ SET grn_number = substring(notes FROM 'GRN Number: ([^\\n\\r]+)')
+ WHERE grn_number IS NULL
+ AND notes IS NOT NULL
+ AND notes ~ 'GRN Number: '
+ `);
+
+ await queryRunner.query(`
+ CREATE INDEX IF NOT EXISTS idx_warehouse_inventory_grn_number
+ ON freight.warehouse_inventory(grn_number)
+ WHERE grn_number IS NOT NULL
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_warehouse_inventory_grn_number`);
+ await queryRunner.query(`
+ ALTER TABLE freight.warehouse_inventory
+ DROP COLUMN IF EXISTS grn_number
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1828000000000-ExtendInvoicesForPartialPayment.ts b/apps/edr-freight-api/src/migrations/1828000000000-ExtendInvoicesForPartialPayment.ts
new file mode 100644
index 000000000..55239c13f
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1828000000000-ExtendInvoicesForPartialPayment.ts
@@ -0,0 +1,71 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Extend `freight.invoices` into the billing record of record for every source
+ * (booking, demurrage, warehouse fees, β¦) so warehouse fee invoices can be
+ * centralized onto it instead of the parallel `warehouse_fee_invoices` table.
+ *
+ * Adds money tracking that supports partial payment (`subtotal/tax/paid/balance`),
+ * a `paid_at` stamp, a `payments` jsonb ledger, and the `ISSUED` / `PARTIALLY_PAID`
+ * statuses the warehouse flow uses.
+ *
+ * Matches billing/entities/invoice.entity.ts. All columns are additive with
+ * defaults, so existing booking/demurrage rows are unaffected.
+ */
+export class ExtendInvoicesForPartialPayment1828000000000
+ implements MigrationInterface
+{
+ name = "ExtendInvoicesForPartialPayment1828000000000";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ // New statuses. ADD VALUE is non-transactional-value-safe on PG 12+ as long
+ // as the value is not referenced in the same transaction (it is not here).
+ await queryRunner.query(
+ `ALTER TYPE freight.invoices_status_enum ADD VALUE IF NOT EXISTS 'ISSUED' BEFORE 'PENDING';`,
+ );
+ await queryRunner.query(
+ `ALTER TYPE freight.invoices_status_enum ADD VALUE IF NOT EXISTS 'PARTIALLY_PAID' BEFORE 'PAID';`,
+ );
+
+ await queryRunner.query(`
+ ALTER TABLE freight.invoices
+ ADD COLUMN IF NOT EXISTS subtotal_amount numeric(14, 2) NOT NULL DEFAULT 0,
+ ADD COLUMN IF NOT EXISTS tax_amount numeric(14, 2) NOT NULL DEFAULT 0,
+ ADD COLUMN IF NOT EXISTS paid_amount numeric(14, 2) NOT NULL DEFAULT 0,
+ ADD COLUMN IF NOT EXISTS balance_amount numeric(14, 2) NOT NULL DEFAULT 0,
+ ADD COLUMN IF NOT EXISTS paid_at timestamptz,
+ ADD COLUMN IF NOT EXISTS payments jsonb NOT NULL DEFAULT '[]';
+ `);
+
+ // Backfill existing rows: subtotal mirrors the total (no tax was modeled),
+ // the outstanding balance is the full total for unpaid invoices.
+ await queryRunner.query(`
+ UPDATE freight.invoices
+ SET subtotal_amount = total_amount,
+ balance_amount = total_amount;
+ `);
+
+ // Already-settled invoices: fully paid, zero balance, stamped from updated_at.
+ await queryRunner.query(`
+ UPDATE freight.invoices
+ SET paid_amount = total_amount,
+ balance_amount = 0,
+ paid_at = updated_at
+ WHERE status = 'PAID';
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.invoices
+ DROP COLUMN IF EXISTS payments,
+ DROP COLUMN IF EXISTS paid_at,
+ DROP COLUMN IF EXISTS balance_amount,
+ DROP COLUMN IF EXISTS paid_amount,
+ DROP COLUMN IF EXISTS tax_amount,
+ DROP COLUMN IF EXISTS subtotal_amount;
+ `);
+ // Postgres cannot drop individual enum values; ISSUED / PARTIALLY_PAID are
+ // left on freight.invoices_status_enum (harmless, unused after down).
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1829000000000-CentralizeWarehouseInvoices.ts b/apps/edr-freight-api/src/migrations/1829000000000-CentralizeWarehouseInvoices.ts
new file mode 100644
index 000000000..75082c5c4
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1829000000000-CentralizeWarehouseInvoices.ts
@@ -0,0 +1,247 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Fold warehouse fee invoices into the central billing system.
+ *
+ * Warehouse fee invoices are no longer a standalone aggregate: each becomes a
+ * global `freight.invoices` row (`source = 'warehouse'`, `source_id =
+ * inventory_id`) with its items as `freight.invoice_lines`. The warehouse
+ * service is now a thin layer over `BillingService`. This migration backfills the
+ * existing rows (preserving ids, numbers, status, amounts and payment history),
+ * then drops the two legacy tables.
+ *
+ * Rows that cannot be billed centrally β no company to bill (`company_id` /
+ * `company_profile_id` underivable from the customer or the booking) β are not
+ * migrated; they could never have been charged through the gateway and are
+ * dropped with the table.
+ */
+export class CentralizeWarehouseInvoices1829000000000 implements MigrationInterface {
+ name = 'CentralizeWarehouseInvoices1829000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ DO $$
+ BEGIN
+ IF EXISTS (
+ SELECT 1
+ FROM information_schema.columns
+ WHERE table_schema = 'freight'
+ AND table_name = 'invoices'
+ AND column_name = 'booking_id'
+ ) THEN
+ ALTER TABLE freight.invoices ALTER COLUMN booking_id DROP NOT NULL;
+ END IF;
+
+ IF EXISTS (
+ SELECT 1
+ FROM information_schema.columns
+ WHERE table_schema = 'freight'
+ AND table_name = 'invoices'
+ AND column_name = 'amount'
+ ) THEN
+ ALTER TABLE freight.invoices ALTER COLUMN amount DROP NOT NULL;
+ END IF;
+ END $$;
+ `);
+
+ // 1. Invoice headers. Keep the same id so items still link, and so any
+ // external reference to the invoice id stays valid.
+ await queryRunner.query(`
+ INSERT INTO freight.invoices (
+ id, invoice_number, company_id, company_profile_id,
+ subtotal_amount, tax_amount, total_amount, paid_amount, balance_amount,
+ currency, status, source, source_id, type,
+ issued_at, paid_at, payments, payment_id, due_at,
+ created_at, updated_at, deleted_at
+ )
+ SELECT
+ fee.id,
+ fee.invoice_number,
+ COALESCE(fee.customer_id, b.company_id),
+ COALESCE(
+ b.company_profile_id,
+ (SELECT cp.id
+ FROM freight.company_profiles cp
+ WHERE cp.company_id = COALESCE(fee.customer_id, b.company_id)
+ AND cp.deleted_at IS NULL
+ ORDER BY cp.created_at ASC
+ LIMIT 1)
+ ),
+ fee.subtotal_amount, fee.tax_amount, fee.total_amount, fee.paid_amount, fee.balance_amount,
+ fee.currency,
+ fee.status::freight.invoices_status_enum,
+ 'warehouse',
+ fee.inventory_id,
+ fee.invoice_type,
+ fee.issued_at,
+ fee.paid_at,
+ COALESCE(fee.payments, '[]'::jsonb),
+ NULL,
+ COALESCE(fee.due_date, fee.issued_at, fee.created_at),
+ fee.created_at, fee.updated_at, fee.deleted_at
+ FROM freight.warehouse_fee_invoices fee
+ LEFT JOIN freight.bookings b ON b.id = fee.booking_id
+ WHERE COALESCE(fee.customer_id, b.company_id) IS NOT NULL
+ AND COALESCE(
+ b.company_profile_id,
+ (SELECT cp.id
+ FROM freight.company_profiles cp
+ WHERE cp.company_id = COALESCE(fee.customer_id, b.company_id)
+ AND cp.deleted_at IS NULL
+ ORDER BY cp.created_at ASC
+ LIMIT 1)
+ ) IS NOT NULL
+ ON CONFLICT (id) DO NOTHING;
+ `);
+
+ // 2. Invoice lines β only for items whose parent invoice migrated. Warehouse
+ // fee fields (fee_rule_id / chargeable_days / free_days) move into the
+ // line's jsonb metadata.
+ await queryRunner.query(`
+ INSERT INTO freight.invoice_lines (
+ id, invoice_id, charge_type, description, quantity, unit_rate, amount,
+ currency, metadata, created_at, updated_at, deleted_at
+ )
+ SELECT
+ item.id,
+ item.invoice_id,
+ item.fee_type,
+ item.description,
+ item.quantity,
+ item.unit_rate,
+ item.amount,
+ item.currency,
+ jsonb_build_object(
+ 'feeRuleId', item.fee_rule_id,
+ 'chargeableDays', item.chargeable_days,
+ 'freeDays', item.free_days
+ ),
+ item.created_at, item.updated_at, item.deleted_at
+ FROM freight.warehouse_fee_invoice_items item
+ JOIN freight.invoices i ON i.id = item.invoice_id AND i.source = 'warehouse'
+ ON CONFLICT (id) DO NOTHING;
+ `);
+
+ // 3. Drop the legacy tables (items first β FK to invoices).
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.warehouse_fee_invoice_items;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.warehouse_fee_invoices;`);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ // Recreate the legacy tables β¦
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.warehouse_fee_invoices (
+ id uuid NOT NULL DEFAULT uuid_generate_v4(),
+ created_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now(),
+ deleted_at timestamptz,
+ invoice_number varchar(40) NOT NULL,
+ booking_id uuid,
+ customer_id uuid,
+ inventory_id uuid NOT NULL,
+ facility_id uuid,
+ warehouse_id uuid,
+ yard_id uuid,
+ zone_id uuid,
+ invoice_type varchar(32) NOT NULL DEFAULT 'MIXED_WAREHOUSE_FEES',
+ status varchar(20) NOT NULL DEFAULT 'DRAFT',
+ subtotal_amount numeric(14,2) NOT NULL DEFAULT 0,
+ tax_amount numeric(14,2) NOT NULL DEFAULT 0,
+ total_amount numeric(14,2) NOT NULL DEFAULT 0,
+ paid_amount numeric(14,2) NOT NULL DEFAULT 0,
+ balance_amount numeric(14,2) NOT NULL DEFAULT 0,
+ currency varchar(8) NOT NULL DEFAULT 'USD',
+ period_start timestamptz,
+ period_end timestamptz,
+ issued_at timestamptz,
+ due_date timestamptz,
+ paid_at timestamptz,
+ cancelled_at timestamptz,
+ payments jsonb NOT NULL DEFAULT '[]',
+ notes text,
+ CONSTRAINT "PK_warehouse_fee_invoices" PRIMARY KEY (id),
+ CONSTRAINT "UQ_warehouse_fee_invoices_invoice_number" UNIQUE (invoice_number)
+ );
+ `);
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS "IDX_warehouse_fee_invoices_booking_id" ON freight.warehouse_fee_invoices (booking_id);`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS "IDX_warehouse_fee_invoices_inventory_id" ON freight.warehouse_fee_invoices (inventory_id);`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS "IDX_warehouse_fee_invoices_status" ON freight.warehouse_fee_invoices (status);`,
+ );
+ await queryRunner.query(`
+ CREATE TABLE IF NOT EXISTS freight.warehouse_fee_invoice_items (
+ id uuid NOT NULL DEFAULT uuid_generate_v4(),
+ created_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now(),
+ deleted_at timestamptz,
+ invoice_id uuid NOT NULL,
+ fee_rule_id uuid,
+ fee_type varchar(32) NOT NULL,
+ description varchar(255) NOT NULL,
+ quantity numeric(12,2) NOT NULL DEFAULT 1,
+ unit_rate numeric(14,2) NOT NULL DEFAULT 0,
+ amount numeric(14,2) NOT NULL DEFAULT 0,
+ currency varchar(8) NOT NULL DEFAULT 'USD',
+ chargeable_days int,
+ free_days int,
+ CONSTRAINT "PK_warehouse_fee_invoice_items" PRIMARY KEY (id),
+ CONSTRAINT "FK_warehouse_fee_invoice_items_invoice"
+ FOREIGN KEY (invoice_id) REFERENCES freight.warehouse_fee_invoices (id) ON DELETE CASCADE
+ );
+ `);
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS "IDX_warehouse_fee_invoice_items_invoice_id" ON freight.warehouse_fee_invoice_items (invoice_id);`,
+ );
+
+ // β¦ then copy the warehouse-source invoices back, deriving the typed FKs and
+ // period from the linked inventory item.
+ await queryRunner.query(`
+ INSERT INTO freight.warehouse_fee_invoices (
+ id, created_at, updated_at, deleted_at, invoice_number,
+ booking_id, customer_id, inventory_id, facility_id, warehouse_id, yard_id, zone_id,
+ invoice_type, status, subtotal_amount, tax_amount, total_amount, paid_amount, balance_amount,
+ currency, period_start, period_end, issued_at, due_date, paid_at, cancelled_at, payments, notes
+ )
+ SELECT
+ i.id, i.created_at, i.updated_at, i.deleted_at, i.invoice_number,
+ inv.booking_id, i.company_id, i.source_id, w.facility_id, inv.warehouse_id, inv.yard_id, inv.zone_id,
+ i.type, i.status::text, i.subtotal_amount, i.tax_amount, i.total_amount, i.paid_amount, i.balance_amount,
+ i.currency, inv.arrived_at, i.issued_at, i.issued_at, i.due_at, i.paid_at,
+ CASE WHEN i.status::text = 'CANCELLED' THEN i.updated_at ELSE NULL END,
+ i.payments, NULL
+ FROM freight.invoices i
+ LEFT JOIN freight.warehouse_inventory inv ON inv.id = i.source_id
+ LEFT JOIN freight.warehouses w ON w.id = inv.warehouse_id
+ WHERE i.source = 'warehouse'
+ ON CONFLICT (id) DO NOTHING;
+ `);
+ await queryRunner.query(`
+ INSERT INTO freight.warehouse_fee_invoice_items (
+ id, created_at, updated_at, deleted_at, invoice_id, fee_rule_id, fee_type,
+ description, quantity, unit_rate, amount, currency, chargeable_days, free_days
+ )
+ SELECT
+ l.id, l.created_at, l.updated_at, l.deleted_at, l.invoice_id,
+ NULLIF(l.metadata->>'feeRuleId', '')::uuid,
+ l.charge_type,
+ COALESCE(l.description, ''),
+ l.quantity, l.unit_rate, l.amount, l.currency,
+ NULLIF(l.metadata->>'chargeableDays', '')::int,
+ NULLIF(l.metadata->>'freeDays', '')::int
+ FROM freight.invoice_lines l
+ JOIN freight.invoices i ON i.id = l.invoice_id AND i.source = 'warehouse'
+ ON CONFLICT (id) DO NOTHING;
+ `);
+
+ // Remove the migrated rows from the central tables.
+ await queryRunner.query(`
+ DELETE FROM freight.invoice_lines
+ WHERE invoice_id IN (SELECT id FROM freight.invoices WHERE source = 'warehouse');
+ `);
+ await queryRunner.query(`DELETE FROM freight.invoices WHERE source = 'warehouse';`);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1829000000000-PhasedClearanceCycleMeta.ts b/apps/edr-freight-api/src/migrations/1829000000000-PhasedClearanceCycleMeta.ts
new file mode 100644
index 000000000..75288e94c
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1829000000000-PhasedClearanceCycleMeta.ts
@@ -0,0 +1,41 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class PhasedClearanceCycleMeta1829000000000 implements MigrationInterface {
+ name = 'PhasedClearanceCycleMeta1829000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles ADD COLUMN IF NOT EXISTS duty_required BOOLEAN;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles ADD COLUMN IF NOT EXISTS vessel_departure_date DATE;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles ADD COLUMN IF NOT EXISTS ro_amendment_requested_at TIMESTAMPTZ;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles ADD COLUMN IF NOT EXISTS ro_hold_reason TEXT;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles ADD COLUMN IF NOT EXISTS current_phase VARCHAR(40);`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles DROP COLUMN IF EXISTS duty_required;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles DROP COLUMN IF EXISTS vessel_departure_date;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles DROP COLUMN IF EXISTS ro_amendment_requested_at;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles DROP COLUMN IF EXISTS ro_hold_reason;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles DROP COLUMN IF EXISTS current_phase;`,
+ );
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1829000000001-SeedRoVesselMinDays.ts b/apps/edr-freight-api/src/migrations/1829000000001-SeedRoVesselMinDays.ts
new file mode 100644
index 000000000..7165ea7a8
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1829000000001-SeedRoVesselMinDays.ts
@@ -0,0 +1,46 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/** Admin-configurable minimum days between today and export RO vessel departure. */
+export class SeedRoVesselMinDays1829000000001 implements MigrationInterface {
+ name = 'SeedRoVesselMinDays1829000000001';
+ private readonly code = 'ro_vessel_min_days';
+ private readonly options: Array<{ value: string; label: string }> = [
+ { value: '2', label: '2 days' },
+ { value: '3', label: '3 days' },
+ ];
+
+ public async up(queryRunner: QueryRunner): Promise {
+ const existing = await queryRunner.query(
+ `SELECT id FROM freight.dropdown_settings WHERE code = $1 LIMIT 1;`,
+ [this.code],
+ );
+ if (existing.length > 0) return;
+
+ const inserted = await queryRunner.query(
+ `INSERT INTO freight.dropdown_settings (code, label, description, multiple)
+ VALUES ($1, $2, $3, false)
+ RETURNING id;`,
+ [
+ this.code,
+ 'RO vessel minimum lead time (days)',
+ 'Minimum days between today and the vessel departure date on an export Release Order.',
+ ],
+ );
+ const settingId = inserted[0].id;
+
+ for (let i = 0; i < this.options.length; i++) {
+ const opt = this.options[i];
+ await queryRunner.query(
+ `INSERT INTO freight.dropdown_options (setting_id, value, label, display_order)
+ VALUES ($1, $2, $3, $4);`,
+ [settingId, opt.value, opt.label, i],
+ );
+ }
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`DELETE FROM freight.dropdown_settings WHERE code = $1;`, [
+ this.code,
+ ]);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1829000000002-BookingClearanceMeta.ts b/apps/edr-freight-api/src/migrations/1829000000002-BookingClearanceMeta.ts
new file mode 100644
index 000000000..c108b7baa
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1829000000002-BookingClearanceMeta.ts
@@ -0,0 +1,41 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class BookingClearanceMeta1829000000002 implements MigrationInterface {
+ name = 'BookingClearanceMeta1829000000002';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS clearance_current_phase VARCHAR(40);`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS duty_required BOOLEAN;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS vessel_departure_date DATE;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS ro_amendment_requested_at TIMESTAMPTZ;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS ro_hold_reason TEXT;`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS clearance_current_phase;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS duty_required;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS vessel_departure_date;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS ro_amendment_requested_at;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS ro_hold_reason;`,
+ );
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1830000000000-AddExpiredInvoiceStatus.ts b/apps/edr-freight-api/src/migrations/1830000000000-AddExpiredInvoiceStatus.ts
new file mode 100644
index 000000000..e4b353b94
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1830000000000-AddExpiredInvoiceStatus.ts
@@ -0,0 +1,27 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Add the `EXPIRED` invoice status. An invoice expires when its source's pay
+ * window closes before settlement (e.g. a booking whose `paymentDeadline`
+ * lapses) β driven event-style from the domain via `BillingService.expirePayable`,
+ * which emits `${source}.invoice.expired`. Terminal and not settle-able (kept out
+ * of `OPEN_STATUSES`), so it is distinct from `CANCELLED` (manual void) and
+ * `OVERDUE` (still payable).
+ *
+ * Matches Freight.InvoiceStatus in packages/types. ADD VALUE only β additive and
+ * not referenced in this same transaction, so it is PG 12+ safe.
+ */
+export class AddExpiredInvoiceStatus1830000000000 implements MigrationInterface {
+ name = "AddExpiredInvoiceStatus1830000000000";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TYPE freight.invoices_status_enum ADD VALUE IF NOT EXISTS 'EXPIRED' AFTER 'REFUNDED';`,
+ );
+ }
+
+ public async down(): Promise {
+ // Postgres cannot drop individual enum values; EXPIRED is left on
+ // freight.invoices_status_enum (harmless, unused after down).
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1830000000000-CreateFirstMileContainerAllocations.ts b/apps/edr-freight-api/src/migrations/1830000000000-CreateFirstMileContainerAllocations.ts
new file mode 100644
index 000000000..b91e88633
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1830000000000-CreateFirstMileContainerAllocations.ts
@@ -0,0 +1,74 @@
+import { MigrationInterface, QueryRunner, Table, TableForeignKey } from 'typeorm';
+
+/**
+ * Create freight.first_mile_container_allocations table β tracks
+ * container allocations per first-mile shipment with optional vehicle assignment.
+ */
+export class CreateFirstMileContainerAllocations1830000000000 implements MigrationInterface {
+ public async up(queryRunner: QueryRunner): Promise {
+ const exists = await queryRunner.hasTable('freight.first_mile_container_allocations');
+ if (exists) return;
+
+ await queryRunner.createTable(
+ new Table({
+ name: 'freight.first_mile_container_allocations',
+ columns: [
+ {
+ name: 'id',
+ type: 'uuid',
+ isPrimary: true,
+ default: 'gen_random_uuid()',
+ },
+ { name: 'first_mile_id', type: 'uuid', isNullable: false },
+ { name: 'container_id', type: 'uuid', isNullable: false },
+ { name: 'vehicle_id', type: 'uuid', isNullable: true },
+ { name: 'container_type', type: 'text', isNullable: false },
+ {
+ name: 'quantity',
+ type: 'int',
+ default: 1,
+ isNullable: false,
+ },
+ { name: 'created_at', type: 'timestamptz', default: 'now()' },
+ { name: 'updated_at', type: 'timestamptz', default: 'now()' },
+ { name: 'deleted_at', type: 'timestamptz', isNullable: true },
+ ],
+ }),
+ true,
+ );
+
+ await queryRunner.createForeignKey(
+ 'freight.first_mile_container_allocations',
+ new TableForeignKey({
+ columnNames: ['first_mile_id'],
+ referencedTableName: 'freight.first_mile',
+ referencedColumnNames: ['id'],
+ onDelete: 'CASCADE',
+ }),
+ );
+
+ await queryRunner.createForeignKey(
+ 'freight.first_mile_container_allocations',
+ new TableForeignKey({
+ columnNames: ['vehicle_id'],
+ referencedTableName: 'freight.vehicles',
+ referencedColumnNames: ['id'],
+ onDelete: 'SET NULL',
+ }),
+ );
+
+ await queryRunner.query(
+ `CREATE INDEX "IDX_first_mile_container_allocations_first_mile_id" ON "freight"."first_mile_container_allocations" ("first_mile_id")`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX "IDX_first_mile_container_allocations_vehicle_id" ON "freight"."first_mile_container_allocations" ("vehicle_id")`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ const exists = await queryRunner.hasTable('freight.first_mile_container_allocations');
+ if (exists) {
+ await queryRunner.dropTable('freight.first_mile_container_allocations');
+ }
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1830000000000-DropCargoTypeShowFreeTextBox.ts b/apps/edr-freight-api/src/migrations/1830000000000-DropCargoTypeShowFreeTextBox.ts
new file mode 100644
index 000000000..5bdfe1f30
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1830000000000-DropCargoTypeShowFreeTextBox.ts
@@ -0,0 +1,19 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class DropCargoTypeShowFreeTextBox1830000000000 implements MigrationInterface {
+ name = 'DropCargoTypeShowFreeTextBox1830000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.cargo_types
+ DROP COLUMN IF EXISTS show_free_text_box
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.cargo_types
+ ADD COLUMN IF NOT EXISTS show_free_text_box boolean NOT NULL DEFAULT false
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1830000000001-RouteStatusAndSegmentKm.ts b/apps/edr-freight-api/src/migrations/1830000000001-RouteStatusAndSegmentKm.ts
new file mode 100644
index 000000000..701b52c18
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1830000000001-RouteStatusAndSegmentKm.ts
@@ -0,0 +1,72 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class RouteStatusAndSegmentKm1830000000001 implements MigrationInterface {
+ name = 'RouteStatusAndSegmentKm1830000000001';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.routes
+ ADD COLUMN IF NOT EXISTS status varchar(32) NOT NULL DEFAULT 'AVAILABLE'
+ `);
+
+ await queryRunner.query(`
+ UPDATE freight.routes
+ SET status = CASE WHEN is_active = true THEN 'AVAILABLE' ELSE 'STOP_WORKING' END
+ `);
+
+ await queryRunner.query(`
+ DROP INDEX IF EXISTS freight."IDX_routes_name"
+ `);
+ await queryRunner.query(`
+ ALTER TABLE freight.routes DROP COLUMN IF EXISTS name
+ `);
+ await queryRunner.query(`
+ ALTER TABLE freight.routes DROP COLUMN IF EXISTS is_active
+ `);
+
+ await queryRunner.query(`
+ CREATE INDEX IF NOT EXISTS "IDX_routes_status" ON freight.routes (status)
+ `);
+
+ await queryRunner.query(`
+ ALTER TABLE freight.route_milestones
+ ADD COLUMN IF NOT EXISTS distance_km numeric(10,2)
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.route_milestones DROP COLUMN IF EXISTS distance_km
+ `);
+
+ await queryRunner.query(`
+ ALTER TABLE freight.routes
+ ADD COLUMN IF NOT EXISTS name varchar(120)
+ `);
+ await queryRunner.query(`
+ UPDATE freight.routes SET name = id::text WHERE name IS NULL
+ `);
+ await queryRunner.query(`
+ ALTER TABLE freight.routes ALTER COLUMN name SET NOT NULL
+ `);
+
+ await queryRunner.query(`
+ ALTER TABLE freight.routes
+ ADD COLUMN IF NOT EXISTS is_active boolean NOT NULL DEFAULT true
+ `);
+ await queryRunner.query(`
+ UPDATE freight.routes
+ SET is_active = CASE WHEN status = 'AVAILABLE' THEN true ELSE false END
+ `);
+
+ await queryRunner.query(`
+ ALTER TABLE freight.routes DROP COLUMN IF EXISTS status
+ `);
+ await queryRunner.query(`
+ DROP INDEX IF EXISTS freight."IDX_routes_status"
+ `);
+ await queryRunner.query(`
+ CREATE UNIQUE INDEX IF NOT EXISTS "IDX_routes_name" ON freight.routes (name)
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1830000000002-PreClearanceFinalizedAt.ts b/apps/edr-freight-api/src/migrations/1830000000002-PreClearanceFinalizedAt.ts
new file mode 100644
index 000000000..df57cd828
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1830000000002-PreClearanceFinalizedAt.ts
@@ -0,0 +1,23 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class PreClearanceFinalizedAt1830000000002 implements MigrationInterface {
+ name = 'PreClearanceFinalizedAt1830000000002';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles ADD COLUMN IF NOT EXISTS pre_clearance_finalized_at TIMESTAMPTZ;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS pre_clearance_finalized_at TIMESTAMPTZ;`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(
+ `ALTER TABLE freight.contract_clearance_cycles DROP COLUMN IF EXISTS pre_clearance_finalized_at;`,
+ );
+ await queryRunner.query(
+ `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS pre_clearance_finalized_at;`,
+ );
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1831000000000-AddWarehouseFeeRuleTiers.ts b/apps/edr-freight-api/src/migrations/1831000000000-AddWarehouseFeeRuleTiers.ts
new file mode 100644
index 000000000..c6da11cc8
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1831000000000-AddWarehouseFeeRuleTiers.ts
@@ -0,0 +1,19 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddWarehouseFeeRuleTiers1831000000000 implements MigrationInterface {
+ name = 'AddWarehouseFeeRuleTiers1831000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.warehouse_fee_rules
+ ADD COLUMN IF NOT EXISTS tiers jsonb NOT NULL DEFAULT '[]';
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.warehouse_fee_rules
+ DROP COLUMN IF EXISTS tiers;
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1832000000000-AddCustomerTruckAssignmentToBookings.ts b/apps/edr-freight-api/src/migrations/1832000000000-AddCustomerTruckAssignmentToBookings.ts
new file mode 100644
index 000000000..c137ca264
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1832000000000-AddCustomerTruckAssignmentToBookings.ts
@@ -0,0 +1,29 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class AddCustomerTruckAssignmentToBookings1832000000000 implements MigrationInterface {
+ name = 'AddCustomerTruckAssignmentToBookings1832000000000';
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.bookings
+ ADD COLUMN IF NOT EXISTS customer_truck_plate_number varchar(32),
+ ADD COLUMN IF NOT EXISTS customer_truck_driver_name varchar(120),
+ ADD COLUMN IF NOT EXISTS customer_truck_type varchar(60),
+ ADD COLUMN IF NOT EXISTS customer_truck_container_number varchar(16),
+ ADD COLUMN IF NOT EXISTS customer_truck_assigned_at timestamptz,
+ ADD COLUMN IF NOT EXISTS customer_truck_arrived_at timestamptz
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.bookings
+ DROP COLUMN IF EXISTS customer_truck_arrived_at,
+ DROP COLUMN IF EXISTS customer_truck_assigned_at,
+ DROP COLUMN IF EXISTS customer_truck_container_number,
+ DROP COLUMN IF EXISTS customer_truck_type,
+ DROP COLUMN IF EXISTS customer_truck_driver_name,
+ DROP COLUMN IF EXISTS customer_truck_plate_number
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1840000000000-CreateFuelTables.ts b/apps/edr-freight-api/src/migrations/1840000000000-CreateFuelTables.ts
new file mode 100644
index 000000000..a74a58f8e
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1840000000000-CreateFuelTables.ts
@@ -0,0 +1,79 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class CreateFuelTables1840000000000 implements MigrationInterface {
+ name = "CreateFuelTables1840000000000";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ const fuelPurchasesExists = await queryRunner.query(
+ `SELECT 1 FROM information_schema.tables WHERE table_schema = 'freight' AND table_name = 'fuel_purchases';`,
+ );
+
+ if (!fuelPurchasesExists.length) {
+ await queryRunner.query(`
+ CREATE TABLE freight.fuel_purchases (
+ id uuid NOT NULL DEFAULT gen_random_uuid(),
+ vehicle_id uuid NOT NULL,
+ purchase_date timestamptz NOT NULL,
+ liters numeric(10, 2) NOT NULL,
+ cost_per_liter numeric(10, 2) NOT NULL,
+ total_cost numeric(14, 2) NOT NULL,
+ fuel_station varchar(255) NULL,
+ payment_method varchar(50) DEFAULT 'CASH',
+ odometer_reading numeric(10, 2) NULL,
+ driver_id uuid NULL,
+ receipt_number varchar(255) NULL,
+ notes text NULL,
+ created_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now(),
+ deleted_at timestamptz NULL,
+ CONSTRAINT pk_fuel_purchases PRIMARY KEY (id),
+ CONSTRAINT fk_fuel_purchases_vehicle FOREIGN KEY (vehicle_id)
+ REFERENCES freight.vehicles (id) ON DELETE CASCADE
+ );
+ `);
+
+ await queryRunner.query(
+ `CREATE INDEX idx_fuel_purchases_vehicle ON freight.fuel_purchases (vehicle_id);`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX idx_fuel_purchases_date ON freight.fuel_purchases (purchase_date);`,
+ );
+ }
+
+ const fuelConsumptionExists = await queryRunner.query(
+ `SELECT 1 FROM information_schema.tables WHERE table_schema = 'freight' AND table_name = 'fuel_consumption';`,
+ );
+
+ if (!fuelConsumptionExists.length) {
+ await queryRunner.query(`
+ CREATE TABLE freight.fuel_consumption (
+ id uuid NOT NULL DEFAULT gen_random_uuid(),
+ vehicle_id uuid NOT NULL,
+ month date NOT NULL,
+ total_liters numeric(10, 2) NOT NULL,
+ total_cost numeric(14, 2) NOT NULL,
+ total_distance_km numeric(10, 2) NOT NULL,
+ fuel_efficiency_km_per_l numeric(10, 2) NULL,
+ number_of_purchases integer DEFAULT 0,
+ average_cost_per_liter numeric(10, 2) NULL,
+ created_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now(),
+ deleted_at timestamptz NULL,
+ CONSTRAINT pk_fuel_consumption PRIMARY KEY (id),
+ CONSTRAINT fk_fuel_consumption_vehicle FOREIGN KEY (vehicle_id)
+ REFERENCES freight.vehicles (id) ON DELETE CASCADE,
+ CONSTRAINT uq_fuel_consumption_vehicle_month UNIQUE (vehicle_id, month)
+ );
+ `);
+
+ await queryRunner.query(
+ `CREATE INDEX idx_fuel_consumption_vehicle_month ON freight.fuel_consumption (vehicle_id, month);`,
+ );
+ }
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.fuel_consumption;`);
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.fuel_purchases;`);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1850000000000-CreateMaintenanceTables.ts b/apps/edr-freight-api/src/migrations/1850000000000-CreateMaintenanceTables.ts
new file mode 100644
index 000000000..26d4afe21
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1850000000000-CreateMaintenanceTables.ts
@@ -0,0 +1,82 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+export class CreateMaintenanceTables1850000000000 implements MigrationInterface {
+ public async up(queryRunner: QueryRunner): Promise {
+ // Create maintenance_schedules table
+ const scheduleTableExists = await queryRunner.query(`
+ SELECT EXISTS(
+ SELECT 1 FROM information_schema.tables
+ WHERE table_schema = 'freight' AND table_name = 'maintenance_schedules'
+ )
+ `);
+
+ if (!scheduleTableExists[0].exists) {
+ await queryRunner.query(`
+ CREATE TABLE "freight"."maintenance_schedules" (
+ "id" uuid NOT NULL DEFAULT gen_random_uuid(),
+ "vehicle_id" uuid NOT NULL,
+ "maintenance_type" varchar NOT NULL,
+ "description" varchar NOT NULL,
+ "scheduled_date" timestamptz NOT NULL,
+ "completed_date" timestamptz,
+ "estimated_cost" numeric(14,2),
+ "actual_cost" numeric(14,2),
+ "status" varchar NOT NULL DEFAULT 'SCHEDULED',
+ "odometer_reading" numeric,
+ "service_provider" varchar,
+ "notes" text,
+ "next_due_km" numeric,
+ "next_due_date" timestamptz,
+ "created_at" timestamptz NOT NULL DEFAULT now(),
+ "updated_at" timestamptz NOT NULL DEFAULT now(),
+ "deleted_at" timestamptz,
+ PRIMARY KEY ("id")
+ )
+ `);
+
+ await queryRunner.query(
+ `CREATE INDEX "idx_maintenance_schedules_vehicle_date" ON "freight"."maintenance_schedules" ("vehicle_id", "scheduled_date")`
+ );
+ }
+
+ // Create maintenance_costs table
+ const costsTableExists = await queryRunner.query(`
+ SELECT EXISTS(
+ SELECT 1 FROM information_schema.tables
+ WHERE table_schema = 'freight' AND table_name = 'maintenance_costs'
+ )
+ `);
+
+ if (!costsTableExists[0].exists) {
+ await queryRunner.query(`
+ CREATE TABLE "freight"."maintenance_costs" (
+ "id" uuid NOT NULL DEFAULT gen_random_uuid(),
+ "vehicle_id" uuid NOT NULL,
+ "maintenance_schedule_id" uuid,
+ "incurred_date" timestamptz NOT NULL,
+ "cost_amount" numeric(14,2) NOT NULL,
+ "cost_type" varchar NOT NULL,
+ "description" varchar NOT NULL,
+ "service_provider" varchar,
+ "invoice_number" varchar,
+ "notes" text,
+ "created_at" timestamptz NOT NULL DEFAULT now(),
+ "updated_at" timestamptz NOT NULL DEFAULT now(),
+ "deleted_at" timestamptz,
+ PRIMARY KEY ("id"),
+ CONSTRAINT "fk_maintenance_schedule" FOREIGN KEY ("maintenance_schedule_id")
+ REFERENCES "freight"."maintenance_schedules" ("id") ON DELETE SET NULL
+ )
+ `);
+
+ await queryRunner.query(
+ `CREATE INDEX "idx_maintenance_costs_vehicle_date" ON "freight"."maintenance_costs" ("vehicle_id", "incurred_date")`
+ );
+ }
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`DROP TABLE IF EXISTS "freight"."maintenance_costs"`);
+ await queryRunner.query(`DROP TABLE IF EXISTS "freight"."maintenance_schedules"`);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1860000000000-AddPaidToFirstAndLastMile.ts b/apps/edr-freight-api/src/migrations/1860000000000-AddPaidToFirstAndLastMile.ts
new file mode 100644
index 000000000..261e16099
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1860000000000-AddPaidToFirstAndLastMile.ts
@@ -0,0 +1,34 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Add paid column to first_mile and last_mile tables to track invoice payment status.
+ */
+export class AddPaidToFirstAndLastMile1860000000000
+ implements MigrationInterface
+{
+ name = "AddPaidToFirstAndLastMile1860000000000";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.first_mile
+ ADD COLUMN IF NOT EXISTS paid boolean NOT NULL DEFAULT false;
+ `);
+
+ await queryRunner.query(`
+ ALTER TABLE freight.last_mile
+ ADD COLUMN IF NOT EXISTS paid boolean NOT NULL DEFAULT false;
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.first_mile
+ DROP COLUMN IF EXISTS paid;
+ `);
+
+ await queryRunner.query(`
+ ALTER TABLE freight.last_mile
+ DROP COLUMN IF EXISTS paid;
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1861000000000-AddBookingWindowGlobalRules.ts b/apps/edr-freight-api/src/migrations/1861000000000-AddBookingWindowGlobalRules.ts
new file mode 100644
index 000000000..a98fcd80d
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1861000000000-AddBookingWindowGlobalRules.ts
@@ -0,0 +1,31 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class AddBookingWindowGlobalRules1861000000000 implements MigrationInterface {
+ name = "AddBookingWindowGlobalRules1861000000000";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.train_scheduling_global_rules
+ ADD COLUMN import_window_lead_days integer NOT NULL DEFAULT 3,
+ ADD COLUMN export_booking_lead_hours integer NOT NULL DEFAULT 24,
+ ADD COLUMN window_open_hour integer NOT NULL DEFAULT 8,
+ ADD COLUMN window_duration_hours numeric(4, 2) NOT NULL DEFAULT 3,
+ ADD COLUMN doc_review_minutes integer NOT NULL DEFAULT 30,
+ ADD COLUMN payment_window_minutes integer NOT NULL DEFAULT 60,
+ ADD COLUMN reopen_delay_minutes integer NOT NULL DEFAULT 90;
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.train_scheduling_global_rules
+ DROP COLUMN IF EXISTS import_window_lead_days,
+ DROP COLUMN IF EXISTS export_booking_lead_hours,
+ DROP COLUMN IF EXISTS window_open_hour,
+ DROP COLUMN IF EXISTS window_duration_hours,
+ DROP COLUMN IF EXISTS doc_review_minutes,
+ DROP COLUMN IF EXISTS payment_window_minutes,
+ DROP COLUMN IF EXISTS reopen_delay_minutes;
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1861000000001-ReleaseStuckAssignedLocomotives.ts b/apps/edr-freight-api/src/migrations/1861000000001-ReleaseStuckAssignedLocomotives.ts
new file mode 100644
index 000000000..0d5155391
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1861000000001-ReleaseStuckAssignedLocomotives.ts
@@ -0,0 +1,40 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * arriveSchedule used to release only the primary locomotive of a train set, leaving
+ * secondary locomotives ASSIGNED forever. Locomotives are now only ASSIGNED while out
+ * on a dispatched train β release every ASSIGNED locomotive that is not attached to a
+ * currently-DISPATCHED schedule.
+ */
+export class ReleaseStuckAssignedLocomotives1861000000001 implements MigrationInterface {
+ name = "ReleaseStuckAssignedLocomotives1861000000001";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ UPDATE freight.locomotives l
+ SET status = 'AVAILABLE'
+ WHERE l.status = 'ASSIGNED'
+ AND NOT EXISTS (
+ SELECT 1
+ FROM freight.train_schedules ts
+ JOIN freight.train_sets tset ON tset.id = ts.train_set_id
+ JOIN (
+ SELECT tsl.train_set_id, tsl.locomotive_id
+ FROM freight.train_set_locomotives tsl
+ WHERE tsl.deleted_at IS NULL
+ UNION
+ SELECT t.id AS train_set_id, t.locomotive_id
+ FROM freight.train_sets t
+ WHERE t.locomotive_id IS NOT NULL
+ ) loco ON loco.train_set_id = tset.id
+ WHERE ts.status = 'DISPATCHED'
+ AND ts.deleted_at IS NULL
+ AND loco.locomotive_id = l.id
+ );
+ `);
+ }
+
+ public async down(): Promise {
+ // Data fix β not reversible.
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1862000000000-AddScheduleWindowPhases.ts b/apps/edr-freight-api/src/migrations/1862000000000-AddScheduleWindowPhases.ts
new file mode 100644
index 000000000..cae33a534
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1862000000000-AddScheduleWindowPhases.ts
@@ -0,0 +1,37 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class AddScheduleWindowPhases1862000000000 implements MigrationInterface {
+ name = "AddScheduleWindowPhases1862000000000";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.train_schedules
+ ADD COLUMN window_phase varchar(20) NULL,
+ ADD COLUMN window_opens_at timestamptz NULL,
+ ADD COLUMN window_closes_at timestamptz NULL,
+ ADD COLUMN doc_review_ends_at timestamptz NULL,
+ ADD COLUMN doc_review_completed_at timestamptz NULL,
+ ADD COLUMN payment_phase_ends_at timestamptz NULL,
+ ADD COLUMN booking_cycle_no integer NOT NULL DEFAULT 0;
+ `);
+ await queryRunner.query(`
+ CREATE INDEX idx_train_schedules_window_phase
+ ON freight.train_schedules (window_phase)
+ WHERE window_phase IS NOT NULL;
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_train_schedules_window_phase;`);
+ await queryRunner.query(`
+ ALTER TABLE freight.train_schedules
+ DROP COLUMN IF EXISTS window_phase,
+ DROP COLUMN IF EXISTS window_opens_at,
+ DROP COLUMN IF EXISTS window_closes_at,
+ DROP COLUMN IF EXISTS doc_review_ends_at,
+ DROP COLUMN IF EXISTS doc_review_completed_at,
+ DROP COLUMN IF EXISTS payment_phase_ends_at,
+ DROP COLUMN IF EXISTS booking_cycle_no;
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1863000000000-CreateBookingBatchOffers.ts b/apps/edr-freight-api/src/migrations/1863000000000-CreateBookingBatchOffers.ts
new file mode 100644
index 000000000..779807a57
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1863000000000-CreateBookingBatchOffers.ts
@@ -0,0 +1,40 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+export class CreateBookingBatchOffers1863000000000 implements MigrationInterface {
+ name = "CreateBookingBatchOffers1863000000000";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ CREATE TABLE freight.booking_batch_offers (
+ id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+ booking_id uuid NOT NULL REFERENCES freight.bookings(id) ON DELETE CASCADE,
+ train_schedule_id uuid NOT NULL REFERENCES freight.train_schedules(id) ON DELETE CASCADE,
+ offered_wagons integer NOT NULL,
+ total_wagons integer NOT NULL,
+ offered_lines jsonb NULL,
+ offered_weight_tons numeric(12, 3) NOT NULL,
+ offered_amount numeric(14, 2) NOT NULL,
+ offered_pricing_breakdown jsonb NULL,
+ invoice_id uuid NULL,
+ payment_deadline timestamptz NOT NULL,
+ status varchar(10) NOT NULL DEFAULT 'OFFERED',
+ created_at timestamptz NOT NULL DEFAULT now(),
+ updated_at timestamptz NOT NULL DEFAULT now(),
+ deleted_at timestamptz NULL
+ );
+ `);
+ await queryRunner.query(
+ `CREATE INDEX idx_booking_batch_offers_booking ON freight.booking_batch_offers (booking_id);`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX idx_booking_batch_offers_schedule ON freight.booking_batch_offers (train_schedule_id);`,
+ );
+ await queryRunner.query(
+ `CREATE INDEX idx_booking_batch_offers_status ON freight.booking_batch_offers (status);`,
+ );
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`DROP TABLE IF EXISTS freight.booking_batch_offers;`);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1870000000000-AddLocationToVehicles.ts b/apps/edr-freight-api/src/migrations/1870000000000-AddLocationToVehicles.ts
new file mode 100644
index 000000000..3434631a2
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1870000000000-AddLocationToVehicles.ts
@@ -0,0 +1,22 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Add location_id column to vehicles table to track vehicle base location.
+ */
+export class AddLocationToVehicles1870000000000 implements MigrationInterface {
+ name = "AddLocationToVehicles1870000000000";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.vehicles
+ ADD COLUMN IF NOT EXISTS location_id uuid;
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.vehicles
+ DROP COLUMN IF EXISTS location_id;
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1880000000000-AddVehicleStatuses.ts b/apps/edr-freight-api/src/migrations/1880000000000-AddVehicleStatuses.ts
new file mode 100644
index 000000000..484a2686b
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1880000000000-AddVehicleStatuses.ts
@@ -0,0 +1,29 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Add FREE and BUSY statuses to vehicle status enum.
+ */
+export class AddVehicleStatuses1880000000000 implements MigrationInterface {
+ name = "AddVehicleStatuses1880000000000";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ // Create enum type if it doesn't exist
+ await queryRunner.query(`
+ DO $$
+ BEGIN
+ IF NOT EXISTS (SELECT 1 FROM pg_type WHERE typname = 'vehicles_status_enum' AND typnamespace = (SELECT oid FROM pg_namespace WHERE nspname = 'freight')) THEN
+ CREATE TYPE freight.vehicles_status_enum AS ENUM ('ACTIVE', 'FREE', 'BUSY', 'MAINTENANCE', 'RETIRED', 'OUT_OF_SERVICE');
+ ELSE
+ -- Add values if enum already exists but doesn't have them
+ ALTER TYPE freight.vehicles_status_enum ADD VALUE IF NOT EXISTS 'FREE' BEFORE 'MAINTENANCE';
+ ALTER TYPE freight.vehicles_status_enum ADD VALUE IF NOT EXISTS 'BUSY' AFTER 'FREE';
+ END IF;
+ END $$;
+ `);
+ }
+
+ public async down(_queryRunner: QueryRunner): Promise {
+ // Note: Postgres cannot drop individual enum values, so the down migration is a no-op
+ // The enum values FREE and BUSY will remain but will be unused after downgrade
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1890000000000-SeparateVehicleAvailability.ts b/apps/edr-freight-api/src/migrations/1890000000000-SeparateVehicleAvailability.ts
new file mode 100644
index 000000000..c0015c3c6
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1890000000000-SeparateVehicleAvailability.ts
@@ -0,0 +1,40 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Split the mixed vehicle status into two fields:
+ * - status: operational state (ACTIVE, MAINTENANCE, RETIRED, OUT_OF_SERVICE)
+ * - availability: assignment state (FREE, BUSY)
+ *
+ * Existing FREE/BUSY statuses are moved to availability and the status is
+ * normalized back to ACTIVE.
+ */
+export class SeparateVehicleAvailability1890000000000 implements MigrationInterface {
+ name = "SeparateVehicleAvailability1890000000000";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.vehicles
+ ADD COLUMN IF NOT EXISTS availability varchar DEFAULT 'FREE'
+ `);
+ await queryRunner.query(`
+ UPDATE freight.vehicles SET availability = 'BUSY' WHERE status = 'BUSY'
+ `);
+ await queryRunner.query(`
+ UPDATE freight.vehicles SET availability = 'FREE' WHERE availability IS NULL
+ `);
+ await queryRunner.query(`
+ UPDATE freight.vehicles SET status = 'ACTIVE' WHERE status IN ('FREE', 'BUSY')
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ // Fold availability back into status before dropping the column
+ await queryRunner.query(`
+ UPDATE freight.vehicles SET status = availability
+ WHERE status = 'ACTIVE' AND availability IN ('FREE', 'BUSY')
+ `);
+ await queryRunner.query(`
+ ALTER TABLE freight.vehicles DROP COLUMN IF EXISTS availability
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/migrations/1890000000001-AddVehicleCodeAndPlates.ts b/apps/edr-freight-api/src/migrations/1890000000001-AddVehicleCodeAndPlates.ts
new file mode 100644
index 000000000..6f9faa1f8
--- /dev/null
+++ b/apps/edr-freight-api/src/migrations/1890000000001-AddVehicleCodeAndPlates.ts
@@ -0,0 +1,28 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Add code, power_plate_no and trailer_plate_no columns to vehicles.
+ * These fields existed in the DTO and UI form but had no entity columns,
+ * so submitted values were silently dropped.
+ */
+export class AddVehicleCodeAndPlates1890000000001 implements MigrationInterface {
+ name = "AddVehicleCodeAndPlates1890000000001";
+
+ public async up(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.vehicles
+ ADD COLUMN IF NOT EXISTS code varchar,
+ ADD COLUMN IF NOT EXISTS power_plate_no varchar,
+ ADD COLUMN IF NOT EXISTS trailer_plate_no varchar
+ `);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise {
+ await queryRunner.query(`
+ ALTER TABLE freight.vehicles
+ DROP COLUMN IF EXISTS code,
+ DROP COLUMN IF EXISTS power_plate_no,
+ DROP COLUMN IF EXISTS trailer_plate_no
+ `);
+ }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/billing.controller.ts b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
index 5a801cf73..7da5e2d66 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.controller.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.controller.ts
@@ -1,5 +1,6 @@
-import { Controller, Get, Param, ParseUUIDPipe } from "@nestjs/common";
-import { ApiOperation, ApiTags } from "@nestjs/swagger";
+import { Controller, Get, Param, ParseUUIDPipe, Res } from "@nestjs/common";
+import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
+import type { Response } from "express";
import { FreightAdmin } from "../../common/booking-guards";
import { BillingService } from "./billing.service";
@@ -7,8 +8,9 @@ import { BillingService } from "./billing.service";
@ApiTags("billing")
@Controller("billing")
@FreightAdmin()
+@ApiBearerAuth()
export class BillingController {
- constructor(private readonly billingService: BillingService) {}
+ constructor(private readonly billingService: BillingService) { }
@Get("invoices")
@ApiOperation({ summary: "List all invoices" })
@@ -16,9 +18,31 @@ export class BillingController {
return this.billingService.findAll();
}
- @Get("invoices/booking/:bookingId")
- @ApiOperation({ summary: "List invoices for a booking" })
- findByBooking(@Param("bookingId", ParseUUIDPipe) bookingId: string) {
- return this.billingService.findByBooking(bookingId);
+ @Get("invoices/:id")
+ @ApiOperation({ summary: "Get an invoice with its line items" })
+ findById(@Param("id", ParseUUIDPipe) id: string) {
+ return this.billingService.findById(id);
+ }
+
+ @Get("invoices/:id/document")
+ @ApiOperation({ summary: "Download the sealed invoice PDF" })
+ async document(@Param("id", ParseUUIDPipe) id: string, @Res() res: Response) {
+ const { filename, buffer } = await this.billingService.document(id);
+ sendPdf(res, filename, buffer);
+ }
+
+ @Get("invoices/:id/receipt")
+ @ApiOperation({ summary: "Download the sealed payment receipt PDF" })
+ async receipt(@Param("id", ParseUUIDPipe) id: string, @Res() res: Response) {
+ const { filename, buffer } = await this.billingService.receipt(id);
+ sendPdf(res, filename, buffer);
}
}
+
+/** Stream a generated PDF as a file download. */
+export function sendPdf(res: Response, filename: string, buffer: Buffer): void {
+ res.setHeader("Content-Type", "application/pdf");
+ res.setHeader("Content-Disposition", `attachment; filename="${filename}"`);
+ res.setHeader("Content-Length", buffer.length);
+ res.send(buffer);
+}
diff --git a/apps/edr-freight-api/src/modules/billing/billing.module.ts b/apps/edr-freight-api/src/modules/billing/billing.module.ts
index 2b16b1515..771156fd3 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.module.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.module.ts
@@ -1,14 +1,27 @@
-import { Module } from "@nestjs/common";
+import { forwardRef, Module } from "@nestjs/common";
import { TypeOrmModule } from "@nestjs/typeorm";
import { BillingController } from "./billing.controller";
+import { PortalBillingController } from "./portal-billing.controller";
+import { PaymentController } from "./payment.controller";
import { BillingService } from "./billing.service";
+import { DocumentsModule } from "./documents/documents.module";
import { Invoice } from "./entities/invoice.entity";
+import { InvoiceLine } from "./entities/invoice-line.entity";
+import { InvoiceRepository } from "./invoice.repository";
+import { InvoiceLineRepository } from "./invoice-line.repository";
+import { PaymentModule } from "../payment/payment.module";
+import { CompaniesModule } from "../companies/companies.module";
@Module({
- imports: [TypeOrmModule.forFeature([Invoice])],
- controllers: [BillingController],
- providers: [BillingService],
+ imports: [
+ TypeOrmModule.forFeature([Invoice, InvoiceLine]),
+ forwardRef(() => PaymentModule),
+ CompaniesModule,
+ DocumentsModule,
+ ],
+ controllers: [BillingController, PortalBillingController, PaymentController],
+ providers: [BillingService, InvoiceRepository, InvoiceLineRepository],
exports: [BillingService],
})
export class BillingModule {}
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
new file mode 100644
index 000000000..4df2a0eb3
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.spec.ts
@@ -0,0 +1,298 @@
+import { Freight } from "@edr/types";
+
+import { BillingService } from "./billing.service";
+
+/**
+ * Minimal in-memory EntityManager stand-in covering the methods
+ * `generateInvoice` / `markInvoiceAsPaid` call on the transaction manager.
+ */
+function makeManager(savedLines: unknown[]) {
+ return {
+ create: (_entity: unknown, data: Record) => data,
+ save: (data: Record) => {
+ const row = { id: data.id ?? "gen-1", ...data };
+ if (data.invoiceId) savedLines.push(row);
+ return Promise.resolve(row);
+ },
+ query: () => Promise.resolve([{ seq: 0 }]),
+ update: jest.fn().mockResolvedValue(undefined),
+ findOne: jest.fn().mockResolvedValue(null),
+ };
+}
+
+function makeEvents() {
+ return { emit: jest.fn() };
+}
+
+function generateInput(overrides: Record = {}) {
+ return {
+ source: Freight.InvoiceSource.Booking,
+ sourceId: "booking-1",
+ type: "prepaid",
+ companyId: "company-1",
+ companyProfileId: "profile-1",
+ currency: "ETB",
+ lines: [
+ {
+ chargeType: "RAIL_FREIGHT",
+ description: "Rail freight",
+ quantity: 2,
+ unitRate: 500,
+ amount: 1000,
+ },
+ {
+ chargeType: "HAZARD_SURCHARGE",
+ description: "Hazard surcharge",
+ quantity: 2,
+ unitRate: 250,
+ amount: 500,
+ },
+ ],
+ ...overrides,
+ };
+}
+
+describe("BillingService.generateInvoice", () => {
+ let savedLines: unknown[];
+ let manager: ReturnType;
+ let events: ReturnType;
+ let dataSource: { transaction: jest.Mock; manager: unknown };
+ let service: BillingService;
+
+ beforeEach(() => {
+ savedLines = [];
+ manager = makeManager(savedLines);
+ events = makeEvents();
+ dataSource = {
+ transaction: jest
+ .fn()
+ .mockImplementation((cb: (mg: unknown) => unknown) => cb(manager)),
+ manager,
+ };
+ service = new BillingService(
+ dataSource as never,
+ {} as never,
+ {} as never,
+ events as never,
+ {} as never, // payment
+ {} as never, // companies
+ {} as never, // invoiceDocuments
+ );
+ });
+
+ it("creates a PENDING invoice with one line per input line", async () => {
+ const invoice = await service.generateInvoice(generateInput());
+
+ expect(invoice.status).toBe(Freight.InvoiceStatus.Pending);
+ expect(invoice.companyId).toBe("company-1");
+ expect(invoice.source).toBe("booking");
+ expect(invoice.sourceId).toBe("booking-1");
+ expect(invoice.totalAmount).toBe(1500);
+ expect(invoice.issuedAt).toBeInstanceOf(Date);
+ expect(invoice.invoiceNumber).toMatch(/^INV-\d{8}-00001$/);
+ expect(savedLines).toHaveLength(2);
+ });
+
+ it("sums line amounts when no explicit totalAmount is given", async () => {
+ const invoice = await service.generateInvoice(
+ generateInput({ totalAmount: undefined }),
+ );
+ expect(invoice.totalAmount).toBe(1500);
+ });
+
+ it("leaves issuedAt null for a DRAFT invoice", async () => {
+ const invoice = await service.generateInvoice(
+ generateInput({ status: Freight.InvoiceStatus.Draft }),
+ );
+ expect(invoice.status).toBe(Freight.InvoiceStatus.Draft);
+ expect(invoice.issuedAt).toBeNull();
+ });
+
+ it("enlists in a caller's transaction when a manager is passed", async () => {
+ await service.generateInvoice(generateInput(), manager as never);
+ expect(dataSource.transaction).not.toHaveBeenCalled();
+ expect(savedLines).toHaveLength(2);
+ });
+});
+
+describe("BillingService.markInvoiceAsPaid", () => {
+ it("marks the invoice PAID, stamps amounts/paidAt, links the payment, and emits ${source}.invoice.paid", async () => {
+ const open = {
+ id: "inv-1",
+ status: Freight.InvoiceStatus.Pending,
+ source: "booking",
+ sourceId: "booking-1",
+ totalAmount: 1500,
+ paidAt: null,
+ };
+ const mg = {
+ findOne: jest.fn().mockResolvedValue(open),
+ update: jest.fn().mockResolvedValue(undefined),
+ };
+ const events = makeEvents();
+ const service = new BillingService(
+ { manager: mg } as never,
+ {} as never,
+ {} as never,
+ events as never,
+ {} as never, // payment
+ {} as never, // companies
+ {} as never, // invoiceDocuments
+ );
+
+ await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
+
+ expect(mg.update).toHaveBeenCalledWith(
+ expect.anything(),
+ { id: "inv-1" },
+ {
+ status: Freight.InvoiceStatus.Paid,
+ paymentId: "pay-1",
+ paidAt: expect.any(Date),
+ paidAmount: 1500,
+ balanceAmount: 0,
+ payments: [
+ {
+ amount: 1500,
+ method: "GATEWAY",
+ reference: "pay-1",
+ paidAt: expect.any(String),
+ metadata: null,
+ },
+ ],
+ },
+ );
+ expect(events.emit).toHaveBeenCalledWith(
+ "booking.invoice.paid",
+ expect.objectContaining({
+ invoiceId: "inv-1",
+ status: Freight.InvoiceStatus.Paid,
+ paymentId: "pay-1",
+ }),
+ );
+ });
+
+ it("is a no-op (no event) when the invoice is already paid", async () => {
+ const paid = {
+ id: "inv-1",
+ status: Freight.InvoiceStatus.Paid,
+ source: "booking",
+ };
+ const mg = {
+ findOne: jest.fn().mockResolvedValue(paid),
+ update: jest.fn().mockResolvedValue(undefined),
+ };
+ const events = makeEvents();
+ const service = new BillingService(
+ { manager: mg } as never,
+ {} as never,
+ {} as never,
+ events as never,
+ {} as never, // payment
+ {} as never, // companies
+ {} as never, // invoiceDocuments
+ );
+
+ await service.markInvoiceAsPaid("inv-1", "pay-1", mg as never);
+
+ expect(mg.update).not.toHaveBeenCalled();
+ expect(events.emit).not.toHaveBeenCalled();
+ });
+});
+
+describe("BillingService.recordPayment", () => {
+ function serviceFor(invoice: Record | null) {
+ const mg = {
+ findOne: jest.fn().mockResolvedValue(invoice),
+ update: jest.fn().mockResolvedValue(undefined),
+ };
+ const events = makeEvents();
+ const dataSource = {
+ manager: mg,
+ transaction: jest
+ .fn()
+ .mockImplementation((cb: (mg: unknown) => unknown) => cb(mg)),
+ };
+ const service = new BillingService(
+ dataSource as never,
+ {} as never,
+ {} as never,
+ events as never,
+ {} as never, // payment
+ {} as never, // companies
+ {} as never, // invoiceDocuments
+ );
+ return { service, mg, events };
+ }
+
+ const openInvoice = (overrides: Record = {}) => ({
+ id: "inv-1",
+ status: Freight.InvoiceStatus.Issued,
+ source: "warehouse",
+ sourceId: "inv-item-1",
+ totalAmount: 1000,
+ paidAmount: 0,
+ balanceAmount: 1000,
+ payments: [],
+ paidAt: null,
+ ...overrides,
+ });
+
+ it("moves to PARTIALLY_PAID and emits no event on a partial payment", async () => {
+ const { service, mg, events } = serviceFor(openInvoice());
+
+ const updated = await service.recordPayment("inv-1", { amount: 400, method: "CASH" });
+
+ expect(updated.status).toBe(Freight.InvoiceStatus.PartiallyPaid);
+ expect(updated.paidAmount).toBe(400);
+ expect(updated.balanceAmount).toBe(600);
+ expect(updated.payments).toHaveLength(1);
+ expect(mg.update).toHaveBeenCalledWith(
+ expect.anything(),
+ { id: "inv-1" },
+ expect.objectContaining({
+ status: Freight.InvoiceStatus.PartiallyPaid,
+ paidAmount: 400,
+ balanceAmount: 600,
+ }),
+ );
+ expect(events.emit).not.toHaveBeenCalled();
+ });
+
+ it("settles to PAID, stamps paidAt, and emits ${source}.invoice.paid when the balance clears", async () => {
+ const { service, mg, events } = serviceFor(openInvoice({ paidAmount: 400, balanceAmount: 600 }));
+
+ const updated = await service.recordPayment("inv-1", { amount: 600 });
+
+ expect(updated.status).toBe(Freight.InvoiceStatus.Paid);
+ expect(updated.balanceAmount).toBe(0);
+ expect(updated.paidAt).toBeInstanceOf(Date);
+ expect(mg.update).toHaveBeenCalled();
+ expect(events.emit).toHaveBeenCalledWith(
+ "warehouse.invoice.paid",
+ expect.objectContaining({ invoiceId: "inv-1", status: Freight.InvoiceStatus.Paid }),
+ );
+ });
+
+ it("rejects a non-positive amount", async () => {
+ const { service, mg } = serviceFor(openInvoice());
+ await expect(service.recordPayment("inv-1", { amount: 0 })).rejects.toThrow();
+ expect(mg.update).not.toHaveBeenCalled();
+ });
+
+ it("rejects a payment that exceeds the outstanding balance", async () => {
+ const { service, mg } = serviceFor(openInvoice());
+ await expect(
+ service.recordPayment("inv-1", { amount: 1500 }),
+ ).rejects.toThrow();
+ expect(mg.update).not.toHaveBeenCalled();
+ });
+
+ it("rejects payment against a cancelled invoice", async () => {
+ const { service, mg } = serviceFor(
+ openInvoice({ status: Freight.InvoiceStatus.Cancelled }),
+ );
+ await expect(service.recordPayment("inv-1", { amount: 100 })).rejects.toThrow();
+ expect(mg.update).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/edr-freight-api/src/modules/billing/billing.service.ts b/apps/edr-freight-api/src/modules/billing/billing.service.ts
index 39eae6ef5..82a47fa29 100644
--- a/apps/edr-freight-api/src/modules/billing/billing.service.ts
+++ b/apps/edr-freight-api/src/modules/billing/billing.service.ts
@@ -1,26 +1,943 @@
-import { Injectable } from "@nestjs/common";
-import { InjectRepository } from "@nestjs/typeorm";
-import { Repository } from "typeorm";
+import { Freight, PaymentReferenceType } from "@edr/types";
+import {
+ BadRequestException,
+ forwardRef,
+ Inject,
+ Injectable,
+ Logger,
+ NotFoundException,
+} from "@nestjs/common";
+import { EventEmitter2 } from "@nestjs/event-emitter";
+import { DataSource, EntityManager, In } from "typeorm";
-import { Invoice } from "./entities/invoice.entity";
+import { CompaniesService } from "../companies/companies.service";
+import { PaymentService } from "../payment/payment.service";
+import { InitiateResponseDto } from "../payment/payments.dto";
+import {
+ InvoiceDocumentModel,
+ InvoiceDocumentService,
+} from "./documents/invoice-document.service";
+import { InvoiceLine } from "./entities/invoice-line.entity";
+import { Invoice, InvoicePayment } from "./entities/invoice.entity";
+import { InvoiceLineRepository } from "./invoice-line.repository";
+import { nextDailyInvoiceNumber } from "./invoice-numbering.util";
+import { applySettlement, round2 } from "./invoice-settlement.util";
+import { InvoiceRepository } from "./invoice.repository";
+
+/** Options forwarded to the payment gateway when settling an invoice. */
+export interface PayInvoiceOptions {
+ method?: string;
+ platform?: "web" | "mobile";
+ payerAccount?: string;
+ returnUrl?: string;
+ failureUrl?: string;
+}
+
+/** A single manual/offline settlement to record against an invoice. */
+export interface RecordPaymentInput {
+ /** Amount settled by this payment; must be > 0. */
+ amount: number;
+ method?: string | null;
+ reference?: string | null;
+ /** When the settlement occurred; defaults to now. */
+ paidAt?: Date;
+ metadata?: Record | null;
+}
+
+/** Default invoice payment-term window, in days, used to compute `dueAt`. */
+const DEFAULT_DUE_DAYS = 14;
+
+/** Statuses an invoice can still be settled (paid/refunded/cancelled) from. */
+const OPEN_STATUSES: Freight.InvoiceStatus[] = [
+ Freight.InvoiceStatus.Issued,
+ Freight.InvoiceStatus.Pending,
+ Freight.InvoiceStatus.PartiallyPaid,
+ Freight.InvoiceStatus.Overdue,
+];
+
+/** A single line to bill on a generated invoice. */
+export interface InvoiceLineInput {
+ chargeType: string;
+ description?: string;
+ /** Units this line bills for; defaults to 1. */
+ quantity?: number;
+ /** Price per unit; defaults to 0. */
+ unitRate?: number;
+ /** Line total; defaults to `quantity * unitRate`. */
+ amount?: number;
+ currency?: string;
+ metadata?: Record | null;
+}
+
+/** Everything needed to generate an invoice for any source. */
+export interface GenerateInvoiceInput {
+ /** Originating subsystem; namespaces events (`${source}.invoice.`). */
+ source: Freight.InvoiceSource;
+ /** Identifier of the source record (e.g. booking id). */
+ sourceId: string;
+ /** What the invoice is for (e.g. "prepaid", "credit"). */
+ type: string;
+ companyId: string;
+ companyProfileId: string;
+ lines: InvoiceLineInput[];
+ currency?: string;
+ /** Explicit pre-tax subtotal; defaults to the sum of line amounts. */
+ subtotalAmount?: number;
+ /** Tax applied on top of the subtotal; defaults to 0. */
+ taxAmount?: number;
+ /** Explicit total; defaults to `subtotalAmount + taxAmount`. */
+ totalAmount?: number;
+ /** Issue date window; defaults to `DEFAULT_DUE_DAYS` from now. */
+ dueAt?: Date;
+ dueInDays?: number;
+ /**
+ * Initial status. DRAFT leaves `issuedAt` null; any issued status
+ * (default PENDING) stamps `issuedAt`.
+ */
+ status?: Freight.InvoiceStatus;
+}
+
+/** Payload broadcast on `${source}.invoice.`. */
+export interface InvoiceEventPayload {
+ invoiceId: string;
+ invoiceNumber: string;
+ source: Freight.InvoiceSource;
+ sourceId: string;
+ type: string;
+ companyId: string;
+ companyProfileId: string;
+ totalAmount: number;
+ currency: string;
+ status: Freight.InvoiceStatus;
+ paymentId?: string | null;
+}
@Injectable()
export class BillingService {
+ private readonly logger = new Logger(BillingService.name);
+
constructor(
- @InjectRepository(Invoice)
- private readonly invoicesRepository: Repository,
- ) {}
+ private readonly dataSource: DataSource,
+ private readonly invoices: InvoiceRepository,
+ private readonly invoiceLines: InvoiceLineRepository,
+ private readonly events: EventEmitter2,
+ @Inject(forwardRef(() => PaymentService))
+ private readonly payment: PaymentService,
+ private readonly companies: CompaniesService,
+ private readonly invoiceDocuments: InvoiceDocumentService,
+ ) { }
+
+ // ββ Reads ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
/** List every invoice (most recent first). */
findAll(): Promise {
- return this.invoicesRepository.find({ order: { issuedAt: "DESC" } });
+ return this.invoices.findAll({ order: { issuedAt: "DESC" } });
}
- /** List invoices for a given booking. */
- findByBooking(bookingId: string): Promise {
- return this.invoicesRepository.find({
- where: { bookingId },
+ /** Invoice header plus its line items. */
+ async findById(id: string): Promise {
+ const invoice = await this.invoices.findById(id);
+ if (!invoice) throw new NotFoundException(`Invoice ${id} not found`);
+ const lines = await this.invoiceLines.findAll({
+ where: { invoiceId: id },
+ order: { createdAt: "ASC" },
+ });
+ return { ...invoice, lines } as Invoice & { lines: InvoiceLine[] };
+ }
+
+ // ββ Documents (central PDF) ββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+ /** Sealed PDF invoice for any source, rendered by the shared document service. */
+ async document(id: string): Promise<{ filename: string; buffer: Buffer }> {
+ const invoice = await this.findById(id);
+ return this.invoiceDocuments.render(
+ this.toDocumentModel(invoice, "INVOICE"),
+ );
+ }
+
+ /** Sealed PDF receipt; available once any payment has been recorded. */
+ async receipt(id: string): Promise<{ filename: string; buffer: Buffer }> {
+ const invoice = await this.findById(id);
+ if (Number(invoice.paidAmount) <= 0) {
+ throw new BadRequestException(
+ "A receipt is available only after payment is recorded.",
+ );
+ }
+ return this.invoiceDocuments.render(
+ this.toDocumentModel(invoice, "RECEIPT"),
+ );
+ }
+
+ /** Map a global invoice (+ lines) onto the source-agnostic document model. */
+ private toDocumentModel(
+ invoice: Invoice & { lines: InvoiceLine[] },
+ kind: "INVOICE" | "RECEIPT",
+ ): InvoiceDocumentModel {
+ const title = invoice.source
+ ? invoice.source.charAt(0).toUpperCase() + invoice.source.slice(1)
+ : "EDR";
+ const totals: InvoiceDocumentModel["totals"] = [
+ { label: "Subtotal", amount: Number(invoice.subtotalAmount) },
+ ];
+ if (Number(invoice.taxAmount) > 0) {
+ totals.push({ label: "Tax", amount: Number(invoice.taxAmount) });
+ }
+ totals.push({
+ label: "Total",
+ amount: Number(invoice.totalAmount),
+ grand: true,
+ });
+ totals.push({ label: "Paid", amount: Number(invoice.paidAmount) });
+ totals.push({ label: "Balance", amount: Number(invoice.balanceAmount) });
+
+ return {
+ kind,
+ title,
+ documentNumber: invoice.invoiceNumber,
+ issuedAt: invoice.issuedAt ?? invoice.createdAt,
+ status: invoice.status,
+ currency: invoice.currency,
+ summary: [
+ { label: "Status", value: invoice.status },
+ { label: "Type", value: invoice.type },
+ { label: "Reference", value: invoice.sourceId },
+ { label: "Currency", value: invoice.currency },
+ {
+ label: "Issued",
+ value: invoice.issuedAt
+ ? new Date(invoice.issuedAt).toLocaleDateString("en-GB")
+ : null,
+ },
+ {
+ label: "Due",
+ value: invoice.dueAt
+ ? new Date(invoice.dueAt).toLocaleDateString("en-GB")
+ : null,
+ },
+ ],
+ categoryHeader: "Charge type",
+ lines: invoice.lines.map((l) => ({
+ description: l.description ?? l.chargeType,
+ category: l.chargeType,
+ quantity: l.quantity,
+ unitRate: l.unitRate,
+ amount: l.amount,
+ currency: l.currency,
+ })),
+ totals,
+ };
+ }
+
+ // ββ Customer-scoped reads (portal) βββββββββββββββββββββββββββββββββββββββββββ
+
+ /** Resolve the customer's company id from their IAM user id (null if none). */
+ async resolveCompanyId(userId: string): Promise {
+ try {
+ const { company } = await this.companies.getCompanyInfoByUserId(userId);
+ return company?.id ?? null;
+ } catch {
+ return null;
+ }
+ }
+
+ /**
+ * Every invoice billed to a company, newest first, with billing relations.
+ * Optionally narrow to a single source record (e.g. a booking's invoices) via
+ * `{ source, sourceId }`.
+ */
+ findByCompany(
+ companyId: string,
+ filter: { source?: string; sourceId?: string } = {},
+ ): Promise {
+ return this.invoices.findAll({
+ where: {
+ companyId,
+ ...(filter.source ? { source: filter.source } : {}),
+ ...(filter.sourceId ? { sourceId: filter.sourceId } : {}),
+ },
+ relations: { company: true, companyProfile: true },
+ order: { createdAt: "DESC" },
+ });
+ }
+
+ /** Invoices for the signed-in customer; empty when they have no company. */
+ async findForUser(
+ userId: string,
+ filter: { source?: string; sourceId?: string } = {},
+ ): Promise {
+ const companyId = await this.resolveCompanyId(userId);
+ return companyId ? this.findByCompany(companyId, filter) : [];
+ }
+
+ /** Company-scoped invoice detail (+ lines); 404 when not owned by the user. */
+ async findByIdForUser(
+ id: string,
+ userId: string,
+ ): Promise {
+ const companyId = await this.resolveCompanyId(userId);
+ const invoice = await this.findById(id);
+ if (!companyId || invoice.companyId !== companyId) {
+ throw new NotFoundException(`Invoice ${id} not found`);
+ }
+ return invoice;
+ }
+
+ /**
+ * Initiate gateway payment for one of the customer's own invoices. Verifies
+ * ownership, then charges the invoice directly by ID (see {@link payInvoice}).
+ */
+ async payInvoiceForUser(
+ id: string,
+ userId: string,
+ opts: PayInvoiceOptions = {},
+ ): Promise {
+ await this.findByIdForUser(id, userId);
+ return this.payInvoice(id, opts);
+ }
+
+ /** Sealed invoice PDF for one of the customer's own invoices (ownership-checked). */
+ async documentForUser(
+ id: string,
+ userId: string,
+ ): Promise<{ filename: string; buffer: Buffer }> {
+ await this.findByIdForUser(id, userId);
+ return this.document(id);
+ }
+
+ /** Sealed receipt PDF for one of the customer's own invoices (ownership-checked). */
+ async receiptForUser(
+ id: string,
+ userId: string,
+ ): Promise<{ filename: string; buffer: Buffer }> {
+ await this.findByIdForUser(id, userId);
+ return this.receipt(id);
+ }
+
+ // ββ Generation βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+ /** `-YYYYMMDD-00001` β sequential per day & prefix, within the active transaction. */
+ private nextInvoiceNumber(mg: EntityManager): Promise {
+ return nextDailyInvoiceNumber(mg, {
+ table: "freight.invoices",
+ code: "INV",
+ });
+ }
+
+ /**
+ * Generate an invoice for any source (booking, demurrage, manual, β¦).
+ *
+ * Persists the header plus its lines in one transaction and assigns the next
+ * sequential `invoice_number`. The total defaults to the sum of line amounts
+ * unless `totalAmount` is given. Issued invoices (default PENDING) stamp
+ * `issuedAt`; pass `status: DRAFT` to leave it unissued.
+ *
+ * Pass `manager` to enlist in a caller's transaction (e.g. when generating an
+ * invoice as part of a larger booking flow).
+ */
+ async generateInvoice(
+ input: GenerateInvoiceInput,
+ manager?: EntityManager,
+ ): Promise {
+ console.log("oooooooooo", input);
+ const run = (mg: EntityManager) => this.createInvoice(input, mg);
+ return manager ? run(manager) : this.dataSource.transaction(run);
+ }
+
+ private async createInvoice(
+ input: GenerateInvoiceInput,
+ mg: EntityManager,
+ ): Promise {
+ const currency = input.currency ?? "ETB";
+ const status = input.status ?? Freight.InvoiceStatus.Pending;
+ const issued = status !== Freight.InvoiceStatus.Draft;
+
+ const lines = input.lines.map((l) => {
+ const quantity = l.quantity ?? 1;
+ const unitRate = l.unitRate ?? 0;
+ return {
+ chargeType: l.chargeType,
+ description: l.description,
+ quantity,
+ unitRate,
+ amount: l.amount ?? quantity * unitRate,
+ currency: l.currency ?? currency,
+ metadata: l.metadata ?? null,
+ };
+ });
+
+ const subtotalAmount =
+ input.subtotalAmount ??
+ lines.reduce((sum, l) => sum + Number(l.amount), 0);
+ const taxAmount = input.taxAmount ?? 0;
+ const totalAmount = input.totalAmount ?? round2(subtotalAmount + taxAmount);
+
+ const dueAt =
+ input.dueAt ??
+ new Date(
+ Date.now() +
+ (input.dueInDays ?? DEFAULT_DUE_DAYS) * 24 * 60 * 60 * 1000,
+ );
+
+ const invoiceNumber = await this.nextInvoiceNumber(mg);
+
+ const invoice = await mg.save(
+ mg.create(Invoice, {
+ invoiceNumber,
+ source: input.source,
+ sourceId: input.sourceId,
+ type: input.type,
+ companyId: input.companyId,
+ companyProfileId: input.companyProfileId,
+ subtotalAmount: round2(subtotalAmount),
+ taxAmount: round2(taxAmount),
+ totalAmount: round2(totalAmount),
+ paidAmount: 0,
+ balanceAmount: round2(totalAmount),
+ payments: [],
+ currency,
+ status,
+ issuedAt: issued ? new Date() : null,
+ dueAt,
+ }),
+ );
+
+ const savedLines = await Promise.all(
+ lines.map((l) =>
+ mg.save(mg.create(InvoiceLine, { ...l, invoiceId: invoice.id })),
+ ),
+ );
+
+ this.logger.log(
+ `Generated invoice ${invoice.invoiceNumber} (${invoice.id}) for ${input.source}:${input.sourceId}`,
+ );
+
+ return { ...invoice, lines: savedLines };
+ }
+
+ // ββ State transitions ββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+
+ /**
+ * Run `fn` inside a transaction and only emit its returned domain event
+ * after commit. When the caller passes their own `manager`, they own commit
+ * timing β `fn`'s event fires inline as soon as it resolves (the outer
+ * transaction may still roll back afterwards; this is the caller's
+ * documented tradeoff). When no `manager` is given, this opens its own
+ * transaction and defers the emit until after that transaction commits, so
+ * listeners (e.g. booking advancement) can never observe an invoice change
+ * that then rolls back.
+ */
+ private async runTransition(
+ manager: EntityManager | undefined,
+ fn: (mg: EntityManager) => Promise<{ result: T; emit?: () => void }>,
+ ): Promise {
+ if (manager) {
+ const { result, emit } = await fn(manager);
+ emit?.();
+ return result;
+ }
+ let pending: (() => void) | undefined;
+ const result = await this.dataSource.transaction(async (mg) => {
+ const out = await fn(mg);
+ pending = out.emit;
+ return out.result;
+ });
+ pending?.();
+ return result;
+ }
+
+ /**
+ * Mark an invoice paid, stamp the paid timestamp, sync paid/balance amounts,
+ * append the settlement to the `payments` ledger, link the gateway payment,
+ * then emit `${source}.invoice.paid`. Full-payment only β no partial
+ * settlement. No-op when the invoice is already paid. Pass `manager` to
+ * enlist in a caller's transaction; otherwise locks the row for update and
+ * emits only after commit (see {@link runTransition}).
+ */
+ async markInvoiceAsPaid(
+ invoiceId: string,
+ paymentId: string | null = null,
+ manager?: EntityManager,
+ settlement: { providerTxnId?: string; paidAt?: Date } = {},
+ ): Promise {
+ return this.runTransition(manager, async (mg) => {
+ const invoice = await mg.findOne(Invoice, {
+ where: { id: invoiceId },
+ lock: { mode: "pessimistic_write" },
+ });
+ if (!invoice) {
+ throw new NotFoundException(`Invoice ${invoiceId} not found`);
+ }
+ if (invoice.status === Freight.InvoiceStatus.Paid) {
+ return { result: invoice };
+ }
+
+ const paidAt = invoice.paidAt ?? settlement.paidAt ?? new Date();
+ const settledAmount = round2(
+ Number(invoice.totalAmount) - Number(invoice.paidAmount ?? 0),
+ );
+ const entry: InvoicePayment = {
+ amount: settledAmount,
+ method: "GATEWAY",
+ reference: settlement.providerTxnId ?? paymentId ?? null,
+ paidAt: paidAt.toISOString(),
+ metadata: null,
+ };
+ const payments = [...(invoice.payments ?? []), entry];
+
+ const patch = {
+ status: Freight.InvoiceStatus.Paid,
+ paymentId,
+ paidAt,
+ paidAmount: invoice.totalAmount,
+ balanceAmount: 0,
+ payments,
+ };
+ await mg.update(Invoice, { id: invoiceId }, patch as never);
+
+ const updated = { ...invoice, ...patch } as Invoice;
+ return {
+ result: updated,
+ emit: () => this.emitInvoiceEvent("paid", updated),
+ };
+ });
+ }
+
+ /**
+ * Record a (possibly partial) settlement against an invoice and sync its
+ * status. Appends to the `payments` ledger, recomputes `paidAmount` /
+ * `balanceAmount`, and moves the invoice to PARTIALLY_PAID or β once the
+ * balance reaches zero β PAID, stamping `paidAt` and emitting
+ * `${source}.invoice.paid`. Use this for manual/offline settlement (e.g. cash
+ * at the warehouse counter); gateway settlement goes through
+ * {@link markInvoiceAsPaid}.
+ *
+ * Throws when the invoice is missing, cancelled, refunded, already fully
+ * paid, `amount` is not positive, or `amount` exceeds the outstanding
+ * balance. Pass `manager` to enlist in a caller's transaction; otherwise
+ * locks the row for update and emits only after commit (see
+ * {@link runTransition}).
+ */
+ async recordPayment(
+ invoiceId: string,
+ input: RecordPaymentInput,
+ manager?: EntityManager,
+ ): Promise {
+ if (!(input.amount > 0)) {
+ throw new BadRequestException(
+ "Payment amount must be greater than zero.",
+ );
+ }
+
+ return this.runTransition(manager, async (mg) => {
+ const invoice = await mg.findOne(Invoice, {
+ where: { id: invoiceId },
+ lock: { mode: "pessimistic_write" },
+ });
+ if (!invoice) {
+ throw new NotFoundException(`Invoice ${invoiceId} not found`);
+ }
+ if (invoice.status === Freight.InvoiceStatus.Cancelled) {
+ throw new BadRequestException("Cannot pay a cancelled invoice.");
+ }
+ if (invoice.status === Freight.InvoiceStatus.Refunded) {
+ throw new BadRequestException("Cannot pay a refunded invoice.");
+ }
+ if (invoice.status === Freight.InvoiceStatus.Paid) {
+ throw new BadRequestException("Invoice is already fully paid.");
+ }
+ if (round2(input.amount) > Number(invoice.balanceAmount)) {
+ throw new BadRequestException(
+ `Payment of ${round2(input.amount)} exceeds the outstanding balance of ${Number(invoice.balanceAmount)}.`,
+ );
+ }
+
+ const at = input.paidAt ?? new Date();
+ const { paidAmount, balanceAmount, fullyPaid } = applySettlement(
+ invoice.totalAmount,
+ invoice.paidAmount,
+ input.amount,
+ );
+ const status = fullyPaid
+ ? Freight.InvoiceStatus.Paid
+ : Freight.InvoiceStatus.PartiallyPaid;
+
+ const entry: InvoicePayment = {
+ amount: round2(input.amount),
+ method: input.method ?? null,
+ reference: input.reference ?? null,
+ paidAt: at.toISOString(),
+ metadata: input.metadata ?? null,
+ };
+ const payments = [...(invoice.payments ?? []), entry];
+
+ const patch = {
+ paidAmount,
+ balanceAmount,
+ status,
+ payments,
+ paidAt: fullyPaid ? at : (invoice.paidAt ?? null),
+ };
+ await mg.update(Invoice, { id: invoice.id }, patch as never);
+
+ const updated = { ...invoice, ...patch } as Invoice;
+ return {
+ result: updated,
+ emit: fullyPaid
+ ? () => this.emitInvoiceEvent("paid", updated)
+ : undefined,
+ };
+ });
+ }
+
+ /**
+ * Mark an invoice refunded and emit `${source}.invoice.refunded`.
+ * No-op when already refunded. Throws when the invoice has no recorded
+ * payment (nothing to refund).
+ */
+ async markInvoiceAsRefunded(
+ invoiceId: string,
+ manager?: EntityManager,
+ ): Promise {
+ return this.transition(
+ invoiceId,
+ Freight.InvoiceStatus.Refunded,
+ "refunded",
+ {},
+ manager,
+ (invoice) => {
+ if (!(Number(invoice.paidAmount) > 0)) {
+ throw new BadRequestException(
+ "Cannot refund an invoice with no recorded payment.",
+ );
+ }
+ },
+ );
+ }
+
+ /**
+ * Mark an invoice cancelled and emit `${source}.invoice.cancelled`.
+ * No-op when already cancelled. Throws when the invoice has payments
+ * recorded against it (refund it instead).
+ */
+ async cancelInvoice(
+ invoiceId: string,
+ manager?: EntityManager,
+ ): Promise {
+ return this.transition(
+ invoiceId,
+ Freight.InvoiceStatus.Cancelled,
+ "cancelled",
+ {},
+ manager,
+ (invoice) => {
+ if (Number(invoice.paidAmount) > 0) {
+ throw new BadRequestException(
+ "Cannot cancel an invoice that has payments recorded against it.",
+ );
+ }
+ },
+ );
+ }
+
+ /**
+ * Load the invoice, apply the new status (+ extra columns), then emit
+ * `${source}.invoice.`. No-op (returns the invoice, skipping `guard`)
+ * when it is already in the target status. Throws when the invoice does not
+ * exist or `guard` rejects the current state. Pass `manager` to enlist in a
+ * caller's transaction; otherwise locks the row for update and emits only
+ * after commit (see {@link runTransition}).
+ */
+ private async transition(
+ invoiceId: string,
+ status: Freight.InvoiceStatus,
+ event: string,
+ extra: { paymentId?: string },
+ manager?: EntityManager,
+ guard?: (invoice: Invoice) => void,
+ ): Promise {
+ return this.runTransition(manager, async (mg) => {
+ const invoice = await mg.findOne(Invoice, {
+ where: { id: invoiceId },
+ lock: { mode: "pessimistic_write" },
+ });
+ if (!invoice) {
+ throw new NotFoundException(`Invoice ${invoiceId} not found`);
+ }
+ if (invoice.status === status) return { result: invoice };
+ guard?.(invoice);
+
+ await mg.update(Invoice, { id: invoice.id }, { status, ...extra });
+
+ const updated = { ...invoice, ...extra, status } as Invoice;
+ return {
+ result: updated,
+ emit: () => this.emitInvoiceEvent(event, updated),
+ };
+ });
+ }
+
+ /** Broadcast `${invoice.source}.invoice.` to in-process listeners. */
+ private emitInvoiceEvent(event: string, invoice: Invoice): void {
+ const payload: InvoiceEventPayload = {
+ invoiceId: invoice.id,
+ invoiceNumber: invoice.invoiceNumber,
+ source: invoice.source as Freight.InvoiceSource,
+ sourceId: invoice.sourceId,
+ type: invoice.type,
+ companyId: invoice.companyId,
+ companyProfileId: invoice.companyProfileId,
+ totalAmount: invoice.totalAmount,
+ currency: invoice.currency,
+ status: invoice.status,
+ paymentId: invoice.paymentId ?? null,
+ };
+ this.events
+ .emitAsync(`${invoice.source}.invoice.${event}`, payload)
+ .catch((err) =>
+ this.logger.error(
+ `Listener for ${invoice.source}.invoice.${event} (invoice ${invoice.id}) failed: ${err instanceof Error ? err.message : String(err)}`,
+ ),
+ );
+ }
+
+ // ββ Payment reconciliation (by source) βββββββββββββββββββββββββββββββββββββββ
+
+ /**
+ * The invoice a source record already has open, or null if it needs a new
+ * one. This is the idempotency check every `ensureInvoiceFor*` (booking,
+ * first-mile, last-mile) runs before generating β it must see DRAFT
+ * invoices too, not just issued ones, otherwise a source that already has
+ * an unissued draft gets a second, duplicate invoice minted alongside it
+ * instead of that draft being reused and then issued.
+ *
+ * Pass `type` to select a specific invoice when a source carries several (e.g.
+ * a booking's up-front vs final charge); omit it to settle whichever single
+ * invoice is currently open. Returns the most recent matching draft-or-open
+ * (unpaid, non-cancelled) invoice.
+ */
+ findPayable(
+ source: Freight.InvoiceSource,
+ sourceId: string,
+ type?: string,
+ ): Promise {
+ return this.dataSource.getRepository(Invoice).findOne({
+ where: {
+ source,
+ sourceId,
+ status: In([Freight.InvoiceStatus.Draft, ...OPEN_STATUSES]),
+ ...(type ? { type } : {}),
+ },
order: { issuedAt: "DESC" },
});
}
+
+ /**
+ * Pass `type` to select a specific invoice when a source carries several (e.g.
+ * a booking's up-front vs final charge); omit it to settle whichever single
+ * invoice is currently open. Returns the most recent matching open (unpaid,
+ * non-cancelled) invoice.
+ */
+ findInvoice(
+ source: Freight.InvoiceSource,
+ sourceId: string,
+ type?: string,
+ ): Promise {
+ return this.dataSource.getRepository(Invoice).findOne({
+ where: {
+ source,
+ sourceId,
+ ...(type ? { type } : {}),
+ },
+ order: { issuedAt: "DESC" },
+ });
+ }
+
+ /**
+ * Expire a source's currently-open invoice (its pay window closed before
+ * settlement), then emit `${source}.invoice.expired`. Resolves the open invoice
+ * and transitions it to EXPIRED β a terminal, non-payable status (kept out of
+ * `OPEN_STATUSES`). No-op (returns null) when the source has no open invoice
+ * (already paid/cancelled/expired).
+ *
+ * Pass the caller's transaction `manager` (e.g. the booking pay-window expiry in
+ * the batch engine) to enlist in its DB transaction.
+ */
+ async expirePayable(
+ source: Freight.InvoiceSource,
+ sourceId: string,
+ type?: string,
+ manager?: EntityManager,
+ ): Promise {
+ const mg = manager ?? this.dataSource.manager;
+ const invoice = await mg.findOne(Invoice, {
+ where: {
+ source,
+ sourceId,
+ status: In(OPEN_STATUSES),
+ ...(type ? { type } : {}),
+ },
+ order: { issuedAt: "DESC" },
+ });
+ if (!invoice) return null;
+
+ return this.transition(
+ invoice.id,
+ Freight.InvoiceStatus.Expired,
+ "expired",
+ {},
+ mg,
+ );
+ }
+
+ /**
+ * Sync a source's open invoice `dueAt` to its real pay-window deadline. The
+ * booking invoice is generated before the pay window opens (at booking
+ * creation/approval), so its printed due date is refreshed when the batch engine
+ * sets `paymentDeadline`. No-op when the source has no open invoice.
+ */
+ async syncPayableDueDate(
+ source: Freight.InvoiceSource,
+ sourceId: string,
+ dueAt: Date,
+ type?: string,
+ manager?: EntityManager,
+ ): Promise {
+ const mg = manager ?? this.dataSource.manager;
+ const invoice = await mg.findOne(Invoice, {
+ where: {
+ source,
+ sourceId,
+ status: In(OPEN_STATUSES),
+ ...(type ? { type } : {}),
+ },
+ order: { issuedAt: "DESC" },
+ });
+ if (!invoice) return;
+ await mg.update(Invoice, { id: invoice.id }, { dueAt });
+ }
+
+ /**
+ * Force an invoice to `status`, including issuing a still-DRAFT invoice
+ * (stamping `issuedAt`) β unlike the other transitions here, this is a
+ * blunt admin/workflow override, not a settlement. No-op when the invoice
+ * is missing or already terminal (paid/cancelled/refunded/expired).
+ */
+ async updateStatus(
+ invoiceId: string,
+ status: Freight.InvoiceStatus,
+ manager?: EntityManager,
+ ): Promise {
+ const mg = manager ?? this.dataSource.manager;
+ const invoice = await mg.findOne(Invoice, {
+ where: {
+ id: invoiceId,
+ status: In([Freight.InvoiceStatus.Draft, ...OPEN_STATUSES]),
+ },
+ });
+ if (!invoice) return;
+ await mg.update(
+ Invoice,
+ { id: invoice.id },
+ { status, issuedAt: invoice.issuedAt ?? new Date() },
+ );
+ }
+
+ // ββ Payment initiation & settlement (the gateway boundary) βββββββββββββββββββ
+
+ /**
+ * Charge an invoice through the payment gateway. Billing is the single place
+ * that turns "what is owed" (the invoice) into a payment intent β the domain
+ * never talks to the payment service directly. Resolves the invoice by ID,
+ * opens an intent for `invoice.balanceAmount` (so partial payments are honored),
+ * records the intent id on the invoice (the settlement correlation key), and
+ * returns the client action.
+ *
+ * When the provider settles synchronously, the invoice is settled inline here β
+ * after the intent id is stored β so the `payment.succeeded` correlation can
+ * never fire before the link exists. Throws when the invoice is not found or
+ * not in an open/payable status.
+ */
+ async payInvoice(
+ invoiceId: string,
+ opts: {
+ method?: string;
+ platform?: "web" | "mobile";
+ payerAccount?: string;
+ returnUrl?: string;
+ failureUrl?: string;
+ } = {},
+ ): Promise {
+ const invoice = await this.dataSource.getRepository(Invoice).findOne({
+ where: { id: invoiceId, status: In(OPEN_STATUSES) },
+ });
+ if (!invoice) {
+ throw new NotFoundException(
+ `Invoice ${invoiceId} not found or not in a payable status`,
+ );
+ }
+
+ const amountDue = Number(invoice.balanceAmount ?? invoice.totalAmount);
+ if (!(amountDue > 0)) {
+ throw new BadRequestException("Invoice has no outstanding balance.");
+ }
+
+ const result = await this.payment.initiate({
+ referenceId: invoice.sourceId,
+ source: invoice.source,
+ // Freight payments settle under the generic SHIPMENT reference β how the
+ // payment service attributes them to the freight API. The payment β invoice
+ // link is the intent id (`paymentId`); per-source post-payment reactions live
+ // in the domain via `${source}.invoice.paid`. Neither billing nor the payment
+ // service branches on a domain-specific reference type.
+ referenceType: PaymentReferenceType.SHIPMENT,
+ orderRef: invoice.invoiceNumber.replace("-", "_"),
+ amountMinor: Math.round(Number(invoice.balanceAmount)),
+ currency: invoice.currency,
+ reason: `Payment for invoice ${invoice.invoiceNumber}`,
+ method: opts.method ?? "TELEBIRR",
+ platform: opts.platform,
+ payerAccount: opts.payerAccount,
+ returnUrl: opts.returnUrl,
+ failureUrl: opts.failureUrl,
+ });
+
+ // Link the intent to the invoice BEFORE any settlement can correlate against it.
+ await this.dataSource
+ .getRepository(Invoice)
+ .update({ id: invoice.id }, { paymentId: result.intentId });
+
+ if (result.immediateSuccess) {
+ await this.settleByPaymentId(
+ result.intentId,
+ result.providerTxnId,
+ result.paidAt,
+ );
+ }
+
+ return result.response;
+ }
+
+ /**
+ * Settle the open invoice linked to a gateway intent id, if any. Called by the
+ * payment service when an intent succeeds: finds the invoice linked by
+ * `paymentId`, marks it paid, and emits `${source}.invoice.paid` for the domain
+ * to advance on. Idempotent β no-op when no open invoice is linked (already
+ * settled, or settled inline by {@link payInvoice}).
+ */
+ async settleByPaymentId(
+ paymentId: string,
+ providerTxnId?: string,
+ paidAt?: Date,
+ ): Promise {
+ const invoice = await this.dataSource.getRepository(Invoice).findOne({
+ where: { paymentId, status: In(OPEN_STATUSES) },
+ order: { issuedAt: "DESC" },
+ });
+ if (!invoice) return null;
+
+ return this.markInvoiceAsPaid(invoice.id, paymentId, undefined, {
+ providerTxnId,
+ paidAt,
+ });
+ }
}
diff --git a/apps/edr-freight-api/src/modules/billing/documents/documents.module.ts b/apps/edr-freight-api/src/modules/billing/documents/documents.module.ts
new file mode 100644
index 000000000..c320a5d44
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/documents.module.ts
@@ -0,0 +1,16 @@
+import { Module } from "@nestjs/common";
+
+import { InvoiceDocumentService } from "./invoice-document.service";
+import { PdfRenderService } from "./pdf-render.service";
+
+/**
+ * Standalone document infrastructure β generic HTMLβPDF plus the shared
+ * invoice/receipt renderer. Has no domain dependencies, so any module (billing,
+ * warehouses, β¦) can import it to print invoices without coupling to the
+ * billing payment graph.
+ */
+@Module({
+ providers: [PdfRenderService, InvoiceDocumentService],
+ exports: [PdfRenderService, InvoiceDocumentService],
+})
+export class DocumentsModule {}
diff --git a/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
new file mode 100644
index 000000000..a07087f8f
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts
@@ -0,0 +1,179 @@
+import { Injectable } from "@nestjs/common";
+
+import { PdfRenderService } from "./pdf-render.service";
+
+export type InvoiceDocumentKind = "INVOICE" | "RECEIPT";
+
+/** One billed line on the document (charge type / fee type agnostic). */
+export interface InvoiceDocumentLine {
+ description: string | null;
+ /** Optional categorisation column (e.g. "Fee type" / "Charge type"). */
+ category?: string | null;
+ quantity?: number | null;
+ unitRate?: number | null;
+ amount?: number | null;
+ currency?: string | null;
+}
+
+/** A labelled total row in the totals box; mark `grand` for the headline total. */
+export interface InvoiceDocumentTotal {
+ label: string;
+ amount: number;
+ grand?: boolean;
+}
+
+/**
+ * Source-agnostic description of a printable invoice/receipt. Each billing
+ * source maps its own entity onto this shape; the renderer owns the layout so
+ * every EDR invoice document looks identical regardless of source.
+ */
+export interface InvoiceDocumentModel {
+ kind: InvoiceDocumentKind;
+ /** Document heading, e.g. "Warehouse Fee Invoice" / "Freight Invoice". */
+ title: string;
+ documentNumber: string;
+ issuedAt?: Date | string | null;
+ status: string;
+ currency: string;
+ /** Free-form summary grid (label/value pairs). */
+ summary: Array<{ label: string; value: string | null }>;
+ /** Header for the line-item category column; column hidden when omitted. */
+ categoryHeader?: string;
+ lines: InvoiceDocumentLine[];
+ totals: InvoiceDocumentTotal[];
+ /** Override the round seal text; defaults from kind/status. */
+ sealText?: string;
+}
+
+/**
+ * Central invoice/receipt PDF renderer shared by every billing source. Turns a
+ * {@link InvoiceDocumentModel} into the sealed EDR document HTML and renders it
+ * via {@link PdfRenderService}. Previously this layout lived (warehouse-only) in
+ * `WarehouseInvoiceService`; it now serves all invoices.
+ */
+@Injectable()
+export class InvoiceDocumentService {
+ constructor(private readonly pdf: PdfRenderService) {}
+
+ async render(
+ model: InvoiceDocumentModel,
+ ): Promise<{ filename: string; buffer: Buffer }> {
+ const html = this.buildHtml(model);
+ const kindLabel = model.kind === "RECEIPT" ? "receipt" : "invoice";
+ return {
+ filename: `${this.safeFilename(model.documentNumber)}-${kindLabel}.pdf`,
+ buffer: await this.pdf.htmlToPdfBuffer(html, { label: `${model.title} ${kindLabel}` }),
+ };
+ }
+
+ buildHtml(model: InvoiceDocumentModel): string {
+ const esc = (value: unknown) =>
+ String(value ?? "-")
+ .replace(/&/g, "&")
+ .replace(//g, ">")
+ .replace(/"/g, """)
+ .replace(/'/g, "'");
+ const money = (amount: unknown, currency = model.currency) =>
+ `${Number(amount ?? 0).toLocaleString()} ${currency === "ETB" ? "Birr (ETB)" : currency}`;
+ const date = (value: unknown) =>
+ value ? new Date(value as string | Date).toLocaleDateString("en-GB") : "-";
+
+ const showCategory = Boolean(model.categoryHeader);
+ const sealText =
+ model.sealText ?? (model.kind === "RECEIPT" || model.status === "PAID" ? "EDR PAID" : "EDR");
+
+ const summaryRows = model.summary
+ .map((row) => `${esc(row.label)}${esc(row.value)}
`)
+ .join("");
+
+ const itemRows = model.lines
+ .map(
+ (item) => `
+ | ${esc(item.description)} |
+ ${showCategory ? `${esc((item.category ?? "").replace(/_/g, " "))} | ` : ""}
+ ${esc(item.quantity ?? 0)} |
+ ${esc(money(item.unitRate, item.currency ?? model.currency))} |
+ ${esc(money(item.amount, item.currency ?? model.currency))} |
+
`,
+ )
+ .join("");
+
+ const totalRows = model.totals
+ .map(
+ (total) =>
+ `${esc(total.label)}${esc(money(total.amount))}
`,
+ )
+ .join("");
+
+ return `
+
+
+
+ ${esc(model.title)} ${model.kind === "RECEIPT" ? "Receipt" : "Invoice"}
+
+
+
+
+
+
+
Ethio-Djibouti Railway S.C.
+
${esc(model.title)} ${model.kind === "RECEIPT" ? "Receipt" : "Invoice"}
+
+
+ Document no.
+ ${esc(model.documentNumber)}
+ Issued: ${esc(date(model.issuedAt))}
+
+
+
${esc(sealText)}
+
${summaryRows}
+
+
+
+ | Description |
+ ${showCategory ? `${esc(model.categoryHeader)} | ` : ""}
+ Qty |
+ Rate |
+ Amount |
+
+
+
+ ${itemRows}
+
+
+
${totalRows}
+
+
-YYYYMMDD-00001`: the sequence is the max existing suffix for
+ * the day + 1. Run inside the caller's transaction (pass that transaction's
+ * manager) so concurrent generation within a transaction stays consistent.
+ */
+
+/** Anything exposing TypeORM's `.query` β an `EntityManager` or `DataSource`. */
+export interface SqlRunner {
+ query(sql: string, params?: unknown[]): Promise;
+}
+
+export interface InvoiceNumberOptions {
+ /** Schema-qualified table to scan, e.g. `freight.invoices`. */
+ table: string;
+ /** Document code prefix, e.g. `FRT` or `WHF`. */
+ code: string;
+ /** Column holding the number; defaults to `invoice_number`. */
+ column?: string;
+ /** Clock injection point (tests); defaults to now. */
+ now?: Date;
+}
+
+export async function nextDailyInvoiceNumber(
+ runner: SqlRunner,
+ opts: InvoiceNumberOptions,
+): Promise {
+ const now = opts.now ?? new Date();
+ const ymd = `${now.getFullYear()}${String(now.getMonth() + 1).padStart(2, "0")}${String(now.getDate()).padStart(2, "0")}`;
+ const prefix = `${opts.code}-${ymd}-`;
+ const column = opts.column ?? "invoice_number";
+
+ // Serialize concurrent allocation for this exact day+code prefix so two
+ // simultaneous transactions can't both read the same MAX(seq) and mint a
+ // duplicate number. Session-scoped to the caller's transaction β released
+ // automatically on commit/rollback. Different prefixes hash to different
+ // keys and never contend with each other.
+ await runner.query(`SELECT pg_advisory_xact_lock(hashtext($1))`, [prefix]);
+
+ const rows = (await runner.query(
+ `SELECT COALESCE(MAX(CAST(split_part(${column}, '-', 3) AS int)), 0) AS seq
+ FROM ${opts.table} WHERE ${column} LIKE $1`,
+ [`${prefix}%`],
+ )) as Array<{ seq: number | string }>;
+ const next = Number(rows[0]?.seq ?? 0) + 1;
+ return `${prefix}${String(next).padStart(5, "0")}`;
+}
diff --git a/apps/edr-freight-api/src/modules/billing/invoice-settlement.util.ts b/apps/edr-freight-api/src/modules/billing/invoice-settlement.util.ts
new file mode 100644
index 000000000..ab1e27b1a
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/invoice-settlement.util.ts
@@ -0,0 +1,36 @@
+/**
+ * Shared payment/settlement math for invoices. Both the global
+ * `BillingService.recordPayment` and the warehouse fee invoice flow apply a
+ * payment the same way β accumulate `paidAmount`, derive the outstanding
+ * `balanceAmount`, and decide whether the invoice is now fully settled. Keeping
+ * it here means the two flows can never drift on rounding or the
+ * partial-vs-full threshold.
+ */
+
+/** Round to 2 decimals, avoiding binary float drift. */
+export const round2 = (n: number): number => Math.round(n * 100) / 100;
+
+export interface SettlementResult {
+ /** New cumulative amount paid. */
+ paidAmount: number;
+ /** Remaining balance (0 once fully paid). */
+ balanceAmount: number;
+ /** True once the balance reaches zero. */
+ fullyPaid: boolean;
+}
+
+/**
+ * Apply a single payment of `amount` to an invoice with `totalAmount` already
+ * carrying `currentPaid`. Caller is responsible for validating `amount > 0` and
+ * the invoice being in a payable state.
+ */
+export function applySettlement(
+ totalAmount: number,
+ currentPaid: number,
+ amount: number,
+): SettlementResult {
+ const total = Number(totalAmount);
+ const paidAmount = round2(Number(currentPaid) + Number(amount));
+ const balanceAmount = Math.max(0, round2(total - paidAmount));
+ return { paidAmount, balanceAmount, fullyPaid: paidAmount >= total };
+}
diff --git a/apps/edr-freight-api/src/modules/billing/invoice.repository.ts b/apps/edr-freight-api/src/modules/billing/invoice.repository.ts
new file mode 100644
index 000000000..cc2e89df7
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/invoice.repository.ts
@@ -0,0 +1,15 @@
+import { BaseRepository } from "@edr/api-common";
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { Repository } from "typeorm";
+
+import { Invoice } from "./entities/invoice.entity";
+
+@Injectable()
+export class InvoiceRepository extends BaseRepository {
+ constructor(
+ @InjectRepository(Invoice) repository: Repository,
+ ) {
+ super(repository);
+ }
+}
diff --git a/apps/edr-freight-api/src/modules/billing/payment.controller.ts b/apps/edr-freight-api/src/modules/billing/payment.controller.ts
new file mode 100644
index 000000000..543c84201
--- /dev/null
+++ b/apps/edr-freight-api/src/modules/billing/payment.controller.ts
@@ -0,0 +1,177 @@
+import {
+ Body,
+ Controller,
+ Get,
+ HttpStatus,
+ Post,
+ Query,
+ Res,
+} from "@nestjs/common";
+import {
+ ApiTags,
+ ApiOperation,
+ ApiQuery,
+ ApiOkResponse,
+ ApiProduces,
+} from "@nestjs/swagger";
+import { Response } from "express";
+import { Public } from "@edr/api-common";
+
+import { BillingService } from "./billing.service";
+import {
+ InitiatePaymentDto,
+ InitiateResponseDto,
+ PaymentMethodTypeEnum,
+ PaymentPlatformDto,
+} from "../payment/payments.dto";
+
+/**
+ * Central payment entrypoints. Domain-agnostic β the caller supplies an
+ * invoice ID and the billing service resolves the amount and drives the
+ * gateway. The domain never talks to the payment service directly.
+ * Routes are unchanged (`/payments/*`) so the portal is unaffected.
+ */
+@ApiTags("Payment")
+@Controller("payments")
+export class PaymentController {
+ constructor(private readonly billing: BillingService) { }
+
+ @Post("initiate")
+ @ApiOperation({
+ summary: "Initiate payment for an invoice",
+ description: "Charges the invoice through the payment gateway.",
+ })
+ @ApiOkResponse({ type: InitiateResponseDto })
+ initiate(@Body() dto: InitiatePaymentDto): Promise {
+ return this.billing.payInvoice(dto.invoiceId, {
+ method: dto.method,
+ platform: dto.platform,
+ payerAccount: dto.payerAccount,
+ returnUrl: dto.returnUrl,
+ failureUrl: dto.failureUrl,
+ });
+ }
+
+ @Get("checkout")
+ @Public()
+ @ApiOperation({
+ summary: "Browser checkout redirect",
+ description:
+ "Charges the invoice and returns an HTML page that auto-redirects to the provider checkout URL. Open directly in a browser tab.",
+ })
+ @ApiQuery({ name: "invoiceId", required: true })
+ @ApiQuery({ name: "method", enum: PaymentMethodTypeEnum, required: true })
+ @ApiQuery({ name: "platform", enum: ["web", "mobile"], required: false })
+ @ApiProduces("text/html")
+ async checkout(
+ @Query("invoiceId") invoiceId: string,
+ @Query("method") method: PaymentMethodTypeEnum,
+ @Query("platform") platform: PaymentPlatformDto = "web",
+ @Res() res: Response,
+ ) {
+ if (!invoiceId) {
+ return res
+ .status(HttpStatus.BAD_REQUEST)
+ .type("html")
+ .send(this.buildErrorHtml("Missing required query parameter: invoiceId"));
+ }
+ if (!method || !Object.values(PaymentMethodTypeEnum).includes(method)) {
+ return res
+ .status(HttpStatus.BAD_REQUEST)
+ .type("html")
+ .send(this.buildErrorHtml("Missing or invalid query parameter: method"));
+ }
+
+ try {
+ const result = await this.billing.payInvoice(
+ invoiceId,
+ { method, platform },
+ );
+ const url =
+ result.clientAction?.type === "REDIRECT" ? result.clientAction.url : undefined;
+
+ if (url) {
+ return res.status(HttpStatus.OK).type("html").send(this.buildRedirectHtml(url));
+ }
+ return res
+ .status(HttpStatus.OK)
+ .type("html")
+ .send(this.buildStatusHtml(result.status, result.intentId));
+ } catch (err: unknown) {
+ const message = err instanceof Error ? err.message : "An unexpected error occurred";
+ return res.status(HttpStatus.OK).type("html").send(this.buildErrorHtml(message));
+ }
+ }
+
+ private buildRedirectHtml(url: string): string {
+ const escaped = url.replace(/\"/g, """);
+ return `
+
+
+
+
+ Redirecting to paymentβ¦
+
+
+
+
+
+
+`;
+ }
+
+ private buildStatusHtml(status: string, intentId: string): string {
+ return `
+
+
+
+ Payment status
+
+
+
+
+
${status}
+
Intent: ${intentId}
+
+
Payment could not be initiated
+
${message}
+
| ${this.escapeHtml(label)} | ${this.escapeHtml(value || '-')} |
|---|
`)
+ .join('');
+ const copy = (watermark: string) => `
+
+ ${this.escapeHtml(watermark)}
+
+
+
+
Customer / Carrier Signature
+
Port Operations Verification
+
Gate Security Verification
+