Tria/edr-platform
1
0
Fork 0
mirror of https://github.com/Tria-plc/edr-platform.git synced 2026-08-26 18:42:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #975 from Tria-plc/dev

Browse Source 
syncing
This commit is contained in:
Nathnael Wondisha
2026-07-27 14:19:45 +03:00
committed by GitHub
parent da51e83152 8449ce0ef3
commit 32093ec1c1
261 changed files with 15418 additions and 1956 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
CLAUDE.md
View File

@@ -24,6 +24,7 @@ Monorepo for the Ethio Djibouti Railway (EDR) digital platform. Contains the Fre
| ---------------------- | ---------------------------------------------------------------------------------- |
| `@edr/types` | Shared TypeScript interfaces and enums |
| `@edr/api-common` | Shared NestJS decorators, filters, interceptors, pipes, BaseEntity, BaseRepository |
| `@edr/iam-seed` | IAM baseline seeder for the apps sharing the `iam` schema (freight + passenger) |
| `@edr/ui-common` | Shared React components and theme |
| `@edr/eslint-config` | Shared ESLint configurations (base/nestjs/react) |
| `@edr/tsconfig` | Shared TypeScript configurations |

9
apps/edr-freight-api/.env.example
View File

@@ -42,8 +42,17 @@ JWT_REFRESH_TOKEN_EXPIRES=7d
# IAM seed defaults (used by @tria-plc/iamapi-common on first boot)
SUPER_ADMIN_EMAIL=superadmin@tria.com
SUPER_ADMIN_PHONE=
# Super-admin password. Falls back to DEFAULT_PASSWORD when empty.
SUPER_ADMIN_DEFAULT_PASSWORD=
DEFAULT_PASSWORD=password@tria
# IAM baseline shared with edr-passenger-api (roles, IAM app + permissions,
# position types, organization types + default units, org/unit settings, super
# admin). Replaces the seeder that shipped inside @tria-plc/iamapi-common — see
# packages/iam-seed. Seeds by DEFAULT when unset; every write is insert-only.
# Set to false to opt out.
SEED_IAM_BASELINE=true
# Freight org + staff (bookings / rule-engine IAM)
SEED_EDR_ORG=true
SEED_FREIGHT_STAFF=true

2
apps/edr-freight-api/package.json
View File

@@ -35,12 +35,12 @@
"iam:migration:run": "pnpm run iam:typeorm:cli migration:run",
"iam:migration:revert": "pnpm run iam:typeorm:cli migration:revert",
"iam:migration:show": "pnpm run iam:typeorm:cli migration:show",
"iam:seed:run": "cross-env APP_MODULE_PATH=./dist/app.module dotenv -- node ./node_modules/@tria-plc/iamapi-common/dist/db/seed.cli.js",
"migrate": "ts-node -r tsconfig-paths/register src/scripts/run-migrations.ts",
"script": "ts-node -r tsconfig-paths/register src/scripts/main.ts"
},
"dependencies": {
"@edr/api-common": "workspace:*",
"@edr/iam-seed": "workspace:*",
"@edr/payment-providers": "workspace:*",
"@edr/types": "workspace:*",
"@golevelup/nestjs-rabbitmq": "^5.5.0",

30
apps/edr-freight-api/src/app.module.ts
View File

@@ -12,7 +12,8 @@ import {
ensurePostgresSchemas,
APPLICATION_SEARCH_PATH,
} from "./config/ensure-postgres-schemas";
import { IamModule, DataSeeder } from "@tria-plc/iamapi-common";
import { IamBaselineSeeder, IamSeedModule } from "@edr/iam-seed";
import { IamModule } from "@tria-plc/iamapi-common";
import { SharedAuthModule } from "@tria-plc/api-common/modules/auth/shared-auth.module";
import appConfig from "./config/app.config";
@@ -153,6 +154,18 @@ import { LoggerMiddleware } from "./logger.middleware";
applications: [EDR_FREIGHT_APPLICATION],
permissions: EDR_FREIGHT_PERMISSIONS,
}),
// Replaces the package's DataSeeder. Shared with edr-passenger-api, which
// seeds the same `iam` schema — see packages/iam-seed.
IamSeedModule.forRoot({
superAdmin: {
username: "superadmin",
name: { am: "ሱፐር አድሚን", en: "Super Admin" },
roleKey: "super_admin",
organizationKey: "edr_freight",
unitKey: "edr_freight_app",
fallbackEmail: "superadmin@tria.com",
},
}),
BookingsModule,
ContractsModule,
SignaturesModule,
@@ -231,7 +244,7 @@ import { LoggerMiddleware } from "./logger.middleware";
})
export class AppModule implements OnApplicationBootstrap {
constructor(
private readonly seeder: DataSeeder,
private readonly iamBaselineSeeder: IamBaselineSeeder,
private readonly edrOrgSeeder: EdrOrgSeeder,
private readonly freightPositionsSeeder: FreightPositionsSeeder,
private readonly fileUploadSettingsSeeder: FileUploadSettingsSeeder,
@@ -261,13 +274,22 @@ export class AppModule implements OnApplicationBootstrap {
// Permissions foundation — keep enabled:
// freightPermissionKeyMigration → renames legacy permission keys
// seeder (IAM DataSeeder) → seeds the IAM app, roles, permissions
// edrOrgSeeder → seeds org/unit + the Permission catalog
// iamBaselineSeeder → @edr/iam-seed: IAM app, roles, permissions,
// position types, organization types +
// default units, org/unit settings and the
// super-admin account. Replaces the package's
// DataSeeder, and is shared with
// edr-passenger-api so one writer owns the
// `iam` schema. Runs after edrOrgSeeder
// because the super admin attaches to the
// edr_freight org/unit.
// Writes nothing unless SEED_IAM_BASELINE=true.
// freightPositionsSeeder → seeds Position + PositionPermission rows
// (depends on edrOrgSeeder, must run after)
await this.freightPermissionKeyMigrationSeeder.run();
await this.seeder.run();
await this.edrOrgSeeder.run();
await this.iamBaselineSeeder.run();
await this.freightPositionsSeeder.run();
// File upload settings — keep enabled.

34
apps/edr-freight-api/src/common/booking-guards.ts
View File

@@ -23,6 +23,14 @@ export const StaffReference = () => applyDecorators(UseGuards(JwtGuard));
export const BookingView = () => BookingStaff(FREIGHT_PERMS.bookings.view);
/**
* The document-review countdown in the backoffice header. Its own permission so
* it can be granted to exactly the position types that decide operation
* requests, instead of every holder of bookings:view.
*/
export const BookingDocReviewAlert = () =>
BookingStaff(FREIGHT_PERMS.bookings.docReviewAlert);
export const TrainSchedulingView = () =>
BookingStaff(FREIGHT_PERMS.trainScheduling.view);
@@ -73,6 +81,32 @@ export const WagonTransferFulfill = () =>
export const WagonTransferHistoryAll = () =>
BookingStaff(FREIGHT_PERMS.wagons.transferHistoryAll);
/**
* Open the transfer-requests desk. `wagons:view` is accepted as a one-of
* fallback so staff who could already reach the queue keep it without a
* re-grant — same pattern the granular fleet keys use.
*/
export const WagonTransferView = () =>
BookingStaff([FREIGHT_PERMS.wagons.transferView, FREIGHT_PERMS.wagons.view]);
/** Withdraw a request that has not moved any wagon yet. */
export const WagonTransferCancel = () =>
BookingStaff([
FREIGHT_PERMS.wagons.transferCancel,
FREIGHT_PERMS.wagons.transferRequest,
]);
/**
* End a request short of the requested count. Whoever may move wagons may also
* declare the yard has no more to give, so fulfil is accepted alongside the
* dedicated key.
*/
export const WagonTransferCloseShort = () =>
BookingStaff([
FREIGHT_PERMS.wagons.transferCloseShort,
FREIGHT_PERMS.wagons.transferFulfill,
]);
/** Org-administration endpoints (user mgmt, billing config, company CRUD, settings). */
export const FreightAdmin = () => BookingStaff(FREIGHT_PERMS.admin);

47
apps/edr-freight-api/src/common/freight-permission.hazardous.spec.ts Normal file
View File

@@ -0,0 +1,47 @@
import { ForbiddenException } from '@nestjs/common';
import {
assertCanApproveContractStep,
canEditContractStep,
} from './freight-permission.util';
import { FREIGHT_PERMS } from '../seed/freight-permissions.registry';
const userWith = (...keys: string[]) => ({
permissions: keys.map((key) => ({ key })),
});
describe('hazardous contract approval steps', () => {
it('rejects an approver who only holds ordinary contract-approve permissions', () => {
// The blanket "any contract approve permission" fallback must NOT reach
// dangerous goods — that is the whole point of the dedicated desks.
const lineStaff = userWith(FREIGHT_PERMS.contracts.approveLineStaff);
expect(() =>
assertCanApproveContractStep(lineStaff, 'HAZARDOUS_APPROVAL_ONE'),
).toThrow(ForbiddenException);
expect(canEditContractStep(lineStaff, 'HAZARDOUS_APPROVAL_ONE')).toBe(false);
});
it('accepts only the matching hazardous permission', () => {
const first = userWith(FREIGHT_PERMS.contracts.hazardousApprovalOne);
expect(() =>
assertCanApproveContractStep(first, 'HAZARDOUS_APPROVAL_ONE'),
).not.toThrow();
// Holding step one does not confer step two.
expect(() =>
assertCanApproveContractStep(first, 'HAZARDOUS_APPROVAL_TWO'),
).toThrow(ForbiddenException);
});
it('does not let a hazardous approver stand in for the commercial chain', () => {
const hazardOnly = userWith(
FREIGHT_PERMS.contracts.hazardousApprovalOne,
FREIGHT_PERMS.contracts.hazardousApprovalTwo,
);
expect(() => assertCanApproveContractStep(hazardOnly, 'CEO')).toThrow(
ForbiddenException,
);
});
});

33
apps/edr-freight-api/src/common/freight-permission.util.ts
View File

@@ -151,6 +151,24 @@ const APPROVE_ROLE_PERMISSION: Record<string, string> = {
CEO: FREIGHT_PERMS.bookings.approveCeo,
};
/**
* Approval-chain roles synthesized for hazardous contracts (see
* `instantiateApprovalSteps`). Unlike the legacy roles below they are NOT
* position types — they authorize purely on their own dedicated permission, and
* they deliberately opt out of the blanket "holds any contract-approve
* permission" fallback so a normal approver cannot sign off dangerous goods.
*/
export const HAZARDOUS_APPROVAL_ROLE_PERMISSION: Record<string, string> = {
HAZARDOUS_APPROVAL_ONE: FREIGHT_PERMS.contracts.hazardousApprovalOne,
HAZARDOUS_APPROVAL_TWO: FREIGHT_PERMS.contracts.hazardousApprovalTwo,
};
/** The two hazardous steps, in the order they are prepended to the chain. */
export const HAZARDOUS_APPROVAL_ROLES = [
'HAZARDOUS_APPROVAL_ONE',
'HAZARDOUS_APPROVAL_TWO',
] as const;
const CONTRACT_APPROVE_ROLE_PERMISSION: Record<string, string> = {
LINE_STAFF: FREIGHT_PERMS.contracts.approveLineStaff,
DIRECTOR: FREIGHT_PERMS.contracts.approveDirector,
@@ -183,6 +201,16 @@ export function assertCanApproveContractStep(
): void {
if (isFreightApprovalAdmin(user)) return;
// Hazardous steps are permission-only and strict — no legacy alias, no
// blanket approve fallback.
const hazardousPermission = HAZARDOUS_APPROVAL_ROLE_PERMISSION[requiredRole];
if (hazardousPermission) {
if (hasFreightPermission(user, hazardousPermission)) return;
throw new ForbiddenException(
`Missing permission: ${hazardousPermission}`,
);
}
const positionTypes = collectPositionTypeKeys(user);
if (positionTypes.includes(requiredRole)) return;
@@ -219,6 +247,11 @@ export function canEditContractStep(
): boolean {
if (isFreightApprovalAdmin(user)) return true;
const hazardousPermission = HAZARDOUS_APPROVAL_ROLE_PERMISSION[requiredRole];
if (hazardousPermission) {
return hasFreightPermission(user, hazardousPermission);
}
const positionTypes = collectPositionTypeKeys(user);
if (positionTypes.includes(requiredRole)) return true;

40
apps/edr-freight-api/src/common/grn.util.spec.ts Normal file
View File

@@ -0,0 +1,40 @@
import { generateGrnNumber, grnOwnerSlug } from './grn.util';
/**
* The GRN is mapped to the goods owner for BOTH directions, so a note is
* identifiable by who owns the cargo. The reference slice stays the uniqueness
* anchor — one owner can have several bookings received the same day.
*/
const date = new Date('2026-07-27T09:15:00Z');
const bookingId = '1a2b3c4d-1111-2222-3333-444455556666';
describe('GRN number', () => {
it('maps an import GRN to the owner', () => {
expect(generateGrnNumber('IMPORT', bookingId, date, 'Shafici Pharmaceutical')).toBe(
'GRN-IMPORT-20260727-SHAFICIPHARM-1A2B3C4D',
);
});
it('maps an export GRN to the owner the same way', () => {
expect(generateGrnNumber('EXPORT', bookingId, date, 'Tria Trading PLC')).toBe(
'GRN-EXPORT-20260727-TRIATRADINGP-1A2B3C4D',
);
});
it('keeps the owner-less format when there is no owner (manual walk-in)', () => {
expect(generateGrnNumber('WH', bookingId, date)).toBe('GRN-WH-20260727-1A2B3C4D');
expect(generateGrnNumber('WH', bookingId, date, ' ')).toBe('GRN-WH-20260727-1A2B3C4D');
});
it('stays unique per booking for one owner on one day', () => {
const a = generateGrnNumber('IMPORT', bookingId, date, 'Acme');
const b = generateGrnNumber('IMPORT', 'ffffffff-9999-0000-0000-000000000000', date, 'Acme');
expect(a).not.toBe(b);
});
it('strips punctuation and caps the owner segment', () => {
expect(grnOwnerSlug('Ethio-Djibouti Railway S.C.')).toBe('ETHIODJIBOUT');
expect(grnOwnerSlug('a/b c')).toBe('ABC');
expect(grnOwnerSlug(null)).toBeNull();
});
});

34
apps/edr-freight-api/src/common/grn.util.ts
View File

@@ -1,13 +1,41 @@
/**
* Goods Received Note number: `GRN-<DIRECTION>-<YYYYMMDD>-<REF8>`.
* Goods Received Note number: `GRN-<DIRECTION>-<YYYYMMDD>-<OWNER>-<REF8>`.
*
* The GRN is mapped to the goods OWNER (the booking's customer / consignee) for
* both import and export, so a note is identifiable by who owns the cargo
* without opening it. The trailing reference slice stays as the uniqueness
* anchor — one owner can have several bookings received on the same day.
* Owner-less receipts (manual walk-ins with no booking) fall back to the
* original `GRN-<DIRECTION>-<YYYYMMDD>-<REF8>` form.
*
* Shared so a GRN raised at a load/unload facility is indistinguishable from one
* raised in a warehouse — the two live in different tables
* (facility_handling_events vs warehouse_inventory), and a second generator would
* eventually let their formats drift apart.
*/
export function generateGrnNumber(direction: string, referenceId: string, date: Date): string {
export function generateGrnNumber(
direction: string,
referenceId: string,
date: Date,
ownerName?: string | null,
): string {
const stamp = date.toISOString().slice(0, 10).replace(/-/g, '');
const suffix = referenceId.replace(/-/g, '').slice(0, 8).toUpperCase();
return `GRN-${direction.toUpperCase()}-${stamp}-${suffix}`;
const owner = grnOwnerSlug(ownerName);
const base = `GRN-${direction.toUpperCase()}-${stamp}`;
return owner ? `${base}-${owner}-${suffix}` : `${base}-${suffix}`;
}
/**
* Owner name → GRN-safe token: letters/digits only, upper-cased, capped so a
* long company name can't run away with the number. Null when there is nothing
* usable, which drops the segment rather than emitting an empty `--`.
*/
export function grnOwnerSlug(ownerName?: string | null): string | null {
const slug = (ownerName ?? '')
.normalize('NFKD')
.replace(/[^a-zA-Z0-9]+/g, '')
.toUpperCase()
.slice(0, 12);
return slug || null;
}

24
apps/edr-freight-api/src/contracts/contract-document-view-model.builder.ts
View File

@@ -1,4 +1,5 @@
import { Injectable, NotFoundException } from '@nestjs/common';
import { hazardClassLabel } from '@edr/types';
import { ContractsRepository } from '../modules/contracts/contracts.repository';
import {
@@ -30,6 +31,8 @@ export interface ContractDocumentSignatureView {
signerDisplayName: string;
signedAt: string;
signatureImageUrl?: string | null;
/** Company stamp/seal; rendered next to the signature when present. */
stampImageUrl?: string | null;
}
/** A single unit-rate row on the contract PDF — price per unit, NO total. */
@@ -141,6 +144,11 @@ export class ContractDocumentViewModelBuilder {
const hasCustomer = signatures.some((s) => s.role === 'CUSTOMER');
const hasStaff = signatures.some((s) => s.role === 'STAFF');
// Signed before company stamps were required — the customer has to sign
// again to attach one, otherwise EDR can never counter-sign the contract.
const customerStampMissing = signatures.some(
(s) => s.role === 'CUSTOMER' && !s.stampImageUrl,
);
const hasContractFile = Boolean(
contract.files?.some((f) => f.code === 'contract'),
);
@@ -183,7 +191,9 @@ export class ContractDocumentViewModelBuilder {
// Cast: contract signers (CUSTOMER|STAFF|DIRECTOR|CEO) widen the booking
// view-model's narrower CUSTOMER|STAFF role union.
signatures: signatures as unknown as ContractViewModel['signatures'],
canSignCustomer: contract.status === 'CONTRACT_READY' && !hasCustomer,
canSignCustomer:
(contract.status === 'CONTRACT_READY' && !hasCustomer) ||
(contract.status === 'SIGNED_CUSTOMER' && customerStampMissing),
canSignStaff:
contract.status === 'SIGNED_CUSTOMER' && hasCustomer && !hasStaff,
hasContractDocument: hasContractFile,
@@ -208,6 +218,7 @@ export class ContractDocumentViewModelBuilder {
signerDisplayName: row.signerDisplayName,
signedAt: this.formatDate(row.signedAt),
signatureImageUrl: row.signatureFile?.url ?? null,
stampImageUrl: row.stampFile?.url ?? null,
};
}
@@ -292,7 +303,16 @@ export class ContractDocumentViewModelBuilder {
cargoDescription: this.valueOrDash(cargoName),
totalWeightVgm: '—',
equipmentReturn: this.valueOrDash(contract.equipmentReturn),
hazardousLabel: contract.isHazardous ? 'Yes' : 'No',
// A hazardous contract names the declared class + UN number on the
// schedule — the flag alone is not a dangerous-goods declaration.
hazardousLabel: contract.isHazardous
? [
hazardClassLabel(contract.hazardClass) ?? 'Yes',
contract.unNumber ? `UN ${contract.unNumber}` : null,
]
.filter(Boolean)
.join(' · ')
: 'No',
firstMilePickupAddress: this.valueOrDash(contract.firstMilePickupAddress),
lastMileDeliveryAddress: this.valueOrDash(contract.lastMileDeliveryAddress),
};

12
apps/edr-freight-api/src/contracts/templates/_partials/signatures_block.hbs
View File

@@ -11,6 +11,12 @@
<p class="sig-line"><strong>Name:</strong> {{signerDisplayName}}</p>
<p class="sig-meta"><strong>Role:</strong> Authorized EDR representative</p>
<p class="sig-meta"><strong>Date:</strong> {{signedAt}}</p>
{{#if stampImageUrl}}
<div class="sig-stamp">
<span class="sig-stamp-label">Company stamp</span>
<div class="sig-stamp-box"><img src="{{stampImageUrl}}" alt="Service provider stamp" /></div>
</div>
{{/if}}
{{/if}}
{{/each}}
{{else}}
@@ -32,6 +38,12 @@
<p class="sig-line"><strong>Name:</strong> {{signerDisplayName}}</p>
<p class="sig-meta"><strong>Role:</strong> Authorized client representative</p>
<p class="sig-meta"><strong>Date:</strong> {{signedAt}}</p>
{{#if stampImageUrl}}
<div class="sig-stamp">
<span class="sig-stamp-label">Company stamp</span>
<div class="sig-stamp-box"><img src="{{stampImageUrl}}" alt="Client stamp" /></div>
</div>
{{/if}}
{{/if}}
{{/each}}
{{else}}

33
apps/edr-freight-api/src/contracts/templates/_partials/styles.hbs
View File

@@ -372,25 +372,30 @@
font-size: 9pt;
margin: 4px 0;
}
/* ── Witnesses ────────────────────────────────────────────────────────── */
.witnesses { margin-top: 20px; }
.witness-table {
font-size: 9.5pt;
margin-top: 6px;
.sig-stamp {
margin-top: 12px;
}
.witness-table th,
.witness-table td {
border-bottom: 1px solid #c9e4d9;
padding: 9px 8px;
text-align: left;
}
.witness-table th {
.sig-stamp-label {
color: #0e5b45;
font-family: Arial, sans-serif;
font-size: 8.5pt;
font-size: 7.5pt;
font-weight: 700;
letter-spacing: 0.4pt;
text-transform: uppercase;
}
.sig-stamp-box {
align-items: center;
display: flex;
height: 30mm;
justify-content: center;
margin-top: 5px;
}
.sig-stamp-box img {
display: block;
max-height: 30mm;
max-width: 45mm;
mix-blend-mode: multiply;
}
@media print {
body { background: #fff; }

13
apps/edr-freight-api/src/contracts/templates/edr-dynamic.hbs
View File

@@ -147,19 +147,6 @@
authorized to sign and execute this Contract Agreement.
</p>
{{> signatures_block}}
<div class="witnesses">
<p class="sig-title">Witnesses</p>
<table class="witness-table">
<thead>
<tr><th></th><th>Name</th><th>Signature</th><th>Date</th></tr>
</thead>
<tbody>
<tr><td>1.</td><td></td><td></td><td></td></tr>
<tr><td>2.</td><td></td><td></td><td></td></tr>
</tbody>
</table>
</div>
</section>
</main>
</body>

39
apps/edr-freight-api/src/migrations/2850000000000-AddBookingDoubleHandling.ts Normal file
View File

@@ -0,0 +1,39 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Double handling becomes an explicit per-booking decision instead of an
* implicit "every import" charge. Warehouse staff record Yes/No after
* unloading (whether the goods actually had to be re-handled); the
* DOUBLE_HANDLING_FEE rule only bills when the answer is Yes.
*
* NULL = not decided yet → no charge, and the UI shows "not set" so the
* operator is prompted. Existing rows stay NULL deliberately: back-billing a
* fee nobody confirmed would be wrong.
*/
export class AddBookingDoubleHandling2850000000000 implements MigrationInterface {
name = 'AddBookingDoubleHandling2850000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS double_handling boolean;`,
);
await queryRunner.query(
`ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS double_handling_set_at timestamptz;`,
);
await queryRunner.query(
`ALTER TABLE freight.bookings ADD COLUMN IF NOT EXISTS double_handling_set_by varchar(160);`,
);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE freight.bookings DROP COLUMN IF EXISTS double_handling_set_by;`,
);
await queryRunner.query(
`ALTER TABLE freight.bookings DROP COLUMN IF EXISTS double_handling_set_at;`,
);
await queryRunner.query(
`ALTER TABLE freight.bookings DROP COLUMN IF EXISTS double_handling;`,
);
}
}

35
apps/edr-freight-api/src/migrations/2860000000000-AddPerTruckDetentionWindow.ts Normal file
View File

@@ -0,0 +1,35 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Per-truck detention clocks. Detention was timed once per last-mile leg
* (last_mile.arrived_at / delivered_at), so every truck on a multi-truck
* delivery shared one window and was billed identical days — wrong the moment
* two trucks arrive or return at different times.
*
* Deliberately NEW columns rather than reusing the existing per-truck
* arrived_at / departed_at on this table: those are WAREHOUSE gate-in/gate-out
* events stamped by release(), whereas detention runs from arrival at the
* DESTINATION until the truck is released/returned.
*
* Both nullable — a truck without its own window falls back to the leg-level
* timestamps, so legacy legs keep billing exactly as before.
*/
export class AddPerTruckDetentionWindow2860000000000 implements MigrationInterface {
name = 'AddPerTruckDetentionWindow2860000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.last_mile_vehicle_assignments
ADD COLUMN IF NOT EXISTS destination_arrived_at timestamptz,
ADD COLUMN IF NOT EXISTS returned_at timestamptz;
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.last_mile_vehicle_assignments
DROP COLUMN IF EXISTS returned_at,
DROP COLUMN IF EXISTS destination_arrived_at;
`);
}
}

28
apps/edr-freight-api/src/migrations/2900000000000-LivestockPerItem.ts Normal file
View File

@@ -0,0 +1,28 @@
import { MigrationInterface, QueryRunner } from "typeorm";
/**
* Livestock is billed and counted per head, not per ton — line it up with the
* other break-bulk cargo types (Machinery, Truck, Automobile) so bulk
* storage/demurrage fees charge per item instead of per ton for it.
*/
export class LivestockPerItem2900000000000 implements MigrationInterface {
name = "LivestockPerItem2900000000000";
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
UPDATE freight.cargo_types
SET unit_of_measure = 'PER_ITEM'
WHERE code = 'LIVESTOCK'
AND unit_of_measure IS DISTINCT FROM 'PER_ITEM'
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
UPDATE freight.cargo_types
SET unit_of_measure = 'PER_TON'
WHERE code = 'LIVESTOCK'
AND unit_of_measure IS DISTINCT FROM 'PER_TON'
`);
}
}

27
apps/edr-freight-api/src/migrations/2910000000000-AddContractSignatureStamp.ts Normal file
View File

@@ -0,0 +1,27 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Company stamp (seal) attached alongside the drawn signature, for both the
* client and the EDR side. Stored the same way the signature image is: a
* FileRecord on the contract (`resource: 'contracts'`, `code: 'stamp_<role>'`)
* referenced from the signature row.
*
* Nullable — existing signature rows predate the stamp requirement. The
* "both stamps recorded" gate lives in ContractTransitionService.counterSign,
* not in a NOT NULL constraint, so historical rows stay readable.
*/
export class AddContractSignatureStamp2910000000000 implements MigrationInterface {
name = 'AddContractSignatureStamp2910000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE freight.contract_signatures ADD COLUMN IF NOT EXISTS stamp_file_id uuid;`,
);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE freight.contract_signatures DROP COLUMN IF EXISTS stamp_file_id;`,
);
}
}

22
apps/edr-freight-api/src/migrations/2920000000000-AddRevisionActorName.ts Normal file
View File

@@ -0,0 +1,22 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Store WHO made a contract edit as a name, not just an id. Denormalised on
* purpose: an audit trail must still read correctly after the user is renamed,
* deactivated or deleted, and `iam.users` lives outside this module's schema.
*/
export class AddRevisionActorName2920000000000 implements MigrationInterface {
name = 'AddRevisionActorName2920000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE freight.contract_document_revisions ADD COLUMN IF NOT EXISTS actor_name varchar(200);`,
);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE freight.contract_document_revisions DROP COLUMN IF EXISTS actor_name;`,
);
}
}

40
apps/edr-freight-api/src/migrations/2930000000000-AddWagonTransferPartialFulfilment.ts Normal file
View File

@@ -0,0 +1,40 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Partial wagon-transfer fulfilment.
*
* A request for 50 wagons no longer has to be met in one go: OCC moves what the
* source yard can spare, whenever it can, and the request stays open until the
* full count is met (FULFILLED) or OCC ends it short (CLOSED_SHORT) so the
* requester can ask another yard for the rest.
*
* Existing rows are back-filled so history keeps reading correctly: a FULFILLED
* request delivered its whole quantity; anything else delivered nothing.
*/
export class AddWagonTransferPartialFulfilment2930000000000
implements MigrationInterface
{
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.wagon_transfer_requests
ADD COLUMN IF NOT EXISTS fulfilled_quantity integer NOT NULL DEFAULT 0,
ADD COLUMN IF NOT EXISTS closed_short_at timestamptz NULL,
ADD COLUMN IF NOT EXISTS closed_short_by_user_id uuid NULL
`);
await queryRunner.query(`
UPDATE freight.wagon_transfer_requests
SET fulfilled_quantity = quantity
WHERE status = 'FULFILLED'
AND fulfilled_quantity = 0
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.wagon_transfer_requests
DROP COLUMN IF EXISTS fulfilled_quantity,
DROP COLUMN IF EXISTS closed_short_at,
DROP COLUMN IF EXISTS closed_short_by_user_id
`);
}
}

34
apps/edr-freight-api/src/migrations/2940000000000-AddFileVersionHistory.ts Normal file
View File

@@ -0,0 +1,34 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Keep every version of a stored document.
*
* Replacing a file used to DELETE the previous row outright, so a staff
* correction erased the customer's original upload with no trail. Superseded
* versions are now soft-deleted (already excluded from every read by TypeORM's
* soft-delete filter) and stamped with who replaced them and why, which is what
* the document's version history reads back.
*/
export class AddFileVersionHistory2940000000000 implements MigrationInterface {
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.files
ADD COLUMN IF NOT EXISTS replaced_by_user_id uuid NULL,
ADD COLUMN IF NOT EXISTS replace_reason text NULL
`);
// History reads walk one document's versions, deleted rows included.
await queryRunner.query(`
CREATE INDEX IF NOT EXISTS "IDX_files_version_history"
ON freight.files (resource, resource_id, code, created_at DESC)
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`DROP INDEX IF EXISTS freight."IDX_files_version_history"`);
await queryRunner.query(`
ALTER TABLE freight.files
DROP COLUMN IF EXISTS replaced_by_user_id,
DROP COLUMN IF EXISTS replace_reason
`);
}
}

37
apps/edr-freight-api/src/migrations/2950000000000-AddTransitAssigneeHandshake.ts Normal file
View File

@@ -0,0 +1,37 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Transit-assignee handshake before the customs declaration.
*
* GL Ethiopia must ask GL Djibouti who will handle the shipment in transit, and
* Djibouti answers with a name, before the declaration can be filed. The whole
* exchange lives on the clearance cycle so it repeats naturally with each cycle
* of a GENERAL contract.
*/
export class AddTransitAssigneeHandshake2950000000000
implements MigrationInterface
{
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.contract_clearance_cycles
ADD COLUMN IF NOT EXISTS transit_assignee_requested_at timestamptz NULL,
ADD COLUMN IF NOT EXISTS transit_assignee_requested_by_user_id uuid NULL,
ADD COLUMN IF NOT EXISTS transit_assignee_request_note text NULL,
ADD COLUMN IF NOT EXISTS transit_assignee_name text NULL,
ADD COLUMN IF NOT EXISTS transit_assignee_assigned_at timestamptz NULL,
ADD COLUMN IF NOT EXISTS transit_assignee_assigned_by_user_id uuid NULL
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.contract_clearance_cycles
DROP COLUMN IF EXISTS transit_assignee_requested_at,
DROP COLUMN IF EXISTS transit_assignee_requested_by_user_id,
DROP COLUMN IF EXISTS transit_assignee_request_note,
DROP COLUMN IF EXISTS transit_assignee_name,
DROP COLUMN IF EXISTS transit_assignee_assigned_at,
DROP COLUMN IF EXISTS transit_assignee_assigned_by_user_id
`);
}
}

34
apps/edr-freight-api/src/migrations/2960000000000-AddContractHazardDeclaration.ts Normal file
View File

@@ -0,0 +1,34 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Hazardous contracts now declare WHAT the dangerous good is, not just that it
* exists: the UN/ADR class (CLASS_1..CLASS_9) and the shipment's UN number. Both
* are captured in the portal alongside the hazard documents and reviewed by the
* two hazardous approval desks.
*
* Nullable — non-hazardous contracts leave both null, and contracts created
* before this change have no declaration to backfill.
*/
export class AddContractHazardDeclaration2960000000000
implements MigrationInterface
{
name = 'AddContractHazardDeclaration2960000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE freight.contracts ADD COLUMN IF NOT EXISTS hazard_class varchar(16);`,
);
await queryRunner.query(
`ALTER TABLE freight.contracts ADD COLUMN IF NOT EXISTS un_number varchar(16);`,
);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE freight.contracts DROP COLUMN IF EXISTS un_number;`,
);
await queryRunner.query(
`ALTER TABLE freight.contracts DROP COLUMN IF EXISTS hazard_class;`,
);
}
}

42
apps/edr-freight-api/src/migrations/2970000000000-AddDoCollectionDates.ts Normal file
View File

@@ -0,0 +1,42 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Djibouti GL must record WHEN the vessel arrived and WHEN the Delivery Order
* was collected, not just attach the DO file. Both are mandatory on DO upload
* (enforced in the clearance services), so the columns are new and nullable —
* DOs uploaded before this change have no dates to backfill.
*
* `vessel_departure_date` is the EXPORT Release-Order date and stays as-is; the
* import arrival date gets its own column rather than overloading it.
*/
export class AddDoCollectionDates2970000000000 implements MigrationInterface {
name = 'AddDoCollectionDates2970000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
for (const table of [
'freight.contract_clearance_cycles',
'freight.bookings',
]) {
await queryRunner.query(
`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS vessel_arrival_date date;`,
);
await queryRunner.query(
`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS do_collected_date date;`,
);
}
}
public async down(queryRunner: QueryRunner): Promise<void> {
for (const table of [
'freight.contract_clearance_cycles',
'freight.bookings',
]) {
await queryRunner.query(
`ALTER TABLE ${table} DROP COLUMN IF EXISTS do_collected_date;`,
);
await queryRunner.query(
`ALTER TABLE ${table} DROP COLUMN IF EXISTS vessel_arrival_date;`,
);
}
}
}

26
apps/edr-freight-api/src/migrations/2980000000000-AddBookingRequestCurrency.ts Normal file
View File

@@ -0,0 +1,26 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Currency moved from the contract to the shipment: a contract now quotes in
* USD and the customer picks the billing currency per booking. On a customs
* contract GL books on the customer's behalf, so the shipment request is where
* the customer states the currency — GL reads it when creating the booking.
*
* Nullable: requests submitted before this change fall back to the contract's
* own currency, which is exactly what their bookings already used.
*/
export class AddBookingRequestCurrency2980000000000 implements MigrationInterface {
name = 'AddBookingRequestCurrency2980000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE freight.booking_requests ADD COLUMN IF NOT EXISTS payment_currency varchar(5);`,
);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE freight.booking_requests DROP COLUMN IF EXISTS payment_currency;`,
);
}
}

131
apps/edr-freight-api/src/migrations/2990000000000-IndodeYardsAndCargoRouting.ts Normal file
View File

@@ -0,0 +1,131 @@
import { MigrationInterface, QueryRunner } from "typeorm";
/**
* Indode's real 11-yard layout, plus the plumbing to auto-route a booking to
* the right yard by cargo type (and, for container yards, trade direction):
*
* - `warehouse_yards.direction` — IMPORT | EXPORT | BOTH | null. Only
* meaningful for CONTAINER_YARD, where import and export stacks are
* physically separate (Yard 5 vs Yard 6). Everything else takes cargo
* either way. A CONTAINER_YARD left at null/BOTH is a signal too: it means
* "not a customer cargo yard" — Yards 10/11 (service/equipment) are
* CONTAINER_YARD structurally but must never be offered for ordinary
* import/export cargo, so the frontend match requires an EXACT IMPORT/
* EXPORT direction hit for container freight rather than treating BOTH as
* a wildcard.
* - `warehouse_yard_cargo_types` — which cargo types a yard accepts (mirrors
* the existing `cargo_type_wagon_types` join table). Empty = open to any
* cargo type of the yard's structural type (additive, never restrictive
* by default), so this cannot break a yard nobody has configured yet.
*
* Three cargo types didn't exist yet (Fertilizer, Coffee, Tea) — added here
* so Yards 1 and 9 have a real mapping ready for when they reopen.
*/
export class IndodeYardsAndCargoRouting2990000000000 implements MigrationInterface {
name = "IndodeYardsAndCargoRouting2990000000000";
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.warehouse_yards
ADD COLUMN IF NOT EXISTS direction varchar(10)
`);
await queryRunner.query(`
CREATE TABLE IF NOT EXISTS freight.warehouse_yard_cargo_types (
yard_id uuid NOT NULL REFERENCES freight.warehouse_yards (id) ON DELETE CASCADE,
cargo_type_id uuid NOT NULL REFERENCES freight.cargo_types (id) ON DELETE CASCADE,
PRIMARY KEY (yard_id, cargo_type_id)
)
`);
// New cargo types Indode's yard list names but the catalog didn't have yet.
await queryRunner.query(`
INSERT INTO freight.cargo_types (code, cargo_type_name, unit_of_measure, is_active)
VALUES
('FERTILIZER', 'Fertilizer', 'PER_TON', true),
('COFFEE', 'Coffee', 'PER_TON', true),
('TEA', 'Tea', 'PER_TON', true)
ON CONFLICT (code) DO NOTHING
`);
// The 11 real yards at Indode Open Warehouse (code 'IOW').
await queryRunner.query(`
INSERT INTO freight.warehouse_yards
(warehouse_id, name, code, type, direction, status, is_active)
SELECT w.id, y.name, y.code, y.type, y.direction, y.status, y.status = 'ACTIVE'
FROM freight.warehouses w
CROSS JOIN (VALUES
('Y1', 'Bagged Cargo Discharge - Fertilizer', 'BULK_YARD', NULL, 'INACTIVE'),
('Y2', 'Break Bulk', 'GENERAL_CARGO_YARD', NULL, 'ACTIVE'),
('Y3', 'Ro-Ro / Pac', 'GENERAL_CARGO_YARD', NULL, 'ACTIVE'),
('Y4', 'Dry Bulk', 'BULK_YARD', NULL, 'INACTIVE'),
('Y5', 'Container Terminal - Import (Stack Area)', 'CONTAINER_YARD', 'IMPORT', 'ACTIVE'),
('Y6', 'Container Terminal - Export', 'CONTAINER_YARD', 'EXPORT', 'ACTIVE'),
('Y7', 'Cold Chain', 'COLD_STORAGE_YARD', NULL, 'INACTIVE'),
('Y8', 'Chemical', 'HAZARDOUS_YARD', NULL, 'INACTIVE'),
('Y9', 'Coffee and Tea', 'GENERAL_CARGO_YARD', NULL, 'INACTIVE'),
('Y10', 'Container Service Yard - Maintenance', 'CONTAINER_YARD', 'BOTH', 'ACTIVE'),
('Y11', 'Equipment (Empty Container)', 'CONTAINER_YARD', 'BOTH', 'ACTIVE')
) AS y(code, name, type, direction, status)
WHERE w.code = 'IOW'
ON CONFLICT (warehouse_id, code) DO NOTHING
`);
// One default zone per new yard, matching its yard's type — every existing
// yard (CY-1, CY-A) already follows this one-zone-per-yard shape.
await queryRunner.query(`
INSERT INTO freight.warehouse_zones (yard_id, name, code, type, status, is_active)
SELECT y.id, y.name || ' Zone 1', 'Z1',
CASE y.type
WHEN 'CONTAINER_YARD' THEN 'CONTAINER_ZONE'
WHEN 'COLD_STORAGE_YARD' THEN 'COLD_STORAGE_ZONE'
WHEN 'HAZARDOUS_YARD' THEN 'HAZARDOUS_ZONE'
WHEN 'BULK_YARD' THEN 'BULK_ZONE'
ELSE 'GENERAL_CARGO_ZONE'
END,
y.status, y.status = 'ACTIVE'
FROM freight.warehouse_yards y
JOIN freight.warehouses w ON w.id = y.warehouse_id
WHERE w.code = 'IOW' AND y.code LIKE 'Y%'
ON CONFLICT (yard_id, code) DO NOTHING
`);
// Cargo-type routing. Yards 5/6/10/11 (CONTAINER_YARD) are intentionally
// left with no rows — direction alone decides those, per the entity comment.
await queryRunner.query(`
INSERT INTO freight.warehouse_yard_cargo_types (yard_id, cargo_type_id)
SELECT y.id, ct.id
FROM freight.warehouses w
JOIN freight.warehouse_yards y ON y.warehouse_id = w.id
JOIN (VALUES
('Y1', 'FERTILIZER'),
('Y2', 'STEEL_BILLET'), ('Y2', 'PLASTIC_BARREL'), ('Y2', 'MACHINERY'), ('Y2', 'LIVESTOCK'),
('Y3', 'AUTOMOBILE'), ('Y3', 'TRUCK'),
('Y4', 'BARLY'), ('Y4', 'BEANS'), ('Y4', 'BULK'), ('Y4', 'CEREAL'),
('Y4', 'EDIBLE_OIL'), ('Y4', 'RICE'), ('Y4', 'SUGAR'), ('Y4', 'WHEAT'),
('Y7', 'PERISHABLE'),
('Y9', 'COFFEE'), ('Y9', 'TEA')
) AS m(yard_code, cargo_code) ON m.yard_code = y.code
JOIN freight.cargo_types ct ON ct.code = m.cargo_code
WHERE w.code = 'IOW'
ON CONFLICT (yard_id, cargo_type_id) DO NOTHING
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
DELETE FROM freight.warehouse_zones z
USING freight.warehouse_yards y, freight.warehouses w
WHERE z.yard_id = y.id AND y.warehouse_id = w.id
AND w.code = 'IOW' AND y.code LIKE 'Y%'
`);
await queryRunner.query(`
DELETE FROM freight.warehouse_yards y
USING freight.warehouses w
WHERE y.warehouse_id = w.id AND w.code = 'IOW' AND y.code LIKE 'Y%'
`);
// Cargo types and the join table are left in place — other data may have
// started referencing them since; dropping columns/tables is not reversible
// once real rows exist, and leaving them is harmless.
}
}

76
apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.spec.ts Normal file
View File

@@ -0,0 +1,76 @@
import { BookingLifecycleNotifierService } from './booking-lifecycle-notifier.service';
import type { Booking } from './entities/booking.entity';
/**
* Who hears "Operations wants changes" depends on who owns the booking. A
* customs (Path B) booking is created BY GL Ethiopia on the customer's behalf —
* the customer can neither edit nor resubmit it, so the note has to reach the GL
* who made it, not the portal.
*/
describe('BookingLifecycleNotifierService — operation changes requested', () => {
const booking = (over: Partial<Booking> = {}): Booking =>
({
id: 'b-1',
reference: 'BKG-0001',
companyId: 'co-1',
contractId: 'ctr-1',
createdByRole: 'CUSTOMER',
company: { email: 'customer@example.com' },
...over,
}) as Booking;
let notifications: { directSend: jest.Mock };
let inbox: { notify: jest.Mock };
let service: BookingLifecycleNotifierService;
const flush = () => new Promise((resolve) => setImmediate(resolve));
beforeEach(() => {
notifications = { directSend: jest.fn().mockResolvedValue(undefined) };
inbox = { notify: jest.fn().mockResolvedValue(undefined) };
service = new BookingLifecycleNotifierService(
notifications as never,
inbox as never,
{ query: jest.fn().mockResolvedValue([{ phone: '+251900000000' }]) } as never,
);
});
it('sends a GL-created booking back to the GL who created it, not the customer', async () => {
service.operationChangesRequested(
booking({ createdByRole: 'GL_ET', createdByUserId: 'gl-user-1' }),
'Cargo weight does not match the declaration',
);
await flush();
expect(inbox.notify).toHaveBeenCalledTimes(1);
const sent = inbox.notify.mock.calls[0][0];
expect(sent.recipients).toEqual({ userIds: ['gl-user-1'] });
expect(sent.audience).toBe('BACKOFFICE');
expect(sent.body).toContain('Cargo weight does not match the declaration');
// Deep-links the clearance page GL works from, not the portal booking.
expect(sent.link).toBe('/dashboard/contracts/clearance/ctr-1');
// The customer is not told to fix something they cannot touch.
expect(notifications.directSend).not.toHaveBeenCalled();
});
it('still tells the customer when the booking is their own', async () => {
service.operationChangesRequested(booking(), 'Please attach the packing list');
await flush();
const sent = inbox.notify.mock.calls[0][0];
expect(sent.recipients).toEqual({ companyId: 'co-1' });
expect(sent.audience).toBe('PORTAL');
expect(sent.link).toBe('/bookings/b-1');
expect(notifications.directSend).toHaveBeenCalled();
});
it('falls back to the customer when the GL creator is unknown (legacy rows)', async () => {
service.operationChangesRequested(
booking({ createdByRole: 'GL_ET', createdByUserId: null }),
'Fix the declaration',
);
await flush();
expect(inbox.notify.mock.calls[0][0].recipients).toEqual({ companyId: 'co-1' });
});
});

47
apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts
View File

@@ -179,8 +179,35 @@ export class BookingLifecycleNotifierService {
});
}
/** Operations returned the operation request for changes. */
/**
* Operations returned the operation request for changes.
*
* A customs (Path B) booking was created BY GL Ethiopia on the customer's
* behalf — the customer cannot edit or resubmit it, so telling them to "update
* from the portal" is a dead end. Those go to the GL who created it, linking
* the contract clearance page they work from. Everything else (customer-made
* bookings) keeps the portal message.
*/
operationChangesRequested(b: Booking, note: string): void {
if (b.createdByRole === 'GL_ET' && b.createdByUserId) {
const msg =
`Operations returned booking ${b.reference} for changes: ${note}. ` +
`Address it on the contract clearance page and resubmit to Operations.`;
this.logger.log(`OPERATION CHANGES REQUESTED (to GL) — ${this.ref(b)}`);
void this.inbox.notify({
recipients: { userIds: [b.createdByUserId] },
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.BOOKING_STATUS,
title: `Booking ${b.reference} needs changes`,
body: msg,
link: b.contractId
? `/dashboard/contracts/clearance/${b.contractId}`
: `/dashboard/bookings/${b.id}/clearance`,
data: { bookingId: b.id, reference: b.reference, note },
});
return;
}
const msg =
`Your operation request for booking ${b.reference} needs changes: ${note}. ` +
`Please update and resubmit from the portal.`;
@@ -197,6 +224,24 @@ export class BookingLifecycleNotifierService {
this.inApp(b, 'Operation request accepted', msg);
}
/**
* GL Ethiopia created this booking on the customer's behalf. On a customs
* (Path B) contract the customer never books themselves, so without this they
* would have no signal that their shipment now exists and is priced.
*/
createdByGlForCustomer(b: Booking): void {
const total = Number(b.totalAmount ?? 0);
const priced =
total > 0
? ` The total is ${total.toLocaleString()} ${b.paymentCurrency}.`
: '';
const msg =
`Global Logistics has created shipment ${b.reference} under your contract.${priced} ` +
`You can review it in the portal.`;
void this.notifyContact(b, msg, 'CREATED BY GL');
this.inApp(b, 'Shipment created for you', msg);
}
/** Shipment started → in transit. */
inTransit(b: Booking): void {
const msg = `Your shipment for booking ${b.reference} is now in transit.`;

244
apps/edr-freight-api/src/modules/bookings/booking-pricing.service.spec.ts
View File

@@ -473,3 +473,247 @@ describe('BookingPricingService — customs clearance fee billed on the booking
expect(result.lineItems.some((l) => l.code.startsWith('CUSTOMS_CLEARANCE'))).toBe(false);
});
});
/**
* Bulk freight bills in the commodity's own unit: tonnage for a weighed
* commodity (PER_TON), item count for a counted one (PER_ITEM). Both read the
* booking's cargo amount; PER_WAGON bills the wagons the cargo occupies.
*/
describe('BookingPricingService — bulk base freight units', () => {
const DJ = 'yard-dj-bulk';
const DIRE_B = 'yard-dire-bulk';
const bulkRate = (overrides: Partial<Rate> = {}): Rate =>
({
id: 'rate-bulk',
rateType: 'BULK_IMPORT',
appliesTo: 'BULK',
trigger: 'ALWAYS',
currency: 'USD',
rateValue: 200,
rateUnit: 'PER_ITEM',
status: 'LIVE',
containerTypeId: null,
cargoTypeId: null,
tradeDirection: 'IMPORT',
originYardId: DJ,
destinationYardId: DIRE_B,
...overrides,
}) as Rate;
const makeService = (liveRates: Rate[], wagonCapacity?: number) =>
new BookingPricingService(
{
calculateWagonCount: jest.fn().mockResolvedValue(0),
findContractRateSnapshots: jest.fn().mockResolvedValue([]),
} as never,
{
evaluate: jest.fn().mockResolvedValue({
priorityScore: 0,
appliedModifiers: [],
containerWeightResults: [],
warnings: [],
hardBlocked: [],
requiresDirectorApproval: false,
}),
} as never,
{ findById: jest.fn() } as never,
{ findLiveRates: jest.fn().mockResolvedValue(liveRates) } as never,
{ getRate: jest.fn().mockResolvedValue(MOCK_CBE_RATE) } as never,
{ validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
{
findById: jest.fn().mockResolvedValue({
wagonTypes: wagonCapacity !== undefined ? [{ capacityTons: wagonCapacity }] : [],
}),
} as never,
);
// 12 machines, not 12 tonnes — a PER_ITEM commodity records its count here.
const booking = (overrides: Record<string, unknown> = {}) =>
({
id: 'b-bulk',
freightType: 'BULK',
tradeDirection: 'IMPORT',
paymentCurrency: 'USD',
cargoTypeId: 'cargo-machinery',
cargoTotalWeightVgm: 12,
originYardId: DJ,
destinationYardId: DIRE_B,
bookingContainers: [],
...overrides,
}) as unknown as Booking;
it('bills a PER_ITEM rate on the item count', async () => {
const result = await makeService([bulkRate()]).computePriceForBooking(booking());
const line = result.lineItems.find((l) => l.code === 'BULK_IMPORT');
expect(line!.unit).toBe('PER_ITEM');
expect(line!.quantity).toBe(12);
expect(line!.amount).toBe(2400);
});
it('bills a PER_TON rate on the tonnage', async () => {
const result = await makeService([
bulkRate({ rateUnit: 'PER_TON', rateValue: 35 }),
]).computePriceForBooking(booking({ cargoTotalWeightVgm: 120 }));
const line = result.lineItems.find((l) => l.code === 'BULK_IMPORT');
expect(line!.unit).toBe('PER_TON');
expect(line!.amount).toBe(35 * 120);
});
it('bills a PER_WAGON rate on the wagons the cargo occupies, not zero', async () => {
const result = await makeService(
[bulkRate({ rateUnit: 'PER_WAGON', rateValue: 500 })],
60,
).computePriceForBooking(booking({ cargoTotalWeightVgm: 120 }));
const line = result.lineItems.find((l) => l.code === 'BULK_IMPORT');
expect(line!.unit).toBe('PER_WAGON');
expect(line!.quantity).toBe(2); // 120 t ÷ 60 t per wagon
expect(line!.amount).toBe(1000);
});
it('prices off the rate scoped to the booking commodity, not another one', async () => {
const result = await makeService([
bulkRate({ id: 'rate-wheat', cargoTypeId: 'cargo-wheat', rateUnit: 'PER_TON', rateValue: 35 }),
bulkRate({ id: 'rate-machinery', cargoTypeId: 'cargo-machinery', rateValue: 200 }),
]).computePriceForBooking(booking());
const line = result.lineItems.find((l) => l.code === 'BULK_IMPORT');
expect(line!.unit).toBe('PER_ITEM');
expect(line!.amount).toBe(2400);
});
it('hard-blocks when the leg only carries another commodity’s rate', async () => {
const result = await makeService([
bulkRate({ id: 'rate-wheat', cargoTypeId: 'cargo-wheat' }),
]).computePriceForBooking(booking());
expect(result.lineItems.some((l) => l.code === 'BULK_IMPORT')).toBe(false);
expect(result.hardBlocked.some((m) => m.includes('rate is configured'))).toBe(true);
});
});
/**
* A PER_WAGON container rate bills the wagons the LINE occupies — two 20ft share
* one wagon, a 40ft takes a whole one. Regression cases taken from real
* bookings on Doraleh → Gelan, where the 20ft line was being charged for the
* 40ft line's wagons as well.
*/
describe('BookingPricingService — PER_WAGON container freight', () => {
const DJ = 'yard-dj-w';
const ET = 'yard-et-w';
const perWagon20: Rate = {
id: 'rate-20-wagon',
rateType: 'CONTAINER_IMPORT',
currency: 'USD',
rateValue: 1690,
rateUnit: 'PER_WAGON',
status: 'LIVE',
containerTypeId: 'ct-20',
originYardId: DJ,
destinationYardId: ET,
} as Rate;
const perContainer40: Rate = {
...perWagon20,
id: 'rate-40-container',
rateValue: 1676,
rateUnit: 'PER_CONTAINER',
containerTypeId: 'ct-40',
} as Rate;
const makeService = () =>
new BookingPricingService(
{
// Booking-wide aggregate — deliberately larger than any single line, so
// a regression that reads it instead of the line's own wagons shows up.
calculateWagonCount: jest.fn().mockResolvedValue(5),
findContractRateSnapshots: jest.fn().mockResolvedValue([]),
} as never,
{
evaluate: jest.fn().mockResolvedValue({
priorityScore: 0,
appliedModifiers: [],
containerWeightResults: [],
warnings: [],
hardBlocked: [],
requiresDirectorApproval: false,
}),
} as never,
{
findById: jest.fn(async (id: string) => ({
id,
sizeFt: id === 'ct-40' ? 40 : 20,
isReefer: false,
code: id === 'ct-40' ? 'C40' : 'C20',
label: id === 'ct-40' ? 'C40' : 'C20',
})),
} as never,
{ findLiveRates: jest.fn().mockResolvedValue([perWagon20, perContainer40]) } as never,
{ getRate: jest.fn().mockResolvedValue(MOCK_CBE_RATE) } as never,
{ validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
{ findById: jest.fn() } as never,
);
const booking = (
lines: Array<{ containerTypeId: string; quantity: number }>,
) =>
({
id: 'b-wagon',
freightType: 'CONTAINER',
tradeDirection: 'IMPORT',
paymentCurrency: 'USD',
originYardId: DJ,
destinationYardId: ET,
bookingContainers: lines.map((l) => ({
containerTypeId: l.containerTypeId,
quantity: l.quantity,
vgmPerUnitTons: 10,
})),
}) as unknown as Booking;
const price = async (
lines: Array<{ containerTypeId: string; quantity: number }>,
) => {
const service = makeService();
const result = await service.computePriceForBooking(booking(lines));
return result.lineItems.filter((l) => l.code === 'CONTAINER_IMPORT');
};
it('bills 2× 20ft as one wagon', async () => {
const [line] = await price([{ containerTypeId: 'ct-20', quantity: 2 }]);
expect(line.unit).toBe('PER_WAGON');
expect(line.quantity).toBe(1);
expect(line.amount).toBe(1690);
});
it('bills 10× 20ft as five wagons', async () => {
const [line] = await price([{ containerTypeId: 'ct-20', quantity: 10 }]);
expect(line.quantity).toBe(5);
expect(line.amount).toBe(5 * 1690);
});
it('does not charge the 20ft line for the 40ft line’s wagons', async () => {
const lines = await price([
{ containerTypeId: 'ct-20', quantity: 4 },
{ containerTypeId: 'ct-40', quantity: 1 },
]);
const twenty = lines.find((l) => l.description.startsWith('C20'))!;
const forty = lines.find((l) => l.description.startsWith('C40'))!;
// 4× 20ft = 2 wagons, NOT the booking-wide 3.
expect(twenty.quantity).toBe(2);
expect(twenty.amount).toBe(2 * 1690);
// The 40ft line keeps billing per container.
expect(forty.quantity).toBe(1);
expect(forty.amount).toBe(1676);
});
it('rounds an odd 20ft count up to a whole wagon', async () => {
const [line] = await price([{ containerTypeId: 'ct-20', quantity: 5 }]);
expect(line.quantity).toBe(3);
expect(line.amount).toBe(3 * 1690);
});
});

135
apps/edr-freight-api/src/modules/bookings/booking-pricing.service.ts
View File

@@ -4,6 +4,7 @@ import { CargoTypesService } from '../rule-engine/services/cargo-types.service';
import { ContainerTypesService } from '../rule-engine/services/container-types.service';
import { RatesService } from '../rule-engine/services/rates.service';
import { Rate } from '../rule-engine/entities/rate.entity';
import { isBulkQuantityUnit } from '../rule-engine/entities/rate-unit.util';
import { ContractRateSnapshot } from '../contracts/entities/contract-rate-snapshot.entity';
import { ExchangeService } from '@edr/api-common';
import {
@@ -199,7 +200,7 @@ export class BookingPricingService {
// route's container freight, never a frozen OVERWEIGHT_PER_TON value.
const frozen = isDerived
? null
: this.frozenRateByCode(frozenRates, mod.surchargeCode, paymentCurrency);
: this.frozenRateByCode(frozenRates, mod.surchargeCode, paymentCurrency, usdToEtb);
const unitAmount = frozen
? Number(frozen.unitPrice)
: isEtbBooking
@@ -529,8 +530,6 @@ export class BookingPricingService {
const usedRatesMap = new Map<string, Rate>();
const warnings: string[] = [];
const blocked: string[] = [];
const wagonCount = await this.resolveWagonCount(booking);
for (const container of evalInput.containers) {
const rate = this.pickRate(
liveRates,
@@ -540,14 +539,15 @@ export class BookingPricingService {
booking.originYardId,
booking.destinationYardId,
);
// H15: frozen contract rate for this container size, when present — its
// unitPrice is already in the booking currency (no USD→currency convert).
// It also stands on its own: a contract line prices off the agreed rate
// even when nobody configured a live rate for this leg + type yet.
// H15: frozen contract rate for this container size, when present —
// converted into the booking currency by frozenRateForContainer. It also
// stands on its own: a contract line prices off the agreed rate even when
// nobody configured a live rate for this leg + type yet.
const frozen = await this.frozenRateForContainer(
frozenRates,
container.containerTypeId,
paymentCurrency,
usdToEtb,
);
const label = await this.containerTypeLabel(container.containerTypeId);
if (!rate && !frozen) {
@@ -565,6 +565,10 @@ export class BookingPricingService {
}
const rateUnit = rate?.rateUnit ?? 'PER_CONTAINER';
// A PER_WAGON line bills the wagons THIS line occupies (two 20ft share
// one), never the booking-wide count — otherwise a booking with a 20ft
// and a 40ft line charges each line for the other's wagons too.
const lineWagons = await this.lineWagonCount(container);
let amount: number;
let unitAmount: number;
if (frozen) {
@@ -573,11 +577,11 @@ export class BookingPricingService {
rateUnit,
unitAmount,
container.quantity,
wagonCount,
lineWagons,
);
} else {
const unitUsd = Number(rate!.rateValue);
const usdAmount = this.amountForRate(rate!, container.quantity, wagonCount);
const usdAmount = this.amountForRate(rate!, container.quantity, lineWagons);
amount = isEtbBooking ? Math.round(usdAmount * usdToEtb) : usdAmount;
unitAmount = isEtbBooking ? Math.round(unitUsd * usdToEtb) : unitUsd;
}
@@ -588,7 +592,7 @@ export class BookingPricingService {
amount,
unitAmount,
unit: rateUnit,
quantity: this.effectiveUnitQuantity(rateUnit, container.quantity, wagonCount),
quantity: this.effectiveUnitQuantity(rateUnit, container.quantity, lineWagons),
currency: paymentCurrency,
});
}
@@ -600,7 +604,10 @@ export class BookingPricingService {
// container type above or stay unpriced with a warning — falling back to
// a corridor rate of a DIFFERENT container type billed once (qty 1) is
// how a 38-container booking was invoiced 40 USD instead of 1900.
const fallback = liveRates.find(
// Within the leg, the rate scoped to the booking's own commodity wins over
// the commodity-wide catch-all — a per-item machinery rate must never
// price a per-ton wheat booking (or the reverse).
const onLeg = liveRates.filter(
(r) =>
r.rateType === rateType &&
r.currency === 'USD' &&
@@ -608,15 +615,29 @@ export class BookingPricingService {
r.originYardId === booking.originYardId &&
r.destinationYardId === booking.destinationYardId,
);
const fallback =
(booking.cargoTypeId
? onLeg.find((r) => r.cargoTypeId === booking.cargoTypeId)
: undefined) ?? onLeg.find((r) => !r.cargoTypeId);
if (fallback) {
usedRatesMap.set(fallback.id, fallback);
const bulkTons = Number(booking.cargoTotalWeightVgm ?? 0);
// Bulk has no container lines to count wagons from, so a PER_WAGON bulk
// rate bills the tonnage-derived estimate for the WHOLE booking (there
// is only ever this one line).
const wagonCount = isBulk
? Number(evalInput.bulkWagons ?? 0) ||
(await this.bulkWagonCount(booking)) ||
0
: await this.resolveWagonCount(booking);
// Bulk quantity is stored in the commodity's own unit — tonnes for a
// PER_TON commodity, item count for a PER_ITEM one.
const bulkQuantity = Number(booking.cargoTotalWeightVgm ?? 0);
const quantity =
isBulk && fallback.rateUnit === 'PER_TON' ? Math.max(bulkTons, 0) : 1;
isBulk && isBulkQuantityUnit(fallback.rateUnit) ? Math.max(bulkQuantity, 0) : 1;
const unitUsd = Number(fallback.rateValue);
// H15: bulk freight uses the frozen BULK_FREIGHT snapshot when present.
const frozen = isBulk
? this.frozenRateByCode(frozenRates, 'BULK_FREIGHT', paymentCurrency)
? this.frozenRateByCode(frozenRates, 'BULK_FREIGHT', paymentCurrency, usdToEtb)
: null;
let amount: number;
let unitAmount: number;
@@ -719,6 +740,7 @@ export class BookingPricingService {
quantity = containerCount;
break;
case 'PER_TON':
case 'PER_ITEM':
quantity = bulkTons;
break;
case 'FLAT':
@@ -727,12 +749,13 @@ export class BookingPricingService {
break;
}
// H15: frozen mile rate (already in booking currency) when the contract
// has one; else the live USD rate converted as before.
// H15: frozen mile rate (converted into the booking currency) when the
// contract has one; else the live USD rate converted as before.
const frozen = this.frozenRateByCode(
frozenRates,
leg.rateType,
paymentCurrency,
usdToEtb,
);
let amount: number;
let unitAmount: number;
@@ -764,6 +787,34 @@ export class BookingPricingService {
return { lineItems: lines, usedRates: [...usedRatesMap.values()] };
}
/**
* Wagons ONE container line occupies: two 20ft share a wagon, a 40ft takes a
* whole one. This — not the booking-wide total — is what a PER_WAGON base
* freight line bills, so a booking of 4×20ft + 1×40ft charges the 20ft line
* for 2 wagons and the 40ft line for its own 1, instead of billing each line
* for all 3.
*/
private async lineWagonCount(container: {
containerTypeId: string;
quantity: number;
wagonsPerUnit?: number;
}): Promise<number> {
let perUnit = container.wagonsPerUnit;
if (perUnit == null) {
// Preview bookings build their eval input without the fraction — read it
// off the container type instead of assuming one wagon per box.
try {
const ct = await this.containerTypesService.findById(
container.containerTypeId,
);
perUnit = wagonsPerUnitForSize(Number(ct.sizeFt));
} catch {
perUnit = 1; // unknown type: never under-bill
}
}
return Math.max(1, Math.ceil(container.quantity * perUnit));
}
/**
* Wagon count for PER_WAGON rates. A persisted booking uses the SQL aggregate;
* an unsaved preview booking (no id) sums the wagonsRequired already computed
@@ -804,6 +855,7 @@ export class BookingPricingService {
return 1;
case 'PER_CONTAINER':
case 'PER_TON':
case 'PER_ITEM':
default:
return quantity;
}
@@ -860,6 +912,7 @@ export class BookingPricingService {
case 'PER_WAGON':
return unitValue * wagonCount;
case 'PER_TON':
case 'PER_ITEM':
return unitValue * quantity;
case 'FLAT':
return unitValue;
@@ -889,20 +942,45 @@ export class BookingPricingService {
}
/**
* The frozen snapshot for a rate code, or null when there is none, its price
* is negative, or it is in a different currency than the booking (in which
* case the live-rate path is safer than a mis-converted frozen price).
* The frozen snapshot for a rate code, expressed in the BOOKING's currency.
*
* A contract quotes in USD and freezes USD unit prices; the customer chooses
* the billing currency per booking. So a currency mismatch is the normal case
* now, not an error — the snapshot is converted rather than discarded. (It
* previously returned null on mismatch, which silently dropped the agreed
* contract price and re-priced the booking at whatever the live rate had
* drifted to.) Grandfathered ETB contracts convert the other way for the same
* reason.
*
* Returns null only when there is no snapshot or its price is unusable.
*/
private frozenRateByCode(
frozenRates: Map<string, ContractRateSnapshot> | null,
code: string,
bookingCurrency: string,
usdToEtb: number,
): ContractRateSnapshot | null {
const snap = frozenRates?.get(code);
if (!snap) return null;
if (snap.currency !== bookingCurrency) return null;
if (!(Number(snap.unitPrice) >= 0)) return null;
return snap;
const unitPrice = Number(snap.unitPrice);
if (!(unitPrice >= 0)) return null;
if (snap.currency === bookingCurrency) return snap;
// Only USD <-> ETB exist; a rate of 0/NaN would silently zero the price.
if (!(usdToEtb > 0)) return null;
const converted =
snap.currency === 'USD' && bookingCurrency === 'ETB'
? Math.round(unitPrice * usdToEtb)
: snap.currency === 'ETB' && bookingCurrency === 'USD'
? unitPrice / usdToEtb
: null;
if (converted == null) return null;
// A copy — the snapshot rows are shared across the pricing pass.
return Object.assign(Object.create(Object.getPrototypeOf(snap)), snap, {
unitPrice: converted,
currency: bookingCurrency,
}) as ContractRateSnapshot;
}
/**
@@ -914,6 +992,7 @@ export class BookingPricingService {
frozenRates: Map<string, ContractRateSnapshot> | null,
containerTypeId: string,
bookingCurrency: string,
usdToEtb: number,
): Promise<ContractRateSnapshot | null> {
if (!frozenRates) return null;
let sizeFt: number | null = null;
@@ -923,7 +1002,7 @@ export class BookingPricingService {
return null;
}
if (!sizeFt) return null;
return this.frozenRateByCode(frozenRates, `CONTAINER_${sizeFt}FT`, bookingCurrency);
return this.frozenRateByCode(frozenRates, `CONTAINER_${sizeFt}FT`, bookingCurrency, usdToEtb);
}
/**
@@ -966,7 +1045,7 @@ export class BookingPricingService {
const hasPerSizeSnapshot =
frozenRates?.has('CUSTOMS_CLEARANCE_20FT') ||
frozenRates?.has('CUSTOMS_CLEARANCE_40FT');
const legacyFlat = this.frozenRateByCode(frozenRates, 'CUSTOMS_CLEARANCE', currency);
const legacyFlat = this.frozenRateByCode(frozenRates, 'CUSTOMS_CLEARANCE', currency, usdToEtb);
if (legacyFlat && !hasPerSizeSnapshot) {
const amount = Number(legacyFlat.unitPrice);
if (amount > 0) {
@@ -995,7 +1074,7 @@ export class BookingPricingService {
// unknown type — falls through to the live per-type lookup below
}
const frozen = sizeFt
? this.frozenRateByCode(frozenRates, `CUSTOMS_CLEARANCE_${sizeFt}FT`, currency)
? this.frozenRateByCode(frozenRates, `CUSTOMS_CLEARANCE_${sizeFt}FT`, currency, usdToEtb)
: null;
const live = onLeg.find((r) => r.containerTypeId === bc.containerTypeId);
if (!frozen && !live) {
@@ -1030,7 +1109,7 @@ export class BookingPricingService {
// flat snapshot share the CUSTOMS_CLEARANCE code; both are the agreed fee.
// Live lookup: the rate scoped to the booking's commodity wins; a
// commodity-less rate (legacy) is the catch-all fallback.
const frozen = this.frozenRateByCode(frozenRates, 'CUSTOMS_CLEARANCE', currency);
const frozen = this.frozenRateByCode(frozenRates, 'CUSTOMS_CLEARANCE', currency, usdToEtb);
const live =
(booking.cargoTypeId
? onLeg.find(
@@ -1044,7 +1123,7 @@ export class BookingPricingService {
const unit = frozen ? this.rateUnitFromSnapshot(frozen.unitOfMeasure) : live!.rateUnit;
const unitAmount = frozen ? Number(frozen.unitPrice) : convert(Number(live!.rateValue));
let billedQty = 1;
if (unit === 'PER_TON') {
if (isBulkQuantityUnit(unit)) {
billedQty = Math.max(0, Number(booking.cargoTotalWeightVgm ?? 0));
} else if (unit === 'PER_WAGON') {
const wagons = await this.bulkWagonCount(booking);
@@ -1081,6 +1160,8 @@ export class BookingPricingService {
return 'PER_WAGON';
case 'per_ton':
return 'PER_TON';
case 'per_item':
return 'PER_ITEM';
case 'per_container':
return 'PER_CONTAINER';
default:

93
apps/edr-freight-api/src/modules/bookings/booking-reference-data.service.ts
View File

@@ -33,41 +33,86 @@ import {
BookingReferenceYardDto,
} from "./dto/booking-reference-data.dto";
/**
* Reference cargo tree: top-level groups, each carrying its selectable
* commodities.
*
* `cargo_types` is an arbitrary-depth tree (Bulk → Steel Billet → S1 → …), but
* only a LEAF is a real commodity — an intermediate node is a container for
* finer types, and booking against it would be ambiguous. So each group's
* `children` are all of its leaf descendants, flattened, whatever the depth.
* Deep leaves carry their path below the group ("Steel Billet → S1") so a
* generically-named leaf still reads unambiguously in a dropdown.
*
* A group with no active descendants is its own leaf and is emitted as its
* single child — otherwise it is selectable as a group but offers no commodity,
* which dead-ends every form that requires one.
*/
export function buildCargoTypeTree(
rows: CargoType[],
): BookingReferenceCargoTypeGroupDto[] {
const active = rows.filter((r) => r.isActive);
const parents = active
.filter((r) => !r.parentGroupId)
.sort(
(a, b) => a.displayOrder - b.displayOrder || a.code.localeCompare(b.code),
);
const byOrder = (a: CargoType, b: CargoType) =>
a.displayOrder - b.displayOrder || a.code.localeCompare(b.code);
const childrenOf = new Map<string, CargoType[]>();
for (const row of active) {
if (!row.parentGroupId) continue;
const siblings = childrenOf.get(row.parentGroupId) ?? [];
siblings.push(row);
childrenOf.set(row.parentGroupId, siblings);
}
for (const siblings of childrenOf.values()) siblings.sort(byOrder);
const parents = active.filter((r) => !r.parentGroupId).sort(byOrder);
/** Depth-first leaf walk; `trail` is the path below the group. */
const collectLeaves = (
node: CargoType,
trail: string[],
seen: Set<string>,
): BookingReferenceCargoTypeChildDto[] => {
// Admin-entered parent pointers could in principle cycle — never loop.
if (seen.has(node.id)) return [];
seen.add(node.id);
const kids = childrenOf.get(node.id) ?? [];
if (kids.length === 0) {
return [
{
id: node.id,
name: [...trail, node.cargoTypeName].join(" → "),
code: node.code,
unit_of_measure: node.unitOfMeasure ?? null,
},
];
}
const nextTrail = [...trail, node.cargoTypeName];
return kids.flatMap((kid) => collectLeaves(kid, nextTrail, seen));
};
return parents.map((parent) => {
const children = active
.filter((r) => r.parentGroupId === parent.id)
.sort(
(a, b) =>
a.displayOrder - b.displayOrder || a.code.localeCompare(b.code),
)
.map(
(child): BookingReferenceCargoTypeChildDto => ({
id: child.id,
name: child.cargoTypeName,
code: child.code,
unit_of_measure: child.unitOfMeasure ?? null,
}),
);
const kids = childrenOf.get(parent.id) ?? [];
const children =
kids.length === 0
? // The group itself is the commodity.
[
{
id: parent.id,
name: parent.cargoTypeName,
code: parent.code,
unit_of_measure: parent.unitOfMeasure ?? null,
},
]
: kids.flatMap((kid) => collectLeaves(kid, [], new Set<string>()));
const group: BookingReferenceCargoTypeGroupDto = {
return {
id: parent.id,
name: parent.cargoTypeName,
code: parent.code,
children,
};
if (children.length > 0) {
group.children = children;
}
return group;
});
}

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

@@ -916,14 +916,15 @@ export class BookingsController {
async uploadBookingDeliveryOrder(
@Param('id', ParseUUIDPipe) id: string,
@UploadedFile() file: Express.Multer.File,
@Body('vesselDepartureDate') vesselDepartureDate: string | undefined,
@Body('vesselArrivalDate') vesselArrivalDate: string | undefined,
@Body('doCollectedDate') doCollectedDate: string | undefined,
@CurrentUser() user: TCurrentUser,
) {
const booking = await this.bookingClearanceService.uploadDeliveryOrder(
id,
file,
resolveAuthUserId(user),
vesselDepartureDate,
{ vesselArrivalDate, doCollectedDate },
);
return this.transitionService.enrichBookingResponse(booking);
}

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

@@ -123,7 +123,9 @@ export class BookingsRepository extends BaseRepository<Booking> {
'booking.files',
FileRecord,
'file',
"file.resource_id = booking.id AND file.resource = 'bookings'",
// Superseded versions are soft-deleted, not dropped — keep them out of
// the live file list (a manual join condition is not filtered for us).
"file.resource_id = booking.id AND file.resource = 'bookings' AND file.deleted_at IS NULL",
)
.getOne();

72
apps/edr-freight-api/src/modules/bookings/cargo-type-tree.spec.ts Normal file
View File

@@ -0,0 +1,72 @@
import { buildCargoTypeTree } from './booking-reference-data.service';
import type { CargoType } from '../rule-engine/entities/cargo-type.entity';
const node = (
id: string,
name: string,
parentGroupId: string | null,
isActive = true,
): CargoType =>
({
id,
cargoTypeName: name,
code: name.toUpperCase().replace(/\s+/g, '_'),
parentGroupId,
displayOrder: 0,
isActive,
unitOfMeasure: 'PER_TON',
}) as unknown as CargoType;
describe('buildCargoTypeTree', () => {
// Bulk ──┬─ Wheat (leaf, depth 2)
// └─ Steel Billet ──┬─ S1 (leaf, depth 3)
// └─ S2 ─ S2a (leaf, depth 4)
const rows = [
node('bulk', 'Bulk', null),
node('wheat', 'Wheat', 'bulk'),
node('steel', 'Steel Billet', 'bulk'),
node('s1', 'S1', 'steel'),
node('s2', 'S2', 'steel'),
node('s2a', 'S2a', 's2'),
node('general', 'General Cargo', null),
];
it('offers only leaves as commodities, at any depth', () => {
const [bulk] = buildCargoTypeTree(rows);
// Leaves stay grouped under their branch (siblings ordered by
// displayOrder then code — STEEL_BILLET before WHEAT here).
expect(bulk.children?.map((c) => c.id)).toEqual(['s1', 's2a', 'wheat']);
// "Steel Billet" is a container for finer types, never bookable itself.
expect(bulk.children?.some((c) => c.id === 'steel')).toBe(false);
});
it('labels deep leaves with their path below the group', () => {
const [bulk] = buildCargoTypeTree(rows);
const byId = new Map(bulk.children?.map((c) => [c.id, c.name]));
expect(byId.get('wheat')).toBe('Wheat');
expect(byId.get('s1')).toBe('Steel Billet → S1');
expect(byId.get('s2a')).toBe('Steel Billet → S2 → S2a');
});
it('emits a childless group as its own commodity', () => {
const general = buildCargoTypeTree(rows).find((g) => g.id === 'general');
expect(general?.children).toEqual([
expect.objectContaining({ id: 'general', name: 'General Cargo' }),
]);
});
it('skips inactive nodes and their descendants', () => {
const withRetired = [
...rows,
node('retired', 'Retired', 'bulk', false),
node('retiredKid', 'Retired Kid', 'retired', false),
];
const [bulk] = buildCargoTypeTree(withRetired);
expect(bulk.children?.map((c) => c.id)).not.toContain('retired');
expect(bulk.children?.map((c) => c.id)).not.toContain('retiredKid');
});
});

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

@@ -302,6 +302,20 @@ export class Booking extends BaseEntity {
@Column({ name: 'customer_truck_arrived_at', type: 'timestamptz', nullable: true })
customerTruckArrivedAt?: Date | null;
/**
* Did the goods need re-handling in the warehouse? Recorded by warehouse
* staff after unloading. Only `true` bills the DOUBLE_HANDLING_FEE rule;
* null = not yet decided (no charge).
*/
@Column({ name: 'double_handling', type: 'boolean', nullable: true })
doubleHandling?: boolean | null;
@Column({ name: 'double_handling_set_at', type: 'timestamptz', nullable: true })
doubleHandlingSetAt?: Date | null;
@Column({ name: 'double_handling_set_by', type: 'varchar', length: 160, nullable: true })
doubleHandlingSetBy?: string | null;
@Column({ name: 'customs_clearing_enabled', type: 'boolean', default: false })
customsClearingEnabled!: boolean;
@@ -526,6 +540,14 @@ export class Booking extends BaseEntity {
@Column({ name: 'vessel_departure_date', type: 'date', nullable: true })
vesselDepartureDate?: string | null;
/** Import DO: when the vessel arrived in Djibouti. Required on DO upload. */
@Column({ name: 'vessel_arrival_date', type: 'date', nullable: true })
vesselArrivalDate?: string | null;
/** Import DO: when GL Djibouti collected the DO. Required on DO upload. */
@Column({ name: 'do_collected_date', type: 'date', nullable: true })
doCollectedDate?: string | null;
@Column({ name: 'ro_amendment_requested_at', type: 'timestamptz', nullable: true })
roAmendmentRequestedAt?: Date | null;

29
apps/edr-freight-api/src/modules/companies/companies.service.ts
View File

@@ -5,7 +5,7 @@ import {
BadRequestException,
ForbiddenException,
} from "@nestjs/common";
import { DataSource } from "typeorm";
import { DataSource, EntityManager } from "typeorm";
import { CompaniesRepository } from "./companies.repository";
import { CompanyProfileRepository } from "./company-profile.repository";
import { CompanyChangeRequestRepository } from "./company-change-request.repository";
@@ -1111,9 +1111,11 @@ export class CompaniesService {
}
// Anything other than approval has no document gate and no concurrency
// hazard — apply it directly.
// hazard — no row lock, just the write.
if (status !== ProfileStatus.Active) {
return this.applyProfileStatus(existing, status, note, reviewerId);
return this.dataSource.transaction((manager) =>
this.applyProfileStatus(manager, existing, status, note, reviewerId),
);
}
// Approving over an outstanding document correction would silently accept the
@@ -1149,7 +1151,7 @@ export class CompaniesService {
);
}
return this.applyProfileStatus(existing, status, note, reviewerId);
return this.applyProfileStatus(manager, existing, status, note, reviewerId);
});
}
@@ -1160,11 +1162,21 @@ export class CompaniesService {
* transaction while every other status skips that overhead.
*/
private async applyProfileStatus(
manager: EntityManager,
existing: CompanyProfile,
status: ProfileStatus,
note?: string,
reviewerId?: string,
): Promise<CompanyProfile> {
// Every write below goes through `manager`. The approval path holds a
// pessimistic_write lock on the company row, and the injected repositories
// are bound to the DataSource's default pool — writing the same row through
// one of them would block on a lock this very transaction holds, hanging the
// request until the statement timed out. That deadlocked the first approval
// of any customer: the profile went Active on its own connection while the
// company stayed Pending and the caller never got a response.
const profileRepo = manager.getRepository(CompanyProfile);
const companyRepo = manager.getRepository(Company);
// A reference number is only minted the first time a profile is approved
// (status → Active). Pending/unapproved profiles carry no reference.
const patch: Partial<CompanyProfile> = { status };
@@ -1190,7 +1202,8 @@ export class CompaniesService {
patch.reviewedAt = new Date();
}
const updated = await this.companyProfilesRepo.update(existing.id, patch);
await profileRepo.update(existing.id, patch);
const updated = await profileRepo.findOne({ where: { id: existing.id } });
if (!updated)
throw new NotFoundException(`Company profile ${existing.id} not found`);
@@ -1208,7 +1221,9 @@ export class CompaniesService {
: "approved"
: null;
if (change) {
const company = await this.companiesRepo.findById(updated.companyId);
const company = await companyRepo.findOne({
where: { id: updated.companyId },
});
if (company) {
this.companyNotifier.profileStatusChanged(
company,
@@ -1222,7 +1237,7 @@ export class CompaniesService {
status === ProfileStatus.Active &&
company.status === CompanyStatus.Pending
) {
await this.companiesRepo.update(updated.companyId, {
await companyRepo.update(updated.companyId, {
status: CompanyStatus.Active,
});
this.companyNotifier.companyApproved(company);

19
apps/edr-freight-api/src/modules/contracts/booking-clearance.service.ts
View File

@@ -19,6 +19,7 @@ import {
} from './entities/clearance-milestone.entity';
import { Booking } from '../bookings/entities/booking.entity';
import { clearanceCodesForBooking } from '../bookings/clearance.util';
import { assertDoCollectionDates } from './contract-clearance.util';
import { ClearanceWorkflowService } from './clearance-workflow.service';
import { ClearanceMilestoneService } from './clearance-milestone.service';
import { GlOperationsService } from './gl-operations.service';
@@ -64,6 +65,9 @@ export interface BookingClearanceView {
roHold?: boolean;
roHoldReason?: string | null;
vesselDepartureDate?: string | null;
/** Import DO dates recorded by GL Djibouti on upload. */
vesselArrivalDate?: string | null;
doCollectedDate?: string | null;
roAmendmentRequestedAt?: string | null;
operationReady?: boolean;
preClearanceFinalized?: boolean;
@@ -261,6 +265,8 @@ export class BookingClearanceService {
roHold: Boolean(booking.roHoldReason),
roHoldReason: booking.roHoldReason ?? null,
vesselDepartureDate: booking.vesselDepartureDate ?? null,
vesselArrivalDate: booking.vesselArrivalDate ?? null,
doCollectedDate: booking.doCollectedDate ?? null,
roAmendmentRequestedAt: booking.roAmendmentRequestedAt
? booking.roAmendmentRequestedAt.toISOString()
: null,
@@ -547,7 +553,7 @@ export class BookingClearanceService {
bookingId: string,
file: Express.Multer.File,
userId?: string,
vesselDepartureDate?: string,
dates?: { vesselArrivalDate?: string; doCollectedDate?: string },
): Promise<Booking> {
const booking = await this.loadBooking(bookingId);
if (booking.tradeDirection !== 'IMPORT') {
@@ -556,6 +562,8 @@ export class BookingClearanceService {
if (!file) throw new BadRequestException('No Delivery Order uploaded');
const { vesselArrivalDate, doCollectedDate } = assertDoCollectionDates(dates);
// DO upload is deliberately un-gated: GL Djibouti may attach it at any point,
// any file type. The DO_COLLECTED milestone (and operation readiness) still
// waits for GL Ethiopia to finalize pre-clearance so the workflow order holds.
@@ -566,11 +574,10 @@ export class BookingClearanceService {
file,
});
if (vesselDepartureDate?.trim()) {
await this.bookingsRepository.update(bookingId, {
vesselDepartureDate: vesselDepartureDate.trim(),
} as never);
}
await this.bookingsRepository.update(bookingId, {
vesselArrivalDate,
doCollectedDate,
} as never);
if (booking.preClearanceFinalizedAt) {
await this.workflowService.completeMilestoneForBooking(bookingId, 'DO_COLLECTED', userId);

17
apps/edr-freight-api/src/modules/contracts/booking-request.service.ts
View File

@@ -30,7 +30,11 @@ export class BookingRequestService {
private readonly notifier: ContractNotifierService,
) {}
/** Only GENERAL contracts that bundle customs use the request → GL → clearance flow. */
/**
* Only GENERAL contracts that bundle customs use the request → GL → clearance
* flow. A ONE_TIME customs contract runs its clearance at the contract level
* and GL books it directly, with no customer-facing request step.
*/
private assertGeneralCustoms(contract: Contract): void {
if (
contract.contractKind !== 'GENERAL' ||
@@ -121,7 +125,11 @@ export class BookingRequestService {
// instance is created first so a failure leaves no half-linked request.
const booking = await this.contractBookingService.initiateForShipmentRequest(
contract,
{ contractRouteId: dto.contractRouteId, userId },
{
contractRouteId: dto.contractRouteId,
userId,
paymentCurrency: dto.paymentCurrency,
},
);
const reference = await this.generateReference();
@@ -134,6 +142,11 @@ export class BookingRequestService {
status: 'ACCEPTED',
createdBookingId: booking.id,
requestedLines,
// Intercity is invoiced in birr whatever the customer picked.
paymentCurrency:
contract.tradeDirection === 'DOMESTIC'
? 'ETB'
: (dto.paymentCurrency ?? contract.paymentCurrency ?? 'USD'),
notes: dto.notes ?? null,
} as never);
this.notifier.shipmentRequestedToStaff(contract, request.id, request.reference);

5
apps/edr-freight-api/src/modules/contracts/contract-booking.consolidation.spec.ts
View File

@@ -57,7 +57,10 @@ describe('ContractBookingService — drawdown consolidation gate', () => {
milestoneService as never,
{} as never, // workflowService
invoiceService as never,
{ createdToStaff: jest.fn() } as never, // bookingNotifier
{
createdToStaff: jest.fn(),
createdByGlForCustomer: jest.fn(),
} as never, // bookingNotifier
{} as never, // dataSource
{} as never, // trainSchedulingService
{} as never, // bookingBatchService

66
apps/edr-freight-api/src/modules/contracts/contract-booking.service.ts
View File

@@ -277,7 +277,7 @@ export class ContractBookingService {
createdByUserId: user?.id ?? null,
scheduledDate: dto.scheduledDate ? new Date(dto.scheduledDate) : null,
serviceTypeId: contract.serviceTypeId,
paymentCurrency: contract.paymentCurrency,
paymentCurrency: this.resolveShipmentCurrency(contract, dto.paymentCurrency),
contractType: 'NEW',
customsClearingEnabled: contract.customsClearingEnabled,
customsClearingAgent: contract.customsClearingAgent ?? null,
@@ -481,7 +481,7 @@ export class ContractBookingService {
createdByUserId: user?.id ?? null,
scheduledDate: null,
serviceTypeId: contract.serviceTypeId,
paymentCurrency: contract.paymentCurrency,
paymentCurrency: this.resolveShipmentCurrency(contract, null),
contractType: 'NEW',
customsClearingEnabled: contract.customsClearingEnabled,
customsClearingAgent: contract.customsClearingAgent ?? null,
@@ -520,7 +520,12 @@ export class ContractBookingService {
*/
async initiateForShipmentRequest(
contract: Contract,
opts: { contractRouteId?: string; userId?: string | null },
opts: {
contractRouteId?: string;
userId?: string | null;
/** Billing currency the customer chose on the shipment request. */
paymentCurrency?: string | null;
},
): Promise<Booking> {
const generalCustoms =
contract.contractKind === 'GENERAL' && Boolean(contract.customsClearingEnabled);
@@ -555,7 +560,7 @@ export class ContractBookingService {
createdByUserId: opts.userId ?? null,
scheduledDate: null,
serviceTypeId: contract.serviceTypeId,
paymentCurrency: contract.paymentCurrency,
paymentCurrency: this.resolveShipmentCurrency(contract, opts?.paymentCurrency),
contractType: 'NEW',
customsClearingEnabled: contract.customsClearingEnabled,
customsClearingAgent: contract.customsClearingAgent ?? null,
@@ -733,6 +738,13 @@ export class ContractBookingService {
cargoFreeText: dto.cargoFreeText?.trim() || null,
cargoTotalWeightVgm: this.resolveBulkTons(dto),
equipmentReturn: this.resolveShipmentEquipmentReturn(contract, dto),
// Completion is where the cargo — and therefore the price — is fixed, so
// it is also where the billing currency is chosen. A bare instance was
// created before the customer had any figure to look at.
paymentCurrency: this.resolveShipmentCurrency(
contract,
dto.paymentCurrency ?? booking.paymentCurrency,
),
} as never);
const loaded = await this.bookingsRepository.findByIdWithFiles(booking.id);
@@ -921,6 +933,33 @@ export class ContractBookingService {
}`,
),
);
// On a customs contract the customer never books — GL Ethiopia does it for
// them (assertGate enforces that) — so tell them their shipment now exists.
//
// Gated on the contract, NOT on booking.createdByRole: a GENERAL customs
// instance is stamped CUSTOMER when the customer's shipment request opens
// it, yet it is GL who later completes it with cargo and a price. Keying on
// the role would silently skip exactly that case.
//
// Sent from here because this is the single funnel every contract booking
// passes through exactly once (create, complete, and the deferred
// consolidation-pairing replay), and it runs after invoicing so the message
// can quote the priced total.
if (contract.customsClearingEnabled) {
// Never let a notification failure read as a finalize failure — the
// booking is already committed by this point.
try {
const priced = await this.bookingsRepository.findByIdWithFiles(bookingId);
this.bookingNotifier.createdByGlForCustomer(priced ?? booking);
} catch (err) {
this.logger.warn(
`Could not notify the customer that GL created booking ${booking.reference}: ${
err instanceof Error ? err.message : String(err)
}`,
);
}
}
}
/**
@@ -1565,6 +1604,23 @@ export class ContractBookingService {
* booking-level override (dto.equipmentReturn ?? contract default) applies.
* Bulk freight keeps the legacy behaviour untouched.
*/
/**
* The billing currency for a shipment under this contract.
*
* A contract quotes in USD only — the currency is a per-shipment choice now.
* Precedence: intercity is always ETB (domestic transport is invoiced in
* birr), then the customer's explicit choice, then the contract's own
* currency, which is USD for contracts created under the current rule and the
* grandfathered value for older ones.
*/
private resolveShipmentCurrency(
contract: Contract,
requested?: string | null,
): string {
if (contract.tradeDirection === 'DOMESTIC') return 'ETB';
return requested?.trim() || contract.paymentCurrency || 'USD';
}
private resolveShipmentEquipmentReturn(
contract: Contract,
dto: CreateBookingUnderContractDto,
@@ -1795,7 +1851,7 @@ export class ContractBookingService {
contractId: contract.id,
freightType: contract.freightType,
tradeDirection: contract.tradeDirection,
paymentCurrency: contract.paymentCurrency,
paymentCurrency: this.resolveShipmentCurrency(contract, dto.paymentCurrency),
serviceTypeId: contract.serviceTypeId,
cargoTypeId: this.resolveCargoTypeId(contract, dto),
isHazardous: this.resolveShipmentHandlingFlag(contract, dto, 'hazardousQuantity'),

330
apps/edr-freight-api/src/modules/contracts/contract-clearance.service.ts
View File

@@ -1,4 +1,9 @@
import { BadRequestException, ConflictException, Injectable } from '@nestjs/common';
import {
BadRequestException,
ConflictException,
Injectable,
NotFoundException,
} from '@nestjs/common';
import {
ContractDocPhase,
type ClearanceFinalInvoiceSummary,
@@ -13,7 +18,10 @@ import { FilesService } from '../files/files.service';
import { ContractsRepository } from './contracts.repository';
import { ContractsService, PaginatedContracts } from './contracts.service';
import { BookingsService } from '../bookings/bookings.service';
import { contractClearanceCodes } from './contract-clearance.util';
import {
assertDoCollectionDates,
contractClearanceCodes,
} from './contract-clearance.util';
import { ClearanceWorkflowService } from './clearance-workflow.service';
import { ClearanceMilestoneService } from './clearance-milestone.service';
import { ContractNotifierService } from './contract-notifier.service';
@@ -72,9 +80,23 @@ export interface ContractClearanceView {
blockedReason?: string | null;
} | null;
dutyRequired?: boolean | null;
/**
* Pre-declaration handshake with GL Djibouti: who will handle the shipment in
* transit. `name` is null until Djibouti answers, and the declaration step is
* shut until it is set.
*/
transitAssignee?: {
requestedAt: string | null;
requestNote: string | null;
name: string | null;
assignedAt: string | null;
} | null;
roHold?: boolean;
roHoldReason?: string | null;
vesselDepartureDate?: string | null;
/** Import DO dates recorded by GL Djibouti on upload. */
vesselArrivalDate?: string | null;
doCollectedDate?: string | null;
roAmendmentRequestedAt?: string | null;
bookingReady?: boolean;
preClearanceFinalized?: boolean;
@@ -84,12 +106,30 @@ export interface ContractClearanceView {
/** Reference + status of the GL-created shipment booking, once it exists. */
linkedBookingReference?: string | null;
linkedBookingStatus?: string | null;
/**
* Operations' latest "needs changes" note on that booking. GL created the
* booking, so GL is the one who has to act on it — surfaced here because the
* clearance page is where GL works, not the portal.
*/
linkedBookingReviewNote?: string | null;
/** Shipment day the booking currently holds — the default when GL resubmits. */
linkedBookingScheduledDate?: string | null;
dutyAdvice?: {
amount: number;
currency: string;
declarationSerial?: string | null;
noticeFile?: { id: string; name: string; url: string } | null;
} | null;
/**
* The customer's open objection to the advised duty — present only while GL
* has not re-advised (the advice milestone is back to PENDING). `rounds` is
* how many times it has been sent back, so both sides can see the loop.
*/
dutyDispute?: {
note: string;
raisedAt: string;
rounds: number;
} | null;
workflowFiles?: ReturnType<typeof buildWorkflowFiles>;
/** Import post-allocation T1 transit document state (null until a booking is linked). */
t1?: ClearanceT1State | null;
@@ -239,6 +279,19 @@ export class ContractClearanceService {
contract = await this.reconcilePrematureBookingReady(contractId, contract, boundary);
const phase = this.workflowService.resolvePhase(contract, cycle, milestones);
const dutyAdvice = this.buildDutyAdvice(files, milestones);
const dutyDispute = await this.buildDutyDispute(contractId, milestones);
const transitAssignee = cycle
? {
requestedAt: cycle.transitAssigneeRequestedAt
? cycle.transitAssigneeRequestedAt.toISOString()
: null,
requestNote: cycle.transitAssigneeRequestNote ?? null,
name: cycle.transitAssigneeName ?? null,
assignedAt: cycle.transitAssigneeAssignedAt
? cycle.transitAssigneeAssignedAt.toISOString()
: null,
}
: null;
let workflowFiles = buildWorkflowFiles(
files,
contract.tradeDirection ?? 'IMPORT',
@@ -301,11 +354,24 @@ export class ContractClearanceService {
// shortly" message. Reuse the export booking load; fetch for import too.
let linkedBookingReference: string | null = null;
let linkedBookingStatus: string | null = null;
let linkedBookingReviewNote: string | null = null;
let linkedBookingScheduledDate: string | null = null;
if (cycle?.bookingId) {
const booking = await this.bookingsService.findById(cycle.bookingId);
if (booking) {
linkedBookingReference = booking.reference ?? null;
linkedBookingStatus = booking.status ?? null;
linkedBookingScheduledDate = booking.scheduledDate
? new Date(booking.scheduledDate).toISOString()
: null;
// Newest changes-requested note (reviewNotes ride along on findById).
linkedBookingReviewNote =
[...(booking.reviewNotes ?? [])]
.filter((n) => n.type === 'CHANGES_REQUESTED')
.sort(
(a, b) =>
new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime(),
)[0]?.note ?? null;
if (contract.tradeDirection === 'EXPORT') {
nextAction = this.workflowService.computeNextActionForBooking(
booking,
@@ -340,6 +406,8 @@ export class ContractClearanceService {
roHold: Boolean(cycle?.roHoldReason),
roHoldReason: cycle?.roHoldReason ?? null,
vesselDepartureDate: cycle?.vesselDepartureDate ?? null,
vesselArrivalDate: cycle?.vesselArrivalDate ?? null,
doCollectedDate: cycle?.doCollectedDate ?? null,
roAmendmentRequestedAt: cycle?.roAmendmentRequestedAt
? cycle.roAmendmentRequestedAt.toISOString()
: null,
@@ -349,7 +417,11 @@ export class ContractClearanceService {
linkedBookingId: cycle?.bookingId ?? null,
linkedBookingReference,
linkedBookingStatus,
linkedBookingReviewNote,
linkedBookingScheduledDate,
dutyAdvice,
dutyDispute,
transitAssignee,
workflowFiles,
t1,
train,
@@ -406,6 +478,32 @@ export class ContractClearanceService {
};
}
/**
* The customer's duty objection, but only while it is still OPEN — i.e. the
* advice milestone sits back at PENDING because nobody has re-advised yet.
* Re-advising completes that milestone again, which closes the dispute here
* without any extra state to keep in sync; the notes stay as the audit trail
* and their count is the round number.
*/
private async buildDutyDispute(
contractId: string,
milestones: ClearanceMilestone[],
): Promise<ContractClearanceView['dutyDispute']> {
const advised = milestones.find((m) => m.milestoneCode === 'DUTY_TAXES_ADVISED');
if (!advised || advised.status === 'COMPLETED') return null;
const notes = await this.contractsRepository.findReviewNotes(
contractId,
'DUTY_DISPUTE',
);
const latest = notes[0];
if (!latest) return null;
return {
note: latest.body,
raisedAt: latest.createdAt.toISOString(),
rounds: notes.length,
};
}
/**
* True when every REQUIRED customer-input field has an APPROVED review row in
* the current cycle. The 100% gate before clearance can be finalized.
@@ -631,6 +729,92 @@ export class ContractClearanceService {
return this.applyReview(contractId, fileKey, status, staffId, 'OPERATIONS', note);
}
/**
* GL corrects a clearance document in place instead of bouncing it back to
* the customer. The customer's upload is NOT lost — it is retired into the
* document's version history, stamped with who replaced it and why — and the
* new version starts unreviewed, so GL still has to approve it (or query it)
* before clearance can be finalized.
*
* Use this for the small fixes staff can make faster than the customer can
* (a wrong page order, a missing stamp scan); a query is still the right tool
* when only the customer can produce the correct document.
*/
async replaceDocument(
contractId: string,
fileKey: string,
file: Express.Multer.File,
staffId: string,
reason?: string,
): Promise<Contract> {
const contract = await this.contractsService.findById(contractId);
this.assertClearanceReviewableStatus(contract);
if (!file) throw new BadRequestException('No replacement file uploaded');
if (!reason?.trim()) {
throw new BadRequestException(
'Say why the document is being replaced — it is kept on the file history.',
);
}
const cycle = await this.contractsRepository.currentCycle(contractId);
if (this.isPhasedCustoms(contract) && cycle?.preClearanceFinalizedAt) {
throw new BadRequestException(
'Documents cannot be changed after pre-clearance is finalized.',
);
}
const existing = await this.filesService.findByCode(
contractId,
'contracts',
fileKey,
);
if (!existing) {
throw new NotFoundException(
`No document is stored under "${fileKey}" on this contract.`,
);
}
await this.filesService.upsertByCode(
{ resourceId: contractId, resource: 'contracts', code: fileKey, file },
{ userId: staffId, reason: reason.trim() },
);
// A fresh version is unreviewed by definition: clear any earlier verdict so
// the corrected file is signed off explicitly rather than inheriting a tick.
const { inputCode, outputCode } = contractClearanceCodes(contract);
const reviews = await this.contractsRepository.findDocumentReviews(
contractId,
cycle?.id ?? null,
);
const settingCode =
reviews.find((r) => r.fileKey === fileKey)?.settingCode ??
(fileKey.startsWith('custom_') ? 'custom' : (inputCode ?? outputCode ?? 'custom'));
await this.contractsRepository.setDocumentReviewStatus({
contractId,
clearanceCycleId: cycle?.id ?? null,
settingCode,
fileKey,
status: 'PENDING',
staffId,
note: `Replaced by staff: ${reason.trim()}`,
});
await this.contractsRepository.createReviewNote(
contractId,
`Document "${fileKey}" replaced by staff: ${reason.trim()}`,
'STAFF_NOTE',
staffId,
'GL_ET',
);
return this.contractsService.findById(contractId);
}
/** Every stored version of one clearance document, newest first. */
async documentVersions(contractId: string, fileKey: string) {
return this.filesService.versionHistory(contractId, 'contracts', fileKey);
}
private async applyReview(
contractId: string,
fileKey: string,
@@ -945,6 +1129,68 @@ export class ContractClearanceService {
// ── Phased clearance actions (ONE_TIME customs, Phase 1) ───────────────────
/** Sync DOCUMENTS_APPROVED when reviews are done but the milestone row lags. */
/**
* GL Ethiopia asks Djibouti to name the officer who will handle the shipment
* in transit. Nothing else moves until Djibouti answers — the declaration is
* gated on it — so this is the first thing ET does once the documents are
* approved. Re-requesting is allowed (a nudge) and simply restamps the ask.
*/
async requestTransitAssignee(
contractId: string,
note: string | undefined,
userId?: string,
): Promise<Contract> {
const contract = await this.contractsService.findById(contractId);
this.assertPhasedCustoms(contract);
const cycle = await this.contractsRepository.currentCycle(contractId);
if (!cycle) throw new BadRequestException('No clearance cycle found');
await this.contractsRepository.updateCycle(cycle.id, {
transitAssigneeRequestedAt: new Date(),
transitAssigneeRequestedByUserId: userId ?? null,
transitAssigneeRequestNote: note?.trim() || null,
});
const updated = await this.contractsService.findById(contractId);
this.notifier.transitAssigneeRequested(updated, note?.trim() ?? null);
return updated;
}
/**
* GL Djibouti names the transit officer — free text, because the person is
* not a platform user. Answering unblocks the declaration for Ethiopia. A
* later call overwrites the name (reassignment) and re-notifies.
*/
async assignTransitAssignee(
contractId: string,
assignee: string,
userId?: string,
): Promise<Contract> {
const contract = await this.contractsService.findById(contractId);
this.assertPhasedCustoms(contract);
if (!assignee?.trim()) {
throw new BadRequestException('Name the officer who will handle the transit.');
}
const cycle = await this.contractsRepository.currentCycle(contractId);
if (!cycle) throw new BadRequestException('No clearance cycle found');
if (!cycle.transitAssigneeRequestedAt) {
throw new BadRequestException(
'GL Ethiopia has not requested a transit assignee for this clearance yet.',
);
}
const previous = cycle.transitAssigneeName ?? null;
await this.contractsRepository.updateCycle(cycle.id, {
transitAssigneeName: assignee.trim(),
transitAssigneeAssignedAt: new Date(),
transitAssigneeAssignedByUserId: userId ?? null,
});
const updated = await this.contractsService.findById(contractId);
this.notifier.transitAssigneeAssigned(updated, assignee.trim(), previous);
return updated;
}
private async ensureDeclarationPrerequisites(
contractId: string,
contract: Contract,
@@ -955,6 +1201,16 @@ export class ContractClearanceService {
'All required customer documents must be approved before uploading a declaration.',
);
}
// The transit officer must be named by Djibouti first — the declaration is
// filed against whoever will physically handle the shipment there.
const cycle = await this.contractsRepository.currentCycle(contractId);
if (!cycle?.transitAssigneeName) {
throw new BadRequestException(
cycle?.transitAssigneeRequestedAt
? 'GL Djibouti has not assigned the transit officer yet — the declaration cannot be filed until they do.'
: 'Request a transit assignee from GL Djibouti before filing the customs declaration.',
);
}
const milestones = await this.workflowService.listMilestones(contractId);
const docsApproved = milestones.find((m) => m.milestoneCode === 'DOCUMENTS_APPROVED');
if (docsApproved?.status !== 'COMPLETED' && docsApproved?.status !== 'SKIPPED') {
@@ -1061,6 +1317,67 @@ export class ContractClearanceService {
return this.contractsService.findById(contractId);
}
/**
* The customer disagrees with the advised duty & tax and asks GL Ethiopia to
* correct it. Nothing is paid; the advice milestone reopens so the Duty & tax
* step becomes actionable again on the GL clearance page, with the customer's
* message shown beside it. GL re-advises (same endpoint as the first time),
* which closes the dispute — the loop may run as many rounds as it takes.
*/
async disputeDuty(
contractId: string,
note: string,
userId?: string,
): Promise<Contract> {
const contract = await this.contractsService.findById(contractId);
this.assertPhasedCustoms(contract);
if (contract.tradeDirection !== 'IMPORT') {
throw new BadRequestException('Duty applies only to import contracts.');
}
if (!note?.trim()) {
throw new BadRequestException(
'Say what is wrong with the advised amount so GL can correct it.',
);
}
const cycle = await this.contractsRepository.currentCycle(contractId);
if (!cycle?.dutyRequired) {
throw new BadRequestException('Duty/tax is not required for this clearance.');
}
const milestones = await this.workflowService.listMilestones(contractId);
const byCode = new Map(milestones.map((m) => [m.milestoneCode, m]));
if (byCode.get('DUTY_TAXES_ADVISED')?.status !== 'COMPLETED') {
throw new BadRequestException(
'There is no advised duty amount to dispute yet.',
);
}
// Once the slip is in, the money is paid — a dispute then is a refund
// conversation, not a re-advice.
if (byCode.get('DUTY_TAX_PAID')?.status === 'COMPLETED') {
throw new BadRequestException(
'The duty payment slip has already been submitted — contact GL Ethiopia directly.',
);
}
await this.contractsRepository.createReviewNote(
contractId,
note.trim(),
'DUTY_DISPUTE',
userId,
'CUSTOMER',
);
// Back to GL: reopening the milestone is what re-arms the Duty & tax step
// (the stepper picks its active step from milestone completion).
await this.milestoneService.reopenForContract(contractId, 'DUTY_TAXES_ADVISED');
await this.contractsRepository.updateCycle(cycle.id, {
currentPhase: ContractDocPhase.GlEtOutput,
});
const updated = await this.contractsService.findById(contractId);
this.notifier.dutyDisputed(updated, note.trim());
return updated;
}
async uploadDutySlip(
contractId: string,
file: Express.Multer.File,
@@ -1175,7 +1492,7 @@ export class ContractClearanceService {
contractId: string,
file: Express.Multer.File,
userId?: string,
vesselDepartureDate?: string,
dates?: { vesselArrivalDate?: string; doCollectedDate?: string },
): Promise<Contract> {
const contract = await this.contractsService.findById(contractId);
this.assertPhasedCustoms(contract);
@@ -1185,6 +1502,8 @@ export class ContractClearanceService {
if (!file) throw new BadRequestException('No Delivery Order uploaded');
const { vesselArrivalDate, doCollectedDate } = assertDoCollectionDates(dates);
// DO upload is deliberately un-gated: GL Djibouti may attach it at any point,
// any file type. The DO_COLLECTED milestone (and booking readiness) still waits
// for GL Ethiopia to finalize pre-clearance so the workflow order holds.
@@ -1196,9 +1515,10 @@ export class ContractClearanceService {
});
const cycle = await this.contractsRepository.currentCycle(contractId);
if (cycle && vesselDepartureDate?.trim()) {
if (cycle) {
await this.contractsRepository.updateCycle(cycle.id, {
vesselDepartureDate: vesselDepartureDate.trim(),
vesselArrivalDate,
doCollectedDate,
});
}
if (cycle?.preClearanceFinalizedAt) {

46
apps/edr-freight-api/src/modules/contracts/contract-clearance.util.ts
View File

@@ -1,3 +1,5 @@
import { BadRequestException } from '@nestjs/common';
import { Contract } from './entities/contract.entity';
import { INTERCITY_DOCUMENTS_SETTING_CODE } from '../bookings/clearance.util';
@@ -84,3 +86,47 @@ export function contractClearanceCodes(contract: Contract): {
includesCustoms,
};
}
/**
* Djibouti GL cannot record a Delivery Order without saying WHEN the vessel
* arrived and WHEN the DO was collected — the file alone leaves the import
* timeline unauditable. Shared by the contract and per-booking DO uploads so
* one endpoint can never be laxer than the other.
*
* Returns the normalized `YYYY-MM-DD` pair; throws if either is missing,
* unparseable, or the DO predates the vessel's arrival.
*/
export function assertDoCollectionDates(dates?: {
vesselArrivalDate?: string;
doCollectedDate?: string;
}): { vesselArrivalDate: string; doCollectedDate: string } {
const vesselArrivalDate = normalizeDoDate(
dates?.vesselArrivalDate,
'Vessel arrival date',
);
const doCollectedDate = normalizeDoDate(
dates?.doCollectedDate,
'DO collected date',
);
if (doCollectedDate < vesselArrivalDate) {
throw new BadRequestException(
'DO collected date cannot be earlier than the vessel arrival date.',
);
}
return { vesselArrivalDate, doCollectedDate };
}
/** `YYYY-MM-DD` or throw — the column is a DATE, so time zones never enter. */
function normalizeDoDate(value: string | undefined, label: string): string {
const trimmed = value?.trim();
if (!trimmed) {
throw new BadRequestException(`${label} is required to upload a Delivery Order.`);
}
const date = trimmed.slice(0, 10);
if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || Number.isNaN(Date.parse(date))) {
throw new BadRequestException(`${label} is not a valid date.`);
}
return date;
}

94
apps/edr-freight-api/src/modules/contracts/contract-document-diff.util.ts
View File

@@ -4,8 +4,9 @@ import type {
} from './entities/contract.entity';
/**
* One recorded change between two document snapshots. Granularity is per
* article: a body edit is reported as "the body changed", not as a text diff.
* One recorded change between two document snapshots. A body edit carries the
* text on both sides so the audit trail shows WHAT was rewritten, not merely
* that something was — the UI diffs the two strings for display.
*/
export type ContractDocumentChange =
| { kind: 'ARTICLE_ADDED'; articleId: string; title: string }
@@ -16,7 +17,14 @@ export type ContractDocumentChange =
title: string;
fromTitle: string;
}
| { kind: 'ARTICLE_BODY_CHANGED'; articleId: string; title: string }
| {
kind: 'ARTICLE_BODY_CHANGED';
articleId: string;
title: string;
/** Body before / after the edit. Absent on revisions recorded earlier. */
fromBody?: string;
toBody?: string;
}
| {
kind: 'ARTICLE_REORDERED';
articleId: string;
@@ -25,7 +33,18 @@ export type ContractDocumentChange =
toOrder: number;
}
| { kind: 'DOCUMENT_TITLE_CHANGED'; title: string; fromTitle: string | null }
| { kind: 'WHEREAS_CHANGED'; added: number; removed: number };
| { kind: 'WHEREAS_CHANGED'; added: number; removed: number }
/**
* A contract field (not a document article) changed — the customer editing a
* DRAFT/CHANGES_REQUESTED contract, e.g. its route, cargo or service type.
*/
| {
kind: 'FIELD_CHANGED';
field: string;
label: string;
from: string | null;
to: string | null;
};
type SnapshotLike = Pick<
ContractDocumentSnapshot,
@@ -109,6 +128,8 @@ export function diffSnapshots(
kind: 'ARTICLE_BODY_CHANGED',
articleId: article.id,
title: article.title,
fromBody: previous.body,
toBody: article.body,
});
}
if (previous.order !== article.order) {
@@ -134,6 +155,60 @@ export function diffSnapshots(
return changes;
}
/** Human label per audited contract field, in the order they read on the form. */
export const CONTRACT_FIELD_LABELS: Record<string, string> = {
contractKind: 'Contract kind',
tradeDirection: 'Trade direction',
freightType: 'Freight type',
serviceType: 'Service type',
paymentCurrency: 'Payment currency',
contractType: 'Contract type',
isHazardous: 'Hazardous',
hazardClass: 'Hazard class',
unNumber: 'UN number',
isReefer: 'Reefer',
equipmentReturn: 'Equipment return',
customsClearingAgent: 'Customs clearing agent',
firstMilePickupAddress: 'First-mile pickup address',
lastMileDeliveryAddress: 'Last-mile delivery address',
routes: 'Routes',
cargoScope: 'Cargo scope',
};
/** Render a field value for the audit trail — never "[object Object]". */
function displayValue(value: unknown): string | null {
if (value === null || value === undefined || value === '') return null;
if (typeof value === 'boolean') return value ? 'Yes' : 'No';
return String(value);
}
/**
* Compare two flat maps of contract fields and report what changed. Only keys
* present in `after` are considered, so a partial update never reports the
* fields it did not touch.
*/
export function diffContractFields(
before: Record<string, unknown>,
after: Record<string, unknown>,
): ContractDocumentChange[] {
const changes: ContractDocumentChange[] = [];
for (const [field, nextRaw] of Object.entries(after)) {
const next = displayValue(nextRaw);
const previous = displayValue(before[field]);
if (next === previous) continue;
changes.push({
kind: 'FIELD_CHANGED',
field,
label: CONTRACT_FIELD_LABELS[field] ?? field,
from: previous,
to: next,
});
}
return changes;
}
/** Short human summary of a change set, e.g. "2 articles edited, 1 article added". */
export function summarizeChanges(changes: ContractDocumentChange[]): string {
if (changes.length === 0) return 'No changes';
@@ -148,6 +223,7 @@ export function summarizeChanges(changes: ContractDocumentChange[]): string {
const counts = new Map<string, number>();
const parts: string[] = [];
const fields: string[] = [];
for (const change of changes) {
const verb = articleVerbs[change.kind];
@@ -157,9 +233,19 @@ export function summarizeChanges(changes: ContractDocumentChange[]): string {
parts.push('document title changed');
} else if (change.kind === 'WHEREAS_CHANGED') {
parts.push('recitals changed');
} else if (change.kind === 'FIELD_CHANGED') {
fields.push(change.label.toLowerCase());
}
}
if (fields.length > 0) {
parts.push(
fields.length <= 3
? `${fields.join(', ')} changed`
: `${fields.length} contract fields changed`,
);
}
const articleParts = [...counts.entries()].map(
([verb, count]) => `${count} article${count === 1 ? '' : 's'} ${verb}`,
);

121
apps/edr-freight-api/src/modules/contracts/contract-document-history.service.ts
View File

@@ -1,8 +1,12 @@
import { Injectable, Logger } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { InjectDataSource, InjectRepository } from '@nestjs/typeorm';
import { DataSource, Repository } from 'typeorm';
import { diffSnapshots, summarizeChanges } from './contract-document-diff.util';
import {
ContractDocumentChange,
diffSnapshots,
summarizeChanges,
} from './contract-document-diff.util';
import { ContractDocumentRevision } from './entities/contract-document-revision.entity';
import type { ContractDocumentSnapshot } from './entities/contract.entity';
@@ -12,6 +16,39 @@ export interface RecordRevisionInput {
after: ContractDocumentSnapshot | null;
actorId?: string | null;
actorRole?: string | null;
actorName?: string | null;
stepId?: string | null;
}
/**
* `iam.users.name` is a localized object ({ en, am, … }), not a string — a
* plain `String(name)` there yields "[object Object]" in the audit trail.
*/
interface IamUserRow {
name?: Record<string, string> | string | null;
username?: string | null;
email?: string | null;
}
/** Best display name for a user row: English label → any locale → login → email. */
function pickUserName(user: IamUserRow): string | null {
const { name } = user;
if (typeof name === 'string' && name.trim()) return name.trim();
if (name && typeof name === 'object') {
const localized =
name.en ?? Object.values(name).find((v) => typeof v === 'string' && v.trim());
if (localized?.trim()) return localized.trim();
}
return user.username?.trim() || user.email?.trim() || null;
}
/** Pre-computed changes (contract fields), rather than a document diff. */
export interface RecordChangesInput {
contractId: string;
changes: ContractDocumentChange[];
actorId?: string | null;
actorRole?: string | null;
actorName?: string | null;
stepId?: string | null;
}
@@ -22,6 +59,7 @@ export class ContractDocumentHistoryService {
constructor(
@InjectRepository(ContractDocumentRevision)
private readonly revisionRepo: Repository<ContractDocumentRevision>,
@InjectDataSource() private readonly dataSource: DataSource,
) {}
/**
@@ -30,18 +68,32 @@ export class ContractDocumentHistoryService {
* and swallowed. A no-op edit records nothing.
*/
async record(input: RecordRevisionInput): Promise<void> {
return this.recordChanges({
...input,
changes: diffSnapshots(input.before, input.after),
});
}
/**
* Append a revision from an already-computed change set — the contract-field
* path, where there is no document snapshot to diff. Same best-effort
* contract as {@link record}: a no-op change set records nothing, and a
* failure here never breaks the edit that triggered it.
*/
async recordChanges(input: RecordChangesInput): Promise<void> {
try {
const changes = diffSnapshots(input.before, input.after);
if (changes.length === 0) return;
if (input.changes.length === 0) return;
await this.revisionRepo.save(
this.revisionRepo.create({
contractId: input.contractId,
actorId: input.actorId ?? null,
actorRole: input.actorRole ?? null,
actorName:
input.actorName ?? (await this.resolveActorName(input.actorId)),
stepId: input.stepId ?? null,
summary: summarizeChanges(changes),
changes,
summary: summarizeChanges(input.changes),
changes: input.changes,
}),
);
} catch (err) {
@@ -51,11 +103,62 @@ export class ContractDocumentHistoryService {
}
}
/**
* Name for the acting user. `iam.users` is owned by the auth system and has
* no entity here, so it is read directly; a miss is not an error — the trail
* still carries the id, role and timestamp.
*/
private async resolveActorName(
actorId?: string | null,
): Promise<string | null> {
if (!actorId) return null;
const names = await this.resolveActorNames([actorId]);
return names.get(actorId) ?? null;
}
/** Batched {@link resolveActorName} — one query for a whole revision list. */
private async resolveActorNames(
actorIds: string[],
): Promise<Map<string, string>> {
const resolved = new Map<string, string>();
const ids = [...new Set(actorIds.filter(Boolean))];
if (ids.length === 0) return resolved;
try {
const rows = (await this.dataSource.query(
`SELECT id, name, username, email FROM iam.users WHERE id = ANY($1::uuid[])`,
[ids],
)) as Array<IamUserRow & { id: string }>;
for (const row of rows) {
const name = pickUserName(row);
if (name) resolved.set(row.id, name);
}
} catch (err) {
this.logger.warn(`Could not resolve actor names: ${String(err)}`);
}
return resolved;
}
/** Revision history for a contract, newest first. */
list(contractId: string): Promise<ContractDocumentRevision[]> {
return this.revisionRepo.find({
async list(contractId: string): Promise<ContractDocumentRevision[]> {
const revisions = await this.revisionRepo.find({
where: { contractId },
order: { createdAt: 'DESC' },
});
// Rows written before actor_name existed still carry an actor_id — resolve
// those for display (one query for the whole list) rather than backfilling.
const missing = revisions
.filter((r) => !r.actorName && r.actorId)
.map((r) => r.actorId as string);
if (missing.length === 0) return revisions;
const names = await this.resolveActorNames(missing);
for (const revision of revisions) {
if (!revision.actorName && revision.actorId) {
revision.actorName = names.get(revision.actorId) ?? null;
}
}
return revisions;
}
}

164
apps/edr-freight-api/src/modules/contracts/contract-duty-dispute.spec.ts Normal file
View File

@@ -0,0 +1,164 @@
import { BadRequestException } from '@nestjs/common';
import { ContractClearanceService } from './contract-clearance.service';
import type { Contract } from './entities/contract.entity';
/**
* The duty advice → dispute → re-advice loop. GL Ethiopia advises an amount;
* the customer either pays it or sends it back with a reason. Sending it back
* reopens the advice milestone — that is what puts the Duty & tax step back in
* GL's hands — and the round can repeat until the amount is agreed.
*/
describe('ContractClearanceService — duty dispute', () => {
const contract = (over: Partial<Contract> = {}): Contract =>
({
id: 'ctr-1',
reference: 'CTR-2026-00042',
tradeDirection: 'IMPORT',
customsClearingEnabled: true,
contractKind: 'ONE_TIME',
...over,
}) as Contract;
const milestone = (code: string, status: string) =>
({ milestoneCode: code, status }) as never;
let repo: {
currentCycle: jest.Mock;
createReviewNote: jest.Mock;
updateCycle: jest.Mock;
findReviewNotes: jest.Mock;
};
let contractsService: { findById: jest.Mock };
let workflowService: { listMilestones: jest.Mock };
let milestoneService: { reopenForContract: jest.Mock };
let notifier: { dutyDisputed: jest.Mock };
let service: ContractClearanceService;
const build = (milestones: unknown[]) => {
workflowService.listMilestones.mockResolvedValue(milestones);
};
beforeEach(() => {
repo = {
currentCycle: jest.fn().mockResolvedValue({ id: 'cyc-1', dutyRequired: true }),
createReviewNote: jest.fn().mockResolvedValue(undefined),
updateCycle: jest.fn().mockResolvedValue(undefined),
findReviewNotes: jest.fn().mockResolvedValue([]),
};
contractsService = { findById: jest.fn().mockResolvedValue(contract()) };
workflowService = { listMilestones: jest.fn().mockResolvedValue([]) };
milestoneService = { reopenForContract: jest.fn().mockResolvedValue(undefined) };
notifier = { dutyDisputed: jest.fn() };
service = new ContractClearanceService(
repo as never,
contractsService as never,
{} as never, // bookingsService
{} as never, // filesService
{} as never, // fileUploadSettingsService
workflowService as never,
milestoneService as never,
{} as never, // dropdownSettingsService
{} as never, // glOperationsService
notifier as never,
);
build([
milestone('DUTY_TAXES_ADVISED', 'COMPLETED'),
milestone('DUTY_TAX_PAID', 'PENDING'),
]);
});
it('records the objection and hands the step back to GL', async () => {
await service.disputeDuty('ctr-1', ' Declared value is wrong ', 'user-1');
expect(repo.createReviewNote).toHaveBeenCalledWith(
'ctr-1',
'Declared value is wrong',
'DUTY_DISPUTE',
'user-1',
'CUSTOMER',
);
// Reopening the advice milestone is what re-arms the Duty & tax step.
expect(milestoneService.reopenForContract).toHaveBeenCalledWith(
'ctr-1',
'DUTY_TAXES_ADVISED',
);
expect(repo.updateCycle).toHaveBeenCalledWith('cyc-1', {
currentPhase: 'GL_ET_OUTPUT',
});
});
it('tells GL Ethiopia, not the customer', async () => {
await service.disputeDuty('ctr-1', 'Too high', 'user-1');
expect(notifier.dutyDisputed).toHaveBeenCalledWith(
expect.objectContaining({ id: 'ctr-1' }),
'Too high',
);
});
it('requires a reason — GL cannot correct an unexplained objection', async () => {
await expect(service.disputeDuty('ctr-1', ' ')).rejects.toBeInstanceOf(
BadRequestException,
);
expect(milestoneService.reopenForContract).not.toHaveBeenCalled();
});
it('refuses when nothing has been advised yet', async () => {
build([milestone('DUTY_TAXES_ADVISED', 'PENDING')]);
await expect(service.disputeDuty('ctr-1', 'Too high')).rejects.toThrow(
/no advised duty amount/i,
);
});
it('refuses once the payment slip is in — that is a refund, not a re-advice', async () => {
build([
milestone('DUTY_TAXES_ADVISED', 'COMPLETED'),
milestone('DUTY_TAX_PAID', 'COMPLETED'),
]);
await expect(service.disputeDuty('ctr-1', 'Too high')).rejects.toThrow(
/already been submitted/i,
);
});
it('refuses when duty was never required for this clearance', async () => {
repo.currentCycle.mockResolvedValue({ id: 'cyc-1', dutyRequired: false });
await expect(service.disputeDuty('ctr-1', 'Too high')).rejects.toThrow(
/not required/i,
);
});
describe('the view', () => {
const buildDispute = (milestones: unknown[]) =>
(
service as unknown as {
buildDutyDispute: (id: string, m: unknown[]) => Promise<unknown>;
}
).buildDutyDispute('ctr-1', milestones);
it('shows the objection while GL still owes a corrected advice', async () => {
repo.findReviewNotes.mockResolvedValue([
{ body: 'Second look please', createdAt: new Date('2026-07-20T09:00:00Z') },
{ body: 'First objection', createdAt: new Date('2026-07-18T09:00:00Z') },
]);
const dispute = await buildDispute([
milestone('DUTY_TAXES_ADVISED', 'PENDING'),
]);
expect(dispute).toMatchObject({ note: 'Second look please', rounds: 2 });
});
it('clears itself once GL re-advises', async () => {
repo.findReviewNotes.mockResolvedValue([
{ body: 'First objection', createdAt: new Date('2026-07-18T09:00:00Z') },
]);
const dispute = await buildDispute([
milestone('DUTY_TAXES_ADVISED', 'COMPLETED'),
]);
expect(dispute).toBeNull();
});
});
});

63
apps/edr-freight-api/src/modules/contracts/contract-expiry.service.spec.ts Normal file
View File

@@ -0,0 +1,63 @@
import { ContractExpiryService } from './contract-expiry.service';
import type { Contract } from './entities/contract.entity';
/**
* The reminder must warn each customer once, ten days out, and must never let a
* notification failure escape into the scheduler (that would also take out the
* expiry sweep sharing this service).
*/
describe('ContractExpiryService — expiry reminder', () => {
const contract = (over: Partial<Contract> = {}): Contract =>
({
id: 'c-1',
reference: 'CTR-2026-00042',
companyId: 'co-1',
contractValidUntil: new Date('2026-08-10T00:00:00.000Z'),
status: 'CONTRACT_ACTIVE',
...over,
}) as Contract;
let repo: { expireLapsedContracts: jest.Mock; findExpiringInDays: jest.Mock };
let inbox: { notify: jest.Mock };
let service: ContractExpiryService;
beforeEach(() => {
repo = {
expireLapsedContracts: jest.fn().mockResolvedValue(0),
findExpiringInDays: jest.fn().mockResolvedValue([]),
};
inbox = { notify: jest.fn().mockResolvedValue(undefined) };
service = new ContractExpiryService(repo as never, inbox as never);
});
it('asks for the contracts lapsing ten days out', async () => {
await service.remindExpiringContracts();
expect(repo.findExpiringInDays).toHaveBeenCalledWith(10);
});
it('notifies the owning company once, deep-linking the contract list', async () => {
repo.findExpiringInDays.mockResolvedValue([contract()]);
await service.remindExpiringContracts();
expect(inbox.notify).toHaveBeenCalledTimes(1);
const sent = inbox.notify.mock.calls[0][0];
expect(sent.recipients).toEqual({ companyId: 'co-1' });
expect(sent.title).toContain('CTR-2026-00042');
expect(sent.title).toContain('10 days');
expect(sent.link).toBe('/contracts');
expect(sent.data).toMatchObject({ contractId: 'c-1', action: 'CONTRACT_EXPIRING' });
});
it('skips a contract with no owning company (nobody to notify)', async () => {
repo.findExpiringInDays.mockResolvedValue([contract({ companyId: null })]);
await service.remindExpiringContracts();
expect(inbox.notify).not.toHaveBeenCalled();
});
it('swallows a notification failure instead of throwing into the scheduler', async () => {
repo.findExpiringInDays.mockResolvedValue([contract()]);
inbox.notify.mockRejectedValue(new Error('inbox down'));
await expect(service.remindExpiringContracts()).resolves.toBeUndefined();
});
});

96
apps/edr-freight-api/src/modules/contracts/contract-expiry.service.ts Normal file
View File

@@ -0,0 +1,96 @@
import { Injectable, Logger } from '@nestjs/common';
import { Cron, CronExpression } from '@nestjs/schedule';
import { NotificationAudience, NotificationType } from '@edr/types';
import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
import { ContractsRepository } from './contracts.repository';
/**
* How many days before a contract lapses the customer is reminded. Mirrored by
* the portal contract list (EXPIRY_NOTICE_DAYS in contract-ui.tsx), which shows
* the same countdown on the row.
*/
const EXPIRY_NOTICE_DAYS = 10;
/** Nightly sweep that flips contracts past contractValidUntil to EXPIRED. */
@Injectable()
export class ContractExpiryService {
private readonly logger = new Logger(ContractExpiryService.name);
constructor(
private readonly contractsRepository: ContractsRepository,
private readonly inbox: NotificationInboxService,
) {}
/**
* Warn every customer whose contract lapses in ~10 days, once. The repository
* window is a rolling 24h slice, so a contract is picked up by exactly one
* daily run — no reminded-flag column needed.
*
* ponytail: a missed run (API down over the slice) skips that contract's
* reminder; the portal list still shows its countdown for the whole window.
*/
@Cron(CronExpression.EVERY_DAY_AT_2AM, { name: 'contract-expiry-reminder' })
async remindExpiringContracts(): Promise<void> {
try {
const expiring =
await this.contractsRepository.findExpiringInDays(EXPIRY_NOTICE_DAYS);
let notified = 0;
for (const contract of expiring) {
if (!contract.companyId || !contract.contractValidUntil) continue;
const endsOn = contract.contractValidUntil.toLocaleDateString('en-GB');
await this.inbox.notify({
recipients: { companyId: contract.companyId },
audience: NotificationAudience.PORTAL,
type: NotificationType.CONTRACT_STATUS,
title: `Contract ${contract.reference} expires in ${EXPIRY_NOTICE_DAYS} days`,
body:
`Your contract ${contract.reference} is valid until ${endsOn}. ` +
'After that date it stops accepting new bookings — contact EDR if ' +
'you need it renewed.',
link: '/contracts',
data: { contractId: contract.id, action: 'CONTRACT_EXPIRING' },
});
notified += 1;
}
this.logger.log(
`Contract expiry reminder: ${notified} customer(s) warned of a contract ` +
`lapsing in ${EXPIRY_NOTICE_DAYS} days`,
);
} catch (err) {
// Never throws into the scheduler — a failed reminder must not stop the
// expiry sweep from running.
this.logger.error(
`Contract expiry reminder failed: ${(err as Error).message}`,
(err as Error).stack,
);
}
}
@Cron(CronExpression.EVERY_DAY_AT_1AM, { name: 'contract-expiry-sweep' })
async expireLapsedContracts(): Promise<void> {
try {
const affected = await this.contractsRepository.expireLapsedContracts();
this.logger.log(`Contract expiry sweep: ${affected} contract(s) marked EXPIRED`);
} catch (err) {
this.logger.error(
`Contract expiry sweep failed: ${(err as Error).message}`,
(err as Error).stack,
);
try {
await this.inbox.notify({
recipients: { allBackoffice: true },
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.GENERIC,
title: 'Contract expiry sweep failed',
body: `The nightly job that expires lapsed contracts failed: ${(err as Error).message}. Contracts past their validity date may still show as active until this is fixed.`,
data: { action: 'CONTRACT_EXPIRY_SWEEP_FAILED' },
});
} catch (notifyErr) {
this.logger.error(
`Contract expiry sweep failure alert also failed: ${(notifyErr as Error).message}`,
);
}
}
}
}

89
apps/edr-freight-api/src/modules/contracts/contract-field-diff.spec.ts Normal file
View File

@@ -0,0 +1,89 @@
import {
diffContractFields,
summarizeChanges,
} from './contract-document-diff.util';
/**
* The contract-field audit runs on the customer's own edits, so it has to be
* exact: never report a field the edit did not touch, and never render a value
* as "[object Object]" or "true" in the trail a reviewer reads.
*/
describe('diffContractFields', () => {
it('reports only the fields that actually changed', () => {
const changes = diffContractFields(
{ freightType: 'BULK', paymentCurrency: 'USD', isReefer: false },
{ freightType: 'CONTAINER', paymentCurrency: 'USD', isReefer: false },
);
expect(changes).toEqual([
{
kind: 'FIELD_CHANGED',
field: 'freightType',
label: 'Freight type',
from: 'BULK',
to: 'CONTAINER',
},
]);
});
it('renders booleans as Yes/No, not true/false', () => {
const [change] = diffContractFields({ isHazardous: false }, { isHazardous: true });
expect(change).toMatchObject({ label: 'Hazardous', from: 'No', to: 'Yes' });
});
it('treats null, undefined and empty string as "not set"', () => {
expect(diffContractFields({ unNumber: null }, { unNumber: '' })).toEqual([]);
expect(diffContractFields({ unNumber: undefined }, { unNumber: null })).toEqual([]);
const [set] = diffContractFields({ unNumber: null }, { unNumber: 'UN1234' });
expect(set).toMatchObject({ from: null, to: 'UN1234' });
});
it('ignores fields absent from the update', () => {
// A partial edit must not report the fields it never sent.
expect(diffContractFields({ freightType: 'BULK', isReefer: true }, {})).toEqual([]);
});
it('records a route swap that keeps the same lane count', () => {
const [change] = diffContractFields(
{ routes: 'Nagad → Mojo' },
{ routes: 'Nagad → Adama' },
);
expect(change).toMatchObject({
label: 'Routes',
from: 'Nagad → Mojo',
to: 'Nagad → Adama',
});
});
it('summarises field changes by name, and by count once there are many', () => {
const few = diffContractFields(
{ freightType: 'BULK', paymentCurrency: 'USD' },
{ freightType: 'CONTAINER', paymentCurrency: 'ETB' },
);
expect(summarizeChanges(few)).toBe('freight type, payment currency changed');
const many = diffContractFields(
{ a: '1', b: '1', c: '1', d: '1' },
{ a: '2', b: '2', c: '2', d: '2' },
);
expect(summarizeChanges(many)).toBe('4 contract fields changed');
});
it('summarises document and field changes together', () => {
const summary = summarizeChanges([
{ kind: 'ARTICLE_BODY_CHANGED', articleId: 'a-1', title: 'Article 1' },
{
kind: 'FIELD_CHANGED',
field: 'routes',
label: 'Routes',
from: 'A → B',
to: 'A → C',
},
]);
expect(summary).toBe('1 article edited, routes changed');
});
});

50
apps/edr-freight-api/src/modules/contracts/contract-notifier.service.ts
View File

@@ -192,6 +192,56 @@ export class ContractNotifierService {
});
}
/**
* GL Ethiopia asked Djibouti to name the transit officer. Staff-only, and
* deep-linked to the Djibouti clearance page where the name is entered — the
* customs declaration is blocked until they answer.
*/
transitAssigneeRequested(c: Contract, note: string | null): void {
const msg =
`GL Ethiopia needs a transit assignee for contract ${c.reference} before ` +
`the customs declaration can be filed.${note ? ` Note: "${note}"` : ''}`;
this.logger.log(`TRANSIT ASSIGNEE REQUESTED — ${c.reference}`);
this.inAppStaff(c, `Transit assignee needed — ${c.reference}`, msg, {
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/gl-djibouti/clearance/${c.id}`,
});
}
/** Djibouti named (or changed) the transit officer — Ethiopia can proceed. */
transitAssigneeAssigned(
c: Contract,
assignee: string,
previous: string | null,
): void {
const msg = previous
? `GL Djibouti changed the transit assignee for contract ${c.reference} from ` +
`"${previous}" to "${assignee}".`
: `GL Djibouti assigned ${assignee} to handle contract ${c.reference} in transit. ` +
`The customs declaration can now be filed.`;
this.logger.log(`TRANSIT ASSIGNEE ASSIGNED — ${c.reference}`);
this.inAppStaff(c, `Transit assignee set — ${c.reference}`, msg, {
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/contracts/clearance/${c.id}`,
});
}
/**
* The customer disputed the advised duty & tax. This goes to STAFF, not the
* customer: GL Ethiopia is the one who has to re-advise, and the clearance
* page is where they do it.
*/
dutyDisputed(c: Contract, note: string): void {
const msg =
`The customer disputed the duty & tax advised on contract ${c.reference}: ` +
`"${note}". Review and re-advise the amount on the clearance page.`;
this.logger.log(`DUTY DISPUTED — ${c.reference}`);
this.inAppStaff(c, `Duty disputed on ${c.reference}`, msg, {
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/contracts/clearance/${c.id}`,
});
}
/** A clearance document was queried — customer must re-upload it. */
clearanceDocumentQueried(c: Contract, fileKey: string, note: string): void {
const msg =

16
apps/edr-freight-api/src/modules/contracts/contract-pricing.service.ts
View File

@@ -35,6 +35,8 @@ function toContractUnit(rateUnit: string): ContractUnitRateLineItem['unit'] {
switch (rateUnit) {
case 'PER_TON':
return 'per_ton';
case 'PER_ITEM':
return 'per_item';
case 'PER_KM':
return 'per_km';
case 'PER_WAGON':
@@ -115,9 +117,19 @@ export class ContractPricingService {
});
}
} else {
const bulkRate =
liveRates.find((r) => r.rateType === baseType && r.currency === 'USD') ?? null;
const cargoScope = (contract.cargoScope ?? []).find((c) => c.cargoTypeId);
// Freeze the rate for the contract's own commodity when one is configured
// — a per-item machinery rate and a per-ton wheat rate live side by side.
const bulkRates = liveRates.filter(
(r) => r.rateType === baseType && r.currency === 'USD',
);
const bulkRate =
(cargoScope?.cargoTypeId
? bulkRates.find((r) => r.cargoTypeId === cargoScope.cargoTypeId)
: undefined) ??
bulkRates.find((r) => !r.cargoTypeId) ??
bulkRates[0] ??
null;
if (bulkRate) {
lineItems.push({
code: 'BULK_FREIGHT',

115
apps/edr-freight-api/src/modules/contracts/contract-revision-actor.spec.ts Normal file
View File

@@ -0,0 +1,115 @@
import { ContractDocumentHistoryService } from './contract-document-history.service';
/**
* `iam.users.name` is a localized jsonb object, not a string. Reading it
* naively puts "[object Object]" in the audit trail — or, worse, throws and
* leaves every revision anonymous. These specs pin the resolution rules.
*/
describe('ContractDocumentHistoryService actor names', () => {
const build = (rows: unknown[]) => {
const saved: Array<Record<string, unknown>> = [];
const service = Object.create(
ContractDocumentHistoryService.prototype,
) as ContractDocumentHistoryService;
Object.assign(service, {
logger: { warn: jest.fn(), error: jest.fn() },
dataSource: { query: jest.fn().mockResolvedValue(rows) },
revisionRepo: {
create: (row: Record<string, unknown>) => row,
save: jest.fn((row: Record<string, unknown>) => {
saved.push(row);
return Promise.resolve(row);
}),
find: jest.fn().mockResolvedValue([]),
},
});
return { service, saved };
};
const change = {
kind: 'FIELD_CHANGED' as const,
field: 'routes',
label: 'Routes',
from: 'A → B',
to: 'A → C',
};
it('prefers the English label from the localized name object', async () => {
const { service, saved } = build([
{ id: 'u-1', name: { am: 'ሱፐር አድሚን', en: 'Super Admin' }, username: 'superadmin' },
]);
await service.recordChanges({ contractId: 'c-1', changes: [change], actorId: 'u-1' });
expect(saved[0].actorName).toBe('Super Admin');
});
it('falls back to another locale, then username, then email', async () => {
const onlyAmharic = build([{ id: 'u-1', name: { am: 'ሱፐር' }, username: 'x' }]);
await onlyAmharic.service.recordChanges({
contractId: 'c-1',
changes: [change],
actorId: 'u-1',
});
expect(onlyAmharic.saved[0].actorName).toBe('ሱፐር');
const noName = build([{ id: 'u-1', name: null, username: 'operator', email: 'o@edr' }]);
await noName.service.recordChanges({
contractId: 'c-1',
changes: [change],
actorId: 'u-1',
});
expect(noName.saved[0].actorName).toBe('operator');
const emailOnly = build([{ id: 'u-1', name: {}, username: null, email: 'o@edr.local' }]);
await emailOnly.service.recordChanges({
contractId: 'c-1',
changes: [change],
actorId: 'u-1',
});
expect(emailOnly.saved[0].actorName).toBe('o@edr.local');
});
it('never writes "[object Object]" as the actor name', async () => {
const { service, saved } = build([{ id: 'u-1', name: { en: 'Real Name' } }]);
await service.recordChanges({ contractId: 'c-1', changes: [change], actorId: 'u-1' });
expect(String(saved[0].actorName)).not.toContain('object Object');
});
it('records nothing when the change set is empty', async () => {
const { service, saved } = build([]);
await service.recordChanges({ contractId: 'c-1', changes: [], actorId: 'u-1' });
expect(saved).toHaveLength(0);
});
it('still records the revision when the user lookup fails', async () => {
const { service, saved } = build([]);
Object.assign(service, {
dataSource: { query: jest.fn().mockRejectedValue(new Error('iam down')) },
});
await service.recordChanges({ contractId: 'c-1', changes: [change], actorId: 'u-1' });
expect(saved).toHaveLength(1);
expect(saved[0].actorName).toBeNull();
});
it('resolves names for legacy rows that predate the actor_name column', async () => {
const { service } = build([{ id: 'u-1', name: { en: 'Abenezer Haile' } }]);
Object.assign(service, {
revisionRepo: {
find: jest
.fn()
.mockResolvedValue([{ id: 'r-1', actorId: 'u-1', actorName: null }]),
},
});
const [revision] = await service.list('c-1');
expect(revision.actorName).toBe('Abenezer Haile');
});
});

81
apps/edr-freight-api/src/modules/contracts/contract-signature-asset.spec.ts Normal file
View File

@@ -0,0 +1,81 @@
import { Readable } from 'stream';
import { ContractTransitionService } from './contract-transition.service';
/**
* A stamp may be uploaded as JPEG/WebP while a drawn signature is always PNG.
* The type must survive the round-trip: data URL in → stored object extension
* → data URL out. Getting this wrong labels JPEG bytes as image/png in the
* contract PDF and leaves the seal to browser content-sniffing.
*/
describe('ContractTransitionService signature/stamp asset typing', () => {
const pngPixel =
'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAAAAAA6fptVAAAACklEQVR4nGMAAQAABQABDQottAAAAABJRU5ErkJggg==';
const jpegPixel = `data:image/jpeg;base64,${Buffer.from('fake-jpeg').toString('base64')}`;
/** Minimal service instance — only filesService/minioService are exercised. */
const build = () => {
const uploaded: Array<{ code: string; mimetype: string; name: string }> = [];
const filesService = {
upsertByCode: jest.fn(({ code, file }) => {
uploaded.push({ code, mimetype: file.mimetype, name: file.originalname });
return Promise.resolve({ id: `file-${code}`, url: `https://minio/x/${file.originalname}` });
}),
};
const minioService = {
getObjectNameFromUrl: (url: string) => url.split('/').pop() ?? '',
getFileStream: () => Promise.resolve(Readable.from(Buffer.from('bytes'))),
};
const service = Object.create(
ContractTransitionService.prototype,
) as ContractTransitionService;
Object.assign(service, { filesService, minioService });
return { service, uploaded };
};
const contract = { id: 'c-1', reference: 'CTR-2026-00001' };
it('stores a drawn PNG signature as image/png', async () => {
const { service, uploaded } = build();
await (service as never as {
uploadSignatureAsset: (c: unknown, code: string, b64: string) => Promise<unknown>;
}).uploadSignatureAsset(contract, 'signature_customer', pngPixel);
expect(uploaded[0].mimetype).toBe('image/png');
expect(uploaded[0].name).toBe('signature-customer-CTR-2026-00001.png');
});
it('keeps an uploaded JPEG stamp as image/jpeg, not image/png', async () => {
const { service, uploaded } = build();
await (service as never as {
uploadSignatureAsset: (c: unknown, code: string, b64: string) => Promise<unknown>;
}).uploadSignatureAsset(contract, 'stamp_customer', jpegPixel);
expect(uploaded[0].mimetype).toBe('image/jpeg');
expect(uploaded[0].name).toBe('stamp-customer-CTR-2026-00001.jpg');
});
it('inlines a stored .jpg back as a data:image/jpeg URI', async () => {
const { service } = build();
const inline = (service as never as {
inlineImageUrl: (url?: string | null) => Promise<string | null | undefined>;
}).inlineImageUrl.bind(service);
await expect(inline('https://minio/x/stamp-customer-CTR.jpg')).resolves.toMatch(
/^data:image\/jpeg;base64,/,
);
await expect(inline('https://minio/x/signature-customer-CTR.png')).resolves.toMatch(
/^data:image\/png;base64,/,
);
});
it('passes through empty and already-inlined values untouched', async () => {
const { service } = build();
const inline = (service as never as {
inlineImageUrl: (url?: string | null) => Promise<string | null | undefined>;
}).inlineImageUrl.bind(service);
await expect(inline(null)).resolves.toBeNull();
await expect(inline(pngPixel)).resolves.toBe(pngPixel);
});
});

131
apps/edr-freight-api/src/modules/contracts/contract-stamp-resign.spec.ts Normal file
View File

@@ -0,0 +1,131 @@
import { BadRequestException, ConflictException } from '@nestjs/common';
import { ContractTransitionService } from './contract-transition.service';
/**
* Signing is one-shot. The single exception: a contract signed before company
* stamps were required must be re-signable so the customer can attach one —
* otherwise counterSign's both-stamps gate strands it forever. These specs pin
* that exception open and pin everything else shut.
*/
describe('customer re-sign to attach a missing stamp', () => {
const contractReady = { id: 'c-1', reference: 'CTR-1', status: 'CONTRACT_READY' };
const signedNoStamp = { id: 'c-1', reference: 'CTR-1', status: 'SIGNED_CUSTOMER' };
const build = (contract: unknown, existingSignature: unknown) => {
const applied: unknown[] = [];
const service = Object.create(
ContractTransitionService.prototype,
) as ContractTransitionService;
Object.assign(service, {
contractsService: {
findById: jest.fn().mockResolvedValue(contract),
assertCustomerCanAccessContract: jest.fn().mockResolvedValue(undefined),
},
contractsRepository: {
findSignature: jest.fn().mockResolvedValue(existingSignature),
update: jest.fn().mockResolvedValue(undefined),
},
otpService: {
verifyOtpForAction: jest.fn().mockResolvedValue(undefined),
sendOtp: jest.fn().mockResolvedValue(undefined),
},
notifier: { customerSignedToStaff: jest.fn() },
resolveSignerContacts: jest.fn().mockResolvedValue({ phone: '+251900000000' }),
applySignature: jest.fn((...args: unknown[]) => {
applied.push(args);
return Promise.resolve();
}),
regenerateContractPdf: jest.fn().mockResolvedValue(undefined),
});
return { service, applied };
};
const dto = {
role: 'CUSTOMER' as const,
signerDisplayName: 'C. Customer',
signatureImageBase64: 'data:image/png;base64,AAAA',
stampImageBase64: 'data:image/png;base64,BBBB',
otp: '123456',
};
it('lets a customer sign again when their signature has no stamp', async () => {
const { service, applied } = build(signedNoStamp, {
id: 's-1',
role: 'CUSTOMER',
stampFileId: null,
});
await expect(service.sign('c-1', dto, { signerUserId: 'u-1' })).resolves.toBeDefined();
expect(applied).toHaveLength(1);
});
it('still refuses a second signature once a stamp is on file', async () => {
const { service } = build(signedNoStamp, {
id: 's-1',
role: 'CUSTOMER',
stampFileId: 'file-1',
});
// Stamped already → not the re-sign case, so the status guard rejects
// SIGNED_CUSTOMER before the already-signed check is reached.
await expect(service.sign('c-1', dto, { signerUserId: 'u-1' })).rejects.toBeInstanceOf(
ConflictException,
);
});
it('refuses a second signature on a still-ready contract', async () => {
const { service } = build(contractReady, {
id: 's-1',
role: 'CUSTOMER',
stampFileId: 'file-1',
});
await expect(service.sign('c-1', dto, { signerUserId: 'u-1' })).rejects.toThrow(
/already signed/i,
);
});
it('signs normally when nothing is on file yet', async () => {
const { service, applied } = build(contractReady, null);
await expect(service.sign('c-1', dto, { signerUserId: 'u-1' })).resolves.toBeDefined();
expect(applied).toHaveLength(1);
});
it('sends a signing OTP for the stamp re-sign', async () => {
const { service } = build(signedNoStamp, {
id: 's-1',
role: 'CUSTOMER',
stampFileId: null,
});
await expect(
service.sendSigningOtp('c-1', { signerUserId: 'u-1' }),
).resolves.toEqual(expect.objectContaining({ sentTo: expect.any(String) }));
});
it('refuses a signing OTP once the contract is signed and stamped', async () => {
const { service } = build(signedNoStamp, {
id: 's-1',
role: 'CUSTOMER',
stampFileId: 'file-1',
});
await expect(
service.sendSigningOtp('c-1', { signerUserId: 'u-1' }),
).rejects.toBeInstanceOf(ConflictException);
});
it('requires the OTP on the re-sign path too', async () => {
const { service } = build(signedNoStamp, {
id: 's-1',
role: 'CUSTOMER',
stampFileId: null,
});
await expect(
service.sign('c-1', { ...dto, otp: undefined }, { signerUserId: 'u-1' }),
).rejects.toBeInstanceOf(BadRequestException);
});
});

221
apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts
View File

@@ -22,6 +22,7 @@ import {
assertCanApproveContractStep,
assertFreightPermission,
canEditContractStep,
HAZARDOUS_APPROVAL_ROLES,
} from '../../common/freight-permission.util';
import {
FREIGHT_PERMS,
@@ -243,6 +244,7 @@ export class ContractTransitionService {
validityDays: number,
documentSnapshot?: ContractDocumentSnapshotInput | null,
user?: TCurrentUser | null,
window?: { validFrom?: string | null; validUntil?: string | null },
): Promise<Contract> {
const contract = await this.contractsService.findById(contractId);
// The route guard passes on either arm; the contract's freight type decides
@@ -259,11 +261,20 @@ export class ContractTransitionService {
);
}
await this.assertValidityDaysConfigured(validityDays);
// Staff picked an explicit window in the accept dialog — honour it verbatim
// (any start, any end). Only the legacy days-only payload is still held to
// the admin-configured period list.
const picked = window?.validFrom && window?.validUntil;
if (!picked) await this.assertValidityDaysConfigured(validityDays);
const validFrom = new Date();
const validUntil = new Date(validFrom);
validUntil.setDate(validUntil.getDate() + validityDays);
const validFrom = picked ? new Date(window!.validFrom!) : new Date();
const validUntil = picked ? new Date(window!.validUntil!) : new Date(validFrom);
if (!picked) validUntil.setDate(validUntil.getDate() + validityDays);
if (validUntil.getTime() <= validFrom.getTime()) {
throw new BadRequestException(
'The contract validity end date must be after the start date.',
);
}
await this.instantiateApprovalSteps(contract);
@@ -273,6 +284,20 @@ export class ContractTransitionService {
// shared six templates are never written here.
const snapshot = await this.resolveDocumentSnapshot(contract, documentSnapshot);
// Audit whatever staff changed in the accept dialog. The baseline is the
// template this contract would otherwise have frozen as-is, so an untouched
// accept diffs to nothing and records no revision.
if (documentSnapshot) {
const baseline = await this.resolveDocumentSnapshot(contract);
await this.documentHistory.record({
contractId,
before: baseline,
after: snapshot,
actorId,
actorRole: 'Reviewing staff',
});
}
await this.contractsRepository.update(contractId, {
status: 'PENDING_APPROVAL',
approvedByStaffId: actorId,
@@ -530,12 +555,26 @@ export class ContractTransitionService {
);
}
for (const rule of chain) {
await this.contractsRepository.createApprovalStep({
contractId: contract.id,
stepOrder: rule.stepOrder,
// Dangerous goods clear two dedicated hazardous desks BEFORE the commercial
// chain — if either refuses, the contract never reaches the approvers who
// would price and sign it. Steps are renumbered sequentially so the prefix
// and the configured chain form one ordered list.
const roles: Array<{ requiredRole: string; blocksRole: string | null }> = [
...(contract.isHazardous ? [...HAZARDOUS_APPROVAL_ROLES] : []).map(
(requiredRole) => ({ requiredRole, blocksRole: null }),
),
...chain.map((rule) => ({
requiredRole: rule.requiredRole,
blocksRole: rule.blocksRole ?? null,
})),
];
for (const [index, role] of roles.entries()) {
await this.contractsRepository.createApprovalStep({
contractId: contract.id,
stepOrder: index + 1,
requiredRole: role.requiredRole,
blocksRole: role.blocksRole,
status: 'PENDING',
});
}
@@ -928,23 +967,41 @@ export class ContractTransitionService {
});
}
/** Replace MinIO signature URLs with inline data URIs so they render in the PDF. */
/**
* Replace MinIO signature/stamp URLs with inline data URIs so they render in
* the PDF — Chromium cannot fetch the private bucket.
*/
private async inlineSignatureImages(
signatures: Array<{ signatureImageUrl?: string | null }>,
signatures: Array<{
signatureImageUrl?: string | null;
stampImageUrl?: string | null;
}>,
): Promise<void> {
for (const sig of signatures) {
if (!sig.signatureImageUrl) continue;
try {
if (sig.signatureImageUrl.startsWith('data:')) continue;
const objectName = this.minioService.getObjectNameFromUrl(
sig.signatureImageUrl,
);
const stream = await this.minioService.getFileStream(objectName);
const buffer = await this.streamToBuffer(stream);
sig.signatureImageUrl = `data:image/png;base64,${buffer.toString('base64')}`;
} catch {
/* keep original url */
}
sig.signatureImageUrl = await this.inlineImageUrl(sig.signatureImageUrl);
sig.stampImageUrl = await this.inlineImageUrl(sig.stampImageUrl);
}
}
/** MinIO URL → data URI. Returns the input unchanged if absent or on failure. */
private async inlineImageUrl(
url?: string | null,
): Promise<string | null | undefined> {
if (!url || url.startsWith('data:')) return url;
try {
const objectName = this.minioService.getObjectNameFromUrl(url);
const stream = await this.minioService.getFileStream(objectName);
const buffer = await this.streamToBuffer(stream);
const extension = objectName.split('.').pop()?.toLowerCase();
const mime =
extension === 'jpg' || extension === 'jpeg'
? 'image/jpeg'
: extension === 'webp'
? 'image/webp'
: 'image/png';
return `data:${mime};base64,${buffer.toString('base64')}`;
} catch {
return url;
}
}
@@ -959,6 +1016,46 @@ export class ContractTransitionService {
});
}
/**
* base64 (data URL or raw) → image FileRecord stored on the contract under
* `code`. Drawn signatures are always PNG; an uploaded stamp may be JPEG or
* WebP, so the type is read off the data-URL prefix rather than assumed —
* the stored extension is what {@link inlineImageUrl} reads it back as.
*/
private async uploadSignatureAsset(
contract: Contract,
code: string,
imageBase64: string,
): Promise<FileRecord> {
const mimetype =
/^data:(image\/[a-z+]+);base64,/i.exec(imageBase64)?.[1]?.toLowerCase() ??
'image/png';
const extension = mimetype === 'image/jpeg' ? 'jpg' : mimetype.split('/')[1];
const raw = imageBase64.includes(',')
? imageBase64.split(',')[1]!
: imageBase64;
const buffer = Buffer.from(raw, 'base64');
const file: Express.Multer.File = {
fieldname: code,
originalname: `${code.replace(/_/g, '-')}-${contract.reference}.${extension}`,
encoding: '7bit',
mimetype,
size: buffer.length,
buffer,
stream: Readable.from(buffer),
destination: '',
filename: '',
path: '',
};
return this.filesService.upsertByCode({
resourceId: contract.id,
resource: 'contracts',
code,
file,
});
}
/** Apply a digital signature row (mirrors booking-contract.service). */
private async applySignature(
contract: Contract,
@@ -985,29 +1082,28 @@ export class ContractTransitionService {
);
}
const raw = imageBase64.includes(',')
? imageBase64.split(',')[1]!
: imageBase64;
const buffer = Buffer.from(raw, 'base64');
const sigFile: Express.Multer.File = {
fieldname: `signature_${role.toLowerCase()}`,
originalname: `signature-${role.toLowerCase()}-${contract.reference}.png`,
encoding: '7bit',
mimetype: 'image/png',
size: buffer.length,
buffer,
stream: Readable.from(buffer),
destination: '',
filename: '',
path: '',
};
// The company stamp is a separate image from the drawn signature. Both
// parties to the contract (client + EDR) must seal it; DIRECTOR/CEO rows
// are internal approval signatures, not party seals, so they stay exempt.
const stampRequired = role === 'CUSTOMER' || role === 'STAFF';
if (stampRequired && !dto.stampImageBase64) {
throw new BadRequestException(
'A company stamp is required to sign this contract.',
);
}
const fileRecord = await this.filesService.upsertByCode({
resourceId: contract.id,
resource: 'contracts',
code: `signature_${role.toLowerCase()}`,
file: sigFile,
});
const fileRecord = await this.uploadSignatureAsset(
contract,
`signature_${role.toLowerCase()}`,
imageBase64,
);
const stampRecord = dto.stampImageBase64
? await this.uploadSignatureAsset(
contract,
`stamp_${role.toLowerCase()}`,
dto.stampImageBase64,
)
: null;
await this.contractsRepository.saveSignature({
contractId: contract.id,
@@ -1015,6 +1111,7 @@ export class ContractTransitionService {
signerDisplayName,
signedAt: new Date(),
signatureFileId: fileRecord.id,
stampFileId: stampRecord?.id ?? null,
consentText: dto.consentText ?? null,
});
@@ -1053,7 +1150,17 @@ export class ContractTransitionService {
options.signerUserId,
contract,
);
assertContractStatus(contract, ['CONTRACT_READY']);
// SIGNED_CUSTOMER is allowed only for the re-sign-to-add-a-stamp case that
// {@link sign} permits — otherwise the code would be useless on arrival.
const existing = await this.contractsRepository.findSignature(
contractId,
'CUSTOMER',
);
const addingMissingStamp = Boolean(existing) && !existing?.stampFileId;
assertContractStatus(
contract,
addingMissingStamp ? ['CONTRACT_READY', 'SIGNED_CUSTOMER'] : ['CONTRACT_READY'],
);
const signerContacts = await this.resolveSignerContacts(options.signerUserId);
await this.otpService.sendOtp(signerContacts);
@@ -1077,9 +1184,16 @@ export class ContractTransitionService {
options.signerUserId,
contract,
);
assertContractStatus(contract, ['CONTRACT_READY']);
const existing = await this.contractsRepository.findSignature(contractId, 'CUSTOMER');
if (existing) {
// Signing is one-shot, with one exception: a contract signed before the
// company stamp was required has to be sealed before EDR can counter-sign
// it, so the customer may sign again purely to attach the missing stamp.
const addingMissingStamp = Boolean(existing) && !existing?.stampFileId;
assertContractStatus(
contract,
addingMissingStamp ? ['CONTRACT_READY', 'SIGNED_CUSTOMER'] : ['CONTRACT_READY'],
);
if (existing && !addingMissingStamp) {
throw new BadRequestException('Customer has already signed this contract');
}
// Sudo-mode gate: a fresh, single-use OTP must be verified before the
@@ -1127,6 +1241,19 @@ export class ContractTransitionService {
const contract = await this.contractsService.findById(contractId);
assertContractStatus(contract, ['SIGNED_CUSTOMER']);
// Both parties' stamps must be on file before the contract executes. The
// EDR stamp is enforced by applySignature below; the customer's is checked
// here so a contract signed before stamps existed can't slip through.
const customerSignature = await this.contractsRepository.findSignature(
contractId,
'CUSTOMER',
);
if (!customerSignature?.stampFileId) {
throw new BadRequestException(
'The customer stamp is missing on this contract — it cannot be counter-signed until the customer signs again with their company stamp.',
);
}
await this.applySignature(contract, dto, options);
const now = new Date();

109
apps/edr-freight-api/src/modules/contracts/contracts.controller.ts
View File

@@ -303,8 +303,10 @@ export class ContractsController {
@Param('id', ParseUUIDPipe) id: string,
@Body() dto: UpdateContractDto,
@UploadedFiles() files: Express.Multer.File[],
// Recorded on the edit's audit revision — who changed the contract.
@CurrentUser() user?: TCurrentUser,
) {
return this.contractsService.update(id, dto, files ?? []);
return this.contractsService.update(id, dto, files ?? [], user?.id);
}
@Delete(':id')
@@ -358,6 +360,7 @@ export class ContractsController {
dto.validityDays,
dto.documentSnapshot,
user,
{ validFrom: dto.validFrom, validUntil: dto.validUntil },
);
}
@@ -738,6 +741,92 @@ export class ContractsController {
return this.clearanceService.finalizePreClearance(id);
}
@Post(':id/clearance/transit-assignee/request')
@BookingStaff(FREIGHT_PERMS.contracts.clearanceEtActions)
@ApiOperation({
summary:
'GL ET asks GL Djibouti to name the transit officer — required before the customs declaration',
})
requestTransitAssignee(
@Param('id', ParseUUIDPipe) id: string,
@Body('note') note: string | undefined,
@CurrentUser() user: AuthUserPayload,
) {
return this.clearanceService.requestTransitAssignee(
id,
note,
resolveAuthUserId(user),
);
}
@Post(':id/clearance/transit-assignee/assign')
@BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
@ApiOperation({
summary:
'GL Djibouti names the transit officer (free text) — unblocks the customs declaration; calling again reassigns',
})
assignTransitAssignee(
@Param('id', ParseUUIDPipe) id: string,
@Body('assignee') assignee: string,
@CurrentUser() user: AuthUserPayload,
) {
return this.clearanceService.assignTransitAssignee(
id,
assignee,
resolveAuthUserId(user),
);
}
@Get(':id/clearance/documents/:fileKey/versions')
@BookingStaff(FREIGHT_PERMS.contracts.clearanceReview)
@ApiOperation({
summary:
'Version history of one clearance document — the customer original plus every staff replacement',
})
documentVersions(
@Param('id', ParseUUIDPipe) id: string,
@Param('fileKey') fileKey: string,
) {
return this.clearanceService.documentVersions(id, fileKey);
}
@Post(':id/clearance/documents/:fileKey/replace')
@BookingStaff(FREIGHT_PERMS.contracts.clearanceReview)
@UseInterceptors(FileInterceptor('file'))
@ApiConsumes('multipart/form-data')
@ApiOperation({
summary:
'GL replaces a clearance document in place (reason required) — the previous version is kept in the file history and the new one needs approving',
})
replaceClearanceDocument(
@Param('id', ParseUUIDPipe) id: string,
@Param('fileKey') fileKey: string,
@UploadedFile() file: Express.Multer.File,
@Body('reason') reason: string,
@CurrentUser() user: AuthUserPayload,
) {
return this.clearanceService.replaceDocument(
id,
fileKey,
file,
resolveAuthUserId(user),
reason,
);
}
@Post(':id/clearance/duty/dispute')
@ApiOperation({
summary:
'Customer disputes the advised duty/tax with a reason — reopens the step so GL Ethiopia can re-advise (repeatable)',
})
disputeContractDuty(
@Param('id', ParseUUIDPipe) id: string,
@Body('note') note: string,
@CurrentUser() user: AuthUserPayload,
) {
return this.clearanceService.disputeDuty(id, note, resolveAuthUserId(user));
}
@Post(':id/clearance/duty-slip')
@UseInterceptors(FileInterceptor('file'))
@ApiConsumes('multipart/form-data')
@@ -766,19 +855,21 @@ export class ContractsController {
@BookingStaff(FREIGHT_PERMS.contracts.clearanceDjActions)
@UseInterceptors(FileInterceptor('file'))
@ApiConsumes('multipart/form-data')
@ApiOperation({ summary: 'GL DJ uploads Delivery Order (import)' })
@ApiOperation({
summary:
'GL DJ uploads Delivery Order (import) with vessel arrival + DO collected dates',
})
uploadDeliveryOrder(
@Param('id', ParseUUIDPipe) id: string,
@UploadedFile() file: Express.Multer.File,
@Body('vesselDepartureDate') vesselDepartureDate: string | undefined,
@Body('vesselArrivalDate') vesselArrivalDate: string | undefined,
@Body('doCollectedDate') doCollectedDate: string | undefined,
@CurrentUser() user: AuthUserPayload,
) {
return this.clearanceService.uploadDeliveryOrder(
id,
file,
resolveAuthUserId(user),
vesselDepartureDate,
);
return this.clearanceService.uploadDeliveryOrder(id, file, resolveAuthUserId(user), {
vesselArrivalDate,
doCollectedDate,
});
}
@Post(':id/clearance/release-order')

2
apps/edr-freight-api/src/modules/contracts/contracts.module.ts
View File

@@ -21,6 +21,7 @@ import { ContractTemplatesModule } from '../contract-templates/contract-template
import { ContractsController } from './contracts.controller';
import { ContractsService } from './contracts.service';
import { ContractsRepository } from './contracts.repository';
import { ContractExpiryService } from './contract-expiry.service';
import { ContractPricingService } from './contract-pricing.service';
import { ContractNotifierService } from './contract-notifier.service';
import { ContractTransitionService } from './contract-transition.service';
@@ -105,6 +106,7 @@ import { ContractDocumentViewModelBuilder } from '../../contracts/contract-docum
providers: [
ContractsService,
ContractsRepository,
ContractExpiryService,
ContractPricingService,
ContractNotifierService,
ContractTransitionService,

103
apps/edr-freight-api/src/modules/contracts/contracts.repository.ts
View File

@@ -14,6 +14,7 @@ import {
import { ContractRateSnapshot } from './entities/contract-rate-snapshot.entity';
import { ContractReviewNote, ContractReviewNoteType } from './entities/contract-review-note.entity';
import { ContractSignature, ContractSignerRole } from './entities/contract-signature.entity';
import { TERMINAL_CONTRACT_STATUSES } from './utils/contract-expiry.util';
export interface ContractListFilterOptions {
statuses?: string[];
@@ -66,6 +67,81 @@ export class ContractsRepository extends BaseRepository<Contract> {
return Number(row?.max ?? 0);
}
/**
* Non-terminal contracts for the same company + service type, with routes
* loaded — candidates for the duplicate-contract check on create(). Terminal
* filtering happens in JS via isEffectivelyExpired (also covers the
* date-passed-but-not-yet-cron-flipped case).
*/
async findDuplicateCandidates(
companyId: string,
serviceTypeId: string,
): Promise<Contract[]> {
return this.repository
.createQueryBuilder('contract')
.leftJoinAndSelect('contract.routes', 'routes')
.where('contract.deleted_at IS NULL')
.andWhere('contract.company_id = :companyId', { companyId })
.andWhere('contract.service_type_id = :serviceTypeId', { serviceTypeId })
.andWhere('contract.status NOT IN (:...terminal)', {
terminal: TERMINAL_CONTRACT_STATUSES,
})
// A ONE_TIME contract allows a single booking, so once that booking
// exists the contract is spent and can never carry another shipment.
// Without this it kept blocking new requests on the same service type +
// route until its validity lapsed — locking a customer out of a lane for
// the rest of the term after one completed shipment.
.andWhere(
`(contract.contract_kind <> 'ONE_TIME' OR NOT EXISTS (
SELECT 1 FROM freight.bookings b
WHERE b.contract_id = contract.id AND b.deleted_at IS NULL
))`,
)
.getMany();
}
/**
* Nightly expiry sweep: flips lapsed contracts to EXPIRED. Returns the
* number of rows updated (for cron logging).
*/
async expireLapsedContracts(): Promise<number> {
const result = await this.repository
.createQueryBuilder()
.update(Contract)
.set({ status: 'EXPIRED' })
.where('deleted_at IS NULL')
.andWhere('status NOT IN (:...terminal)', { terminal: TERMINAL_CONTRACT_STATUSES })
.andWhere('contract_valid_until IS NOT NULL AND contract_valid_until < :now', {
now: new Date(),
})
.execute();
return result.affected ?? 0;
}
/**
* Live contracts whose validity ends between `days` and `days + 1` days from
* now — the slice the daily expiry-reminder cron warns about. The window is
* rolling and exactly 24h wide, so consecutive daily runs tile it without
* gaps or overlaps: each contract is picked up by exactly one run and the
* customer is notified once, with no "already reminded" flag to store.
*/
async findExpiringInDays(days: number): Promise<Contract[]> {
const now = Date.now();
return this.repository
.createQueryBuilder('contract')
.where('contract.deleted_at IS NULL')
.andWhere('contract.status NOT IN (:...terminal)', {
terminal: TERMINAL_CONTRACT_STATUSES,
})
.andWhere('contract.contract_valid_until >= :from', {
from: new Date(now + days * 86_400_000),
})
.andWhere('contract.contract_valid_until < :to', {
to: new Date(now + (days + 1) * 86_400_000),
})
.getMany();
}
/** Find a contract by ID with all child collections, service type, company and files. */
async findByIdWithRelations(id: string): Promise<Contract | null> {
if (!id) return null;
@@ -88,7 +164,9 @@ export class ContractsRepository extends BaseRepository<Contract> {
'contract.files',
FileRecord,
'file',
"file.resource_id = contract.id AND file.resource = 'contracts'",
// Superseded versions are soft-deleted, not dropped — keep them out of
// the live file list (a manual join condition is not filtered for us).
"file.resource_id = contract.id AND file.resource = 'contracts' AND file.deleted_at IS NULL",
)
.getOne();
@@ -434,7 +512,7 @@ export class ContractsRepository extends BaseRepository<Contract> {
findSignatures(contractId: string): Promise<ContractSignature[]> {
return this.dataSource.getRepository(ContractSignature).find({
where: { contractId },
relations: ['signatureFile'],
relations: ['signatureFile', 'stampFile'],
order: { signedAt: 'ASC' },
});
}
@@ -445,7 +523,7 @@ export class ContractsRepository extends BaseRepository<Contract> {
): Promise<ContractSignature | null> {
return this.dataSource.getRepository(ContractSignature).findOne({
where: { contractId, role },
relations: ['signatureFile'],
relations: ['signatureFile', 'stampFile'],
});
}
@@ -482,6 +560,17 @@ export class ContractsRepository extends BaseRepository<Contract> {
);
}
/** Review notes of one type, newest first — the duty advice/dispute rounds. */
async findReviewNotes(
contractId: string,
noteType: ContractReviewNoteType,
): Promise<ContractReviewNote[]> {
return this.dataSource.getRepository(ContractReviewNote).find({
where: { contractId, noteType },
order: { createdAt: 'DESC' },
});
}
async findLatestReviewNote(
contractId: string,
noteType?: ContractReviewNoteType,
@@ -649,12 +738,20 @@ export class ContractsRepository extends BaseRepository<Contract> {
ContractClearanceCycle,
| 'dutyRequired'
| 'vesselDepartureDate'
| 'vesselArrivalDate'
| 'doCollectedDate'
| 'roAmendmentRequestedAt'
| 'roHoldReason'
| 'currentPhase'
| 'status'
| 'preClearanceFinalizedAt'
| 'completedAt'
| 'transitAssigneeRequestedAt'
| 'transitAssigneeRequestedByUserId'
| 'transitAssigneeRequestNote'
| 'transitAssigneeName'
| 'transitAssigneeAssignedAt'
| 'transitAssigneeAssignedByUserId'
>
>,
): Promise<void> {

142
apps/edr-freight-api/src/modules/contracts/contracts.service.ts
View File

@@ -1,5 +1,6 @@
import {
BadRequestException,
ConflictException,
ForbiddenException,
Injectable,
NotFoundException,
@@ -24,6 +25,9 @@ import { ContractListSummaryDto } from './dto/contract-list-summary.dto';
import { Contract, CONTRACT_STATUSES, CONTRACT_CUSTOMER_EDITABLE_STATUSES } from './entities/contract.entity';
import { ContractRoute } from './entities/contract-route.entity';
import { ContractCargoScope } from './entities/contract-cargo-scope.entity';
import { isEffectivelyExpired } from './utils/contract-expiry.util';
import { diffContractFields } from './contract-document-diff.util';
import { ContractDocumentHistoryService } from './contract-document-history.service';
import { FileRecord } from '../files/entities/file.entity';
/** Paginated contract list: flat `total` (backoffice) + `meta` block (portal). */
@@ -40,6 +44,35 @@ export interface PaginatedContracts {
};
}
/** Route list as a readable lane string, e.g. "Nagad → Mojo, Mojo → Adama". */
function describeRoutes(routes?: ContractRoute[]): string | null {
if (!routes?.length) return null;
return [...routes]
.sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))
.map(
(r) =>
`${r.originYard?.label ?? r.originYardId} → ${r.destinationYard?.label ?? r.destinationYardId}`,
)
.join(', ');
}
/** Cargo scope as a readable string, e.g. "20ft ×2, 40ft ×1" or "Wheat ×500". */
function describeCargoScope(scope?: ContractCargoScope[]): string | null {
if (!scope?.length) return null;
return scope
.map((row) => {
const label =
row.containerSize ??
row.cargoType?.cargoTypeName ??
row.cargoFreeText ??
row.cargoTypeId ??
'cargo';
return row.quantityCap != null ? `${label} ×${row.quantityCap}` : String(label);
})
.sort()
.join(', ');
}
const NEEDS_ACTION_STATUSES = [
'SUBMITTED',
'PENDING_APPROVAL',
@@ -55,6 +88,7 @@ export class ContractsService {
private readonly companiesService: CompaniesService,
private readonly filesService: FilesService,
private readonly minioService: MinioService,
private readonly documentHistory: ContractDocumentHistoryService,
) {}
/** Generate a unique contract reference number (CTR-YYYY-NNNNN). */
@@ -155,6 +189,42 @@ export class ContractsService {
}
}
/**
* Same customer + same service type + an overlapping route already has a
* non-expired contract → block. A route "overlaps" if any origin/destination
* pair matches — good enough today since ONE_TIME and GENERAL contracts both
* carry a single route in practice, and still correct if that changes.
*/
private async assertNoDuplicateContract(
companyId: string,
serviceTypeId: string,
routes: CreateContractDto['routes'],
): Promise<void> {
const candidates = await this.contractsRepository.findDuplicateCandidates(
companyId,
serviceTypeId,
);
const duplicate = candidates.find(
(c) =>
!isEffectivelyExpired(c) &&
(c.routes ?? []).some((existingRoute) =>
routes.some(
(r) =>
r.originYardId === existingRoute.originYardId &&
r.destinationYardId === existingRoute.destinationYardId,
),
),
);
if (duplicate) {
const until = duplicate.contractValidUntil
? duplicate.contractValidUntil.toISOString().slice(0, 10)
: 'its approval completes';
throw new ConflictException(
`An active contract already exists for this service type and route (${duplicate.reference}, valid until ${until}). A new request can't be submitted until it expires or is rejected/cancelled.`,
);
}
}
/** Create a new contract (DRAFT) with its routes and cargo-scope rows. */
async create(
dto: CreateContractDto,
@@ -186,6 +256,9 @@ export class ContractsService {
this.assertCargoScopeShape(dto.freightType, dto.cargoScope);
this.assertRouteShape(dto.contractKind, dto.routes);
await this.assertRoutesMatchDirection(dto.tradeDirection, dto.routes);
if (companyId) {
await this.assertNoDuplicateContract(companyId, dto.serviceTypeId, dto.routes);
}
// Stamp the operational profile for portal scoping. A forwarder contract
// pins its profile explicitly (trade direction can't tell it apart from a
@@ -291,7 +364,11 @@ export class ContractsService {
tradeDirection: dto.tradeDirection,
freightType: dto.freightType,
serviceTypeId: dto.serviceTypeId,
paymentCurrency: dto.paymentCurrency,
// A contract is always QUOTED in USD — the billing currency is chosen per
// booking (or on the shipment request when GL books for the customer), so
// any client-supplied currency here is ignored. Contracts created before
// this rule keep whatever they stored; update() never rewrites it.
paymentCurrency: 'USD',
customsClearingEnabled: includesCustoms,
customsClearingAgent: includesCustoms ? null : (dto.customsClearingAgent ?? null),
equipmentReturn: dto.equipmentReturn ?? null,
@@ -302,6 +379,10 @@ export class ContractsService {
lastMileDeliveryLat: dto.lastMileDeliveryLat ?? null,
lastMileDeliveryLng: dto.lastMileDeliveryLng ?? null,
isHazardous: dto.isHazardous ?? false,
// Hazard class / UN number only exist on a hazardous contract — a stale
// pair from an earlier draft must never survive the flag being turned off.
hazardClass: dto.isHazardous ? (dto.hazardClass ?? null) : null,
unNumber: dto.isHazardous ? (dto.unNumber ?? null) : null,
isReefer: dto.isReefer ?? false,
contractType: dto.contractType ?? null,
status: 'DRAFT',
@@ -445,6 +526,7 @@ export class ContractsService {
id: string,
dto: UpdateContractDto,
files: Express.Multer.File[],
actorId?: string,
): Promise<{ contract: Contract; warnings: string[] }> {
const existing = await this.findById(id);
if (!CONTRACT_CUSTOMER_EDITABLE_STATUSES.includes(existing.status as never)) {
@@ -471,9 +553,18 @@ export class ContractsService {
tradeDirection: dto.tradeDirection ?? existing.tradeDirection,
freightType,
serviceTypeId: dto.serviceTypeId ?? existing.serviceTypeId,
paymentCurrency: dto.paymentCurrency ?? existing.paymentCurrency,
// Never rewritten: grandfathered contracts keep the currency (and frozen
// snapshots) they were signed with.
paymentCurrency: existing.paymentCurrency,
isHazardous: dto.isHazardous ?? existing.isHazardous,
isReefer: dto.isReefer ?? existing.isReefer,
// Same rule as create: clearing the flag clears the declaration with it.
hazardClass: (dto.isHazardous ?? existing.isHazardous)
? (dto.hazardClass ?? existing.hazardClass ?? null)
: null,
unNumber: (dto.isHazardous ?? existing.isHazardous)
? (dto.unNumber ?? existing.unNumber ?? null)
: null,
equipmentReturn: dto.equipmentReturn ?? existing.equipmentReturn,
firstMilePickupAddress: dto.firstMilePickupAddress ?? existing.firstMilePickupAddress,
firstMilePickupLat: dto.firstMilePickupLat ?? existing.firstMilePickupLat,
@@ -524,7 +615,52 @@ export class ContractsService {
existing.companyProfileId ?? null,
);
return { contract: await this.findById(id), warnings };
const updated = await this.findById(id);
// Audit what this edit actually changed. Runs after the writes so the
// "after" side is read back from the contract rather than from the DTO.
await this.recordFieldRevision(existing, updated, actorId);
return { contract: updated, warnings };
}
/** Fields worth auditing on a customer edit, read off a loaded contract. */
private auditableFields(contract: Contract): Record<string, unknown> {
return {
contractKind: contract.contractKind,
tradeDirection: contract.tradeDirection,
freightType: contract.freightType,
serviceType: contract.serviceType?.serviceName ?? contract.serviceTypeId,
paymentCurrency: contract.paymentCurrency,
contractType: contract.contractType,
isHazardous: contract.isHazardous,
hazardClass: contract.hazardClass,
unNumber: contract.unNumber,
isReefer: contract.isReefer,
equipmentReturn: contract.equipmentReturn,
customsClearingAgent: contract.customsClearingAgent,
firstMilePickupAddress: contract.firstMilePickupAddress,
lastMileDeliveryAddress: contract.lastMileDeliveryAddress,
routes: describeRoutes(contract.routes),
cargoScope: describeCargoScope(contract.cargoScope),
};
}
/** Append a revision describing a customer's edit to the contract itself. */
private async recordFieldRevision(
before: Contract,
after: Contract,
actorId?: string,
): Promise<void> {
const changes = diffContractFields(
this.auditableFields(before),
this.auditableFields(after),
);
await this.documentHistory.recordChanges({
contractId: after.id,
changes,
actorId: actorId ?? null,
actorRole: 'Customer',
});
}
/** Parse comma-separated or repeated status query values. */

46
apps/edr-freight-api/src/modules/contracts/do-collection-dates.spec.ts Normal file
View File

@@ -0,0 +1,46 @@
import { BadRequestException } from '@nestjs/common';
import { assertDoCollectionDates } from './contract-clearance.util';
describe('assertDoCollectionDates', () => {
it('requires both dates', () => {
expect(() => assertDoCollectionDates(undefined)).toThrow(BadRequestException);
expect(() =>
assertDoCollectionDates({ vesselArrivalDate: '2026-07-01' }),
).toThrow(/DO collected date is required/);
expect(() =>
assertDoCollectionDates({ doCollectedDate: '2026-07-01' }),
).toThrow(/Vessel arrival date is required/);
// Whitespace is not a date.
expect(() =>
assertDoCollectionDates({ vesselArrivalDate: ' ', doCollectedDate: ' ' }),
).toThrow(BadRequestException);
});
it('rejects a DO collected before the vessel arrived', () => {
expect(() =>
assertDoCollectionDates({
vesselArrivalDate: '2026-07-10',
doCollectedDate: '2026-07-09',
}),
).toThrow(/cannot be earlier than the vessel arrival date/);
});
it('normalizes an ISO datetime down to its date part', () => {
expect(
assertDoCollectionDates({
vesselArrivalDate: '2026-07-10T21:00:00.000Z',
doCollectedDate: '2026-07-10T05:00:00.000Z',
}),
).toEqual({ vesselArrivalDate: '2026-07-10', doCollectedDate: '2026-07-10' });
});
it('rejects a malformed date', () => {
expect(() =>
assertDoCollectionDates({
vesselArrivalDate: '10/07/2026',
doCollectedDate: '2026-07-10',
}),
).toThrow(/not a valid date/);
});
});

24
apps/edr-freight-api/src/modules/contracts/dto/accept-contract.dto.ts
View File

@@ -1,6 +1,13 @@
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { Type } from 'class-transformer';
import { IsInt, IsOptional, Max, Min, ValidateNested } from 'class-validator';
import {
IsDateString,
IsInt,
IsOptional,
Max,
Min,
ValidateNested,
} from 'class-validator';
import { UpdateContractDocumentDto } from './contract-document.dto';
@@ -18,6 +25,21 @@ export class AcceptContractDto {
@Max(3650)
validityDays!: number;
/**
* Explicit validity window picked by staff in the accept dialog. When both are
* present they win over `validityDays` (which is then only the derived span)
* and the configured-period check is skipped — staff may enter any range.
*/
@ApiPropertyOptional({ description: 'Validity start (ISO date)' })
@IsOptional()
@IsDateString()
validFrom?: string;
@ApiPropertyOptional({ description: 'Validity end (ISO date)' })
@IsOptional()
@IsDateString()
validUntil?: string;
/**
* Optional per-contract document override edited by staff in the accept
* dialog. When present its articles are frozen onto THIS contract; when

10
apps/edr-freight-api/src/modules/contracts/dto/create-booking-request.dto.ts
View File

@@ -2,6 +2,7 @@ import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { Transform, Type } from 'class-transformer';
import {
IsArray,
IsIn,
IsInt,
IsNumber,
IsOptional,
@@ -91,6 +92,15 @@ export class CreateBookingRequestDto {
@Type(() => RequestBulkLineDto)
bulk?: RequestBulkLineDto;
@ApiPropertyOptional({
enum: ['ETB', 'USD'],
description:
'Billing currency for the shipment GL will book. Intercity is always ETB.',
})
@IsOptional()
@IsIn(['ETB', 'USD'])
paymentCurrency?: string;
@ApiPropertyOptional()
@IsOptional()
@IsString()

16
apps/edr-freight-api/src/modules/contracts/dto/create-booking-under-contract.dto.ts
View File

@@ -15,6 +15,8 @@ import {
ValidateNested,
} from 'class-validator';
import { PAYMENT_CURRENCIES } from './create-contract.dto';
/** Per-shipment equipment return — "NA" stays contract-level only. */
const SHIPMENT_EQUIPMENT_RETURNS = ['WITH_RETURN', 'WITHOUT_RETURN'] as const;
@@ -150,6 +152,20 @@ export class CreateBookingUnderContractDto {
@IsUUID()
contractRouteId?: string;
/**
* The contract quotes in USD; the customer picks the billing currency here.
* Omitted → the contract's own currency (USD for contracts created under the
* current rule, the grandfathered currency for older ones). Intercity is
* forced to ETB by the service regardless of what is sent.
*/
@ApiPropertyOptional({
enum: PAYMENT_CURRENCIES,
description: 'Billing currency for this shipment. Intercity is always ETB.',
})
@IsOptional()
@IsIn([...PAYMENT_CURRENCIES])
paymentCurrency?: string;
@ApiPropertyOptional({
description:
'Binding shipment day. Omitted for intercity (DOMESTIC) bookings — staff assign a passing train later.',

39
apps/edr-freight-api/src/modules/contracts/dto/create-contract.dto.ts
View File

@@ -17,6 +17,8 @@ import {
ValidateNested,
} from 'class-validator';
import { HAZARD_CLASS_VALUES } from '@edr/types';
import { CONTRACT_KINDS } from '../entities/contract.entity';
const TRADE_DIRECTIONS = ['IMPORT', 'EXPORT', 'DOMESTIC'] as const;
@@ -156,9 +158,20 @@ export class CreateContractDto {
@IsUUID()
serviceTypeId!: string;
@ApiProperty({ enum: PAYMENT_CURRENCIES })
/**
* Deprecated at the contract level. A contract now always quotes in USD; the
* customer picks the billing currency per booking (or on the shipment request
* when GL books on their behalf). Accepted but ignored on create so older
* clients don't break — the service forces USD.
*/
@ApiPropertyOptional({
enum: PAYMENT_CURRENCIES,
deprecated: true,
description: 'Ignored — contracts always quote in USD. Choose currency at booking.',
})
@IsOptional()
@IsIn([...PAYMENT_CURRENCIES])
paymentCurrency!: string;
paymentCurrency?: string;
@ApiPropertyOptional({ description: 'Whether EDR/GL handles customs clearance' })
@IsOptional()
@@ -228,6 +241,28 @@ export class CreateContractDto {
@Transform(({ value }) => value === 'true' || value === true)
isHazardous?: boolean;
@ApiPropertyOptional({
enum: HAZARD_CLASS_VALUES,
description: 'UN/ADR dangerous-goods class. Required when isHazardous.',
})
@ValidateIf((o: CreateContractDto) => o.isHazardous === true)
@IsIn(HAZARD_CLASS_VALUES, {
message: `hazardClass must be one of: ${HAZARD_CLASS_VALUES.join(', ')}`,
})
hazardClass?: string;
@ApiPropertyOptional({
description: 'UN number of the dangerous good. Required when isHazardous.',
})
@ValidateIf((o: CreateContractDto) => o.isHazardous === true)
@IsString()
@MinLength(1)
@MaxLength(16)
@Transform(({ value }) =>
typeof value === 'string' ? value.trim().toUpperCase() : value,
)
unNumber?: string;
@ApiPropertyOptional({ default: false, description: 'Sets contracts.is_reefer' })
@IsOptional()
@IsBoolean()

11
apps/edr-freight-api/src/modules/contracts/dto/sign-contract.dto.ts
View File

@@ -17,6 +17,17 @@ export class SignContractDto {
@MinLength(20)
signatureImageBase64?: string;
@ApiPropertyOptional({
description:
'PNG company stamp/seal image as base64 (with or without data URL prefix). ' +
'Required for the CUSTOMER and STAFF roles — both parties must seal the ' +
'contract before it is fully executed.',
})
@IsOptional()
@IsString()
@MinLength(20)
stampImageBase64?: string;
@ApiProperty()
@IsString()
@MinLength(1)

8
apps/edr-freight-api/src/modules/contracts/entities/booking-request.entity.ts
View File

@@ -43,6 +43,14 @@ export class BookingRequest extends BaseEntity {
@Column({ name: 'requested_lines', type: 'jsonb', default: () => "'{}'::jsonb" })
requestedLines!: Freight.RequestedShipmentLines;
/**
* Billing currency the customer chose for this shipment. The contract quotes
* in USD; on a customs contract GL creates the booking, so this is where the
* customer states which currency to be invoiced in.
*/
@Column({ name: 'payment_currency', type: 'varchar', length: 5, nullable: true })
paymentCurrency?: string | null;
@Column({ name: 'notes', type: 'text', nullable: true })
notes?: string | null;

35
apps/edr-freight-api/src/modules/contracts/entities/contract-clearance-cycle.entity.ts
View File

@@ -43,6 +43,41 @@ export class ContractClearanceCycle extends BaseEntity {
@Column({ name: 'vessel_departure_date', type: 'date', nullable: true })
vesselDepartureDate?: string | null;
/** Import DO: when the vessel arrived in Djibouti. Required on DO upload. */
@Column({ name: 'vessel_arrival_date', type: 'date', nullable: true })
vesselArrivalDate?: string | null;
/** Import DO: when GL Djibouti collected the DO. Required on DO upload. */
@Column({ name: 'do_collected_date', type: 'date', nullable: true })
doCollectedDate?: string | null;
/**
* Transit-assignee handshake that runs BEFORE the customs declaration: GL
* Ethiopia asks Djibouti for the officer who will handle the shipment in
* transit, and Djibouti answers with a name. The declaration step stays shut
* until `transitAssigneeName` is set; Djibouti may overwrite it later
* (reassignment) and the newer name simply wins.
*/
@Column({ name: 'transit_assignee_requested_at', type: 'timestamptz', nullable: true })
transitAssigneeRequestedAt?: Date | null;
@Column({ name: 'transit_assignee_requested_by_user_id', type: 'uuid', nullable: true })
transitAssigneeRequestedByUserId?: string | null;
/** What GL Ethiopia asked for — shown on the Djibouti queue. */
@Column({ name: 'transit_assignee_request_note', type: 'text', nullable: true })
transitAssigneeRequestNote?: string | null;
/** The officer Djibouti named — free text, no user directory to bind to. */
@Column({ name: 'transit_assignee_name', type: 'text', nullable: true })
transitAssigneeName?: string | null;
@Column({ name: 'transit_assignee_assigned_at', type: 'timestamptz', nullable: true })
transitAssigneeAssignedAt?: Date | null;
@Column({ name: 'transit_assignee_assigned_by_user_id', type: 'uuid', nullable: true })
transitAssigneeAssignedByUserId?: string | null;
@Column({ name: 'ro_amendment_requested_at', type: 'timestamptz', nullable: true })
roAmendmentRequestedAt?: Date | null;

7
apps/edr-freight-api/src/modules/contracts/entities/contract-document-revision.entity.ts
View File

@@ -21,6 +21,13 @@ export class ContractDocumentRevision extends BaseEntity {
@Column({ name: 'actor_id', type: 'uuid', nullable: true })
actorId?: string | null;
/**
* Who made the edit, captured at the time. Denormalised so the trail still
* names them after a rename or a deactivated account.
*/
@Column({ name: 'actor_name', type: 'varchar', length: 200, nullable: true })
actorName?: string | null;
/** The approval step's required role at the time of the edit. */
@Column({ name: 'actor_role', type: 'varchar', length: 64, nullable: true })
actorRole?: string | null;

5
apps/edr-freight-api/src/modules/contracts/entities/contract-review-note.entity.ts
View File

@@ -8,6 +8,11 @@ export const CONTRACT_REVIEW_NOTE_TYPES = [
'STAFF_NOTE',
'CUSTOMER_NOTE',
'AMENDMENT',
/**
* The customer disputed the advised duty & tax and asked GL Ethiopia to
* correct it. One row per round — the advice/dispute loop can repeat.
*/
'DUTY_DISPUTE',
] as const;
export type ContractReviewNoteType =
(typeof CONTRACT_REVIEW_NOTE_TYPES)[number];

8
apps/edr-freight-api/src/modules/contracts/entities/contract-signature.entity.ts
View File

@@ -29,6 +29,14 @@ export class ContractSignature extends BaseEntity {
@JoinColumn({ name: 'signature_file_id' })
signatureFile?: FileRecord | null;
/** Company stamp/seal image, uploaded alongside the drawn signature. */
@Column({ name: 'stamp_file_id', type: 'uuid', nullable: true })
stampFileId?: string | null;
@ManyToOne(() => FileRecord, { nullable: true })
@JoinColumn({ name: 'stamp_file_id' })
stampFile?: FileRecord | null;
@Column({ name: 'consent_text', type: 'text', nullable: true })
consentText?: string | null;

8
apps/edr-freight-api/src/modules/contracts/entities/contract.entity.ts
View File

@@ -188,6 +188,14 @@ export class Contract extends BaseEntity {
@Column({ name: 'is_hazardous', type: 'boolean', default: false })
isHazardous!: boolean;
/** UN/ADR dangerous-goods class (CLASS_1..CLASS_9); null unless hazardous. */
@Column({ name: 'hazard_class', type: 'varchar', length: 16, nullable: true })
hazardClass?: string | null;
/** UN number of the dangerous good; null unless hazardous. */
@Column({ name: 'un_number', type: 'varchar', length: 16, nullable: true })
unNumber?: string | null;
@Column({ name: 'is_reefer', type: 'boolean', default: false })
isReefer!: boolean;

85
apps/edr-freight-api/src/modules/contracts/shipment-currency.spec.ts Normal file
View File

@@ -0,0 +1,85 @@
import { ContractBookingService } from './contract-booking.service';
import { BookingPricingService } from '../bookings/booking-pricing.service';
import type { Contract } from './entities/contract.entity';
import type { ContractRateSnapshot } from './entities/contract-rate-snapshot.entity';
const contract = (over: Partial<Contract>): Contract =>
({ tradeDirection: 'IMPORT', paymentCurrency: 'USD', ...over }) as Contract;
/** The private resolver, reached without standing up the whole Nest graph. */
const resolveCurrency = (c: Contract, requested?: string | null): string =>
(
ContractBookingService.prototype as unknown as {
resolveShipmentCurrency: (c: Contract, r?: string | null) => string;
}
).resolveShipmentCurrency(c, requested);
const snapshot = (currency: string, unitPrice: number): ContractRateSnapshot =>
({ rateCode: 'CONTAINER_20FT', currency, unitPrice }) as ContractRateSnapshot;
const frozenByCode = (
snap: ContractRateSnapshot | null,
bookingCurrency: string,
usdToEtb: number,
): ContractRateSnapshot | null =>
(
BookingPricingService.prototype as unknown as {
frozenRateByCode: (
m: Map<string, ContractRateSnapshot> | null,
code: string,
bookingCurrency: string,
usdToEtb: number,
) => ContractRateSnapshot | null;
}
).frozenRateByCode(
snap ? new Map([['CONTAINER_20FT', snap]]) : null,
'CONTAINER_20FT',
bookingCurrency,
usdToEtb,
);
describe('per-shipment billing currency', () => {
it('takes the customer choice over the contract', () => {
expect(resolveCurrency(contract({}), 'ETB')).toBe('ETB');
expect(resolveCurrency(contract({}), 'USD')).toBe('USD');
});
it('falls back to the contract currency when none is chosen', () => {
// Grandfathered ETB contract with no explicit choice.
expect(resolveCurrency(contract({ paymentCurrency: 'ETB' }))).toBe('ETB');
expect(resolveCurrency(contract({}), ' ')).toBe('USD');
});
it('forces ETB on intercity whatever was requested', () => {
const domestic = contract({ tradeDirection: 'DOMESTIC' });
expect(resolveCurrency(domestic, 'USD')).toBe('ETB');
expect(resolveCurrency(domestic)).toBe('ETB');
});
});
describe('frozen contract rate in the booking currency', () => {
it('converts a USD snapshot for an ETB booking instead of dropping it', () => {
// The old behaviour returned null here, which silently re-priced the
// booking at live rates and lost the agreed contract price.
expect(frozenByCode(snapshot('USD', 400), 'ETB', 150)?.unitPrice).toBe(60_000);
});
it('converts a grandfathered ETB snapshot back for a USD booking', () => {
expect(frozenByCode(snapshot('ETB', 60_000), 'USD', 150)?.unitPrice).toBe(400);
});
it('passes a matching-currency snapshot through untouched', () => {
const snap = snapshot('USD', 400);
expect(frozenByCode(snap, 'USD', 1)).toBe(snap);
});
it('refuses to price off an unusable exchange rate', () => {
// Converting with 0 would zero the whole line.
expect(frozenByCode(snapshot('USD', 400), 'ETB', 0)).toBeNull();
expect(frozenByCode(snapshot('USD', 400), 'ETB', Number.NaN)).toBeNull();
});
it('returns null when there is no snapshot', () => {
expect(frozenByCode(null, 'ETB', 150)).toBeNull();
});
});

175
apps/edr-freight-api/src/modules/contracts/transit-assignee.spec.ts Normal file
View File

@@ -0,0 +1,175 @@
import { BadRequestException } from '@nestjs/common';
import { ContractClearanceService } from './contract-clearance.service';
import type { Contract } from './entities/contract.entity';
/**
* Pre-declaration transit-assignee handshake. GL Ethiopia asks Djibouti who will
* handle the shipment in transit; Djibouti answers with a name. The customs
* declaration stays shut until that name exists, and Djibouti may send a
* different one later.
*/
describe('ContractClearanceService — transit assignee', () => {
const contract = (over: Partial<Contract> = {}): Contract =>
({
id: 'ctr-1',
reference: 'CTR-2026-00042',
tradeDirection: 'IMPORT',
customsClearingEnabled: true,
contractKind: 'ONE_TIME',
...over,
}) as Contract;
let repo: { currentCycle: jest.Mock; updateCycle: jest.Mock };
let contractsService: { findById: jest.Mock };
let notifier: {
transitAssigneeRequested: jest.Mock;
transitAssigneeAssigned: jest.Mock;
};
let service: ContractClearanceService;
const cycle = (over: Record<string, unknown> = {}) => ({
id: 'cyc-1',
transitAssigneeRequestedAt: null,
transitAssigneeName: null,
...over,
});
beforeEach(() => {
repo = {
currentCycle: jest.fn().mockResolvedValue(cycle()),
updateCycle: jest.fn().mockResolvedValue(undefined),
};
contractsService = { findById: jest.fn().mockResolvedValue(contract()) };
notifier = {
transitAssigneeRequested: jest.fn(),
transitAssigneeAssigned: jest.fn(),
};
service = new ContractClearanceService(
repo as never,
contractsService as never,
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
{} as never,
notifier as never,
);
});
describe('request (GL Ethiopia)', () => {
it('stamps the ask and pings Djibouti', async () => {
await service.requestTransitAssignee('ctr-1', ' Reefer, needs a cold-chain officer ', 'et-1');
const patch = repo.updateCycle.mock.calls[0][1];
expect(patch.transitAssigneeRequestedAt).toBeInstanceOf(Date);
expect(patch.transitAssigneeRequestedByUserId).toBe('et-1');
expect(patch.transitAssigneeRequestNote).toBe(
'Reefer, needs a cold-chain officer',
);
expect(notifier.transitAssigneeRequested).toHaveBeenCalled();
});
});
describe('assign (GL Djibouti)', () => {
it('records the officer and tells Ethiopia they can proceed', async () => {
repo.currentCycle.mockResolvedValue(
cycle({ transitAssigneeRequestedAt: new Date() }),
);
await service.assignTransitAssignee('ctr-1', ' Ahmed Bourhan ', 'dj-1');
const patch = repo.updateCycle.mock.calls[0][1];
expect(patch.transitAssigneeName).toBe('Ahmed Bourhan');
expect(patch.transitAssigneeAssignedByUserId).toBe('dj-1');
expect(notifier.transitAssigneeAssigned).toHaveBeenCalledWith(
expect.objectContaining({ id: 'ctr-1' }),
'Ahmed Bourhan',
null,
);
});
it('reassigns, carrying the previous name into the notice', async () => {
repo.currentCycle.mockResolvedValue(
cycle({
transitAssigneeRequestedAt: new Date(),
transitAssigneeName: 'Ahmed Bourhan',
}),
);
await service.assignTransitAssignee('ctr-1', 'Fatouma Ali', 'dj-1');
expect(notifier.transitAssigneeAssigned).toHaveBeenCalledWith(
expect.anything(),
'Fatouma Ali',
'Ahmed Bourhan',
);
});
it('refuses an empty name', async () => {
repo.currentCycle.mockResolvedValue(
cycle({ transitAssigneeRequestedAt: new Date() }),
);
await expect(
service.assignTransitAssignee('ctr-1', ' ', 'dj-1'),
).rejects.toBeInstanceOf(BadRequestException);
});
it('refuses before Ethiopia has asked', async () => {
await expect(
service.assignTransitAssignee('ctr-1', 'Ahmed Bourhan', 'dj-1'),
).rejects.toThrow(/not requested/i);
});
});
describe('declaration gate', () => {
const ensure = (c: Contract) =>
(
service as unknown as {
ensureDeclarationPrerequisites: (id: string, c: Contract) => Promise<void>;
}
).ensureDeclarationPrerequisites('ctr-1', c);
beforeEach(() => {
// Documents are approved; only the assignee decides the outcome here.
(
service as unknown as { isClearanceFullyApproved: unknown }
).isClearanceFullyApproved = jest.fn().mockResolvedValue(true);
});
it('tells GL to raise the request when none exists', async () => {
await expect(ensure(contract())).rejects.toThrow(
/Request a transit assignee/i,
);
});
it('tells GL to wait when Djibouti has not answered', async () => {
repo.currentCycle.mockResolvedValue(
cycle({ transitAssigneeRequestedAt: new Date() }),
);
await expect(ensure(contract())).rejects.toThrow(/has not assigned/i);
});
it('lets the declaration through once the officer is named', async () => {
repo.currentCycle.mockResolvedValue(
cycle({
transitAssigneeRequestedAt: new Date(),
transitAssigneeName: 'Ahmed Bourhan',
}),
);
(
service as unknown as { workflowService: unknown }
).workflowService = {
listMilestones: jest
.fn()
.mockResolvedValue([
{ milestoneCode: 'DOCUMENTS_APPROVED', status: 'COMPLETED' },
]),
};
await expect(ensure(contract())).resolves.toBeUndefined();
});
});
});

25
apps/edr-freight-api/src/modules/contracts/utils/contract-expiry.util.ts Normal file
View File

@@ -0,0 +1,25 @@
import type { Contract } from '../entities/contract.entity';
/** Statuses that already mean "done/void" — a contract in one of these never blocks a duplicate. */
export const TERMINAL_CONTRACT_STATUSES = [
'REJECTED',
'CANCELLED',
'CONTRACT_CLOSED',
'ARCHIVED',
'EXPIRED',
] as const;
/**
* True once a contract is done, either explicitly (terminal status) or by date
* (past contractValidUntil). Checked by date too because the nightly expiry
* cron only flips the status once a day — this keeps same-day checks correct
* even a few hours before the cron runs.
*/
export function isEffectivelyExpired(
contract: Pick<Contract, 'status' | 'contractValidUntil'>,
): boolean {
if ((TERMINAL_CONTRACT_STATUSES as readonly string[]).includes(contract.status)) {
return true;
}
return Boolean(contract.contractValidUntil && contract.contractValidUntil < new Date());
}

12
apps/edr-freight-api/src/modules/files/entities/file.entity.ts
View File

@@ -53,4 +53,16 @@ export class FileRecord extends BaseEntity {
@Column({ name: "reviewed_at", type: "timestamptz", nullable: true })
reviewedAt!: Date | null;
/**
* Who replaced this version, when a newer file took its place. Superseded
* versions are soft-deleted rather than dropped, so the original a customer
* uploaded survives a staff correction and the two can be compared.
*/
@Column({ name: "replaced_by_user_id", type: "uuid", nullable: true })
replacedByUserId!: string | null;
/** Why the file was replaced — shown on the document's version history. */
@Column({ name: "replace_reason", type: "text", nullable: true })
replaceReason!: string | null;
}

37
apps/edr-freight-api/src/modules/files/files.repository.ts
View File

@@ -41,12 +41,47 @@ export class FilesRepository extends BaseRepository<FileRecord> {
return this.repository.findOne({ where: { resourceId, resource, code } });
}
/**
* Retire the live version(s) of a document code. SOFT delete on purpose: the
* bytes and the row stay so the original upload can still be read back from
* the version history after staff replace it. Every normal read already
* filters soft-deleted rows, so callers see only the current version.
*
* `replacedBy` / `reason` are stamped on the retired row when a newer file is
* taking its place (as opposed to a plain removal).
*/
async deleteByCode(
resourceId: string,
resource: string,
code: string,
replacedBy?: { userId?: string | null; reason?: string | null },
): Promise<void> {
await this.repository.delete({ resourceId, resource, code });
if (replacedBy) {
await this.repository.update(
{ resourceId, resource, code },
{
replacedByUserId: replacedBy.userId ?? null,
replaceReason: replacedBy.reason ?? null,
},
);
}
await this.repository.softDelete({ resourceId, resource, code });
}
/**
* Every version of one document code, newest first — superseded versions
* included. The only read that deliberately looks past the soft-delete filter.
*/
findVersionHistory(
resourceId: string,
resource: string,
code: string,
): Promise<FileRecord[]> {
return this.repository.find({
where: { resourceId, resource, code },
withDeleted: true,
order: { createdAt: "DESC" },
});
}
/**

112
apps/edr-freight-api/src/modules/files/files.service.spec.ts Normal file
View File

@@ -0,0 +1,112 @@
import { FilesService } from './files.service';
/**
* Replacing a stored document must never destroy the previous one: the customer
* uploaded it, and a staff correction has to stay auditable against it. The old
* row is soft-deleted (so every normal read still returns exactly the current
* version) and stamped with who replaced it and why.
*/
describe('FilesService — document versions', () => {
const file = {
originalname: 'bill-of-lading.pdf',
size: 1234,
mimetype: 'application/pdf',
buffer: Buffer.from('x'),
} as Express.Multer.File;
let filesRepository: {
deleteByCode: jest.Mock;
create: jest.Mock;
findVersionHistory: jest.Mock;
};
let service: FilesService;
beforeEach(() => {
filesRepository = {
deleteByCode: jest.fn().mockResolvedValue(undefined),
create: jest.fn(async (row) => ({ id: 'file-new', ...row })),
findVersionHistory: jest.fn().mockResolvedValue([]),
};
service = new FilesService(
filesRepository as never,
{
uploadFile: jest.fn().mockResolvedValue('https://minio/bucket/new.pdf'),
getObjectNameFromUrl: (u: string) => u,
getSignedUrl: jest.fn(),
} as never,
);
});
it('stamps the retired version with who replaced it and why', async () => {
await service.upsertByCode(
{ resourceId: 'ctr-1', resource: 'contracts', code: 'bill_of_lading', file },
{ userId: 'gl-user-1', reason: 'Customer sent page 2 only' },
);
expect(filesRepository.deleteByCode).toHaveBeenCalledWith(
'ctr-1',
'contracts',
'bill_of_lading',
{ userId: 'gl-user-1', reason: 'Customer sent page 2 only' },
);
});
it('still replaces silently when no replacer is given (system overwrites)', async () => {
await service.upsertByCode({
resourceId: 'ctr-1',
resource: 'contracts',
code: 'contract_pdf',
file,
});
expect(filesRepository.deleteByCode).toHaveBeenCalledWith(
'ctr-1',
'contracts',
'contract_pdf',
undefined,
);
});
it('marks the live row current and the soft-deleted ones superseded', async () => {
filesRepository.findVersionHistory.mockResolvedValue([
{
id: 'v2',
name: 'corrected.pdf',
url: 'u2',
size: 2,
mimeType: 'application/pdf',
createdAt: new Date('2026-07-20T10:00:00Z'),
deletedAt: null,
replacedByUserId: null,
replaceReason: null,
},
{
id: 'v1',
name: 'original.pdf',
url: 'u1',
size: 1,
mimeType: 'application/pdf',
createdAt: new Date('2026-07-18T10:00:00Z'),
deletedAt: new Date('2026-07-20T10:00:00Z'),
replacedByUserId: 'gl-user-1',
replaceReason: 'Wrong page order',
},
]);
const versions = await service.versionHistory(
'ctr-1',
'contracts',
'bill_of_lading',
);
expect(versions[0]).toMatchObject({ id: 'v2', isCurrent: true, replacedAt: null });
expect(versions[1]).toMatchObject({
id: 'v1',
isCurrent: false,
replacedByUserId: 'gl-user-1',
replaceReason: 'Wrong page order',
});
// The customer's original is still readable — that is the whole point.
expect(versions[1].url).toBe('u1');
});
});

59
apps/edr-freight-api/src/modules/files/files.service.ts
View File

@@ -104,13 +104,66 @@ export class FilesService {
});
}
/** Replace existing file row for the same resource + code (e.g. contract PDF). */
async upsertByCode(input: CreateFileInput): Promise<FileRecord> {
/**
* Replace the file stored under a resource + code (e.g. contract PDF). The
* previous version is retired, not destroyed — pass `replacedBy` to record who
* swapped it and why, which is what the version history shows.
*/
async upsertByCode(
input: CreateFileInput,
replacedBy?: { userId?: string | null; reason?: string | null },
): Promise<FileRecord> {
const { resourceId, resource, code } = input;
await this.filesRepository.deleteByCode(resourceId, resource, code);
await this.filesRepository.deleteByCode(
resourceId,
resource,
code,
replacedBy,
);
return this.upload(input);
}
/**
* Every stored version of one document, newest first. `isCurrent` marks the
* live row; the rest are superseded uploads kept for audit.
*/
async versionHistory(
resourceId: string,
resource: string,
code: string,
): Promise<
Array<{
id: string;
name: string;
url: string;
size: number;
mimeType: string;
uploadedAt: string;
isCurrent: boolean;
replacedAt: string | null;
replacedByUserId: string | null;
replaceReason: string | null;
}>
> {
const rows = await this.filesRepository.findVersionHistory(
resourceId,
resource,
code,
);
return rows.map((row) => ({
id: row.id,
name: row.name,
url: row.url,
size: row.size,
mimeType: row.mimeType,
uploadedAt: row.createdAt.toISOString(),
isCurrent: row.deletedAt == null,
replacedAt: row.deletedAt ? row.deletedAt.toISOString() : null,
replacedByUserId: row.replacedByUserId,
replaceReason: row.replaceReason,
}));
}
async deleteByCode(
resourceId: string,
resource: string,

29
apps/edr-freight-api/src/modules/last-mile/dto/set-detention-times.dto.ts Normal file
View File

@@ -0,0 +1,29 @@
import { Type } from 'class-transformer';
import { IsArray, IsDateString, IsOptional, IsUUID, ValidateNested } from 'class-validator';
/**
* One truck's detention window. Each truck reaches the destination and is
* released at its own time, so detention days differ between trucks on the
* same delivery. Null clears the value (falls back to the leg-level pair).
*/
export class TruckDetentionTimeInput {
@IsUUID()
vehicleId!: string;
/** Detention clock start — this truck reached the destination. */
@IsOptional()
@IsDateString()
destinationArrivedAt?: string | null;
/** Detention clock end — this truck was released/returned. Omit = still out. */
@IsOptional()
@IsDateString()
returnedAt?: string | null;
}
export class SetDetentionTimesDto {
@IsArray()
@ValidateNested({ each: true })
@Type(() => TruckDetentionTimeInput)
trucks!: TruckDetentionTimeInput[];
}

15
apps/edr-freight-api/src/modules/last-mile/entities/last-mile-vehicle-assignment.entity.ts
View File

@@ -51,6 +51,21 @@ export class LastMileVehicleAssignment extends BaseEntity {
@Column({ name: 'departed_at', type: 'timestamptz', nullable: true })
departedAt?: Date | null;
/**
* Detention clock START for THIS truck: reached the delivery destination.
* Distinct from `arrivedAt` (warehouse gate-in). Null falls back to the
* leg-level `last_mile.arrived_at`.
*/
@Column({ name: 'destination_arrived_at', type: 'timestamptz', nullable: true })
destinationArrivedAt?: Date | null;
/**
* Detention clock END for THIS truck: released / returned by the customer.
* Null (with no leg-level `delivered_at`) means still out — detention accrues.
*/
@Column({ name: 'returned_at', type: 'timestamptz', nullable: true })
returnedAt?: Date | null;
/** Weighed gross on exit, in TONNES (not kg — see the migration note). */
@Column({ name: 'gross_weight_tons', type: 'numeric', precision: 14, scale: 3, nullable: true })
grossWeightTons?: number | null;

13
apps/edr-freight-api/src/modules/last-mile/last-mile.controller.ts
View File

@@ -23,6 +23,7 @@ import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
import { CreateLastMileDto } from './dto/create-last-mile.dto';
import { UpdateLastMileDto } from './dto/update-last-mile.dto';
import { SetVehiclesDto } from './dto/set-vehicles.dto';
import { SetDetentionTimesDto } from './dto/set-detention-times.dto';
import { SetDistancesDto } from './dto/set-distances.dto';
import { RecordProofOfDeliveryDto } from './dto/record-proof-of-delivery.dto';
import { LastMileStatus } from './entities/last-mile.entity';
@@ -131,6 +132,18 @@ export class LastMileController {
return this.lastMileService.setDistances(id, dto.distances, dto.remainingPayment);
}
@Post(':id/detention-times')
@BookingStaff(FREIGHT_PERMS.lastMile.update)
@ApiOperation({
summary: 'Set each truck\'s own detention window (arrived at destination / returned)',
})
async setDetentionTimes(
@Param('id', ParseUUIDPipe) id: string,
@Body() dto: SetDetentionTimesDto,
) {
return this.lastMileService.setDetentionTimes(id, dto.trucks);
}
@Post(':id/proof-of-delivery')
@BookingStaff(FREIGHT_PERMS.lastMile.update)
@UseInterceptors(AnyFilesInterceptor())

40
apps/edr-freight-api/src/modules/last-mile/last-mile.service.ts
View File

@@ -869,6 +869,46 @@ export class LastMileService {
* sum and drives billing; `remainingPayment` (total km × rate) is recomputed
* client-side. Does NOT generate an invoice — that's a separate explicit step.
*/
/**
* Per-truck detention windows. Each truck reaches the destination and is
* released at its own time, so every truck gets its own clock (and therefore
* its own chargeable days). Locked once the detention invoice exists.
*/
async setDetentionTimes(
id: string,
trucks: Array<{
vehicleId: string;
destinationArrivedAt?: string | null;
returnedAt?: string | null;
}>,
): Promise<LastMile> {
await this.findById(id);
const invoices = await this.billing.findBySourceIds('last_mile', [id]);
if (invoices.length) {
throw new BadRequestException(
'Detention times cannot be changed after the invoice is generated',
);
}
for (const t of trucks) {
const start = t.destinationArrivedAt ? new Date(t.destinationArrivedAt) : null;
const end = t.returnedAt ? new Date(t.returnedAt) : null;
if (start && end && end.getTime() < start.getTime()) {
throw new BadRequestException(
'A truck cannot be returned before it arrived — check the detention times',
);
}
await this.dataSource.manager.update(
LastMileVehicleAssignment,
{ lastMileId: id, vehicleId: t.vehicleId },
{ destinationArrivedAt: start, returnedAt: end },
);
}
return this.findById(id);
}
async setDistances(
id: string,
distances: Array<{ vehicleId: string; distanceKm: number }>,

21
apps/edr-freight-api/src/modules/locomotives/dto/create-locomotive.dto.ts
View File

@@ -65,25 +65,4 @@ export class CreateLocomotiveDto {
@IsNumber()
@Min(0)
overageToleranceMeters?: number;
@ApiPropertyOptional({ example: 4200 })
@IsOptional()
@Transform(({ value }) => (value === '' || value == null ? undefined : Number(value)))
@IsNumber()
@Min(0)
powerKw?: number;
@ApiPropertyOptional({ example: 300 })
@IsOptional()
@Transform(({ value }) => (value === '' || value == null ? undefined : Number(value)))
@IsNumber()
@Min(0)
tractionForceKn?: number;
@ApiPropertyOptional({ example: 120 })
@IsOptional()
@Transform(({ value }) => (value === '' || value == null ? undefined : Number(value)))
@IsNumber()
@Min(0)
maxSpeedKmh?: number;
}

9
apps/edr-freight-api/src/modules/locomotives/entities/locomotive.entity.ts
View File

@@ -76,15 +76,6 @@ export class Locomotive extends BaseEntity {
@JoinColumn({ name: 'current_yard_id' })
currentYard?: Yard | null;
@Column({ name: 'power_kw', type: 'numeric', precision: 10, scale: 3, nullable: true })
powerKw?: number | null;
@Column({ name: 'traction_force_kn', type: 'numeric', precision: 10, scale: 3, nullable: true })
tractionForceKn?: number | null;
@Column({ name: 'max_speed_kmh', type: 'numeric', precision: 10, scale: 3, nullable: true })
maxSpeedKmh?: number | null;
@OneToMany(() => TrainSet, (trainSet) => trainSet.locomotive)
trainSets?: TrainSet[];
}

8
apps/edr-freight-api/src/modules/locomotives/locomotives.service.ts
View File

@@ -113,9 +113,6 @@ export class LocomotivesService {
maxTrainLengthMeters: dto.maxTrainLengthMeters,
overageToleranceTons: dto.overageToleranceTons ?? null,
overageToleranceMeters: dto.overageToleranceMeters ?? null,
powerKw: dto.powerKw ?? null,
tractionForceKn: dto.tractionForceKn ?? null,
maxSpeedKmh: dto.maxSpeedKmh ?? null,
});
}
@@ -176,11 +173,6 @@ export class LocomotivesService {
? locomotive.currentYardId
: (dto.currentYardId ?? null),
name: dto.name === undefined ? locomotive.name : dto.name?.trim() || null,
powerKw: dto.powerKw === undefined ? locomotive.powerKw : dto.powerKw ?? null,
tractionForceKn:
dto.tractionForceKn === undefined ? locomotive.tractionForceKn : dto.tractionForceKn ?? null,
maxSpeedKmh:
dto.maxSpeedKmh === undefined ? locomotive.maxSpeedKmh : dto.maxSpeedKmh ?? null,
});
if (!updated) {

80
apps/edr-freight-api/src/modules/routes/routes.duplicate.spec.ts Normal file
View File

@@ -0,0 +1,80 @@
import { ConflictException } from '@nestjs/common';
import type { DataSource } from 'typeorm';
import { RoutesService } from './routes.service';
import type { RoutesRepository } from './routes.repository';
type StopSeq = Array<{ yardId: string; sequenceNo: number }>;
/** DataSource stub whose Route repository returns the given existing routes. */
const serviceWith = (
existing: Array<{ id: string; milestones: StopSeq }>,
): RoutesService => {
const dataSource = {
getRepository: () => ({ find: async () => existing }),
} as unknown as DataSource;
return new RoutesService(dataSource, {} as RoutesRepository);
};
const assertNotDuplicate = (
service: RoutesService,
yardIds: string[],
excludeRouteId?: string,
): Promise<void> =>
(
service as unknown as {
assertNotDuplicate: (
m: Array<{ yardId: string }>,
id?: string,
) => Promise<void>;
}
).assertNotDuplicate(
yardIds.map((yardId) => ({ yardId })),
excludeRouteId,
);
describe('RoutesService duplicate guard', () => {
const addisAdamaDire: StopSeq = [
{ yardId: 'addis', sequenceNo: 1 },
{ yardId: 'adama', sequenceNo: 2 },
{ yardId: 'dire', sequenceNo: 3 },
];
it('rejects an identical stop sequence', async () => {
const service = serviceWith([{ id: 'r1', milestones: addisAdamaDire }]);
await expect(
assertNotDuplicate(service, ['addis', 'adama', 'dire']),
).rejects.toBeInstanceOf(ConflictException);
});
it('allows the same endpoints with a different corridor', async () => {
// Same origin + destination, but skipping Adama is a genuinely other route.
const service = serviceWith([{ id: 'r1', milestones: addisAdamaDire }]);
await expect(
assertNotDuplicate(service, ['addis', 'dire']),
).resolves.toBeUndefined();
});
it('does not flag the route being edited against itself', async () => {
const service = serviceWith([{ id: 'r1', milestones: addisAdamaDire }]);
await expect(
assertNotDuplicate(service, ['addis', 'adama', 'dire'], 'r1'),
).resolves.toBeUndefined();
});
it('compares stops by sequence, not storage order', async () => {
const shuffled: StopSeq = [
{ yardId: 'dire', sequenceNo: 3 },
{ yardId: 'addis', sequenceNo: 1 },
{ yardId: 'adama', sequenceNo: 2 },
];
const service = serviceWith([{ id: 'r1', milestones: shuffled }]);
await expect(
assertNotDuplicate(service, ['addis', 'adama', 'dire']),
).rejects.toBeInstanceOf(ConflictException);
});
});

55
apps/edr-freight-api/src/modules/routes/routes.service.ts
View File

@@ -5,7 +5,7 @@ import {
NotFoundException,
} from '@nestjs/common';
import { TrainScheduleStatus } from '@edr/types';
import { DataSource, In } from 'typeorm';
import { DataSource, In, Not } from 'typeorm';
import { deriveTradeDirection } from '../../common/derive-trade-direction.util';
import { Yard } from '../rule-engine/entities/yard.entity';
@@ -15,7 +15,7 @@ import { CreateRouteDto } from './dto/create-route.dto';
import { FilterRoutesDto } from './dto/filter-routes.dto';
import { UpdateRouteDto } from './dto/update-route.dto';
import { RouteMilestone } from './entities/route-milestone.entity';
import { formatRouteLabel, Route } from './entities/route.entity';
import { formatRouteLabel, Route, type RouteStatus } from './entities/route.entity';
import { RoutesRepository } from './routes.repository';
/** Order-insensitive key: distances are symmetric. */
@@ -88,6 +88,7 @@ export class RoutesService {
async create(dto: CreateRouteDto): Promise<Route> {
const validated = await this.validateMilestones(dto.milestones);
await this.assertNotDuplicate(validated.milestones);
const route = await this.dataSource.transaction(async (manager) => {
const savedRoute = await manager.getRepository(Route).save(
@@ -123,6 +124,11 @@ export class RoutesService {
? await this.validateMilestones(dto.milestones)
: null;
// An edit can collide with another route just as easily as a create can.
if (milestoneInput) {
await this.assertNotDuplicate(milestoneInput.milestones, id);
}
// Milestones or endpoints are about to be rewritten — reject if any
// non-terminal schedule still references this route, otherwise its stop list
// and distances would silently shift under a live plan. Status-only /
@@ -187,6 +193,51 @@ export class RoutesService {
return this.findById(id);
}
/**
* A route IS its ordered stop list — "Addis → Adama → Dire Dawa" and
* "Addis → Dire Dawa" share endpoints but are different corridors. So the
* duplicate test compares the full yard sequence, not just origin/destination.
*
* Decommissioned routes (STOP_WORKING) are ignored: replacing a retired
* corridor with a fresh one is exactly what an admin does after deactivating,
* and there is no reactivate action to fall back on.
*/
private async assertNotDuplicate(
milestones: Array<{ yardId: string }>,
excludeRouteId?: string,
): Promise<void> {
const signature = milestones.map((m) => m.yardId).join('>');
const candidates = await this.dataSource.getRepository(Route).find({
where: {
originYardId: milestones[0].yardId,
destinationYardId: milestones[milestones.length - 1].yardId,
status: Not<RouteStatus>('STOP_WORKING'),
},
relations: {
originYard: true,
destinationYard: true,
milestones: { yard: true },
},
});
const duplicate = candidates.find((route) => {
if (route.id === excludeRouteId) return false;
const stops = [...(route.milestones ?? [])]
.sort((a, b) => a.sequenceNo - b.sequenceNo)
.map((m) => m.yardId)
.join('>');
return stops === signature;
});
if (duplicate) {
throw new ConflictException(
`This route already exists: ${formatRouteLabel(duplicate)}. ` +
'Edit the existing route instead of creating a duplicate.',
);
}
}
private async validateMilestones(milestones: Array<{ yardId: string }>) {
if (milestones.length < 2) {
throw new BadRequestException('A route requires at least two yards');

70
apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.spec.ts Normal file
View File

@@ -0,0 +1,70 @@
import { allowedRateUnits, isBulkQuantityUnit } from "./rate-unit.util";
/**
* A bulk rate's weighting unit follows how its commodity is counted: wheat is
* weighed (per ton), machinery is counted (per item). Per-wagon is offered
* either way.
*/
describe("allowedRateUnits — bulk unit of measure", () => {
it("offers per-ton for a weighed commodity", () => {
expect(
allowedRateUnits({
appliesTo: "BULK",
trigger: "ALWAYS",
cargoUnitOfMeasure: "PER_TON",
}),
).toEqual(["PER_TON", "PER_WAGON"]);
});
it("offers per-item for a counted commodity", () => {
expect(
allowedRateUnits({
appliesTo: "BULK",
trigger: "ALWAYS",
cargoUnitOfMeasure: "PER_ITEM",
}),
).toEqual(["PER_ITEM", "PER_WAGON"]);
});
it("falls back to per-ton when the rate is not scoped to a commodity", () => {
expect(allowedRateUnits({ appliesTo: "BULK", trigger: "ALWAYS" })).toEqual([
"PER_TON",
"PER_WAGON",
]);
});
it("swaps the per-ton slot for counted commodities on every bulk-capable shape", () => {
expect(
allowedRateUnits({
appliesTo: "OTHER",
trigger: "CUSTOMS_CLEARANCE",
cargoKind: "BULK",
cargoUnitOfMeasure: "PER_ITEM",
}),
).toEqual(["PER_ITEM", "PER_WAGON"]);
expect(
allowedRateUnits({
appliesTo: "INTERCITY",
trigger: "ALWAYS",
cargoUnitOfMeasure: "PER_ITEM",
}),
).toEqual(["PER_CONTAINER", "PER_ITEM", "PER_WAGON", "PER_KM"]);
});
it("never offers per-item for overweight, which is always per excess ton", () => {
expect(
allowedRateUnits({
appliesTo: "OTHER",
trigger: "OVERWEIGHT",
cargoUnitOfMeasure: "PER_TON",
}),
).toEqual(["PER_TON"]);
});
it("treats per-ton and per-item as the same booking quantity", () => {
expect(isBulkQuantityUnit("PER_TON")).toBe(true);
expect(isBulkQuantityUnit("PER_ITEM")).toBe(true);
expect(isBulkQuantityUnit("PER_WAGON")).toBe(false);
expect(isBulkQuantityUnit("FLAT")).toBe(false);
});
});

30
apps/edr-freight-api/src/modules/rule-engine/entities/rate-unit.util.ts
View File

@@ -1,5 +1,17 @@
import type { RateAppliesTo, RateTrigger, RateUnit } from './rate.entity';
/** How the bulk commodity a rate is scoped to is counted (cargo_types.unit_of_measure). */
export type CargoUom = 'PER_TON' | 'PER_ITEM' | null | undefined;
/**
* Units billed against a booking's bulk quantity. That quantity is recorded in
* the commodity's own unit — tonnes for a PER_TON commodity, item count for a
* PER_ITEM one — so both units scale off the same field and only differ in what
* they are called.
*/
export const isBulkQuantityUnit = (unit: string): boolean =>
unit === 'PER_TON' || unit === 'PER_ITEM';
/**
* Which rate units make sense for a given rate shape. The weighting basis is
* driven by the *type* of thing being billed — a container leg bills per
@@ -8,6 +20,10 @@ import type { RateAppliesTo, RateTrigger, RateUnit } from './rate.entity';
* ton. This keeps the rate table dynamic yet non-conflicting: the admin can
* only pick a unit the pricing engine knows how to apply.
*
* A rate scoped to a break-bulk commodity (unit_of_measure = PER_ITEM) offers
* PER_ITEM wherever a weighed commodity offers PER_TON — machinery is priced
* per unit shipped, wheat per tonne. Per-wagon is offered either way.
*
* Returned lists are ordered with the most natural/default unit first.
*/
export function allowedRateUnits(input: {
@@ -15,6 +31,19 @@ export function allowedRateUnits(input: {
trigger: RateTrigger;
/** CUSTOMS_CLEARANCE only: which cargo kind the fee covers. */
cargoKind?: 'CONTAINER' | 'BULK' | null;
/** Unit of measure of the bulk commodity the rate is scoped to, when any. */
cargoUnitOfMeasure?: CargoUom;
}): RateUnit[] {
const units = unitsForShape(input);
return input.cargoUnitOfMeasure === 'PER_ITEM'
? units.map((u) => (u === 'PER_TON' ? 'PER_ITEM' : u))
: units;
}
function unitsForShape(input: {
appliesTo: RateAppliesTo;
trigger: RateTrigger;
cargoKind?: 'CONTAINER' | 'BULK' | null;
}): RateUnit[] {
const { appliesTo, trigger } = input;
@@ -81,6 +110,7 @@ export function isRateUnitAllowed(input: {
appliesTo: RateAppliesTo;
trigger: RateTrigger;
cargoKind?: 'CONTAINER' | 'BULK' | null;
cargoUnitOfMeasure?: CargoUom;
unit: RateUnit;
}): boolean {
return allowedRateUnits(input).includes(input.unit);

3
apps/edr-freight-api/src/modules/rule-engine/entities/rate.entity.ts
View File

@@ -34,6 +34,9 @@ export type RateStatus = typeof RATE_STATUSES[number];
export const RATE_UNITS = [
'PER_WAGON',
'PER_TON',
// Break-bulk commodities are counted, not weighed (cargo_types.unit_of_measure
// = PER_ITEM) — their rates bill per item off the same booking quantity field.
'PER_ITEM',
'PER_CONTAINER',
'PER_KM',
'PER_INVOICE',

3
apps/edr-freight-api/src/modules/rule-engine/interfaces/rates.repository.interface.ts
View File

@@ -14,7 +14,8 @@ export interface IRatesRepository {
findLiveRatesDetailed(): Promise<Rate[]>;
findByPattern(pattern: {
rateType: string;
rateUnit: string;
/** Omitted for singly-resolved rates — see the repository implementation. */
rateUnit?: string;
containerTypeId?: string | null;
cargoTypeId?: string | null;
tradeDirection?: string | null;

26
apps/edr-freight-api/src/modules/rule-engine/repositories/rates.repository.ts
View File

@@ -18,10 +18,17 @@ export class RatesRepository implements IRatesRepository {
return this.repo.findOne({ where: { id } });
}
/**
* Every LIVE rate, newest first. The ordering is load-bearing: pricing picks
* the first match for a pattern, so without it Postgres heap order decided
* which of two overlapping rates a booking was billed at. Newest-first also
* means the most recent configuration wins where legacy overlaps still exist.
*/
findLiveRates(): Promise<Rate[]> {
return this.repo
.createQueryBuilder('rate')
.where('rate.status = :status', { status: 'LIVE' })
.orderBy('rate.created_at', 'DESC')
.getMany();
}
@@ -47,9 +54,21 @@ export class RatesRepository implements IRatesRepository {
* insert so the admin gets a friendly error instead of a raw constraint fault.
* NULL scope columns are matched with IS NULL, mirroring the COALESCE index.
*/
/**
* The live/draft rate already covering a pricing pattern, if any.
*
* `rateUnit` is optional on purpose. Where pricing resolves ONE rate for a
* lane (base freight, customs, lashing, empty return) the unit is not part of
* the identity — a per-container and a per-wagon row for the same lane are
* two answers to one question and the engine picks whichever came back first,
* so the caller omits it and the second row is rejected. Additive surcharges
* (hazard, reefer, demurrage…) are the opposite: the engine bills every
* matching rate by its own unit, so one per freight shape is the design and
* the caller passes the unit to keep them apart.
*/
findByPattern(pattern: {
rateType: string;
rateUnit: string;
rateUnit?: string;
containerTypeId?: string | null;
cargoTypeId?: string | null;
tradeDirection?: string | null;
@@ -59,9 +78,12 @@ export class RatesRepository implements IRatesRepository {
const qb = this.repo
.createQueryBuilder('rate')
.where('rate.rate_type = :rateType', { rateType: pattern.rateType })
.andWhere('rate.rate_unit = :rateUnit', { rateUnit: pattern.rateUnit })
.andWhere('rate.status <> :superseded', { superseded: 'SUPERSEDED' });
if (pattern.rateUnit) {
qb.andWhere('rate.rate_unit = :rateUnit', { rateUnit: pattern.rateUnit });
}
if (pattern.containerTypeId) {
qb.andWhere('rate.container_type_id = :containerTypeId', { containerTypeId: pattern.containerTypeId });
} else {

6
apps/edr-freight-api/src/modules/rule-engine/rule-engine.service.ts
View File

@@ -2,6 +2,7 @@ import { Inject, Injectable, BadRequestException } from '@nestjs/common';
import { DataSource } from 'typeorm';
import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.entity';
import { Rate, RateTrigger } from './entities/rate.entity';
import { isBulkQuantityUnit } from './entities/rate-unit.util';
import {
ICargoTypesRepository,
CARGO_TYPES_REPOSITORY,
@@ -377,6 +378,9 @@ export class RuleEngineService {
let calculatedAmount: number;
switch (rate.rateUnit) {
// PER_ITEM is PER_TON for a counted (break-bulk) commodity — the bulk
// quantity is recorded in the commodity's own unit either way.
case 'PER_ITEM':
case 'PER_TON':
// OVERWEIGHT bills the excess tons; every other PER_TON surcharge
// (e.g. bulk reefer) bills the full bulk tonnage.
@@ -608,7 +612,7 @@ export class RuleEngineService {
if (!rate) return modifiers;
const billedQty =
rate.rateUnit === 'PER_TON'
isBulkQuantityUnit(rate.rateUnit)
? Math.max(0, Number(input.bulkTons ?? 0))
: rate.rateUnit === 'PER_WAGON'
? Math.max(0, Number(input.bulkWagons ?? 0))

138
apps/edr-freight-api/src/modules/rule-engine/services/rates.duplicate-pattern.spec.ts Normal file
View File

@@ -0,0 +1,138 @@
import { ConflictException } from '@nestjs/common';
import { RatesService } from './rates.service';
import type { Rate } from '../entities/rate.entity';
/**
* One rate per lane + scope, whatever the unit.
*
* Pricing resolves a single rate for a (type, container type, leg) and then
* applies whatever unit it carries — it has no way to choose between a
* per-container and a per-wagon row for the same 20ft lane, and used to bill
* whichever the database happened to return first. So the unit is NOT part of a
* rate's identity: changing how a lane is billed means editing its rate.
*/
describe('RatesService — one rate per pattern', () => {
const DJ = '11111111-1111-4000-8000-000000000001';
const ET = '11111111-1111-4000-8000-000000000002';
const CT20 = '11111111-1111-4000-8000-000000000003';
const existing = (over: Partial<Rate> = {}): Rate =>
({
id: 'rate-existing',
rateType: 'CONTAINER_IMPORT',
rateUnit: 'PER_WAGON',
rateValue: 1690,
containerTypeId: CT20,
cargoTypeId: null,
tradeDirection: 'IMPORT',
originYardId: DJ,
destinationYardId: ET,
status: 'LIVE',
...over,
}) as Rate;
const dto = {
appliesTo: 'CONTAINER',
trigger: 'ALWAYS',
tradeDirection: 'IMPORT',
containerTypeId: CT20,
originYardId: DJ,
destinationYardId: ET,
rateValue: 845,
rateUnit: 'PER_CONTAINER',
};
let repository: { findByPattern: jest.Mock; create: jest.Mock };
let service: RatesService;
beforeEach(() => {
repository = {
findByPattern: jest.fn().mockResolvedValue(null),
create: jest.fn(async (r) => ({ id: 'rate-new', ...r })),
};
service = new RatesService(
repository as never,
{
findById: jest.fn(async (id: string) => ({
id,
country: id === DJ ? 'Djibouti' : 'Ethiopia',
label: id === DJ ? 'Doraleh' : 'Gelan',
})),
} as never,
{ findById: jest.fn().mockResolvedValue(null) } as never,
);
});
it('refuses a second rate on the same lane that only differs by unit', async () => {
repository.findByPattern.mockResolvedValue(existing());
await expect(service.create(dto as never, 'staff-1')).rejects.toBeInstanceOf(
ConflictException,
);
expect(repository.create).not.toHaveBeenCalled();
});
it('looks the pattern up without the unit, so either order collides', async () => {
await service.create(dto as never, 'staff-1');
const pattern = repository.findByPattern.mock.calls[0][0];
expect(pattern).not.toHaveProperty('rateUnit');
expect(pattern).toMatchObject({
rateType: 'CONTAINER_IMPORT',
containerTypeId: CT20,
originYardId: DJ,
destinationYardId: ET,
});
});
it('still allows the same unit on a different lane', async () => {
await service.create(dto as never, 'staff-1');
expect(repository.create).toHaveBeenCalledWith(
expect.objectContaining({
rateUnit: 'PER_CONTAINER',
rateValue: 845,
status: 'DRAFT',
}),
);
});
/**
* Additive surcharges are billed per matching rate, each by its own unit, so
* hazard is legitimately per-container for boxes AND per-ton for bulk. The
* unit stays part of their identity or the second one could never be created.
*/
it('keeps the unit in the key for an additive surcharge', async () => {
await service.create(
{
appliesTo: 'OTHER',
trigger: 'HAZARDOUS',
rateValue: 300,
rateUnit: 'PER_CONTAINER',
} as never,
'staff-1',
);
expect(repository.findByPattern.mock.calls[0][0]).toMatchObject({
rateType: 'HAZARD_SURCHARGE',
rateUnit: 'PER_CONTAINER',
});
});
it('treats lashing as singly resolved — one unit per direction', async () => {
await service.create(
{
appliesTo: 'OTHER',
trigger: 'LASHING',
tradeDirection: 'IMPORT',
rateValue: 40,
rateUnit: 'PER_TON',
} as never,
'staff-1',
);
expect(repository.findByPattern.mock.calls[0][0]).not.toHaveProperty(
'rateUnit',
);
});
});

80
apps/edr-freight-api/src/modules/rule-engine/services/rates.service.ts
View File

@@ -12,7 +12,11 @@ import { ListRatesQueryDto } from '../dto/list-rule-engine-query.dto';
import { UpdateRateDto } from '../dto/update-rate.dto';
import { Rate } from '../entities/rate.entity';
import { deriveRateType } from '../entities/rate-type.util';
import { allowedRateUnits, isRateUnitAllowed } from '../entities/rate-unit.util';
import { CargoUom, allowedRateUnits, isRateUnitAllowed } from '../entities/rate-unit.util';
import {
CARGO_TYPES_REPOSITORY,
ICargoTypesRepository,
} from '../interfaces/cargo-types.repository.interface';
import { IRatesRepository, RATES_REPOSITORY } from '../interfaces/rates.repository.interface';
import { IYardsRepository, YARDS_REPOSITORY } from '../interfaces/yards.repository.interface';
@@ -32,6 +36,8 @@ export class RatesService {
private readonly repository: IRatesRepository,
@Inject(YARDS_REPOSITORY)
private readonly yardsRepository: IYardsRepository,
@Inject(CARGO_TYPES_REPOSITORY)
private readonly cargoTypesRepository: ICargoTypesRepository,
) {}
/** List rates — standard paginated envelope with server-side search. */
@@ -63,25 +69,37 @@ export class RatesService {
* Normalise + validate the weighting unit for a rate shape. Overweight is
* always billed per excess ton, so its unit is forced to PER_TON regardless
* of what the client sent. Every other shape must pick a unit the pricing
* engine can actually apply (see `allowedRateUnits`).
* engine can actually apply (see `allowedRateUnits`) — for a rate scoped to a
* bulk commodity that means the commodity's own unit of measure: a PER_ITEM
* commodity bills per item where a weighed one bills per ton.
*/
private resolveRateUnit(
private async resolveRateUnit(
appliesTo: Rate['appliesTo'],
trigger: Rate['trigger'],
requestedUnit: Rate['rateUnit'] | undefined,
cargoKind?: 'CONTAINER' | 'BULK' | null,
): Rate['rateUnit'] {
cargoTypeId?: string | null,
): Promise<Rate['rateUnit']> {
// Overweight is per-ton, full stop — the admin form hides the unit field
// for it and omits rateUnit from the payload entirely.
if (trigger === 'OVERWEIGHT') return 'PER_TON';
const allowed = allowedRateUnits({ appliesTo, trigger, cargoKind });
const cargoUnitOfMeasure = await this.cargoUnitOfMeasure(cargoTypeId);
const allowed = allowedRateUnits({ appliesTo, trigger, cargoKind, cargoUnitOfMeasure });
if (!requestedUnit) {
throw new BadRequestException(
`Pick a rate unit for this rate. Allowed: ${allowed.join(', ')}.`,
);
}
if (!isRateUnitAllowed({ appliesTo, trigger, cargoKind, unit: requestedUnit })) {
if (
!isRateUnitAllowed({
appliesTo,
trigger,
cargoKind,
cargoUnitOfMeasure,
unit: requestedUnit,
})
) {
throw new BadRequestException(
`Rate unit "${requestedUnit}" is not valid for this rate. Allowed: ${allowed.join(', ')}.`,
);
@@ -89,6 +107,13 @@ export class RatesService {
return requestedUnit;
}
/** Unit of measure of the bulk commodity a rate is scoped to; null when unscoped. */
private async cargoUnitOfMeasure(cargoTypeId?: string | null): Promise<CargoUom> {
if (!cargoTypeId) return null;
const cargo = await this.cargoTypesRepository.findById(cargoTypeId);
return cargo?.unitOfMeasure ?? null;
}
/** Base rail freight is priced per leg; surcharges and truck legs are not. */
private isBaseFreight(appliesTo: Rate['appliesTo'], trigger: Rate['trigger']): boolean {
return trigger === 'ALWAYS' && BASE_FREIGHT_CATEGORIES.includes(appliesTo);
@@ -107,6 +132,24 @@ export class RatesService {
);
}
/**
* True when pricing resolves exactly ONE rate for this shape (base freight,
* customs clearance, lashing, empty-container return — all `find()`-based
* lookups). For those the unit is not part of the rate's identity: two rows
* for the same lane differing only by unit are a duplicate the engine cannot
* choose between.
*
* The additive surcharges are the opposite — the engine bills EVERY matching
* rate by its own unit, which is how hazard can be per-container for boxes
* and per-ton for bulk at the same time — so their unit stays part of the key.
*/
private resolvesSingleRate(
appliesTo: Rate['appliesTo'],
trigger: Rate['trigger'],
): boolean {
return this.isRouteScoped(appliesTo, trigger) || trigger === 'LASHING';
}
/**
* Which country each end of the leg must sit in, given what the rate is for.
* The railway only sells three shapes: import lands at the Djibouti ports and
@@ -301,10 +344,17 @@ export class RatesService {
* Reject a second rate with the same identity pattern (rateType + scope). With
* effective-date windows gone, two LIVE/DRAFT rates for the same pattern would
* make pricing ambiguous — so we allow exactly one per pattern.
*
* The UNIT is not part of that identity. Pricing resolves one rate per lane +
* scope and then applies whatever unit it carries; a per-container and a
* per-wagon row for the same 20ft lane are two answers to one question, and
* the engine silently picked one of them. Changing how a lane is billed means
* editing its rate, not adding a second.
*/
private async assertNoDuplicatePattern(pattern: {
rateType: string;
rateUnit: string;
/** Passed only for additive surcharges — see {@link resolvesSingleRate}. */
rateUnit?: string;
containerTypeId: string | null;
cargoTypeId: string | null;
tradeDirection: string | null;
@@ -380,16 +430,17 @@ export class RatesService {
tradeDirection,
isBulk: this.resolvesToBulk(appliesTo, intercityKind),
});
const rateUnit = this.resolveRateUnit(
const rateUnit = await this.resolveRateUnit(
appliesTo,
trigger,
dto.rateUnit as Rate['rateUnit'] | undefined,
cargoKind,
cargoTypeId,
);
await this.assertNoDuplicatePattern({
rateType,
rateUnit,
...(this.resolvesSingleRate(appliesTo, trigger) ? {} : { rateUnit }),
containerTypeId,
cargoTypeId,
tradeDirection,
@@ -562,12 +613,19 @@ export class RatesService {
// Re-validate the unit against the (possibly changed) shape; overweight is
// forced to PER_TON.
const requestedUnit = (dto.rateUnit as Rate['rateUnit']) ?? existing.rateUnit;
updates.rateUnit = this.resolveRateUnit(appliesTo, trigger, requestedUnit, cargoKind);
const rateUnit = await this.resolveRateUnit(
appliesTo,
trigger,
requestedUnit,
cargoKind,
updates.cargoTypeId,
);
updates.rateUnit = rateUnit;
// Guard the pattern uniqueness for the new identity, ignoring this row.
await this.assertNoDuplicatePattern({
rateType,
rateUnit: updates.rateUnit,
...(this.resolvesSingleRate(appliesTo, trigger) ? {} : { rateUnit }),
containerTypeId: updates.containerTypeId,
cargoTypeId: updates.cargoTypeId,
tradeDirection: updates.tradeDirection,

16
apps/edr-freight-api/src/modules/train-scheduling/booking-batch.service.ts
View File

@@ -3000,6 +3000,22 @@ export class BookingBatchService implements OnModuleInit {
}
}
/**
* How many bookings on this route-day would be expired if document review
* ended right now — i.e. requests staff have neither accepted nor rejected.
* Same query the doc-review-end sweep runs, so the number staff see is
* exactly what is at risk.
*/
async countUnacceptedForRouteDay(group: RouteDayGroup): Promise<number> {
const corridorYards = await this.corridorYardsForRouteDay(group);
if (corridorYards.length === 0) return 0;
const unaccepted = await this.bookingsRepository.findUnacceptedForRouteDay(
corridorYards,
group.day,
);
return unaccepted.length;
}
/**
* Free capacity for a government booking by displacing the lowest-priority commercial
* bookings (reserved first, then allocated — including PAID). Displaced → EXPIRED + notified.

85
apps/edr-freight-api/src/modules/train-scheduling/booking-window.service.spec.ts
View File

@@ -22,6 +22,7 @@ describe('BookingWindowService — window state machine', () => {
expireLeftoverDayPool: jest.Mock;
expireLeftoverExportDay: jest.Mock;
fillFromWaitingList: jest.Mock;
countUnacceptedForRouteDay: jest.Mock;
};
let trainSchedulesRepository: { findById: jest.Mock; findAll: jest.Mock };
let trainSchedulingService: { finalizeSchedule: jest.Mock; getWindowConfig: jest.Mock };
@@ -79,6 +80,7 @@ describe('BookingWindowService — window state machine', () => {
expireLeftoverExportDay: jest.fn().mockResolvedValue(undefined),
// No waiting booking fits by default, so conclude proceeds to reopen/DONE.
fillFromWaitingList: jest.fn().mockResolvedValue(0),
countUnacceptedForRouteDay: jest.fn().mockResolvedValue(0),
};
trainSchedulesRepository = {
findById: jest.fn().mockResolvedValue(null),
@@ -267,4 +269,87 @@ describe('BookingWindowService — window state machine', () => {
expect(s.windowPhase).toBe('OPEN');
expect(batch.setWindow).not.toHaveBeenCalled();
});
// ---- header alarm ---------------------------------------------------------
describe('getDocReviewAlert', () => {
const reviewing = (over: Partial<TrainSchedule>): TrainSchedule =>
baseSchedule({
windowPhase: 'DOC_REVIEW',
docReviewEndsAt: new Date('2026-07-01T01:30:00.000Z'),
...over,
});
it('returns null when nothing is under document review', async () => {
trainSchedulesRepository.findAll.mockResolvedValue([
baseSchedule({ windowPhase: 'OPEN' }),
]);
expect(await service.getDocReviewAlert()).toBeNull();
});
it('returns null when every request on the route-day is decided', async () => {
trainSchedulesRepository.findAll.mockResolvedValue([reviewing({})]);
batch.countUnacceptedForRouteDay.mockResolvedValue(0);
expect(await service.getDocReviewAlert()).toBeNull();
});
it('reports the deadline, its own pending count and the phase length', async () => {
trainSchedulesRepository.findAll.mockResolvedValue([reviewing({})]);
batch.countUnacceptedForRouteDay.mockResolvedValue(3);
const alert = await service.getDocReviewAlert();
expect(alert).toMatchObject({
scheduleId,
originYardId: 'yard-o',
destinationYardId: 'yard-d',
tradeDirection: 'IMPORT',
pendingCount: 3,
docReviewMinutes: 30,
docReviewEndsAt: '2026-07-01T01:30:00.000Z',
});
});
it('skips the nearest deadline when it has nothing pending', async () => {
trainSchedulesRepository.findAll.mockResolvedValue([
reviewing({
id: 'sched-later',
destinationStationId: 'yard-far',
docReviewEndsAt: new Date('2026-07-01T02:00:00.000Z'),
}),
reviewing({ id: 'sched-soon' }),
]);
// Nearest (sched-soon, yard-d) is clear; the later route-day still isn't.
batch.countUnacceptedForRouteDay.mockImplementation(
async (g: { destinationYardId: string }) =>
g.destinationYardId === 'yard-far' ? 2 : 0,
);
const alert = await service.getDocReviewAlert();
expect(alert?.scheduleId).toBe('sched-later');
expect(alert?.pendingCount).toBe(2);
});
it('counts a route-day once when sibling trains share the review phase', async () => {
trainSchedulesRepository.findAll.mockResolvedValue([
reviewing({ id: 'sched-a' }),
reviewing({ id: 'sched-b' }),
]);
batch.countUnacceptedForRouteDay.mockResolvedValue(4);
const alert = await service.getDocReviewAlert();
expect(alert?.pendingCount).toBe(4);
expect(batch.countUnacceptedForRouteDay).toHaveBeenCalledTimes(1);
});
it('ignores a phase staff already completed early', async () => {
trainSchedulesRepository.findAll.mockResolvedValue([
reviewing({ docReviewCompletedAt: new Date('2026-07-01T01:10:00.000Z') }),
]);
batch.countUnacceptedForRouteDay.mockResolvedValue(5);
expect(await service.getDocReviewAlert()).toBeNull();
});
});
});

81
apps/edr-freight-api/src/modules/train-scheduling/booking-window.service.ts
View File

@@ -30,6 +30,28 @@ import {
} from './batch-window.util';
import { type BookingWindowConfig } from './booking-window.config';
/**
* The most urgent document-review deadline that still has un-accepted booking
* requests behind it. Backoffice counts down to it and warns staff, because
* everything still pending when the phase ends is expired automatically.
*/
export interface DocReviewAlert {
/** A schedule of the route-day group under review (deep-link target). */
scheduleId: string;
originYardId: string;
destinationYardId: string;
/** EAT booking day of the group, YYYY-MM-DD. */
day: string;
/** IMPORT (the usual) or DOMESTIC — both run a review phase; export does not. */
tradeDirection: string;
/** ISO deadline the review phase ends at. */
docReviewEndsAt: string;
/** Full length of the review phase — the client warns past its halfway mark. */
docReviewMinutes: number;
/** Requests neither accepted nor rejected — they expire at the deadline. */
pendingCount: number;
}
/**
* Drives the one-booking-day window cycle for IMPORT schedules and the FCFS
* booking window for EXPORT schedules. All state lives in DB timestamps on the
@@ -130,6 +152,65 @@ export class BookingWindowService implements OnModuleInit {
}
}
/**
* The route-day currently in document review whose deadline is nearest and
* which still has un-accepted requests. Null when nothing is under review or
* every request has been decided — the backoffice header shows nothing then.
*
* One card, one deadline, one count: route-days are checked in deadline order
* and the first with pending work wins, so the number always belongs to the
* clock beside it.
*/
async getDocReviewAlert(): Promise<DocReviewAlert | null> {
const reviewing = (
await this.trainSchedulesRepository.findAll({
where: [
{ status: TrainScheduleStatusEnum.Draft },
{ status: TrainScheduleStatusEnum.Scheduled },
],
})
)
.filter(
(s) =>
s.windowPhase === 'DOC_REVIEW' &&
s.docReviewCompletedAt == null &&
s.docReviewEndsAt != null &&
s.scheduledDepartureDate != null,
)
.sort((a, b) => a.docReviewEndsAt!.getTime() - b.docReviewEndsAt!.getTime());
if (reviewing.length === 0) return null;
const liveCfg = await this.trainSchedulingService.getWindowConfig();
const seen = new Set<string>();
for (const schedule of reviewing) {
const group = {
originYardId: schedule.originStationId,
destinationYardId: schedule.destinationStationId,
day: eatDay(schedule.scheduledDepartureDate),
};
// Sibling trains share one review phase for the route-day pool — count it once.
const key = `${group.originYardId}|${group.destinationYardId}|${group.day}`;
if (seen.has(key)) continue;
seen.add(key);
const pendingCount =
await this.bookingBatchService.countUnacceptedForRouteDay(group);
if (pendingCount === 0) continue;
return {
scheduleId: schedule.id,
...group,
// Carried so the backoffice list opens on the same direction the
// at-risk requests belong to (import corridor, or a domestic day).
tradeDirection: schedule.direction ?? 'IMPORT',
docReviewEndsAt: schedule.docReviewEndsAt!.toISOString(),
docReviewMinutes: effectiveWindowConfig(schedule, liveCfg).docReviewMinutes,
pendingCount,
};
}
return null;
}
/** Staff finished document review early — start the batch/payment phase now. */
async completeDocReview(scheduleId: string): Promise<TrainSchedule> {
const schedule = await this.trainSchedulesRepository.findById(scheduleId);

94
apps/edr-freight-api/src/modules/train-scheduling/consist-order.util.spec.ts Normal file
View File

@@ -0,0 +1,94 @@
import { orderConsistWagons } from './consist-order.util';
// Built train: A-B-C-D coupled in that order. Slots are created by the wagon
// PLAN, so their sequenceNo says nothing about where the wagon actually sits.
const TRAIN = ['A', 'B', 'C', 'D'];
const slot = (sequenceNo: number, physicalWagonId: string | null) => ({
sequenceNo,
physicalWagonId,
});
describe('orderConsistWagons', () => {
it('draws slots in the train coupling order, not slot order', () => {
// Plan order says D then B; the train says B sits ahead of D.
const drawn = orderConsistWagons([slot(1, 'D'), slot(2, 'B')], {
physicalWagonIdsInOrder: TRAIN,
});
expect(drawn.map((w) => w.physicalWagonId)).toEqual(['B', 'D']);
expect(drawn.map((w) => w.position)).toEqual([1, 2]);
});
it('interleaves empty consist wagons in their real place', () => {
// Loaded slots on A and C; B and D ride along empty. The empties used to be
// appended after every loaded slot, so the drawing was never the train.
const drawn = orderConsistWagons(
[slot(1, 'A'), slot(2, 'C'), slot(98, 'B'), slot(99, 'D')],
{ physicalWagonIdsInOrder: TRAIN },
);
expect(drawn.map((w) => w.physicalWagonId)).toEqual(['A', 'B', 'C', 'D']);
});
it('keeps every wagon in place when a load moves between wagons', () => {
// Load sat on A (slot 1); staff drag it onto empty D. The move repins the
// slot, so the SAME slot now reads as wagon D and A falls back to empty.
const before = orderConsistWagons([slot(1, 'A'), slot(98, 'D')], {
physicalWagonIdsInOrder: TRAIN,
});
const after = orderConsistWagons([slot(1, 'D'), slot(98, 'A')], {
physicalWagonIdsInOrder: TRAIN,
});
// A is drawn first and D last, before and after — the train did not shuffle.
expect(before.map((w) => w.physicalWagonId)).toEqual(['A', 'D']);
expect(after.map((w) => w.physicalWagonId)).toEqual(['A', 'D']);
});
it('follows a train-builder reorder without touching any slot row', () => {
const slots = [slot(1, 'A'), slot(2, 'B')];
// Builder swaps the coupling order; the slots are untouched.
const drawn = orderConsistWagons(slots, {
physicalWagonIdsInOrder: ['B', 'A', 'C', 'D'],
});
expect(drawn.map((w) => w.physicalWagonId)).toEqual(['B', 'A']);
});
it('draws back-to-front when the caller reverses the train', () => {
const drawn = orderConsistWagons([slot(1, 'A'), slot(2, 'C')], {
physicalWagonIdsInOrder: [...TRAIN].reverse(),
reverseWagonOrder: true,
});
expect(drawn.map((w) => w.physicalWagonId)).toEqual(['C', 'A']);
});
it('parks unpinned slots last, in slot order', () => {
const drawn = orderConsistWagons([slot(9, null), slot(4, null), slot(1, 'C')], {
physicalWagonIdsInOrder: TRAIN,
});
expect(drawn.map((w) => [w.physicalWagonId, w.sequenceNo])).toEqual([
['C', 1],
[null, 4],
[null, 9],
]);
});
it('falls back to slot order when there is no built train', () => {
// Frozen schedules and loose-wagon schedules pass no physical order.
const drawn = orderConsistWagons([slot(2, 'X'), slot(1, 'Y')], {
physicalWagonIdsInOrder: [],
});
expect(drawn.map((w) => w.sequenceNo)).toEqual([1, 2]);
const reversed = orderConsistWagons([slot(1, 'X'), slot(2, 'Y')], {
physicalWagonIdsInOrder: [],
reverseWagonOrder: true,
});
expect(reversed.map((w) => w.sequenceNo)).toEqual([2, 1]);
});
});

54
apps/edr-freight-api/src/modules/train-scheduling/consist-order.util.ts Normal file
View File

@@ -0,0 +1,54 @@
/**
* Draw order for a schedule's consist.
*
* A slot's stored `sequenceNo` is its place in the wagon PLAN, not its place in
* the train. The train's real coupling order lives on the physical wagons
* (`wagons.sequence_number`), which the caller passes in already ordered — ASC
* normally, DESC for a `reverseWagonOrder` schedule.
*
* Ordering by the physical wagon is what keeps the drawing honest:
* - moving a load between wagons repaints WHICH wagon is loaded and never
* shuffles the train, because each slot is drawn wherever its wagon sits;
* - a train-builder reorder lands on the next read, allocations included,
* since the order is derived on every read instead of copied at pin time.
*
* Slots with no physical wagon (not pinned yet, or a schedule that isn't tied
* to a built train) have no place in the consist — they keep slot order, last.
*/
export interface ConsistOrderable {
sequenceNo: number;
physicalWagonId?: string | null;
}
export interface ConsistOrderOptions {
/**
* Every wagon coupled to the built train, in real coupling order (already
* reversed by the caller for a `reverseWagonOrder` schedule). Empty for a
* frozen schedule or one with no built train — the consist then keeps slot
* order.
*/
physicalWagonIdsInOrder: string[];
reverseWagonOrder?: boolean;
}
export const orderConsistWagons = <T extends ConsistOrderable>(
wagons: T[],
{ physicalWagonIdsInOrder, reverseWagonOrder }: ConsistOrderOptions,
): (T & { position: number })[] => {
const physicalOrder = new Map(physicalWagonIdsInOrder.map((id, index) => [id, index]));
const bySlotSequence = (a: T, b: T) =>
reverseWagonOrder ? b.sequenceNo - a.sequenceNo : a.sequenceNo - b.sequenceNo;
const ordered = physicalOrder.size
? [...wagons].sort((a, b) => {
const ai = a.physicalWagonId ? physicalOrder.get(a.physicalWagonId) : undefined;
const bi = b.physicalWagonId ? physicalOrder.get(b.physicalWagonId) : undefined;
if (ai == null && bi == null) return bySlotSequence(a, b);
if (ai == null) return 1;
if (bi == null) return -1;
return ai - bi;
})
: [...wagons].sort(bySlotSequence);
return ordered.map((wagon, index) => ({ ...wagon, position: index + 1 }));
};

19
apps/edr-freight-api/src/modules/train-scheduling/facility-handling.service.ts
View File

@@ -48,10 +48,12 @@ export class FacilityHandlingService {
if (!facility?.hasFacility) return null;
const occurredAt = input.occurredAt ?? new Date();
// Mapped to the goods owner, same as every warehouse-raised GRN.
const grnNumber = generateGrnNumber(
booking.tradeDirection ?? 'DOMESTIC',
booking.id,
occurredAt,
booking.company?.name ?? null,
);
// Link the storage record when this facility keeps cargo — that link is
@@ -67,6 +69,21 @@ export class FacilityHandlingService {
inventoryId = inv?.id ?? null;
}
// The handed-over weight: the booking's declared VGM, else what its
// containers actually carry. A GRN without a weight is not a receipt.
let weightTons = Number(booking.cargoTotalWeightVgm) || null;
if (!weightTons) {
const [sum]: Array<{ tons: string | null }> = await manager.query(
`SELECT SUM(bcu.vgm_tons) AS tons
FROM freight.booking_container_units bcu
JOIN freight.booking_container bc
ON bc.id = bcu.booking_container_id AND bc.deleted_at IS NULL
WHERE bc.booking_id = $1 AND bcu.deleted_at IS NULL`,
[booking.id],
);
weightTons = Number(sum?.tons) || null;
}
const repo = manager.getRepository(FacilityHandlingEvent);
await repo.save(
repo.create({
@@ -75,7 +92,7 @@ export class FacilityHandlingService {
trainScheduleId: input.trainScheduleId ?? null,
eventType,
grnNumber,
weightTons: Number(booking.cargoTotalWeightVgm) || null,
weightTons,
inventoryId,
performedBy: input.performedBy ?? null,
occurredAt,

13
apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.controller.ts
View File

@@ -8,6 +8,7 @@ import {
} from "@nestjs/common";
import { CurrentUser } from "@edr/api-common";
import {
BookingDocReviewAlert,
TrainSchedulingCancel,
TrainSchedulingCreate,
TrainSchedulingReschedule,
@@ -747,6 +748,18 @@ export class TrainSchedulingController {
return this.trainSchedulingService.getContainerTrainScheduleById(id);
}
@Get("doc-review-alert")
// Dedicated permission, not scheduling or bookings:view — the alarm is meant
// for the position types that actually decide operation requests.
@BookingDocReviewAlert()
@ApiOperation({
summary:
"Nearest document-review deadline that still has un-accepted booking requests behind it (null when there is none) — drives the backoffice header countdown",
})
async getDocReviewAlert() {
return this.bookingWindowService.getDocReviewAlert();
}
@Post("schedules/:id/doc-review-complete")
@TrainSchedulingUpdate()
@ApiOperation({

Some files were not shown because too many files have changed in this diff Show More