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 branch 'dev' into quick-fix

Browse Source
This commit is contained in:
Stephanos A.
2026-07-19 08:33:16 +03:00
committed by GitHub
parent 93c583edf6 5ac48bf05b
commit e9590205f7
337 changed files with 16245 additions and 2090 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -14,6 +14,7 @@
"test": "jest",
"test:e2e": "jest --config ./test/jest-e2e.json",
"seed:wagons": "ts-node -r tsconfig-paths/register src/scripts/seed-edr-wagons.ts",
"seed:trucks": "ts-node -r tsconfig-paths/register src/scripts/seed-edr-trucks.ts",
"type-check": "tsc --noEmit",
"seed:demo-scheduling": "ts-node -r tsconfig-paths/register src/scripts/seed-demo-scheduling.ts",
"seed:freight-demo": "ts-node -r tsconfig-paths/register src/scripts/seed-freight-demo.ts",

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

@@ -39,6 +39,7 @@ import { TrackingModule } from "./modules/tracking/tracking.module";
import { BillingModule } from "./modules/billing/billing.module";
import { NotificationsModule } from "./modules/notifications/notifications.module";
import { NotificationInboxModule } from "./modules/notification-inbox/notification-inbox.module";
import { SupportChatModule } from "./modules/support-chat/support-chat.module";
import { FileUploadSettingsModule } from "./modules/file-upload-settings/file-upload-settings.module";
import { DropdownSettingsModule } from "./modules/dropdown-settings/dropdown-settings.module";
import { ContractTemplatesModule } from "./modules/contract-templates/contract-templates.module";
@@ -59,6 +60,7 @@ import { FreightPositionsSeeder } from "./seed/freight-positions.seeder";
import { PaymentModule } from "./modules/payment/payment.module";
// import { PricingDataSeeder } from "./seed/pricing-data.seeder";
import { FileUploadSettingsSeeder } from "./seed/file-upload-settings.seeder";
import { YardFacilitiesSeeder } from "./seed/yard-facilities.seeder";
// import { IndodeFacilitySeeder } from "./seed/indode-facility.seeder";
// import { Batch14TestDataSeeder } from "./seed/batch1-4-test-data.seeder";
// import { Batch5TestDataSeeder } from "./seed/batch5-test-data.seeder";
@@ -159,6 +161,7 @@ import { LoggerMiddleware } from "./logger.middleware";
BillingModule,
NotificationsModule,
NotificationInboxModule,
SupportChatModule,
FileUploadSettingsModule,
DropdownSettingsModule,
ContractTemplatesModule,
@@ -196,6 +199,7 @@ import { LoggerMiddleware } from "./logger.middleware";
EdrOrgSeeder,
FreightPositionsSeeder,
FileUploadSettingsSeeder,
YardFacilitiesSeeder,
FreightPermissionKeyMigrationSeeder,
// Disabled seeds — providers commented out (imports/injection/run too):
// DemoUsersSeeder,
@@ -221,6 +225,7 @@ export class AppModule implements OnApplicationBootstrap {
private readonly edrOrgSeeder: EdrOrgSeeder,
private readonly freightPositionsSeeder: FreightPositionsSeeder,
private readonly fileUploadSettingsSeeder: FileUploadSettingsSeeder,
private readonly yardFacilitiesSeeder: YardFacilitiesSeeder,
private readonly freightPermissionKeyMigrationSeeder: FreightPermissionKeyMigrationSeeder,
// Disabled seeds — injections commented out (imports/provider/run too):
// private readonly demoUsersSeeder: DemoUsersSeeder,
@@ -258,6 +263,10 @@ export class AppModule implements OnApplicationBootstrap {
// File upload settings — keep enabled.
await this.fileUploadSettingsSeeder.run();
// Flags which yards can load/unload cargo (Indode, Sebeta, Modjo, Adama,
// Dire Dawa). Idempotent; creates no yards.
await this.yardFacilitiesSeeder.run();
// Dropdown settings are not seeded on boot; run them with
// `pnpm seed:dropdown-settings` (src/scripts/seed-dropdown-settings.ts).

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

@@ -0,0 +1,13 @@
/**
* Goods Received Note number: `GRN-<DIRECTION>-<YYYYMMDD>-<REF8>`.
*
* 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 {
const stamp = date.toISOString().slice(0, 10).replace(/-/g, '');
const suffix = referenceId.replace(/-/g, '').slice(0, 8).toUpperCase();
return `GRN-${direction.toUpperCase()}-${stamp}-${suffix}`;
}

11
apps/edr-freight-api/src/common/rule-engine-guards.ts
View File

@@ -4,6 +4,7 @@ import { JwtGuard } from '@tria-plc/api-common/modules/auth/services/jwt.guard';
import { FreightPermissionGuard } from './freight-permission.guard';
import {
FREIGHT_PERMS,
type RuleEngineApprovableSlug,
type RuleEngineResourceSlug,
} from '../seed/freight-permissions.registry';
@@ -16,3 +17,13 @@ export const RuleEngineManage = (slug: RuleEngineResourceSlug) =>
applyDecorators(
UseGuards(JwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.manage(slug)])),
);
/**
* Deciding a filed change — a step above `manage`, which only lets a staff
* member propose one. Super admins pass any freight permission check, so
* approvals work before the permission is granted to a director role.
*/
export const RuleEngineApprove = (slug: RuleEngineApprovableSlug) =>
applyDecorators(
UseGuards(JwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.approve(slug)])),
);

28
apps/edr-freight-api/src/common/schedule-bookings.sql.ts Normal file
View File

@@ -0,0 +1,28 @@
/**
* SQL CTE resolving the bookings riding a train schedule, as `sched_bookings
* (schedule_id, booking_id)`. Use as: `WITH ${SCHEDULE_BOOKINGS_CTE} SELECT ...`.
*
* A booking reaches a train through WAGON ALLOCATION
* (train_schedules -> train_sets -> train_set_wagons -> wagon_booking_allocations),
* which is what the allocation UI writes. `train_schedule_bookings` is only ever
* written by the demo seeders, so both sources are unioned: real allocations work
* and the seeded scenarios keep working.
*
* Shared so the warehouse loading queue and the train dispatch guard agree on
* exactly which bookings are on a train — if they drift, a train can be
* dispatched leaving cargo the warehouse still thinks it should load.
*/
export const SCHEDULE_BOOKINGS_CTE = `
sched_bookings AS (
SELECT ts.id AS schedule_id, wba.booking_id
FROM freight.train_schedules ts
JOIN freight.train_set_wagons tsw
ON tsw.train_set_id = ts.train_set_id AND tsw.deleted_at IS NULL
JOIN freight.wagon_booking_allocations wba
ON wba.train_set_wagon_id = tsw.id AND wba.deleted_at IS NULL
WHERE ts.deleted_at IS NULL
UNION
SELECT tsb.train_schedule_id, tsb.booking_id
FROM freight.train_schedule_bookings tsb
WHERE tsb.deleted_at IS NULL
)`;

3
apps/edr-freight-api/src/contracts/contract-article.util.ts
View File

@@ -13,6 +13,9 @@ export interface RenderedClause {
/** A dynamic article ready for the Handlebars template. */
export interface RenderedArticle {
number: number;
/** Stable article id from the template (e.g. "pricing") — lets the layout
* inject the live rate schedule table under the pricing article. */
id: string;
title: string;
/** Set (instead of clauses) when the body is a single plain paragraph. */
paragraph?: string;

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

@@ -18,6 +18,7 @@ import {
ContractDynamicTemplateView,
ContractViewModel,
} from './contract-view-model.builder';
import { RateSchedule } from './contract-rate-schedule.builder';
/**
* Signature row for the contract PDF. Mirrors the booking builder's
@@ -135,6 +136,7 @@ export class ContractDocumentViewModelBuilder {
}
const pricing = this.buildPricing(contract);
const rateSchedule = this.buildRateSchedule(pricing);
const signatures = await this.loadSignatures(contractId);
const hasCustomer = signatures.some((s) => s.role === 'CUSTOMER');
@@ -177,6 +179,7 @@ export class ContractDocumentViewModelBuilder {
},
schedule: this.buildSchedule(contract),
pricing: pricing as unknown as ContractViewModel['pricing'],
rateSchedule,
// 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'],
@@ -230,6 +233,40 @@ export class ContractDocumentViewModelBuilder {
};
}
/**
* A rate schedule for the contract PDF, sourced from the contract's own frozen
* unit rates (its agreed lane prices) rather than the global rate config — a
* signed contract must show the prices it was signed on. Rendered as freight
* lanes labelled with the contract's primary origin → destination route.
*/
private buildRateSchedule(pricing: ContractUnitRateSchedule): RateSchedule {
const route = `${pricing.originLabel} → ${pricing.destinationLabel}`;
const freightLanes = pricing.unitRates.map((line) => ({
route,
cargo: line.label,
currency: line.currency,
amount: this.formatAmount(line.unitPrice),
unit: line.unit.startsWith('per ') ? line.unit : `per ${line.unit}`,
}));
return {
freightLanes,
additionalServices: [],
surcharges: [],
isEmpty: freightLanes.length === 0,
currencyLabel: pricing.currency,
};
}
private formatAmount(value: number | string): string {
const num = Number(value);
if (!Number.isFinite(num)) return String(value);
return num.toLocaleString('en-US', {
minimumFractionDigits: 0,
maximumFractionDigits: 2,
});
}
private buildSchedule(contract: Contract): ContractViewModel['schedule'] {
const firstRoute = this.firstRoute(contract);
const cargoScope = (contract.cargoScope ?? [])[0];

29
apps/edr-freight-api/src/contracts/contract-dynamic-template.spec.ts
View File

@@ -133,6 +133,17 @@ describe('dynamic template rendering (edr-dynamic.hbs)', () => {
originLabel: 'Nagad',
destinationLabel: 'Galaan Multipurpose Port',
} as unknown as ContractViewModel['pricing'],
rateSchedule: {
freightLanes: [
{ route: 'Nagad → Galaan Multipurpose Port', cargo: 'Wheat', currency: 'USD', amount: '100', unit: 'per wagon' },
],
additionalServices: [
{ route: 'First-mile pickup by truck', cargo: '—', currency: 'USD', amount: '50', unit: 'per wagon' },
],
surcharges: [],
isEmpty: false,
currencyLabel: 'USD',
},
signatures: [],
canSignCustomer: false,
canSignStaff: false,
@@ -151,11 +162,17 @@ describe('dynamic template rendering (edr-dynamic.hbs)', () => {
body: 'Integrated logistics services including:\n- Rail transport to GMP\n- Customs clearance',
order: 1,
},
{
id: 'pricing',
title: 'Contract Price and Payment Terms',
body: 'Rates are set out in the Rate Schedule below.\nPayments 100% in advance.',
order: 2,
},
{
id: 'duration',
title: 'Duration',
body: 'Valid until August 31, {{contractYear}}.',
order: 2,
order: 3,
},
],
},
@@ -175,6 +192,16 @@ describe('dynamic template rendering (edr-dynamic.hbs)', () => {
expect(html).toContain('#1b9e7a');
});
it('renders the live rate schedule lane under the pricing article', () => {
const html = renderer.render(dynamicView());
expect(html).toContain('Rate Schedule');
// Base freight lane pulled from the rate config
expect(html).toContain('Nagad → Galaan Multipurpose Port');
expect(html).toContain('USD 100 per wagon');
// Additional-service group
expect(html).toContain('First-mile pickup by truck');
});
it('keeps the generic layout when no dynamic template is attached', () => {
const view = dynamicView();
delete view.dynamicTemplate;

98
apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.spec.ts Normal file
View File

@@ -0,0 +1,98 @@
import { ContractRateScheduleBuilder } from './contract-rate-schedule.builder';
import { Rate } from '../modules/rule-engine/entities/rate.entity';
/** Minimal Rate factory for the builder unit tests. */
function rate(partial: Partial<Rate>): Rate {
return {
trigger: 'ALWAYS',
appliesTo: 'CONTAINER',
tradeDirection: 'IMPORT',
rateType: 'CONTAINER_IMPORT',
currency: 'USD',
rateValue: 200,
rateUnit: 'PER_CONTAINER',
...partial,
} as Rate;
}
describe('ContractRateScheduleBuilder', () => {
const LIVE: Rate[] = [
rate({
appliesTo: 'CONTAINER',
tradeDirection: 'IMPORT',
rateType: 'CONTAINER_IMPORT',
rateValue: 200,
rateUnit: 'PER_CONTAINER',
originYard: { label: 'Negad' } as never,
destinationYard: { label: 'Mojo Dry Port' } as never,
containerType: { label: '40ft GP' } as never,
}),
rate({
appliesTo: 'CONTAINER',
tradeDirection: 'EXPORT', // wrong direction — must be filtered out for import
rateType: 'CONTAINER_EXPORT',
rateValue: 819,
originYard: { label: 'GMP' } as never,
destinationYard: { label: 'SGTD' } as never,
}),
rate({
appliesTo: 'BULK', // wrong freight — filtered out for a container contract
tradeDirection: 'IMPORT',
rateType: 'BULK_IMPORT',
rateUnit: 'PER_WAGON',
rateValue: 100,
}),
rate({
appliesTo: 'FIRST_MILE',
trigger: 'ALWAYS',
tradeDirection: null,
rateUnit: 'PER_CONTAINER',
rateValue: 50,
}),
rate({
appliesTo: 'OTHER',
trigger: 'CUSTOMS_CLEARANCE',
tradeDirection: null,
rateType: 'CUSTOMS_CLEARANCE',
rateUnit: 'FLAT',
rateValue: 120,
}),
];
const build = (dir: 'IMP' | 'EXP' | 'DOM', freight: 'CON' | 'BULK') => {
const service = { findLiveRatesDetailed: jest.fn().mockResolvedValue(LIVE) };
return new ContractRateScheduleBuilder(service as never).build(dir, freight);
};
it('shows only import container lanes for an import container contract', async () => {
const s = await build('IMP', 'CON');
expect(s.freightLanes).toHaveLength(1);
expect(s.freightLanes[0]).toMatchObject({
route: 'Negad → Mojo Dry Port',
cargo: '40ft GP',
currency: 'USD',
amount: '200',
unit: 'per container',
});
});
it('always lists route-agnostic services and surcharges', async () => {
const s = await build('IMP', 'CON');
expect(s.additionalServices).toHaveLength(1);
expect(s.additionalServices[0].route).toBe('First-mile pickup by truck');
expect(s.surcharges).toHaveLength(1);
expect(s.surcharges[0].route).toBe('Customs clearance service');
});
it('excludes container lanes from a bulk contract', async () => {
const s = await build('IMP', 'BULK');
expect(s.freightLanes).toHaveLength(1);
expect(s.freightLanes[0]).toMatchObject({ amount: '100', unit: 'per wagon' });
});
it('flags an empty schedule when nothing priced matches', async () => {
const service = { findLiveRatesDetailed: jest.fn().mockResolvedValue([]) };
const s = await new ContractRateScheduleBuilder(service as never).build('DOM', 'CON');
expect(s.isEmpty).toBe(true);
});
});

226
apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.ts Normal file
View File

@@ -0,0 +1,226 @@
import { Injectable } from '@nestjs/common';
import { RatesService } from '../modules/rule-engine/services/rates.service';
import { Rate } from '../modules/rule-engine/entities/rate.entity';
import {
ContractDirection,
ContractFreight,
} from './contract-template.types';
/** One priced line in the contract's rate schedule. */
export interface RateScheduleRow {
/** "Negad → Mojo Dry Port" for base freight, service name otherwise. */
route: string;
/** "40ft GP", "Wheat", or "—" when the rate is not scoped to a type. */
cargo: string;
currency: string;
/** Pre-formatted amount, e.g. "200" (grouped, no trailing zeros). */
amount: string;
/** Human unit, e.g. "per container", "per wagon", "per ton". */
unit: string;
}
/**
* The origin → destination rate schedule shown in a generated contract's
* pricing article. Grouped so the reader sees rail freight lanes first, then
* pickup/delivery legs, then trigger-based surcharges and demurrage.
*/
export interface RateSchedule {
/** Base rail freight lanes matching this contract's direction + freight. */
freightLanes: RateScheduleRow[];
/** First-mile / last-mile truck legs (route-agnostic). */
additionalServices: RateScheduleRow[];
/** Hazard, reefer, overweight, demurrage, customs, etc. */
surcharges: RateScheduleRow[];
/** True when every group is empty — the template falls back to prose. */
isEmpty: boolean;
/** Currencies present across the schedule, e.g. "USD" or "USD, ETB". */
currencyLabel: string;
}
const UNIT_LABELS: Record<string, string> = {
PER_WAGON: 'per wagon',
PER_TON: 'per ton',
PER_CONTAINER: 'per container',
PER_KM: 'per km',
PER_INVOICE: 'per invoice',
FLAT: 'flat',
};
const SERVICE_ROUTE_LABELS: Partial<Record<Rate['appliesTo'], string>> = {
FIRST_MILE: 'First-mile pickup by truck',
LAST_MILE: 'Last-mile delivery by truck',
};
/** Friendly wording for the trigger-based charges shown in the surcharge group. */
const TRIGGER_ROUTE_LABELS: Partial<Record<Rate['trigger'], string>> = {
HAZARDOUS: 'Hazardous cargo surcharge',
OVERWEIGHT: 'Overweight surcharge',
REEFER: 'Reefer (refrigerated) surcharge',
WITH_RETURN: 'Empty-container return service',
SHIPPING_LINE: 'Shipping line handling',
CONSOLIDATION: 'Container consolidation (extra document)',
LASHING: 'Cargo lashing and securing',
CANCELLATION: 'Booking cancellation fee',
DEMURRAGE: 'Demurrage / wagon detention',
PIL_EXTRA_FEE: 'PIL shipping line extra fee',
CUSTOMS_CLEARANCE: 'Customs clearance service',
};
@Injectable()
export class ContractRateScheduleBuilder {
constructor(private readonly ratesService: RatesService) {}
/**
* Build the rate schedule for a contract of the given direction + freight.
* Base-freight lanes are filtered to the matching trade direction / freight
* kind so an import container contract shows import container lanes only;
* additional services and surcharges are route-agnostic and always shown.
*/
async build(
direction: ContractDirection,
freight: ContractFreight,
): Promise<RateSchedule> {
const rates = await this.ratesService.findLiveRatesDetailed();
const freightLanes: RateScheduleRow[] = [];
const additionalServices: RateScheduleRow[] = [];
const surcharges: RateScheduleRow[] = [];
for (const rate of rates) {
if (this.isBaseFreight(rate)) {
if (this.baseFreightMatches(rate, direction, freight)) {
freightLanes.push(this.laneRow(rate));
}
continue;
}
if (rate.appliesTo === 'FIRST_MILE' || rate.appliesTo === 'LAST_MILE') {
additionalServices.push(this.serviceRow(rate));
continue;
}
// Everything left is a trigger-based charge (surcharge / demurrage / customs).
surcharges.push(this.surchargeRow(rate));
}
const currencyLabel = this.currencyLabel([
...freightLanes,
...additionalServices,
...surcharges,
]);
return {
freightLanes,
additionalServices,
surcharges,
isEmpty:
freightLanes.length === 0 &&
additionalServices.length === 0 &&
surcharges.length === 0,
currencyLabel,
};
}
private isBaseFreight(rate: Rate): boolean {
return (
rate.trigger === 'ALWAYS' &&
(rate.appliesTo === 'BULK' ||
rate.appliesTo === 'CONTAINER' ||
rate.appliesTo === 'INTERCITY')
);
}
private baseFreightMatches(
rate: Rate,
direction: ContractDirection,
freight: ContractFreight,
): boolean {
// Domestic contracts price off intercity rates; the freight kind is carried
// in the derived rateType (INTERCITY_BULK vs INTERCITY_CONTAINER).
if (direction === 'DOM') {
if (rate.appliesTo !== 'INTERCITY') return false;
return freight === 'BULK'
? rate.rateType === 'INTERCITY_BULK'
: rate.rateType === 'INTERCITY_CONTAINER';
}
// Import / export price off BULK or CONTAINER rates matching the direction.
const wantAppliesTo = freight === 'BULK' ? 'BULK' : 'CONTAINER';
if (rate.appliesTo !== wantAppliesTo) return false;
const wantDirection = direction === 'IMP' ? 'IMPORT' : 'EXPORT';
return rate.tradeDirection === wantDirection;
}
private laneRow(rate: Rate): RateScheduleRow {
const origin = rate.originYard?.label ?? rate.originYard?.code ?? '—';
const destination =
rate.destinationYard?.label ?? rate.destinationYard?.code ?? '—';
return {
route: `${origin} → ${destination}`,
cargo: this.cargoLabel(rate),
currency: rate.currency,
amount: this.formatAmount(rate.rateValue),
unit: this.unitLabel(rate.rateUnit),
};
}
private serviceRow(rate: Rate): RateScheduleRow {
return {
route: SERVICE_ROUTE_LABELS[rate.appliesTo] ?? rate.appliesTo,
cargo: this.cargoLabel(rate),
currency: rate.currency,
amount: this.formatAmount(rate.rateValue),
unit: this.unitLabel(rate.rateUnit),
};
}
private surchargeRow(rate: Rate): RateScheduleRow {
return {
route: TRIGGER_ROUTE_LABELS[rate.trigger] ?? this.titleCase(rate.trigger),
cargo: this.cargoLabel(rate),
currency: rate.currency,
amount: this.formatAmount(rate.rateValue),
unit: this.unitLabel(rate.rateUnit),
};
}
/** The type a rate is scoped to (container/cargo), or a dash when unscoped. */
private cargoLabel(rate: Rate): string {
return (
rate.containerType?.label ??
rate.containerType?.code ??
rate.cargoType?.cargoTypeName ??
'—'
);
}
private unitLabel(unit: Rate['rateUnit']): string {
return UNIT_LABELS[unit] ?? unit.toLowerCase().replace(/_/g, ' ');
}
/** Group thousands and drop the DB's trailing zeros: "200.0000" → "200". */
private formatAmount(value: number | string): string {
const num = Number(value);
if (!Number.isFinite(num)) return String(value);
return num.toLocaleString('en-US', {
minimumFractionDigits: 0,
maximumFractionDigits: 2,
});
}
private currencyLabel(rows: RateScheduleRow[]): string {
const seen: string[] = [];
for (const row of rows) {
if (!seen.includes(row.currency)) seen.push(row.currency);
}
return seen.join(', ') || 'USD';
}
private titleCase(value: string): string {
return value
.toLowerCase()
.replace(/_/g, ' ')
.replace(/\b\w/g, (c) => c.toUpperCase());
}
}

9
apps/edr-freight-api/src/contracts/contract-renderer.service.spec.ts
View File

@@ -58,6 +58,15 @@ describe('ContractRendererService', () => {
destinationLabel: 'Modjo',
containerLines: [{ label: '40ft', quantity: 2, vgmPerUnitTons: 12 }],
},
rateSchedule: {
freightLanes: [
{ route: 'SGTD → Modjo', cargo: '40ft GP', currency: 'USD', amount: '200', unit: 'per container' },
],
additionalServices: [],
surcharges: [],
isEmpty: false,
currencyLabel: 'USD',
},
signatures: [],
canSignCustomer: true,
canSignStaff: false,

1
apps/edr-freight-api/src/contracts/contract-renderer.service.ts
View File

@@ -57,6 +57,7 @@ export class ContractRendererService implements OnModuleInit {
.sort((a, b) => (a.order ?? 0) - (b.order ?? 0))
.map((article, index) => ({
number: index + 1,
id: article.id,
title: interpolateTemplateText(article.title, view),
...parseArticleBody(interpolateTemplateText(article.body, view)),
}));

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

@@ -7,6 +7,7 @@ import {
ContractSignerRole,
} from '../modules/bookings/entities/booking-contract-signature.entity';
import { ContractPricingScheduleBuilder, PricingSchedule } from './contract-pricing-schedule.builder';
import { ContractRateScheduleBuilder, RateSchedule } from './contract-rate-schedule.builder';
import { ContractTemplateResolver } from './contract-template.resolver';
import { ContractTemplateMeta, getTemplateMeta } from './contract-template.registry';
@@ -74,6 +75,12 @@ export interface ContractViewModel {
lastMileDeliveryAddress: string;
};
pricing: PricingSchedule;
/**
* The live origin → destination rate schedule (base freight lanes + services
* + surcharges) matching this contract's direction and freight kind. Drives
* the pricing article's rate table so the contract mirrors the rate config.
*/
rateSchedule: RateSchedule;
signatures: ContractSignatureView[];
canSignCustomer: boolean;
canSignStaff: boolean;
@@ -89,6 +96,7 @@ export class ContractViewModelBuilder {
private readonly bookingsRepository: BookingsRepository,
private readonly templateResolver: ContractTemplateResolver,
private readonly pricingBuilder: ContractPricingScheduleBuilder,
private readonly rateScheduleBuilder: ContractRateScheduleBuilder,
) {}
async build(bookingId: string): Promise<{ booking: Booking; view: ContractViewModel }> {
@@ -101,6 +109,10 @@ export class ContractViewModelBuilder {
booking.contractTemplateKey ?? this.templateResolver.resolve(booking);
const template = getTemplateMeta(templateKey);
const pricing = await this.pricingBuilder.build(booking);
const rateSchedule = await this.rateScheduleBuilder.build(
template.direction,
template.freight,
);
const signatures = await this.loadSignatures(bookingId);
const hasCustomer = signatures.some((s) => s.role === 'CUSTOMER');
@@ -143,6 +155,7 @@ export class ContractViewModelBuilder {
},
schedule: this.buildSchedule(booking),
pricing,
rateSchedule,
signatures,
canSignCustomer:
booking.status === 'CONTRACT_READY' && !hasCustomer,

24
apps/edr-freight-api/src/contracts/templates/_partials/article5_pricing.hbs
View File

@@ -25,25 +25,9 @@
<p><strong>Equipment return:</strong> {{pricing.equipmentReturn}}</p>
{{/if}}
{{#if pricing.unitRates}}
<h3>Unit Rate Schedule</h3>
<p>
The rates below are the frozen unit prices applicable to this contract. Quantities and the resulting
totals are determined per shipment at booking time; no total contract value is fixed at this stage.
</p>
<table class="schedule">
<thead>
<tr><th>Item</th><th>Unit price</th></tr>
</thead>
<tbody>
{{#each pricing.unitRates}}
<tr>
<td>{{label}}</td>
<td>{{currency}} {{unitPrice}} / {{unit}}</td>
</tr>
{{/each}}
</tbody>
</table>
{{#unless rateSchedule.isEmpty}}
<h3>Rate Schedule</h3>
{{> rate_schedule}}
{{else}}
<h3>Charges</h3>
<table class="schedule">
@@ -76,7 +60,7 @@
</tr>
</tbody>
</table>
{{/if}}
{{/unless}}
<h3>Terms of payment</h3>
<p>
Unless otherwise agreed in writing, the Client shall settle the contract value in

4
apps/edr-freight-api/src/contracts/templates/_partials/dynamic_articles.hbs
View File

@@ -20,5 +20,9 @@
{{/each}}
</ol>
{{/if}}
{{#if (eq id "pricing")}}
<h3>Rate Schedule</h3>
{{> rate_schedule}}
{{/if}}
</section>
{{/each}}

55
apps/edr-freight-api/src/contracts/templates/_partials/rate_schedule.hbs Normal file
View File

@@ -0,0 +1,55 @@
{{#if rateSchedule.isEmpty}}
<p class="muted-note">
No published rate schedule is currently on file for this corridor. Applicable charges will be quoted
by the Service Provider per shipment in accordance with the prevailing EDR tariff.
</p>
{{else}}
<p>
The charges below are the current published railway tariff for this contract's trade direction and
freight type, expressed as unit prices per origin → destination lane. Quantities and the resulting
totals are determined per shipment at booking time.
</p>
<table class="schedule">
<thead>
<tr>
<th>Route / Service</th>
<th>Cargo / Equipment</th>
<th>Unit price</th>
</tr>
</thead>
<tbody>
{{#if rateSchedule.freightLanes.length}}
<tr><th colspan="3">Railway Freight — Origin → Destination</th></tr>
{{#each rateSchedule.freightLanes}}
<tr>
<td>{{route}}</td>
<td>{{cargo}}</td>
<td>{{currency}} {{amount}} {{unit}}</td>
</tr>
{{/each}}
{{/if}}
{{#if rateSchedule.additionalServices.length}}
<tr><th colspan="3">Additional Services</th></tr>
{{#each rateSchedule.additionalServices}}
<tr>
<td>{{route}}</td>
<td>{{cargo}}</td>
<td>{{currency}} {{amount}} {{unit}}</td>
</tr>
{{/each}}
{{/if}}
{{#if rateSchedule.surcharges.length}}
<tr><th colspan="3">Surcharges, Demurrage &amp; Fees</th></tr>
{{#each rateSchedule.surcharges}}
<tr>
<td>{{route}}</td>
<td>{{cargo}}</td>
<td>{{currency}} {{amount}} {{unit}}</td>
</tr>
{{/each}}
{{/if}}
</tbody>
</table>
{{/if}}

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

@@ -134,26 +134,8 @@
</tbody>
</table>
{{#if pricing.unitRates.length}}
<h3>Agreed Unit Rates</h3>
<p class="muted-note">
The rates below are the frozen unit prices applicable to this contract. Quantities and resulting
totals are determined per shipment at booking time.
</p>
<table class="schedule">
<thead>
<tr><th>Item</th><th>Unit price</th></tr>
</thead>
<tbody>
{{#each pricing.unitRates}}
<tr>
<td>{{label}}</td>
<td>{{currency}} {{unitPrice}} / {{unit}}</td>
</tr>
{{/each}}
</tbody>
</table>
{{/if}}
<h3>Published Rate Schedule</h3>
{{> rate_schedule}}
</section>
{{!-- ────────────────────────── Signatures ───────────────────────────── --}}

14
apps/edr-freight-api/src/migrations/2260000000000-SeedEdrWagonFleetErNumbering.ts
View File

@@ -44,13 +44,13 @@ export class SeedEdrWagonFleetErNumbering2260000000000 implements MigrationInter
// train_set_wagons null their link, wagon_movements cascade.
await queryRunner.query(`DELETE FROM freight.wagons;`);
// Wagon.wagonNumber declares `unique: true`, but some environments never got
// the constraint. Repair it here — the table is empty at this point, so the
// index build cannot fail on pre-existing duplicates.
await queryRunner.query(`
CREATE UNIQUE INDEX IF NOT EXISTS wagons_wagon_number_key
ON freight.wagons (wagon_number);
`);
// Deliberately does NOT create a unique index on wagon_number. It once did,
// to satisfy an ON CONFLICT clause that no longer exists (the DELETE above
// makes collisions impossible). Recreating the plain index here would undo
// WagonNumberPartialUnique2280000000000, which replaces it with a PARTIAL
// unique index so soft-deleted wagons stop reserving their number — this
// seeder is run directly by scripts/seed-edr-wagons.ts, which would
// otherwise resurrect the plain index on an already-migrated database.
for (const row of FLEET) {
if (row.end - row.start + 1 !== row.count) {

28
apps/edr-freight-api/src/migrations/2270000000000-AddWagonTrainNumbers.ts Normal file
View File

@@ -0,0 +1,28 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Per-wagon EXPORT/IMPORT run numbers, editable from the wagon form.
*
* Nullable with no default: a wagon is not on a run until an operator says so.
* Mirrors the width of trains.export_train_number / trains.import_train_number
* (varchar 20) so the two stay comparable.
*/
export class AddWagonTrainNumbers2270000000000 implements MigrationInterface {
name = 'AddWagonTrainNumbers2270000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.wagons
ADD COLUMN IF NOT EXISTS export_train_number varchar(20),
ADD COLUMN IF NOT EXISTS import_train_number varchar(20);
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.wagons
DROP COLUMN IF EXISTS export_train_number,
DROP COLUMN IF EXISTS import_train_number;
`);
}
}

206
apps/edr-freight-api/src/migrations/2280000000000-SeedWagonRunNumbers.ts Normal file
View File

@@ -0,0 +1,206 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Assign EDR export/import run numbers to the wagon fleet.
*
* Runs AFTER SeedEdrWagonFleetErNumbering2260000000000, which recreates every
* wagon with NULL run numbers — so this must stay later in timestamp order.
*
* Source data below is the operator-supplied roster, kept verbatim rather than
* pre-resolved so its quirks stay visible:
* - ER0697 is listed twice under run 8101 (deduped here -> 49, not 50).
* - Four wagons are claimed by two runs each. A wagon holds a single run, so
* FIRST-LISTED WINS, which is why four runs land one short of their listed
* count:
* ER0484 8301 over 8401
* ER0451 8401 over 8701
* ER0887 8701 over 9001
* ER0936 8801 over 8901
*
* Wagons outside this roster (PW2 ER0001-0220 and ER0941-1100) keep NULL runs.
*/
/** Odd EXPORT run (Ethiopia -> Djibouti) -> the wagons rostered to it. */
const RUN_WAGONS: Record<string, string[]> = {
'8001': [
'ER0744', 'ER0734', 'ER0791', 'ER0885', 'ER0410', 'ER0901',
'ER0692', 'ER0784', 'ER0663', 'ER0547', 'ER0635', 'ER0840',
'ER0660', 'ER0541', 'ER0850', 'ER0764', 'ER0786', 'ER0694',
'ER0656', 'ER0432', 'ER0666', 'ER0879', 'ER0724', 'ER0868',
'ER0835', 'ER0650', 'ER0926', 'ER0915', 'ER0858', 'ER0826',
'ER0474', 'ER0539', 'ER0419', 'ER0695', 'ER0462', 'ER0825',
'ER0820', 'ER0790', 'ER0905', 'ER0557', 'ER0712', 'ER0782',
'ER0816', 'ER0447', 'ER0674', 'ER0424', 'ER0544', 'ER0519',
'ER0479', 'ER0440',
],
'8101': [
'ER0458', 'ER0600', 'ER0521', 'ER0559', 'ER0846', 'ER0459',
'ER0863', 'ER0925', 'ER0746', 'ER0821', 'ER0914', 'ER0768',
'ER0676', 'ER0470', 'ER0697', 'ER0697', 'ER0923', 'ER0937',
'ER0431', 'ER0412', 'ER0254', 'ER0555', 'ER0527', 'ER0590',
'ER0480', 'ER0723', 'ER0316', 'ER0800', 'ER0648', 'ER0435',
'ER0844', 'ER0939', 'ER0747', 'ER0654', 'ER0752', 'ER0633',
'ER0725', 'ER0567', 'ER0838', 'ER0920', 'ER0843', 'ER0520',
'ER0646', 'ER0407', 'ER0515', 'ER0760', 'ER0703', 'ER0880',
'ER0422', 'ER0852',
],
'8201': [
'ER0322', 'ER0314', 'ER0274', 'ER0514', 'ER0505', 'ER0618',
'ER0812', 'ER0776', 'ER0698', 'ER0662', 'ER0888', 'ER0625',
'ER0568', 'ER0596', 'ER0918', 'ER0524', 'ER0684', 'ER0231',
'ER0907', 'ER0445', 'ER0839', 'ER0430', 'ER0799', 'ER0464',
'ER0491', 'ER0833', 'ER0855', 'ER0571', 'ER0452', 'ER0733',
'ER0606', 'ER0822', 'ER0845', 'ER0771', 'ER0542', 'ER0588',
'ER0443', 'ER0585', 'ER0624', 'ER0538', 'ER0642', 'ER0928',
'ER0411', 'ER0794', 'ER0564', 'ER0906', 'ER0348', 'ER0236',
'ER0933', 'ER0456',
],
'8301': [
'ER0264', 'ER0691', 'ER0562', 'ER0686', 'ER0881', 'ER0780',
'ER0400', 'ER0420', 'ER0475', 'ER0425', 'ER0396', 'ER0818',
'ER0537', 'ER0917', 'ER0421', 'ER0766', 'ER0728', 'ER0485',
'ER0830', 'ER0804', 'ER0935', 'ER0898', 'ER0577', 'ER0762',
'ER0558', 'ER0612', 'ER0484', 'ER0566', 'ER0876', 'ER0528',
'ER0292', 'ER0630', 'ER0761', 'ER0849', 'ER0578', 'ER0232',
'ER0673', 'ER0870', 'ER0575', 'ER0250', 'ER0599', 'ER0622',
'ER0801', 'ER0806', 'ER0594', 'ER0831', 'ER0513',
],
'8401': [
'ER0616', 'ER0730', 'ER0415', 'ER0522', 'ER0454', 'ER0758',
'ER0715', 'ER0658', 'ER0602', 'ER0649', 'ER0540', 'ER0434',
'ER0678', 'ER0550', 'ER0402', 'ER0636', 'ER0500', 'ER0740',
'ER0664', 'ER0397', 'ER0565', 'ER0704', 'ER0720', 'ER0787',
'ER0884', 'ER0573', 'ER0755', 'ER0392', 'ER0739', 'ER0530',
'ER0437', 'ER0484', 'ER0653', 'ER0502', 'ER0615', 'ER0563',
'ER0641', 'ER0391', 'ER0789', 'ER0451', 'ER0819', 'ER0442',
'ER0798', 'ER0729', 'ER0772', 'ER0940', 'ER0682', 'ER0614',
'ER0561', 'ER0393',
],
'8501': [
'ER0807', 'ER0289', 'ER0587', 'ER0902', 'ER0877', 'ER0748',
'ER0837', 'ER0408', 'ER0307', 'ER0759', 'ER0847', 'ER0433',
'ER0498', 'ER0492', 'ER0735', 'ER0503', 'ER0461', 'ER0508',
'ER0243', 'ER0583', 'ER0924', 'ER0395', 'ER0707', 'ER0572',
'ER0536', 'ER0796', 'ER0929', 'ER0713', 'ER0603', 'ER0814',
'ER0756', 'ER0398', 'ER0853', 'ER0276', 'ER0405', 'ER0418',
'ER0517', 'ER0919', 'ER0781', 'ER0516', 'ER0417', 'ER0702',
'ER0857', 'ER0486', 'ER0637', 'ER0736', 'ER0859', 'ER0483',
'ER0824', 'ER0640', 'ER0714',
],
'8601': [
'ER0455', 'ER0930', 'ER0293', 'ER0294', 'ER0677', 'ER0808',
'ER0785', 'ER0628', 'ER0545', 'ER0551', 'ER0644', 'ER0922',
'ER0670', 'ER0864', 'ER0629', 'ER0306', 'ER0494', 'ER0496',
'ER0679', 'ER0874', 'ER0921', 'ER0910', 'ER0621', 'ER0667',
'ER0262', 'ER0774', 'ER0488', 'ER0300', 'ER0234', 'ER0711',
'ER0605', 'ER0897', 'ER0841', 'ER0778', 'ER0769', 'ER0487',
'ER0556', 'ER0526', 'ER0795', 'ER0268', 'ER0266', 'ER0257',
],
'8701': [
'ER0263', 'ER0661', 'ER0282', 'ER0394', 'ER0423', 'ER0665',
'ER0598', 'ER0909', 'ER0481', 'ER0854', 'ER0471', 'ER0582',
'ER0671', 'ER0466', 'ER0788', 'ER0934', 'ER0683', 'ER0680',
'ER0890', 'ER0531', 'ER0647', 'ER0823', 'ER0608', 'ER0900',
'ER0467', 'ER0607', 'ER0554', 'ER0233', 'ER0911', 'ER0726',
'ER0675', 'ER0291', 'ER0313', 'ER0619', 'ER0775', 'ER0705',
'ER0548', 'ER0891', 'ER0560', 'ER0904', 'ER0429', 'ER0655',
'ER0224', 'ER0700', 'ER0797', 'ER0706', 'ER0533', 'ER0861',
'ER0580', 'ER0449', 'ER0409', 'ER0613', 'ER0645', 'ER0315',
'ER0718', 'ER0553', 'ER0444', 'ER0593', 'ER0499', 'ER0693',
'ER0525', 'ER0451', 'ER0634', 'ER0689', 'ER0878', 'ER0518',
'ER0887',
],
'8801': [
'ER0811', 'ER0652', 'ER0889', 'ER0886', 'ER0936', 'ER0476',
'ER0832', 'ER0626', 'ER0669', 'ER0404', 'ER0546', 'ER0501',
'ER0894', 'ER0460', 'ER0805', 'ER0465', 'ER0717', 'ER0601',
'ER0751', 'ER0777', 'ER0504', 'ER0749', 'ER0827', 'ER0896',
'ER0903', 'ER0591', 'ER0436', 'ER0552', 'ER0716', 'ER0895',
'ER0463', 'ER0809', 'ER0473', 'ER0883', 'ER0569', 'ER0610',
'ER0275', 'ER0333', 'ER0344', 'ER0469',
],
'8901': [
'ER0913', 'ER0310', 'ER0873', 'ER0448', 'ER0763', 'ER0441',
'ER0936', 'ER0767', 'ER0416', 'ER0413', 'ER0589', 'ER0453',
'ER0507', 'ER0287', 'ER0414', 'ER0406', 'ER0584', 'ER0866',
'ER0893', 'ER0627', 'ER0227', 'ER0403', 'ER0428', 'ER0908',
'ER0349', 'ER0221', 'ER0271', 'ER0659', 'ER0765', 'ER0478',
'ER0511', 'ER0506', 'ER0743', 'ER0512', 'ER0916', 'ER0497',
'ER0643', 'ER0638', 'ER0468', 'ER0597',
],
'9001': [
'ER0446', 'ER0802', 'ER0570', 'ER0836', 'ER0576', 'ER0672',
'ER0631', 'ER0490', 'ER0851', 'ER0450', 'ER0872', 'ER0912',
'ER0815', 'ER0882', 'ER0738', 'ER0899', 'ER0620', 'ER0399',
'ER0685', 'ER0477', 'ER0842', 'ER0529', 'ER0617', 'ER0865',
'ER0754', 'ER0737', 'ER0753', 'ER0732', 'ER0623', 'ER0574',
'ER0803', 'ER0651', 'ER0489', 'ER0668', 'ER0741', 'ER0699',
'ER0592', 'ER0225', 'ER0229', 'ER0298', 'ER0270', 'ER0259',
'ER0337', 'ER0770', 'ER0327', 'ER0251', 'ER0285', 'ER0927',
'ER0810', 'ER0681', 'ER0887',
],
};
/**
* Even IMPORT run (Djibouti -> Ethiopia) for each export run. Listed rather
* than computed as export+1 so a run that ever breaks the convention stays
* correct. Run numbers are always 4 digits (8401, never 84001).
*/
const IMPORT_RUN: Record<string, string> = {
'8001': '8002',
'8101': '8102',
'8201': '8202',
'8301': '8302',
'8401': '8402',
'8501': '8502',
'8601': '8602',
'8701': '8702',
'8801': '8802',
'8901': '8902',
'9001': '9002',
};
export class SeedWagonRunNumbers2280000000000 implements MigrationInterface {
name = 'SeedWagonRunNumbers2280000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
// Idempotent: clear the roster's runs first so a re-run cannot leave a
// wagon on a run it was since moved off of.
await queryRunner.query(`
UPDATE freight.wagons
SET export_train_number = NULL, import_train_number = NULL
WHERE export_train_number IS NOT NULL;
`);
const claimed = new Set<string>();
for (const [exportRun, wagons] of Object.entries(RUN_WAGONS)) {
const importRun = IMPORT_RUN[exportRun];
if (!importRun) throw new Error(`import_run_missing:${exportRun}`);
// First-listed wins — skip any wagon an earlier run already claimed.
const fresh = wagons.filter((w) => !claimed.has(w));
fresh.forEach((w) => claimed.add(w));
if (!fresh.length) continue;
await queryRunner.query(
`
UPDATE freight.wagons
SET export_train_number = $1,
import_train_number = $2,
updated_at = now()
WHERE wagon_number = ANY($3::text[]);
`,
[exportRun, importRun, fresh],
);
}
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
UPDATE freight.wagons
SET export_train_number = NULL, import_train_number = NULL
WHERE export_train_number IS NOT NULL;
`);
}
}

29
apps/edr-freight-api/src/migrations/2290000000000-DropContainerWagonsPerUnit.ts Normal file
View File

@@ -0,0 +1,29 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* container_types.wagons_per_unit is no longer stored: the wagon fraction is
* derived from size_ft everywhere (40ft = 1.00 wagon, 20ft = 0.50 — two per
* wagon; see rule-engine/container-type.util.ts). The stored value duplicated
* that rule and could silently drift from it.
*/
export class DropContainerWagonsPerUnit2290000000000 implements MigrationInterface {
name = 'DropContainerWagonsPerUnit2290000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.container_types DROP COLUMN IF EXISTS wagons_per_unit;
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.container_types
ADD COLUMN IF NOT EXISTS wagons_per_unit numeric(4,2);
`);
// Backfill from the same size rule the code now derives from.
await queryRunner.query(`
UPDATE freight.container_types
SET wagons_per_unit = CASE WHEN size_ft >= 40 THEN 1.00 ELSE 0.50 END;
`);
}
}

68
apps/edr-freight-api/src/migrations/2290000000000-SeedWagonYardDoraleh.ts Normal file
View File

@@ -0,0 +1,68 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Stand the whole wagon fleet in Doraleh.
*
* Runs AFTER SeedEdrWagonFleetErNumbering2260000000000, which recreates every
* wagon with a NULL yard — so this must stay later in timestamp order.
*
* A wagon with no yard cannot be coupled to a train (the train builder only
* offers AVAILABLE wagons standing in the train's own yard), which left the
* seeded fleet unusable. Doraleh is the Djibouti-side port yard the import runs
* originate from.
*
* The yard is created when absent: environments disagree about which yards
* exist, so this cannot assume one is there.
*/
const YARD_CODE = 'DORALEH';
export class SeedWagonYardDoraleh2290000000000 implements MigrationInterface {
name = 'SeedWagonYardDoraleh2290000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
// Ensure the yard exists and is usable. Deliberately does NOT overwrite an
// existing label/country — a deployment that already calls this yard
// something else keeps its own naming.
await queryRunner.query(
`
INSERT INTO freight.yards (code, label, country, is_active, display_order)
VALUES ($1, 'Doraleh', 'Djibouti', true, 12)
ON CONFLICT (code) DO UPDATE SET
is_active = true,
deleted_at = NULL,
updated_at = now();
`,
[YARD_CODE],
);
const [yard] = await queryRunner.query(
`SELECT id FROM freight.yards WHERE code = $1 AND deleted_at IS NULL LIMIT 1;`,
[YARD_CODE],
);
if (!yard?.id) {
throw new Error(`yard_missing:${YARD_CODE}`);
}
// Whole fleet — a wagon already coupled to a built train follows the train,
// so leave those where they stand.
await queryRunner.query(
`
UPDATE freight.wagons
SET current_yard_id = $1::uuid,
updated_at = now()
WHERE train_id IS NULL;
`,
[yard.id],
);
}
public async down(queryRunner: QueryRunner): Promise<void> {
// Back to the state SeedEdrWagonFleetErNumbering leaves them in.
await queryRunner.query(`
UPDATE freight.wagons
SET current_yard_id = NULL
WHERE train_id IS NULL;
`);
}
}

85
apps/edr-freight-api/src/migrations/2290000000000-YardFacilities.ts Normal file
View File

@@ -0,0 +1,85 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Intercity (DOMESTIC) cargo is loaded at its origin yard and unloaded at its
* destination yard, but only some yards have the equipment to do it. EDR's
* load/unload facilities are Indode, Sebeta, Modjo, Adama, Dire Dawa and Negad —
* and the set grows, so it must be data, not a constant.
*
* `yards.has_facility` marks a yard as a load/unload point; `yard_facilities`
* holds what that facility can do. Only a facility with `has_warehouse` (Indode
* today) stores cargo, and therefore accrues storage/demurrage — the rest just
* move it on and off the train.
*
* `facility_handling_events` records each load/unload and carries its GRN.
* warehouse_inventory can't do that job: its warehouse/yard/zone are NOT NULL, so
* a facility with no warehouse could never have a row. `inventory_id` links to the
* storage record when the facility does have a warehouse.
*/
export class YardFacilities2290000000000 implements MigrationInterface {
name = 'YardFacilities2290000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.yards
ADD COLUMN IF NOT EXISTS has_facility boolean NOT NULL DEFAULT false
`);
await queryRunner.query(`
CREATE TABLE IF NOT EXISTS freight.yard_facilities (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
yard_id uuid NOT NULL REFERENCES freight.yards(id) ON DELETE CASCADE,
has_warehouse boolean NOT NULL DEFAULT false,
equipment_notes text NULL,
is_active boolean NOT NULL DEFAULT true,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
deleted_at timestamptz NULL
)
`);
// One facility record per yard.
await queryRunner.query(`
CREATE UNIQUE INDEX IF NOT EXISTS "UQ_yard_facility_yard"
ON freight.yard_facilities (yard_id) WHERE deleted_at IS NULL
`);
await queryRunner.query(`
CREATE TABLE IF NOT EXISTS freight.facility_handling_events (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
booking_id uuid NOT NULL REFERENCES freight.bookings(id),
yard_id uuid NOT NULL REFERENCES freight.yards(id),
train_schedule_id uuid NULL REFERENCES freight.train_schedules(id),
event_type varchar(10) NOT NULL,
grn_number varchar(60) NULL,
quantity numeric(14, 3) NULL,
weight_tons numeric(14, 3) NULL,
inventory_id uuid NULL REFERENCES freight.warehouse_inventory(id),
performed_by varchar(120) NULL,
occurred_at timestamptz NOT NULL DEFAULT now(),
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
deleted_at timestamptz NULL
)
`);
await queryRunner.query(`
CREATE INDEX IF NOT EXISTS "IDX_facility_handling_events_booking"
ON freight.facility_handling_events (booking_id)
`);
await queryRunner.query(`
CREATE INDEX IF NOT EXISTS "IDX_facility_handling_events_yard"
ON freight.facility_handling_events (yard_id)
`);
await queryRunner.query(`
CREATE INDEX IF NOT EXISTS "IDX_facility_handling_events_grn"
ON freight.facility_handling_events (grn_number) WHERE grn_number IS NOT NULL
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`DROP TABLE IF EXISTS freight.facility_handling_events`);
await queryRunner.query(`DROP TABLE IF EXISTS freight.yard_facilities`);
await queryRunner.query(`
ALTER TABLE freight.yards DROP COLUMN IF EXISTS has_facility
`);
}
}

47
apps/edr-freight-api/src/migrations/2300000000000-CreateRateChangeRequests.ts Normal file
View File

@@ -0,0 +1,47 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Approval workflow for edits to LIVE rates. A LIVE rate is what pricing
* charges, so it is never edited in place: the edit is filed here as PENDING
* and the live row keeps its value until an approver applies it.
*
* `payload` holds the changed fields only; `previous_values` snapshots what
* they were at submit time so the approver sees a real before→after diff.
*/
export class CreateRateChangeRequests2300000000000 implements MigrationInterface {
name = 'CreateRateChangeRequests2300000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
CREATE TABLE IF NOT EXISTS freight.rate_change_requests (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
rate_id uuid NOT NULL REFERENCES freight.rates (id),
payload jsonb NOT NULL,
previous_values jsonb NOT NULL,
status varchar(10) NOT NULL DEFAULT 'PENDING',
requested_by_user_id uuid NULL,
decided_by_user_id uuid NULL,
decided_at timestamptz NULL,
decision_note text NULL,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
deleted_at timestamptz NULL
)
`);
await queryRunner.query(`
CREATE INDEX IF NOT EXISTS idx_rcr_status
ON freight.rate_change_requests (status)
`);
// At most one pending edit per rate — two racing requests would both pass
// validation and the second would silently overwrite the first on approval.
await queryRunner.query(`
CREATE UNIQUE INDEX IF NOT EXISTS uq_rcr_one_pending_per_rate
ON freight.rate_change_requests (rate_id)
WHERE status = 'PENDING' AND deleted_at IS NULL
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`DROP TABLE IF EXISTS freight.rate_change_requests`);
}
}

83
apps/edr-freight-api/src/migrations/2300000000000-RepairGpsTrackingTables.ts Normal file
View File

@@ -0,0 +1,83 @@
import { MigrationInterface, QueryRunner } from "typeorm";
/**
* Repair for environments missing the GPS tracking tables.
*
* AddGpsTracking2000000000000 creates freight.gps_devices / gps_positions, but
* some databases have it RECORDED in public.migrations without the tables ever
* landing. TypeORM never re-runs a recorded migration, so those environments
* stay broken through any number of restarts — the GT06 listener accepts tracker
* packets on its TCP port regardless of schema state and fails per packet with
* `relation "freight.gps_devices" does not exist`, dropping position fixes.
*
* This re-issues the same DDL under a new name so it is applied afresh. Every
* statement is IF NOT EXISTS, so it is a no-op where the tables already exist
* and safe on every environment.
*
* Kept byte-identical to the original DDL on purpose: this must converge on the
* schema the entities expect, not a variant of it.
*/
export class RepairGpsTrackingTables2300000000000 implements MigrationInterface {
name = "RepairGpsTrackingTables2300000000000";
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
CREATE TABLE IF NOT EXISTS freight.gps_devices (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
imei varchar(20) NOT NULL UNIQUE,
name varchar,
vehicle_id uuid REFERENCES freight.vehicles(id),
status varchar(16) NOT NULL DEFAULT 'REGISTERED',
last_seen_at timestamptz,
last_lat numeric(10,6),
last_lng numeric(10,6),
last_speed numeric(6,2),
last_course int,
last_fix_at timestamptz,
voltage_level int,
gsm_level int,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
deleted_at timestamptz
)
`);
await queryRunner.query(`
CREATE INDEX IF NOT EXISTS "IDX_GPS_DEVICES_VEHICLE"
ON freight.gps_devices (vehicle_id)
`);
await queryRunner.query(`
CREATE TABLE IF NOT EXISTS freight.gps_positions (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
device_id uuid NOT NULL,
imei varchar(20) NOT NULL,
vehicle_id uuid,
lat numeric(10,6) NOT NULL,
lng numeric(10,6) NOT NULL,
speed numeric(6,2) NOT NULL DEFAULT 0,
course int NOT NULL DEFAULT 0,
satellites int NOT NULL DEFAULT 0,
positioned boolean NOT NULL DEFAULT false,
gps_time timestamptz NOT NULL,
alarm int NOT NULL DEFAULT 0,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
deleted_at timestamptz
)
`);
await queryRunner.query(`
CREATE INDEX IF NOT EXISTS "IDX_GPS_POSITIONS_DEVICE_TIME"
ON freight.gps_positions (device_id, gps_time)
`);
await queryRunner.query(`
CREATE INDEX IF NOT EXISTS "IDX_GPS_POSITIONS_VEHICLE_TIME"
ON freight.gps_positions (vehicle_id, gps_time)
`);
}
public async down(): Promise<void> {
// No-op: dropping the tables would discard tracker history on environments
// where this migration was the one that created them. AddGpsTracking owns
// the teardown.
}
}

78
apps/edr-freight-api/src/migrations/2310000000000-CreateSupportChat.ts Normal file
View File

@@ -0,0 +1,78 @@
import { MigrationInterface, QueryRunner } from "typeorm";
/**
* Customer-support chat. A `support_conversations` row is the single ongoing
* thread with a company; `support_messages` are its text messages. There is no
* lifecycle column — a thread is opened by whichever side speaks first and
* stays open. Enum-like columns are varchar (no PG enum churn).
*
* The unique index on `company_id` is load-bearing, not just an optimization:
* the get-or-create path depends on it to settle concurrent first-messages.
* It is partial on `deleted_at IS NULL` so a soft-deleted thread doesn't block
* a fresh one.
*/
export class CreateSupportChat2310000000000 implements MigrationInterface {
name = "CreateSupportChat2310000000000";
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
CREATE TABLE IF NOT EXISTS freight.support_conversations (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
company_id uuid NOT NULL,
company_name varchar(200),
created_by_user_id uuid,
last_message_at timestamptz,
last_message_preview varchar(280),
last_message_author_role varchar(12),
customer_last_read_at timestamptz,
agent_last_read_at timestamptz,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
deleted_at timestamptz
)
`);
await queryRunner.query(`
CREATE UNIQUE INDEX IF NOT EXISTS "IDX_SUPPORT_CONV_COMPANY"
ON freight.support_conversations (company_id)
WHERE deleted_at IS NULL
`);
await queryRunner.query(`
CREATE INDEX IF NOT EXISTS "IDX_SUPPORT_CONV_LASTMSG"
ON freight.support_conversations (last_message_at)
`);
await queryRunner.query(`
CREATE TABLE IF NOT EXISTS freight.support_messages (
id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
conversation_id uuid NOT NULL,
author_user_id uuid NOT NULL,
author_role varchar(12) NOT NULL,
author_name varchar(200),
body text NOT NULL,
created_at timestamptz NOT NULL DEFAULT now(),
updated_at timestamptz NOT NULL DEFAULT now(),
deleted_at timestamptz
)
`);
await queryRunner.query(`
CREATE INDEX IF NOT EXISTS "IDX_SUPPORT_MSG_CONV_CREATED"
ON freight.support_messages (conversation_id, created_at)
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`DROP INDEX IF EXISTS freight."IDX_SUPPORT_MSG_CONV_CREATED"`,
);
await queryRunner.query(`DROP TABLE IF EXISTS freight.support_messages`);
await queryRunner.query(
`DROP INDEX IF EXISTS freight."IDX_SUPPORT_CONV_LASTMSG"`,
);
await queryRunner.query(
`DROP INDEX IF EXISTS freight."IDX_SUPPORT_CONV_COMPANY"`,
);
await queryRunner.query(
`DROP TABLE IF EXISTS freight.support_conversations`,
);
}
}

140
apps/edr-freight-api/src/migrations/2320000000000-AddRateYardScope.ts Normal file
View File

@@ -0,0 +1,140 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Scope base rail freight to a route (origin yard → destination yard).
*
* Until now a base-freight rate was keyed by direction + container/bulk scope
* only, so "container import" cost the same whether the box was railed to Dire
* Dawa or to Mojo. Rates now carry the yard pair the price is quoted for, which
* is what the business actually sells: `container import, Djibouti → Dire Dawa,
* 500 USD`.
*
* Existing base-freight rates predate the yard pair and cannot be backfilled —
* there is no way to know which route each was meant for. They are retired
* (SUPERSEDED + soft-deleted) rather than deleted, because booking_rate_snapshot
* and rate_change_requests hold FKs to them (RESTRICT) and those rows are price
* history. Retiring drops them out of pricing and the admin UI just the same;
* the yard-scoped replacements must be re-entered.
*
* Surcharges, first-mile and last-mile rates are untouched: they are not
* route-scoped and keep NULL yards.
*/
export class AddRateYardScope2320000000000 implements MigrationInterface {
name = 'AddRateYardScope2320000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
// ── 1. Yard columns + FKs ──────────────────────────────────────────────
await queryRunner.query(`
ALTER TABLE freight.rates
ADD COLUMN IF NOT EXISTS origin_yard_id uuid NULL,
ADD COLUMN IF NOT EXISTS destination_yard_id uuid NULL;
`);
await queryRunner.query(`
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'FK_rates_origin_yard_id') THEN
ALTER TABLE freight.rates
ADD CONSTRAINT "FK_rates_origin_yard_id"
FOREIGN KEY (origin_yard_id) REFERENCES freight.yards(id);
END IF;
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'FK_rates_destination_yard_id') THEN
ALTER TABLE freight.rates
ADD CONSTRAINT "FK_rates_destination_yard_id"
FOREIGN KEY (destination_yard_id) REFERENCES freight.yards(id);
END IF;
END $$;
`);
await queryRunner.query(
`CREATE INDEX IF NOT EXISTS "IDX_rates_origin_yard_id" ON freight.rates (origin_yard_id);`,
);
await queryRunner.query(
`CREATE INDEX IF NOT EXISTS "IDX_rates_destination_yard_id" ON freight.rates (destination_yard_id);`,
);
// ── 2. Retire route-less base freight ──────────────────────────────────
// Soft-delete, not DELETE: booking_rate_snapshot.rate_id is ON DELETE
// RESTRICT and those snapshots are what past bookings were charged.
await queryRunner.query(`
UPDATE freight.rates
SET status = 'SUPERSEDED',
deleted_at = now(),
updated_at = now()
WHERE deleted_at IS NULL
AND "trigger" = 'ALWAYS'
AND applies_to IN ('BULK', 'CONTAINER', 'INTERCITY');
`);
// ── 3. Route is part of a rate's identity ──────────────────────────────
// Two rates may now share rateType + scope + unit as long as they price
// different legs, so the yard pair joins the uniqueness tuple.
await queryRunner.query(`DROP INDEX IF EXISTS freight."UQ_rates_pattern";`);
await queryRunner.query(`
CREATE UNIQUE INDEX IF NOT EXISTS "UQ_rates_pattern"
ON freight.rates (
rate_type,
COALESCE(container_type_id, '00000000-0000-0000-0000-000000000000'::uuid),
COALESCE(cargo_type_id, '00000000-0000-0000-0000-000000000000'::uuid),
COALESCE(trade_direction, ''),
COALESCE(origin_yard_id, '00000000-0000-0000-0000-000000000000'::uuid),
COALESCE(destination_yard_id, '00000000-0000-0000-0000-000000000000'::uuid),
rate_unit
)
WHERE deleted_at IS NULL AND status <> 'SUPERSEDED';
`);
// ── 4. Base freight must carry a route; nothing else may ───────────────
// Retired rows are exempt — they are the route-less rates step 2 just
// superseded, and they must stay readable for snapshot history.
await queryRunner.query(`
DO $$ BEGIN
IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'CK_rates_yard_scope') THEN
ALTER TABLE freight.rates
ADD CONSTRAINT "CK_rates_yard_scope" CHECK (
deleted_at IS NOT NULL
OR status = 'SUPERSEDED'
OR CASE
WHEN "trigger" = 'ALWAYS' AND applies_to IN ('BULK', 'CONTAINER', 'INTERCITY')
THEN origin_yard_id IS NOT NULL AND destination_yard_id IS NOT NULL
ELSE origin_yard_id IS NULL AND destination_yard_id IS NULL
END
);
END IF;
END $$;
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
// The retired rates are not un-superseded: which route each belonged to was
// never recorded, so reviving them would restore rates that price the wrong
// legs. Down only reverses the schema.
await queryRunner.query(
`ALTER TABLE freight.rates DROP CONSTRAINT IF EXISTS "CK_rates_yard_scope";`,
);
await queryRunner.query(`DROP INDEX IF EXISTS freight."UQ_rates_pattern";`);
await queryRunner.query(`
CREATE UNIQUE INDEX IF NOT EXISTS "UQ_rates_pattern"
ON freight.rates (
rate_type,
COALESCE(container_type_id, '00000000-0000-0000-0000-000000000000'::uuid),
COALESCE(cargo_type_id, '00000000-0000-0000-0000-000000000000'::uuid),
COALESCE(trade_direction, ''),
rate_unit
)
WHERE deleted_at IS NULL AND status <> 'SUPERSEDED';
`);
await queryRunner.query(`DROP INDEX IF EXISTS freight."IDX_rates_destination_yard_id";`);
await queryRunner.query(`DROP INDEX IF EXISTS freight."IDX_rates_origin_yard_id";`);
await queryRunner.query(
`ALTER TABLE freight.rates DROP CONSTRAINT IF EXISTS "FK_rates_destination_yard_id";`,
);
await queryRunner.query(
`ALTER TABLE freight.rates DROP CONSTRAINT IF EXISTS "FK_rates_origin_yard_id";`,
);
await queryRunner.query(`
ALTER TABLE freight.rates
DROP COLUMN IF EXISTS destination_yard_id,
DROP COLUMN IF EXISTS origin_yard_id;
`);
}
}

52
apps/edr-freight-api/src/migrations/2330000000000-AddBookingCloseOffset.ts Normal file
View File

@@ -0,0 +1,52 @@
import { MigrationInterface, QueryRunner } from "typeorm";
/**
* Add a global "booking close offset" — how long BEFORE departure a schedule's
* booking window shuts — configurable separately for import and export.
*
* When an offset is set, the window's close instant is `departure − offset`
* (e.g. departure 17:00 with a 3-hour import offset closes at 14:00; departure
* Jul-10 16:00 with a 1-day export offset closes Jul-9 16:00). It caps the whole
* booking lifecycle: the first window close, every reopen cycle, and the export
* FCFS close all land at/at-or-before this cutoff instead of at departure.
*
* NULL / 0 preserves the previous behaviour exactly (import closes at
* open+duration clamped to departure; export closes at departure), so existing
* installs are unaffected until an offset is entered.
*
* `*_close_offset_minutes` on the global-rules singleton is the live config; the
* matching `rule_*_close_offset_minutes` snapshot on each schedule freezes it at
* creation so the batch board keeps drawing the window the customer was shown
* even after a later global-rules edit. Both are nullable with no backfill —
* absent means "no offset", the safe default.
*/
export class AddBookingCloseOffset2330000000000 implements MigrationInterface {
name = "AddBookingCloseOffset2330000000000";
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.train_scheduling_global_rules
ADD COLUMN IF NOT EXISTS import_close_offset_minutes integer,
ADD COLUMN IF NOT EXISTS export_close_offset_minutes integer;
`);
await queryRunner.query(`
ALTER TABLE freight.train_schedules
ADD COLUMN IF NOT EXISTS rule_import_close_offset_minutes integer,
ADD COLUMN IF NOT EXISTS rule_export_close_offset_minutes integer;
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.train_schedules
DROP COLUMN IF EXISTS rule_import_close_offset_minutes,
DROP COLUMN IF EXISTS rule_export_close_offset_minutes;
`);
await queryRunner.query(`
ALTER TABLE freight.train_scheduling_global_rules
DROP COLUMN IF EXISTS import_close_offset_minutes,
DROP COLUMN IF EXISTS export_close_offset_minutes;
`);
}
}

26
apps/edr-freight-api/src/migrations/2340000000000-AddCargoTypeHasLashing.ts Normal file
View File

@@ -0,0 +1,26 @@
import { MigrationInterface, QueryRunner } from "typeorm";
/**
* Add `has_lashing` to cargo types.
*
* When true, every booking of that cargo type incurs the flat LASHING
* surcharge (a rate with trigger = 'LASHING'). Defaults to false so existing
* cargo ships without the fee until the flag is turned on.
*/
export class AddCargoTypeHasLashing2340000000000 implements MigrationInterface {
name = "AddCargoTypeHasLashing2340000000000";
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.cargo_types
ADD COLUMN IF NOT EXISTS has_lashing boolean NOT NULL DEFAULT false;
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.cargo_types
DROP COLUMN IF EXISTS has_lashing;
`);
}
}

30
apps/edr-freight-api/src/migrations/2340000000000-AddReverseWagonOrder.ts Normal file
View File

@@ -0,0 +1,30 @@
import { MigrationInterface, QueryRunner } from "typeorm";
/**
* Add an opt-in "reverse wagon order" flag to a train schedule.
*
* When true, the built wagon plan is flipped at build time so the physically-last
* wagon sits at position 1. Only the order (sequence_no) changes — composition and
* booking allocations travel with their slot. The flag is frozen on the schedule
* at creation and re-applied every time the wagon plan is rebuilt, so the stored
* train order and the schedule order always match.
*
* Defaults to false; existing schedules keep their as-built order.
*/
export class AddReverseWagonOrder2340000000000 implements MigrationInterface {
name = "AddReverseWagonOrder2340000000000";
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.train_schedules
ADD COLUMN IF NOT EXISTS reverse_wagon_order boolean NOT NULL DEFAULT false;
`);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(`
ALTER TABLE freight.train_schedules
DROP COLUMN IF EXISTS reverse_wagon_order;
`);
}
}

63
apps/edr-freight-api/src/migrations/2350000000000-RefreshContractPricingArticles.ts Normal file
View File

@@ -0,0 +1,63 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
import { CONTRACT_TEMPLATE_DEFAULTS } from '../seed/data/contract-template-defaults';
/**
* Refresh the "pricing" article of each seeded contract template so it points
* at the live Rate Schedule instead of hardcoded price figures (USD 400/wagon,
* USD 919/40ft, …). The original CreateContractTemplates migration seeded the
* old prose with ON CONFLICT DO NOTHING, so those figures are frozen in the DB
* rows and would otherwise contradict the rate-config-driven schedule table now
* rendered under the pricing article.
*
* Only the article whose id = 'pricing' is touched, and only when its body
* still matches the originally-seeded prose — so any admin edit to the pricing
* article is left untouched. Idempotent: re-running is a no-op once refreshed.
*/
export class RefreshContractPricingArticles2350000000000
implements MigrationInterface
{
public async up(queryRunner: QueryRunner): Promise<void> {
for (const seed of CONTRACT_TEMPLATE_DEFAULTS) {
const pricing = seed.articles.find((article) => article.id === 'pricing');
if (!pricing) continue;
// jsonb_set the title + body of the element whose id = 'pricing', matched
// by array index. Guarded so admin-edited bodies are never overwritten.
await queryRunner.query(
`
UPDATE freight.contract_templates ct
SET articles = (
SELECT jsonb_agg(
CASE
WHEN elem->>'id' = 'pricing'
THEN elem || jsonb_build_object('title', $2::text, 'body', $3::text)
ELSE elem
END
)
FROM jsonb_array_elements(ct.articles) elem
)
WHERE ct.code = $1
AND EXISTS (
SELECT 1 FROM jsonb_array_elements(ct.articles) e
WHERE e->>'id' = 'pricing'
AND e->>'body' LIKE ANY (ARRAY[
'%USD 59.4 per metric ton%',
'%USD 696 (six hundred ninety-six) per wagon%',
'%USD 400 (four hundred) per wagon%',
'%From SGTD to Dire Dawa dry port, the rate is USD 919%',
'%Railway transportation charges from GMP to SGTD: USD 819%',
'%prevailing EDR domestic container tariff, as set out in the commercial schedule%'
])
);
`,
[seed.code, pricing.title, pricing.body],
);
}
}
public async down(): Promise<void> {
// No-op: the refreshed pricing prose is the correct forward state; reverting
// to hardcoded figures would reintroduce the rate-schedule contradiction.
}
}

69
apps/edr-freight-api/src/migrations/2360000000000-RefreshContractPricingArticles.ts Normal file
View File

@@ -0,0 +1,69 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
import { CONTRACT_TEMPLATE_DEFAULTS } from '../seed/data/contract-template-defaults';
/**
* Refresh the `pricing` article body of the six seeded contract templates to
* the live-rate-schedule wording. The per-lane figures (e.g. "USD 400 per
* wagon") are now rendered from the LIVE rate config instead of frozen prose,
* so any template whose pricing article still carries a hardcoded price token
* is rewritten to the current seed text.
*
* The guard `body ~ '(USD|ETB) [0-9]'` identifies the auto-seeded original
* prose (which always quoted a currency + figure) and matches neither an
* already-migrated body nor a hand-edited one that adopted the schedule
* wording — so admin edits are preserved. Idempotent: after the rewrite the
* price token is gone, so a re-run is a no-op. Fresh databases seed the new
* text directly (CreateContractTemplates imports the same seed), making this
* a targeted backfill for databases seeded before the seed changed.
*/
const HARDCODED_PRICE_TOKEN = '(USD|ETB) [0-9]';
export class RefreshContractPricingArticles2360000000000
implements MigrationInterface
{
public async up(queryRunner: QueryRunner): Promise<void> {
for (const seed of CONTRACT_TEMPLATE_DEFAULTS) {
const pricing = seed.articles.find((a) => a.id === 'pricing');
if (!pricing) continue;
// Rewrite only the article whose id = 'pricing', in place, and only when
// its body still quotes a hardcoded currency figure. jsonb_agg keeps the
// rest of the article (id/title/order) and every other article intact.
await queryRunner.query(
`
UPDATE freight.contract_templates AS t
SET articles = (
SELECT jsonb_agg(
CASE
WHEN elem->>'id' = 'pricing'
THEN jsonb_set(elem, '{body}', to_jsonb($2::text), true)
ELSE elem
END
ORDER BY ord
)
FROM jsonb_array_elements(t.articles) WITH ORDINALITY AS a(elem, ord)
),
updated_at = now()
WHERE t.code = $1
AND EXISTS (
SELECT 1
FROM jsonb_array_elements(t.articles) AS x
WHERE x->>'id' = 'pricing'
AND x->>'body' ~ $3
);
`,
[seed.code, pricing.body, HARDCODED_PRICE_TOKEN],
);
}
}
/**
* Irreversible in practice — the original per-lane figures are not restored.
* A no-op down keeps the migration reversible-by-contract without
* resurrecting stale hardcoded prices.
*/
public async down(): Promise<void> {
// intentionally empty
}
}

28
apps/edr-freight-api/src/migrations/2370000000000-AddContainerUnitReturnFlag.ts Normal file
View File

@@ -0,0 +1,28 @@
import { MigrationInterface, QueryRunner } from 'typeorm';
/**
* Per-container handling opt-in: each physical container can now be marked
* hazardous / reefer / with-return individually, next to its VGM. The hazardous
* and reefer flags already existed on the unit row; only the return leg was
* missing, so a booking of 20 containers with 10 returning empty can bill the
* WITH_RETURN surcharge on 10 instead of all 20.
*
* Backfill: existing rows keep false. The line-level counts
* (booking_container.return_quantity etc.) stay authoritative for bookings made
* before this change — the rule engine falls back to them when no unit is flagged.
*/
export class AddContainerUnitReturnFlag2370000000000 implements MigrationInterface {
name = 'AddContainerUnitReturnFlag2370000000000';
public async up(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE "freight"."booking_container_units" ADD COLUMN IF NOT EXISTS "is_return" boolean NOT NULL DEFAULT false`,
);
}
public async down(queryRunner: QueryRunner): Promise<void> {
await queryRunner.query(
`ALTER TABLE "freight"."booking_container_units" DROP COLUMN IF EXISTS "is_return"`,
);
}
}

62
apps/edr-freight-api/src/modules/auth/account.controller.ts Normal file
View File

@@ -0,0 +1,62 @@
import { Body, Controller, Patch, Post, UseGuards } from "@nestjs/common";
import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
import { CurrentUser } from "@tria-plc/api-common/modules/auth/decorators/current-user.decorator";
import { JwtGuard } from "@tria-plc/api-common/modules/auth/services/jwt.guard";
import type { TCurrentUser } from "@tria-plc/api-common/modules/auth/types/current-user.type";
import { AccountService } from "./account.service";
import {
SendContactOtpDto,
UpdateAccountNameDto,
UpdateContactDto,
} from "./dto/account.dto";
/**
* The caller's own account record. Everything here is scoped to the JWT's user
* id — there is no `:id` parameter to tamper with, so these routes need no
* permission key beyond being authenticated.
*/
@ApiTags("auth")
@Controller("me")
@ApiBearerAuth()
@UseGuards(JwtGuard)
export class AccountController {
constructor(private readonly accountService: AccountService) {}
@Post("contact/otp")
@ApiOperation({
summary: "Send a verification code to a new email/phone before changing it",
description:
"The code goes to the NEW value supplied here, proving the caller controls " +
"it. Returns the target masked — an unverified caller never gets it back in full.",
})
sendContactOtp(
@CurrentUser() user: TCurrentUser,
@Body() dto: SendContactOtpDto,
): Promise<{ sentTo: string }> {
return this.accountService.sendContactOtp(user.id, dto);
}
@Patch("contact")
@ApiOperation({
summary: "Change the account's email or phone, gated by a verification code",
description:
"Verifies the code and writes the new value in one call, so the API never " +
"has to take a client's word that verification happened.",
})
updateContact(
@CurrentUser() user: TCurrentUser,
@Body() dto: UpdateContactDto,
): Promise<{ success: true; value: string }> {
return this.accountService.updateContact(user.id, dto);
}
@Patch("name")
@ApiOperation({ summary: "Change the account's display name" })
updateName(
@CurrentUser() user: TCurrentUser,
@Body() dto: UpdateAccountNameDto,
): Promise<{ success: true }> {
return this.accountService.updateName(user.id, dto);
}
}

226
apps/edr-freight-api/src/modules/auth/account.service.ts Normal file
View File

@@ -0,0 +1,226 @@
import {
BadRequestException,
ConflictException,
Injectable,
Logger,
} from "@nestjs/common";
import { InjectDataSource, InjectRepository } from "@nestjs/typeorm";
import { DataSource, EntityManager, Repository } from "typeorm";
import { isValidPhoneNumber } from "libphonenumber-js";
import { EUserVerifiedBy } from "@tria-plc/api-common/utils/enums/user.enum";
import type { TCurrentTokenUser } from "@tria-plc/iamapi-common/types/current-user.type";
import { Employee } from "@tria-plc/iamapi-common/entities/iam/organization-structure/employee.entity";
import { Session } from "@tria-plc/iamapi-common/entities/iam/user/session.entity";
import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
import { normalizeE164 } from "../../common/validators/is-phone-number.validator";
import { OtpService, OtpTarget } from "../otp/otp.service";
import {
ContactChannel,
SendContactOtpDto,
UpdateAccountNameDto,
UpdateContactDto,
} from "./dto/account.dto";
import { maskOtpTarget } from "./mask-target.util";
/** How long a contact-change code stays valid before it must be re-requested. */
const CONTACT_OTP_TTL_MS = 10 * 60 * 1000;
/** Postgres unique-violation SQLSTATE. */
const PG_UNIQUE_VIOLATION = "23505";
/**
* Self-serve management of the caller's own IAM user record.
*
* IAM ships `PATCH /api/auth/update-profile`, but it takes email + username +
* phone + name all at once (every field `@IsNotEmpty`) and performs no
* verification — it will move an account's phone to any number the caller
* types. These routes exist so a contact change is *proven*: the code goes to
* the NEW address and the write only lands once it comes back.
*/
@Injectable()
export class AccountService {
private readonly logger = new Logger(AccountService.name);
constructor(
@InjectRepository(User)
private readonly userRepository: Repository<User>,
@InjectDataSource()
private readonly dataSource: DataSource,
private readonly otpService: OtpService,
) {}
/**
* Send a code to the address the caller wants to move TO. Sending to the new
* value (rather than the one on file) is the whole point — it proves control
* of the destination before anything is written.
*/
async sendContactOtp(
userId: string,
dto: SendContactOtpDto,
): Promise<{ sentTo: string }> {
const value = this.normalize(dto.channel, dto.value);
await this.assertNotTaken(dto.channel, value, userId);
const target = this.targetFor(dto.channel, value);
await this.otpService.sendOtp(target);
return { sentTo: maskOtpTarget(target) };
}
/**
* Verify the code, then write the new contact value. The verify and the write
* are one call: the API never has to trust that a client "already verified"
* — unlike the signup flow, where the OTP is client-orchestrated and
* `POST /api/otp/verify` is a separate public route the client may simply skip.
*/
async updateContact(
userId: string,
dto: UpdateContactDto,
): Promise<{ success: true; value: string }> {
const value = this.normalize(dto.channel, dto.value);
await this.assertNotTaken(dto.channel, value, userId);
await this.otpService.verifyOtpForAction(
this.targetFor(dto.channel, value),
dto.otp,
CONTACT_OTP_TTL_MS,
);
const isEmail = dto.channel === ContactChannel.Email;
const userPatch = isEmail
? { email: value }
: {
phoneNumber: value,
// The number just passed an OTP, which is exactly what IAM's own
// phone-verification flag means. Set it here so the freight app stops
// needing its own parallel "verified phone" bookkeeping.
isPhoneNumberVerified: true,
verifiedBy: EUserVerifiedBy.PHONE_NUMBER,
};
const sessionPatch: Partial<TCurrentTokenUser> = isEmail
? { email: value }
: { phoneNumber: value, isPhoneNumberVerified: true };
try {
await this.dataSource.transaction(async (manager) => {
await manager.getRepository(User).update({ id: userId }, userPatch);
await this.refreshSessions(manager, userId, sessionPatch);
});
} catch (error) {
throw this.asConflict(error, dto.channel);
}
this.logger.log(`Account ${dto.channel} updated for user ${userId}`);
return { success: true, value };
}
/** Rename the account. No OTP — a name change proves nothing and grants nothing. */
async updateName(
userId: string,
dto: UpdateAccountNameDto,
): Promise<{ success: true }> {
const en = dto.name.en?.trim();
const name = { am: dto.name.am.trim(), ...(en ? { en } : {}) };
await this.dataSource.transaction(async (manager) => {
await manager.getRepository(User).update({ id: userId }, { name });
// IAM mirrors the name onto the employee row. Portal customers are
// `individual` users with no employee row at all, so this is a no-op for
// them — hence an unconditional update() rather than a lookup-then-write.
await manager.getRepository(Employee).update({ userId }, { name });
await this.refreshSessions(manager, userId, { name });
});
return { success: true };
}
/**
* `GET /api/auth/me` serves `session.userInfo` — a snapshot IAM writes only
* when a session is created at login. Without patching it here, a saved change
* stays invisible to /me (and to anything reading the token's claims) until the
* user logs out and back in, which reads as "my edit didn't save".
*/
private async refreshSessions(
manager: EntityManager,
userId: string,
patch: Partial<TCurrentTokenUser>,
): Promise<void> {
const repo = manager.getRepository(Session);
const sessions = await repo.find({ where: { userId } });
await Promise.all(
sessions.map((session) =>
repo.update(
{ id: session.id },
{ userInfo: { ...session.userInfo, ...patch } },
),
),
);
}
/** Canonicalise for the channel and reject anything malformed up front. */
private normalize(channel: ContactChannel, value: string): string {
const raw = value.trim();
if (channel === ContactChannel.Email) {
const email = raw.toLowerCase();
if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
throw new BadRequestException("A valid email address is required");
}
return email;
}
if (!isValidPhoneNumber(raw)) {
throw new BadRequestException(
"A valid international phone number is required (E.164, e.g. +251911223344)",
);
}
// Store the same canonical form the OTP is keyed by, so the code sent here
// is findable on verify regardless of how the number was typed.
return normalizeE164(raw) as string;
}
private targetFor(channel: ContactChannel, value: string): OtpTarget {
return channel === ContactChannel.Email ? { email: value } : { phone: value };
}
/**
* `iam.users.email` and `.phone_number` are each independently UNIQUE, so a
* collision would otherwise surface as a raw 500 at write time. This is a
* courtesy check, not the guard — it races, so {@link asConflict} still has to
* catch the violation.
*/
private async assertNotTaken(
channel: ContactChannel,
value: string,
userId: string,
): Promise<void> {
const existing = await this.userRepository.findOne({
where:
channel === ContactChannel.Email
? { email: value }
: { phoneNumber: value },
select: { id: true },
});
if (existing && existing.id !== userId) {
throw this.takenError(channel);
}
}
private asConflict(error: unknown, channel: ContactChannel): Error {
const code = (error as { code?: string } | null)?.code;
if (code === PG_UNIQUE_VIOLATION) return this.takenError(channel);
return error as Error;
}
private takenError(channel: ContactChannel): ConflictException {
return new ConflictException(
channel === ContactChannel.Email
? "That email address is already registered to another account"
: "That phone number is already registered to another account",
);
}
}

60
apps/edr-freight-api/src/modules/auth/dto/account.dto.ts Normal file
View File

@@ -0,0 +1,60 @@
import { ApiProperty, ApiPropertyOptional } from "@nestjs/swagger";
import { Type } from "class-transformer";
import {
IsEnum,
IsNotEmpty,
IsObject,
IsOptional,
IsString,
ValidateNested,
} from "class-validator";
/** The contact channel being changed on the caller's own account. */
export enum ContactChannel {
Email = "email",
Phone = "phone",
}
export class SendContactOtpDto {
@ApiProperty({ enum: ContactChannel })
@IsEnum(ContactChannel)
channel!: ContactChannel;
@ApiProperty({
description:
"The NEW email or phone to verify. The code is sent here, not to the " +
"address currently on the account — that is what proves the caller " +
"controls the number/inbox they are moving to.",
example: "+251911223344",
})
@IsString()
@IsNotEmpty()
value!: string;
}
export class UpdateContactDto extends SendContactOtpDto {
@ApiProperty({ description: "The 6-digit code sent to the new value" })
@IsString()
@IsNotEmpty()
otp!: string;
}
export class AccountNameDto {
@ApiProperty({ description: "Amharic name", example: "አበበ በቀለ" })
@IsString()
@IsNotEmpty()
am!: string;
@ApiPropertyOptional({ description: "English name", example: "Abebe Bekele" })
@IsOptional()
@IsString()
en?: string;
}
export class UpdateAccountNameDto {
@ApiProperty({ type: AccountNameDto })
@IsObject()
@ValidateNested()
@Type(() => AccountNameDto)
name!: AccountNameDto;
}

9
apps/edr-freight-api/src/modules/auth/forgot-password.service.ts
View File

@@ -11,6 +11,7 @@ import { UserVerification } from "@tria-plc/iamapi-common/entities/iam/user/user
import { OtpService, OtpTarget } from "../otp/otp.service";
import { ResetChannel } from "./dto/forgot-password.dto";
import { maskOtpTarget } from "./mask-target.util";
/**
* How long the reset ticket minted for `PATCH /api/auth/set-password` stays
@@ -158,12 +159,6 @@ export class ForgotPasswordService {
/** `+251911234567` -> `+251•••••4567`; `ab@x.com` -> `a•@x.com`. */
maskTarget(target: OtpTarget): string {
if (target.email) {
const [local, domain] = target.email.split("@");
const head = local.slice(0, 1);
return `${head}${"•".repeat(Math.max(local.length - 1, 1))}@${domain}`;
}
const phone = target.phone ?? "";
return `${phone.slice(0, 4)}${"•".repeat(Math.max(phone.length - 8, 1))}${phone.slice(-4)}`;
return maskOtpTarget(target);
}
}

14
apps/edr-freight-api/src/modules/auth/freight-auth.module.ts
View File

@@ -1,11 +1,15 @@
import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { Employee } from '@tria-plc/iamapi-common/entities/iam/organization-structure/employee.entity';
import { Session } from '@tria-plc/iamapi-common/entities/iam/user/session.entity';
import { User } from '@tria-plc/iamapi-common/entities/iam/user/user.entity';
import { UserVerification } from '@tria-plc/iamapi-common/entities/iam/user/user-verification.entity';
import { ExternalProfile } from '../companies/entities/external-profile.entity';
import { OtpModule } from '../otp/otp.module';
import { AccountController } from './account.controller';
import { AccountService } from './account.service';
import { CheckAvailabilityController } from './check-availability.controller';
import { CheckAvailabilityService } from './check-availability.service';
import { CustomerResetController } from './customer-reset.controller';
@@ -17,17 +21,25 @@ import { FreightMeService } from './freight-me.service';
@Module({
imports: [
TypeOrmModule.forFeature([User, UserVerification, ExternalProfile]),
TypeOrmModule.forFeature([
User,
UserVerification,
ExternalProfile,
Session,
Employee,
]),
OtpModule,
],
controllers: [
FreightMeController,
AccountController,
CheckAvailabilityController,
ForgotPasswordController,
CustomerResetController,
],
providers: [
FreightMeService,
AccountService,
CheckAvailabilityService,
ForgotPasswordService,
CustomerResetService,

16
apps/edr-freight-api/src/modules/auth/mask-target.util.ts Normal file
View File

@@ -0,0 +1,16 @@
import { OtpTarget } from "../otp/otp.service";
/**
* Mask an OTP target for echoing back to the caller: `+251911234567` ->
* `+251•••••4567`; `ab@x.com` -> `a•@x.com`. Never return an unmasked target to
* a caller who has not yet proven possession of the channel.
*/
export function maskOtpTarget(target: OtpTarget): string {
if (target.email) {
const [local, domain] = target.email.split("@");
const head = local.slice(0, 1);
return `${head}${"•".repeat(Math.max(local.length - 1, 1))}@${domain}`;
}
const phone = target.phone ?? "";
return `${phone.slice(0, 4)}${"•".repeat(Math.max(phone.length - 8, 1))}${phone.slice(-4)}`;
}

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

@@ -1016,7 +1016,7 @@ export class BillingService {
// in the domain via `${source}.invoice.paid`. Neither billing nor the payment
// service branches on a domain-specific reference type.
referenceType: PaymentReferenceType.SHIPMENT,
orderRef: invoice.invoiceNumber.replace("-", "_"),
orderRef: invoice.invoiceNumber.replace(/-/g, "_"),
amountMinor: Math.round(Number(invoice.balanceAmount)),
currency: invoice.currency,
reason: `Payment for invoice ${invoice.invoiceNumber}`,
@@ -1032,10 +1032,8 @@ export class BillingService {
.getRepository(Invoice)
.update({ id: invoice.id }, { paymentId: result.intentId });
// DEMO: manually fire the gateway `payment.succeeded` callback here, without
// waiting for real gateway settlement. Runs AFTER the paymentId link above so
// `handlePaymentEvent → settleByPaymentId` can correlate the invoice. TODO:
// remove — real settlement flips this via the `${source}.invoice.paid` handler.
// Settlement is driven by the payment API (webhook/outbox → payment.succeeded);
// billing must not simulate it. Kept commented for local demos only.
if (!result.immediateSuccess) {
await this.payment.handlePaymentEvent({
eventType: "payment.succeeded",

15
apps/edr-freight-api/src/modules/bookings/booking-invoice.service.ts
View File

@@ -16,6 +16,7 @@ import {
InvoiceLineInput,
} from "../billing/billing.service";
import { Invoice } from "../billing/entities/invoice.entity";
import { CLEARANCE_BOOKING_INVOICE_TYPE } from "../contracts/clearance-fee.service";
import { FirstMileService } from "../first-mile/first-mile.service";
import { BookingBatchService } from "../train-scheduling/booking-batch.service";
import { PriceLineItemDto } from "./dto/generate-price-response.dto";
@@ -120,17 +121,27 @@ export class BookingInvoiceService {
}
/**
* Expire the booking's currently-open prepaid invoice when the booking is
* Expire the booking's currently-open invoices (freight PREPAID and the
* per-shipment clearance fee) when the booking is
* cancelled or rejected — the counterpart to the pay-window-expiry path
* (which also calls {@link BillingService.expirePayable}). Stops a terminated
* booking from leaving a payable invoice open. No-op when the booking has no
* open invoice (never invoiced, already paid/cancelled/expired). Pass a
* caller `manager` to enlist in its transaction.
*/
expireOpenInvoices(
async expireOpenInvoices(
bookingId: string,
manager?: EntityManager,
): Promise<Invoice | null> {
// The per-shipment clearance fee (GENERAL contracts) bills this same booking
// id under its own source/type — retire it alongside the freight invoice, or
// a cancelled shipment keeps a payable clearance invoice open.
await this.billing.expirePayable(
Freight.InvoiceSource.Clearance,
bookingId,
CLEARANCE_BOOKING_INVOICE_TYPE,
manager,
);
return this.billing.expirePayable(
Freight.InvoiceSource.Booking,
bookingId,

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

@@ -1,4 +1,6 @@
import { Injectable, Logger } from '@nestjs/common';
import { InjectDataSource } from '@nestjs/typeorm';
import { DataSource } from 'typeorm';
import {
NotificationAudience,
NotificationType,
@@ -8,6 +10,7 @@ import {
import { Booking } from './entities/booking.entity';
import { NotificationsService } from '../notifications/notifications.service';
import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
import { resolveCompanyNotifyPhone } from '../notifications/resolve-company-phone.util';
/**
* Customer + staff notifications for the booking lifecycle: review, clearance
@@ -27,6 +30,8 @@ export class BookingLifecycleNotifierService {
constructor(
private readonly notifications: NotificationsService,
private readonly inbox: NotificationInboxService,
@InjectDataSource()
private readonly dataSource: DataSource,
) {}
private ref(b: Booking): string {
@@ -40,7 +45,9 @@ export class BookingLifecycleNotifierService {
logLabel: string,
): Promise<void> {
this.logger.log(`${logLabel} — ${this.ref(b)}`);
const phone = b.company?.contactPersonPhone ?? b.company?.phone ?? null;
const phone = b.companyId
? await resolveCompanyNotifyPhone(this.dataSource, b.companyId)
: null;
const email = b.company?.email ?? b.company?.generalManagerEmail ?? null;
if (phone) {

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

@@ -4,6 +4,12 @@ import type { Rate } from '../rule-engine/entities/rate.entity';
const MOCK_CBE_RATE = 130;
// Base freight is configured per leg, so every rate and every booking names the
// route it runs. MOJO → DIRE is the corridor these rates are priced for.
const MOJO = 'yard-mojo';
const DIRE = 'yard-dire-dawa';
const LEBU = 'yard-lebu';
describe('BookingPricingService — domestic corridor', () => {
const intercityBulkUsd: Rate = {
id: 'rate-intercity-bulk-usd',
@@ -13,6 +19,8 @@ describe('BookingPricingService — domestic corridor', () => {
rateUnit: 'PER_TON',
status: 'LIVE',
containerTypeId: null,
originYardId: MOJO,
destinationYardId: DIRE,
} as Rate;
const intercityContainerUsd: Rate = {
@@ -23,6 +31,8 @@ describe('BookingPricingService — domestic corridor', () => {
rateUnit: 'PER_CONTAINER',
status: 'LIVE',
containerTypeId: null,
originYardId: MOJO,
destinationYardId: DIRE,
} as Rate;
let service: BookingPricingService;
@@ -56,6 +66,8 @@ describe('BookingPricingService — domestic corridor', () => {
tradeDirection: 'DOMESTIC',
paymentCurrency: 'ETB',
cargoTotalWeightVgm: 120,
originYardId: MOJO,
destinationYardId: DIRE,
bookingContainers: [],
} as unknown as Booking;
@@ -81,6 +93,8 @@ describe('BookingPricingService — domestic corridor', () => {
tradeDirection: 'DOMESTIC',
paymentCurrency: 'USD',
cargoTotalWeightVgm: 120,
originYardId: MOJO,
destinationYardId: DIRE,
bookingContainers: [],
} as unknown as Booking;
@@ -106,6 +120,8 @@ describe('BookingPricingService — domestic corridor', () => {
tradeDirection: 'DOMESTIC',
paymentCurrency: 'ETB',
cargoTotalWeightVgm: 50,
originYardId: MOJO,
destinationYardId: DIRE,
bookingContainers: [],
} as unknown as Booking;
@@ -126,4 +142,59 @@ describe('BookingPricingService — domestic corridor', () => {
const line = result.lineItems.find((l) => l.code === 'INTERCITY_CONTAINER')!;
expect(line.currency).toBe('ETB');
});
// Rates are quoted per leg, so one configured for MOJO → DIRE must not price a
// shipment that runs LEBU → DIRE. Charging the wrong corridor's price because
// nobody configured this one yet is worse than billing no base freight.
it('does not price bulk off a rate configured for a different leg', async () => {
const booking = {
id: 'b-3',
freightType: 'BULK',
tradeDirection: 'DOMESTIC',
paymentCurrency: 'USD',
cargoTotalWeightVgm: 120,
originYardId: LEBU,
destinationYardId: DIRE,
bookingContainers: [],
} as unknown as Booking;
const result = await (
service as unknown as {
computeBaseRailLinesWithRates: (
b: Booking,
input: { containers: [] },
) => Promise<{ lineItems: Array<{ amount: number }> }>;
}
).computeBaseRailLinesWithRates(booking, { containers: [] });
expect(result.lineItems).toHaveLength(0);
});
it('does not price containers off a rate configured for a different leg', async () => {
const booking = {
id: 'b-4',
freightType: 'CONTAINER',
tradeDirection: 'DOMESTIC',
paymentCurrency: 'USD',
cargoTotalWeightVgm: 50,
originYardId: LEBU,
destinationYardId: DIRE,
bookingContainers: [],
} as unknown as Booking;
const result = await (
service as unknown as {
computeBaseRailLinesWithRates: (
b: Booking,
input: {
containers: Array<{ containerTypeId: string; quantity: number }>;
},
) => Promise<{ lineItems: Array<{ amount: number }> }>;
}
).computeBaseRailLinesWithRates(booking, {
containers: [{ containerTypeId: 'ct-20', quantity: 3 }],
});
expect(result.lineItems).toHaveLength(0);
});
});

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

@@ -10,11 +10,9 @@ import {
BookingEvaluationInput,
RuleEngineService,
} from '../rule-engine/rule-engine.service';
import { containersPerWagonForSize } from '../rule-engine/container-type.util';
import { BookingsRepository } from './bookings.repository';
import {
containersPerWagon,
wagonRemainder,
} from './consolidation.service';
import { wagonRemainder } from './consolidation.service';
import { GeneratePriceResponseDto, PriceLineItemDto } from './dto/generate-price-response.dto';
import { Booking } from './entities/booking.entity';
import { assertBookingStatus } from './booking-status.util';
@@ -307,8 +305,12 @@ export class BookingPricingService {
vgmPerUnitTons: vgm,
totalVgmTons: qty * vgm,
isReefer: ct.isReefer,
// Per-container opt-ins — PER_CONTAINER surcharges bill these.
hazardousQuantity: Number(bc.hazardousQuantity ?? 0),
reeferQuantity: Number(bc.reeferQuantity ?? 0),
returnQuantity: Number(bc.returnQuantity ?? 0),
},
perWagon: containersPerWagon(Number(ct.wagonsPerUnit)),
perWagon: containersPerWagonForSize(ct.sizeFt),
quantity: qty,
};
}),
@@ -477,7 +479,14 @@ export class BookingPricingService {
const wagonCount = await this.resolveWagonCount(booking);
for (const container of evalInput.containers) {
const rate = this.pickRate(liveRates, rateType, container.containerTypeId, 'USD');
const rate = this.pickRate(
liveRates,
rateType,
container.containerTypeId,
'USD',
booking.originYardId,
booking.destinationYardId,
);
if (!rate) continue;
usedRatesMap.set(rate.id, rate);
@@ -517,8 +526,15 @@ export class BookingPricingService {
}
if (lines.length === 0) {
// Bulk (and any booking with no container lines) still has to price off a
// rate configured for this leg — never one belonging to another route.
const fallback = liveRates.find(
(r) => r.rateType === rateType && r.currency === 'USD' && r.status === 'LIVE',
(r) =>
r.rateType === rateType &&
r.currency === 'USD' &&
r.status === 'LIVE' &&
r.originYardId === booking.originYardId &&
r.destinationYardId === booking.destinationYardId,
);
if (fallback) {
usedRatesMap.set(fallback.id, fallback);
@@ -713,20 +729,32 @@ export class BookingPricingService {
}
}
/**
* Base freight is quoted per leg, so a rate only applies to a booking running
* the exact origin → destination it was configured for. There is deliberately
* no route-agnostic fallback: charging a Dire Dawa price for a Mojo shipment
* because nobody configured Mojo yet is worse than surfacing no line at all.
* Within the leg, a rate scoped to the container type wins over one that
* covers every type.
*/
private pickRate(
rates: Rate[],
rateType: string,
containerTypeId: string,
currency: string,
originYardId: string,
destinationYardId: string,
): Rate | undefined {
const onLeg = rates.filter(
(r) =>
r.rateType === rateType &&
r.currency === currency &&
r.originYardId === originYardId &&
r.destinationYardId === destinationYardId,
);
return (
rates.find(
(r) =>
r.rateType === rateType &&
r.currency === currency &&
r.containerTypeId === containerTypeId,
) ??
rates.find((r) => r.rateType === rateType && r.currency === currency && !r.containerTypeId)
onLeg.find((r) => r.containerTypeId === containerTypeId) ??
onLeg.find((r) => !r.containerTypeId)
);
}

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

@@ -110,7 +110,6 @@ export function groupContainersBySize(
name: ct.label?.trim() ? ct.label : ct.code,
code: ct.code,
is_reefer: ct.isReefer ?? false,
wagons_per_unit: Number(ct.wagonsPerUnit ?? 1),
}),
),
}));

97
apps/edr-freight-api/src/modules/bookings/booking-transition.operation.spec.ts
View File

@@ -1,4 +1,4 @@
import { BadRequestException } from '@nestjs/common';
import { BadRequestException, ConflictException } from '@nestjs/common';
import { BookingTransitionService } from './booking-transition.service';
/**
@@ -116,3 +116,98 @@ describe('BookingTransitionService — operation review', () => {
);
});
});
/**
* Export over-book gate at the customer's requestOperation step: export never
* splits, so the free-space check runs the moment the customer commits to a
* shipment day. When no single export train that day can carry the whole
* booking, `pickExportSchedule` throws and the request is refused BEFORE the
* booking moves to OPERATION_REQUEST_PENDING. Import bookings are never gated
* here (they are batched + splittable later).
*/
describe('BookingTransitionService — requestOperation export space gate', () => {
function makeService(tradeDirection: 'EXPORT' | 'IMPORT', overbook: boolean) {
const booking = {
id: 'b-1',
reference: 'BKG-1',
status: 'CLEARANCE_READY',
tradeDirection,
originYardId: 'o-1',
destinationYardId: 'd-1',
totalAmount: 1000,
contractId: null,
serviceType: { code: 'RAIL_CONTAINER' },
};
const bookingsRepository = {
update: jest.fn().mockResolvedValue({ id: 'b-1' }),
};
const bookingsService = {
findById: jest.fn().mockResolvedValue(booking),
checkDayCompatibilityForBooking: jest
.fn()
.mockResolvedValue({ hasDeparture: true, hasCompatible: true }),
};
const bookingBatchService = {
// Over-book → the export gate rejects; otherwise it returns a schedule id.
pickExportSchedule: overbook
? jest.fn().mockRejectedValue(new ConflictException('Not enough train space'))
: jest.fn().mockResolvedValue('sched-1'),
};
const notifier = { operationRequestedToStaff: jest.fn() };
const service = new BookingTransitionService(
bookingsRepository as never,
{} as never, // ruleEngineService
{} as never, // pricingService
{} as never, // contractService
{} as never, // filesService
{} as never, // fileUploadSettingsService
bookingBatchService as never,
bookingsService as never,
{ isPhasedGeneralCustomsBooking: () => false } as never,
{} as never, // workflowService
{} as never, // invoiceService
{ validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
notifier as never,
);
return { service, bookingsRepository, bookingBatchService };
}
it('rejects an over-booked export request and does NOT advance the booking', async () => {
const { service, bookingsRepository, bookingBatchService } = makeService(
'EXPORT',
true,
);
await expect(
service.requestOperation('b-1', '2026-07-20T00:00:00.000Z'),
).rejects.toBeInstanceOf(ConflictException);
expect(bookingBatchService.pickExportSchedule).toHaveBeenCalledTimes(1);
expect(bookingsRepository.update).not.toHaveBeenCalled();
});
it('lets an export request through when a train fits the whole booking', async () => {
const { service, bookingsRepository, bookingBatchService } = makeService(
'EXPORT',
false,
);
await service.requestOperation('b-1', '2026-07-20T00:00:00.000Z');
expect(bookingBatchService.pickExportSchedule).toHaveBeenCalledTimes(1);
expect(bookingsRepository.update).toHaveBeenCalledWith(
'b-1',
expect.objectContaining({ status: 'OPERATION_REQUEST_PENDING' }),
);
});
it('never runs the export gate for an import request', async () => {
const { service, bookingsRepository, bookingBatchService } = makeService(
'IMPORT',
true, // would reject IF called — proves it is not called
);
await service.requestOperation('b-1', '2026-07-20T00:00:00.000Z');
expect(bookingBatchService.pickExportSchedule).not.toHaveBeenCalled();
expect(bookingsRepository.update).toHaveBeenCalledWith(
'b-1',
expect.objectContaining({ status: 'OPERATION_REQUEST_PENDING' }),
);
});
});

76
apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts
View File

@@ -42,6 +42,7 @@ export class BookingTransitionService {
private readonly bookingsRepository: BookingsRepository,
private readonly ruleEngineService: RuleEngineService,
private readonly pricingService: BookingPricingService,
@Inject(forwardRef(() => BookingContractService))
private readonly contractService: BookingContractService,
private readonly filesService: FilesService,
private readonly fileUploadSettingsService: FileUploadSettingsService,
@@ -1036,6 +1037,40 @@ export class BookingTransitionService {
);
}
// Export is FCFS and never splits — a booking must ride one train whole. So
// the free-space check belongs HERE, the moment the customer commits to a
// shipment day, not later at staff operation-accept. Blocking now stops the
// customer booking more wagons than any single export train that day can
// still carry; `exportSpaceReport` throws a 409 whose message carries the
// largest bookable leftover ("reduce to N wagons or pick another day").
// Import/domestic bookings are batched + splittable, so they are NOT gated
// here — they get an advisory count below and the batch engine sizes them.
const scheduledBooking = { ...booking, scheduledDate: date } as Booking;
const isExportTrain =
booking.tradeDirection === "EXPORT" &&
!isRoadService(booking.serviceType);
if (isExportTrain) {
// With export split ON the booking no longer has to ride ONE train whole:
// the largest fitting part is offered and the leftover rebooks on the next
// train. So the day is only unbookable when NO export train that day has
// any room at all — reject on the day total, not on a single-train fit.
// With the flag off this stays the strict whole-booking gate.
if (process.env.FREIGHT_EXPORT_SPLIT === "true") {
const fitting = await this.bookingBatchService.fittingTrainsForDay(
scheduledBooking,
eatDay(date),
"EXPORT",
);
if (!fitting.length) {
throw new ConflictException(
"No export train on this day has space left — pick another shipment day.",
);
}
} else {
await this.bookingBatchService.pickExportSchedule(scheduledBooking);
}
}
await this.bookingsRepository.update(bookingId, {
status: "OPERATION_REQUEST_PENDING",
scheduledDate: date,
@@ -1045,6 +1080,47 @@ export class BookingTransitionService {
return fresh;
}
/**
* Advisory availability for a shipment day the customer is considering — a
* planning hint for the day picker, computed but never enforced. For EXPORT it
* mirrors the real request-time gate: `fits` is whether a single open train
* that day can carry the WHOLE booking (export never splits), and `freeWagons`
* is the largest single-train leftover. For IMPORT/DOMESTIC `freeWagons` is the
* TOTAL room across the day's trains for the booking's wagon type (the batch
* engine may still split or defer a remainder), and `fits` is whether that
* total covers the booking. `trainsForDay` is false when no departure carries
* the leg — the day is unbookable regardless of space.
*/
async dayAvailabilityForBooking(
bookingId: string,
scheduledDate: string,
): Promise<{ fits: boolean; freeWagons: number; trainsForDay: boolean }> {
const booking = await this.bookingsService.findById(bookingId);
const date = new Date(scheduledDate);
if (Number.isNaN(date.getTime())) {
throw new BadRequestException("A valid schedule date is required");
}
const day = eatDay(date);
const isExportTrain =
booking.tradeDirection === "EXPORT" &&
!isRoadService(booking.serviceType);
if (isExportTrain) {
const scheduledBooking = { ...booking, scheduledDate: date } as Booking;
const report =
await this.bookingBatchService.exportSpaceReport(scheduledBooking);
return {
fits: report.scheduleId != null,
freeWagons: report.bestAvailable?.wagons ?? 0,
trainsForDay: report.trainsForDay && report.corridorMatched,
};
}
const { freeWagons, need, trainsForDay } =
await this.bookingBatchService.dayImportAvailability(booking, day);
return { fits: freeWagons >= need, freeWagons, trainsForDay };
}
/**
* Operations team reviews a pending operation request (capacity, documents,
* route). Two outcomes:

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

@@ -370,6 +370,31 @@ export class BookingsController {
return this.bookingsService.availableDaysForBooking(id);
}
@Get(':id/day-availability')
@ApiOperation({
summary:
'Advisory free-wagon count for a shipment day (planning hint, not enforced). ' +
'Export: whole-booking fit + largest single-train leftover. ' +
'Import/domestic: total room across the day for the booking\'s wagon type.',
})
async dayAvailability(
@Param('id', ParseUUIDPipe) id: string,
@Query('date') date: string,
@CurrentUser() user: TCurrentUser,
) {
const booking = await this.bookingsService.findById(id);
if (
!hasFreightPermission(user, FREIGHT_PERMS.bookings.view) &&
!hasFreightPermission(user, FREIGHT_PERMS.bookings.clearanceView)
) {
await this.bookingsService.assertCustomerCanAccessBooking(
user?.id,
booking,
);
}
return this.transitionService.dayAvailabilityForBooking(id, date);
}
@Get(':id/mile-summary')
@ApiOperation({
summary: 'First/last-mile operational summary for a booking (customer-safe)',

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

@@ -47,6 +47,7 @@ import { ContractPdfService } from '../../contracts/contract-pdf.service';
import { ContractsModule } from '../contracts/contracts.module';
import { BookingContainerAllocation } from "./entities/booking-container-allocation.entity";
import { ContractPricingScheduleBuilder } from "../../contracts/contract-pricing-schedule.builder";
import { ContractRateScheduleBuilder } from "../../contracts/contract-rate-schedule.builder";
import { ContractRendererService } from "../../contracts/contract-renderer.service";
import { ContractTemplateResolver } from "../../contracts/contract-template.resolver";
import { ContractViewModelBuilder } from "../../contracts/contract-view-model.builder";
@@ -106,6 +107,7 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
ContractTemplateResolver,
ContractViewModelBuilder,
ContractPricingScheduleBuilder,
ContractRateScheduleBuilder,
ContractRendererService,
ContractPdfService,
CustomerTruckAssignmentsRepository,

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

@@ -4,6 +4,7 @@ import { Injectable } from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { DataSource, EntityManager, FindOptionsWhere, In, Repository, SelectQueryBuilder } from 'typeorm';
import { wagonsPerUnitForSize } from '../rule-engine/container-type.util';
import { ContainerType } from '../rule-engine/entities/container-type.entity';
import { Contract } from '../contracts/entities/contract.entity';
import { ContractRateSnapshot } from '../contracts/entities/contract-rate-snapshot.entity';
@@ -149,7 +150,7 @@ export class BookingsRepository extends BaseRepository<Booking> {
for (const item of containers) {
const ct = await typeRepo.findOne({ where: { id: item.containerTypeId } });
const wagonsPerUnit = ct ? Number(ct.wagonsPerUnit) : 1;
const wagonsPerUnit = wagonsPerUnitForSize(ct?.sizeFt);
const totalVgm = item.quantity * item.vgmPerUnitTons;
const wagonsRequired = Math.ceil(item.quantity * wagonsPerUnit);
// A per-line breakdown can never exceed the line's own quantity.
@@ -179,7 +180,10 @@ export class BookingsRepository extends BaseRepository<Booking> {
async calculateWagonCount(bookingId: string): Promise<number> {
const result = await this.dataSource
.createQueryBuilder()
.select('CEILING(SUM(bc.quantity * ct.wagons_per_unit))', 'total')
.select(
'CEILING(SUM(bc.quantity * CASE WHEN ct.size_ft >= 40 THEN 1 WHEN ct.size_ft > 0 THEN 0.5 ELSE 1 END))',
'total',
)
.from(BookingContainer, 'bc')
.innerJoin(ContainerType, 'ct', 'ct.id = bc.container_type_id')
.where('bc.booking_id = :bookingId', { bookingId })

3
apps/edr-freight-api/src/modules/bookings/bookings.service.ts
View File

@@ -18,6 +18,7 @@ import { TrainSchedulingService } from '../train-scheduling/train-scheduling.ser
import { eatDay } from '../train-scheduling/batch-window.util';
import { FilesService } from '../files/files.service';
import { MinioService } from '../minio/minio.service';
import { wagonsPerUnitForSize } from '../rule-engine/container-type.util';
import { ContainerTypesService } from '../rule-engine/services/container-types.service';
import {
BookingEvaluationInput,
@@ -438,7 +439,7 @@ export class BookingsService {
vgmPerUnitTons: c.vgmPerUnitTons,
totalVgmTons,
isReefer: ct.isReefer,
wagonsRequired: c.quantity * (Number(ct.wagonsPerUnit) || 1),
wagonsRequired: c.quantity * wagonsPerUnitForSize(ct.sizeFt),
};
}),
);

10
apps/edr-freight-api/src/modules/bookings/consolidation.service.ts
View File

@@ -1,5 +1,6 @@
import { Injectable } from '@nestjs/common';
import { containersPerWagonForSize } from '../rule-engine/container-type.util';
import { ContainerTypesService } from '../rule-engine/services/container-types.service';
import { Booking } from './entities/booking.entity';
@@ -19,13 +20,6 @@ export interface ConsolidationAttemptResult {
messages: string[];
}
/** Containers that fit on one wagon for a given container type (inverse of wagons_per_unit). */
export function containersPerWagon(wagonsPerUnit: number): number {
const wpu = Number(wagonsPerUnit);
if (!wpu || wpu <= 0) return 1;
return Math.max(1, Math.round(1 / wpu));
}
export function wagonRemainder(quantity: number, perWagon: number): number {
const r = quantity % perWagon;
return r;
@@ -73,7 +67,7 @@ export class ConsolidationService {
const slots: ConsolidationSlot[] = [];
for (const [containerTypeId, quantity] of quantityByType) {
const ct = await this.containerTypesService.findById(containerTypeId);
const perWagon = containersPerWagon(Number(ct.wagonsPerUnit));
const perWagon = containersPerWagonForSize(ct.sizeFt);
const remainder = wagonRemainder(quantity, perWagon);
if (remainder === 0) continue;
slots.push({

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

@@ -27,9 +27,6 @@ export class BookingReferenceContainerTypeDto {
@ApiProperty()
is_reefer!: boolean;
@ApiProperty({ example: 0.5, description: 'Wagon fraction per container' })
wagons_per_unit!: number;
}
export class BookingReferenceContainerSizeGroupDto {

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

@@ -32,6 +32,10 @@ export class BookingContainerUnit extends BaseEntity {
@Column({ name: 'is_reefer', type: 'boolean', default: false })
isReefer!: boolean;
/** This container ships back empty after unloading (equipment return). */
@Column({ name: 'is_return', type: 'boolean', default: false })
isReturn!: boolean;
@Column({ name: 'sort_order', type: 'smallint', default: 0 })
sortOrder!: number;

74
apps/edr-freight-api/src/modules/companies/companies.repository.ts
View File

@@ -8,6 +8,27 @@ import { CompanyStatsResponseDto } from './dto/company-stats-response.dto';
@Injectable()
export class CompaniesRepository extends BaseRepository<Company> {
/**
* A company still being filled in by its owner in the portal wizard: it was
* self-registered (so it has an external profile) and nobody has submitted
* onboarding yet. The row exists from the wizard's first click, carrying a
* placeholder name + TIN, so it must not be offered up for review.
* Staff-created companies have no external profiles and are never drafts.
*/
private static readonly DRAFT_SQL = `(
EXISTS (
SELECT 1 FROM freight.external_profiles ep
WHERE ep.company_id = company.id
AND ep.deleted_at IS NULL
)
AND NOT EXISTS (
SELECT 1 FROM freight.external_profiles ep
WHERE ep.company_id = company.id
AND ep.deleted_at IS NULL
AND ep.onboarding_completed = true
)
)`;
constructor(
@InjectRepository(Company)
repo: Repository<Company>,
@@ -38,11 +59,22 @@ export class CompaniesRepository extends BaseRepository<Company> {
async findPaginated(
query: ListCompaniesQueryDto,
): Promise<{ items: Company[]; total: number }> {
const { page = 1, pageSize = 20, search, type, kind, status } = query;
const {
page = 1,
pageSize = 20,
search,
type,
kind,
status,
onboardingCompleted,
} = query;
const qb = this.repository
.createQueryBuilder('company')
.leftJoinAndSelect('company.companyProfiles', 'companyProfiles')
// External profiles carry onboardingCompleted, which the backoffice list
// uses to flag customers still mid-onboarding (not yet reviewable).
.leftJoinAndSelect('company.profiles', 'profiles')
.where('company.deleted_at IS NULL');
if (type) {
@@ -57,6 +89,14 @@ export class CompaniesRepository extends BaseRepository<Company> {
qb.andWhere('company.status = :status', { status });
}
if (onboardingCompleted !== undefined) {
qb.andWhere(
onboardingCompleted
? `NOT ${CompaniesRepository.DRAFT_SQL}`
: CompaniesRepository.DRAFT_SQL,
);
}
if (search) {
const term = `%${search.trim()}%`;
qb.andWhere(
@@ -83,21 +123,35 @@ export class CompaniesRepository extends BaseRepository<Company> {
}
async getStats(): Promise<CompanyStatsResponseDto> {
const rows: { status: string; count: string }[] = await this.repository
.createQueryBuilder('company')
.select('company.status', 'status')
.addSelect('COUNT(*)', 'count')
.where('company.deleted_at IS NULL')
.groupBy('company.status')
.getRawMany();
// Drafts are counted separately rather than under `pending`: they carry
// status=pending from creation, which would otherwise inflate the review
// queue's KPI with customers who haven't submitted anything yet.
const rows: { status: string; is_draft: boolean; count: string }[] =
await this.repository
.createQueryBuilder('company')
.select('company.status', 'status')
.addSelect(CompaniesRepository.DRAFT_SQL, 'is_draft')
.addSelect('COUNT(*)', 'count')
.where('company.deleted_at IS NULL')
.groupBy('company.status')
.addGroupBy(CompaniesRepository.DRAFT_SQL)
.getRawMany();
const map = new Map(rows.map((r) => [r.status, parseInt(r.count, 10)]));
const total = rows.reduce((sum, r) => sum + parseInt(r.count, 10), 0);
const map = new Map<string, number>();
let onboarding = 0;
let total = 0;
for (const row of rows) {
const count = parseInt(row.count, 10);
total += count;
if (row.is_draft) onboarding += count;
else map.set(row.status, (map.get(row.status) ?? 0) + count);
}
return {
total,
active: map.get('active') ?? 0,
pending: map.get('pending') ?? 0,
onboarding,
suspended: map.get('suspended') ?? 0,
blacklisted: map.get('blacklisted') ?? 0,
};

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

@@ -372,6 +372,9 @@ export class CompaniesService {
const company = await this.companiesRepo.findById(id);
if (!company) throw new NotFoundException(`Company ${id} not found`);
company.companyProfiles = await this.companyProfilesRepo.findByCompanyId(id);
// External profiles carry the onboarding flag the backoffice gates
// approval decisions on (see ResponseCompanyDto.onboardingCompleted).
company.profiles = await this.profilesRepo.findByCompanyId(id);
return company;
}
@@ -962,6 +965,28 @@ export class CompaniesService {
if (!existing)
throw new NotFoundException(`Company profile ${profileId} not found`);
// A self-registered company is only reviewable once its owner submits the
// onboarding wizard (markOnboardingComplete) — until then its profiles are
// half-filled drafts and approving one would mint a reference against an
// application that doesn't exist yet. Staff-created companies have no
// external profiles and are exempt.
//
// Only the review decision itself is gated (a profile still awaiting one:
// Pending, or Rejected and awaiting re-approval). Profiles already in
// service stay managable so staff can suspend/blacklist them — including to
// undo an approval granted before this guard existed.
const awaitingReview =
existing.status === ProfileStatus.Pending ||
existing.status === ProfileStatus.Rejected;
if (awaitingReview) {
const owners = await this.profilesRepo.findByCompanyId(existing.companyId);
if (owners.length > 0 && !owners.some((o) => o.onboardingCompleted)) {
throw new BadRequestException(
"This customer hasn't finished onboarding yet. Their roles can be reviewed once they submit their application.",
);
}
}
// 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 };

7
apps/edr-freight-api/src/modules/companies/company-notifier.service.ts
View File

@@ -1,4 +1,6 @@
import { Injectable, Logger } from "@nestjs/common";
import { InjectDataSource } from "@nestjs/typeorm";
import { DataSource } from "typeorm";
import {
NotificationAudience,
NotificationPriority,
@@ -8,6 +10,7 @@ import {
import { Company, CompanyStatus } from "./entities/company.entity";
import { NotificationsService } from "../notifications/notifications.service";
import { NotificationInboxService } from "../notification-inbox/notification-inbox.service";
import { resolveCompanyNotifyPhone } from "../notifications/resolve-company-phone.util";
/** Account statuses that lock the customer out and therefore must be told to them. */
const PUNITIVE_STATUSES: readonly CompanyStatus[] = [
@@ -28,11 +31,13 @@ export class CompanyNotifierService {
constructor(
private readonly notifications: NotificationsService,
private readonly inbox: NotificationInboxService,
@InjectDataSource()
private readonly dataSource: DataSource,
) {}
/** Send SMS + email to the company contact; log-only on failure. */
private async notifyContact(company: Company, message: string): Promise<void> {
const phone = company.contactPersonPhone ?? company.phone ?? null;
const phone = await resolveCompanyNotifyPhone(this.dataSource, company.id);
const email = company.email ?? company.generalManagerEmail ?? null;
if (phone) {

3
apps/edr-freight-api/src/modules/companies/dto/company-stats-response.dto.ts
View File

@@ -1,7 +1,10 @@
export class CompanyStatsResponseDto {
total!: number;
active!: number;
/** Submitted applications awaiting review. Excludes drafts. */
pending!: number;
/** Self-registered companies still working through the onboarding wizard. */
onboarding!: number;
suspended!: number;
blacklisted!: number;
}

12
apps/edr-freight-api/src/modules/companies/dto/list-companies-query.dto.ts
View File

@@ -1,5 +1,5 @@
import { ApiPropertyOptional } from "@nestjs/swagger";
import { IsIn, IsInt, IsOptional, IsString, Min } from "class-validator";
import { IsBoolean, IsIn, IsInt, IsOptional, IsString, Min } from "class-validator";
import { Transform } from "class-transformer";
import { CompanyKind, CompanyStatus, CompanyType } from "../entities/company.entity";
@@ -37,4 +37,14 @@ export class ListCompaniesQueryDto {
@IsOptional()
@IsIn(Object.values(CompanyStatus))
status?: CompanyStatus;
@ApiPropertyOptional({
description:
"Filter by onboarding submission. `true` = reviewable applications; " +
"`false` = drafts still in the portal wizard. Omit for both.",
})
@IsOptional()
@Transform(({ value }: { value: unknown }) => value === "true" || value === true)
@IsBoolean()
onboardingCompleted?: boolean;
}

11
apps/edr-freight-api/src/modules/companies/dto/response-company.dto.ts
View File

@@ -62,6 +62,13 @@ export class ResponseCompanyDto {
attributes?: Record<string, any> | null;
profiles?: ResponseExternalProfileDto[];
companyProfiles?: ResponseCompanyProfileDto[];
/**
* Whether the owning portal user has submitted the onboarding wizard.
* Approval decisions are blocked while this is false. Staff-created
* companies (no external profiles) count as completed. Undefined when the
* external profiles weren't loaded.
*/
onboardingCompleted?: boolean;
createdAt: Date;
updatedAt: Date;
@@ -84,6 +91,10 @@ export class ResponseCompanyDto {
this.companyProfiles = company.companyProfiles?.map(
(p) => new ResponseCompanyProfileDto(p),
);
this.onboardingCompleted = company.profiles
? company.profiles.length === 0 ||
company.profiles.some((p) => p.onboardingCompleted)
: undefined;
this.createdAt = company.createdAt;
this.updatedAt = company.updatedAt;
}

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

@@ -2,6 +2,7 @@ import { BadRequestException, Injectable, NotFoundException } from "@nestjs/comm
import { randomUUID } from "node:crypto";
import { ContractRendererService } from "../../contracts/contract-renderer.service";
import { RateSchedule } from "../../contracts/contract-rate-schedule.builder";
import { getTemplateMeta } from "../../contracts/contract-template.registry";
import {
ContractDynamicTemplateView,
@@ -177,17 +178,9 @@ export class ContractTemplatesService {
const isBulk = code.endsWith("_BULK");
const now = new Date();
const unitRates = isBulk
? [
{ label: "Rail transport — per metric ton", unitPrice: 59.4, unit: "ton", currency: "USD" },
{ label: "Origin handling and documentation", unitPrice: 18, unit: "ton", currency: "USD" },
{ label: "Lashing material (when provided by EDR)", unitPrice: 150, unit: "unit", currency: "USD" },
]
: [
{ label: "Rail transport — 40ft container", unitPrice: 1916, unit: "container", currency: "USD" },
{ label: "Rail transport — 2 × 20ft containers", unitPrice: 1944, unit: "container", currency: "USD" },
{ label: "Excess tonnage surcharge", unitPrice: 10, unit: "ton", currency: "USD" },
];
// Representative rate schedule so the admin preview shows the live-rate
// table shape. Real contracts populate this from freight.rates (LIVE).
const rateSchedule = this.mockRateSchedule(code, isBulk);
return {
bookingId: "00000000-0000-0000-0000-000000000000",
@@ -239,13 +232,16 @@ export class ContractTemplatesService {
lastMileDeliveryAddress: "—",
},
pricing: {
displayMode: "UNIT_RATES",
unitRates,
lineItems: [],
surcharges: [],
totalAmount: 0,
currency: "USD",
equipmentReturn: isBulk ? "—" : "With empty return",
originLabel: isBulk ? "Nagad Railway Station" : "SGTD Freight Station",
destinationLabel: "Galaan Multipurpose Port (GMP)",
containerLines: [],
} as unknown as ContractViewModel["pricing"],
rateSchedule,
signatures: [],
canSignCustomer: false,
canSignStaff: false,
@@ -256,6 +252,43 @@ export class ContractTemplatesService {
};
}
/** Static, representative rate schedule for the admin preview only. */
private mockRateSchedule(code: ContractTemplateCode, isBulk: boolean): RateSchedule {
const dir = code.startsWith("IMPORT")
? "import"
: code.startsWith("EXPORT")
? "export"
: "domestic";
const lane =
dir === "export"
? "Galaan Multipurpose Port → SGTD"
: dir === "domestic"
? "Mojo Dry Port → Dire Dawa"
: "Negad → Mojo Dry Port";
const freightLanes = isBulk
? [
{ route: lane, cargo: "Wheat", currency: "USD", amount: "100", unit: "per wagon" },
]
: [
{ route: lane, cargo: "40ft GP", currency: "USD", amount: "200", unit: "per container" },
{ route: lane, cargo: "20ft GP", currency: "USD", amount: "180", unit: "per container" },
];
return {
freightLanes,
additionalServices: [
{ route: "First-mile pickup by truck", cargo: "—", currency: "USD", amount: "50", unit: "per container" },
{ route: "Last-mile delivery by truck", cargo: "—", currency: "USD", amount: "50", unit: "per container" },
],
surcharges: [
{ route: "Customs clearance service", cargo: "—", currency: "USD", amount: "120", unit: "flat" },
],
isEmpty: false,
currencyLabel: "USD",
};
}
private assertCode(code: string): ContractTemplateCode {
const upper = code?.toUpperCase() as ContractTemplateCode;
if (!CONTRACT_TEMPLATE_CODES.includes(upper)) {

15
apps/edr-freight-api/src/modules/contracts/clearance-fee.service.ts
View File

@@ -161,6 +161,21 @@ export class ClearanceFeeService {
return invoice;
}
/**
* Retire (idempotently) the unpaid contract-level fee invoice when the
* contract reaches a terminal state — a dead contract must not leave a
* payable clearance invoice open for the customer to settle. No-op when the
* fee was already paid or never invoiced (mirrors the booking cancel path,
* {@link BillingService.expirePayable}).
*/
async expireForContract(contractId: string): Promise<Invoice | null> {
return this.billing.expirePayable(
Freight.InvoiceSource.Clearance,
contractId,
CLEARANCE_CONTRACT_INVOICE_TYPE,
);
}
/**
* Settlement branch point for `clearance`-source invoices: unlock the
* document-upload step the fee was gating. Idempotent — a replayed event on

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

@@ -25,6 +25,8 @@ import { validate20ftWeightPairing } from '../bookings/container-pairing.util';
import { TrainSchedulingGlobalRules } from '../train-scheduling/entities/train-scheduling-global-rules.entity';
import { TrainSchedulingService } from '../train-scheduling/train-scheduling.service';
import { BookingBatchService } from '../train-scheduling/booking-batch.service';
import { eatDay } from '../train-scheduling/batch-window.util';
import { wagonsPerUnitForSize } from '../rule-engine/container-type.util';
import { ContainerTypesService } from '../rule-engine/services/container-types.service';
import { RuleEngineService } from '../rule-engine/rule-engine.service';
import { ContainerType } from '../rule-engine/entities/container-type.entity';
@@ -38,7 +40,10 @@ import { ContractsRepository } from './contracts.repository';
import { ClearanceFeeService } from './clearance-fee.service';
import { ClearanceMilestoneService } from './clearance-milestone.service';
import { ClearanceWorkflowService } from './clearance-workflow.service';
import { CreateBookingUnderContractDto } from './dto/create-booking-under-contract.dto';
import {
CreateBookingContainerLineDto,
CreateBookingUnderContractDto,
} from './dto/create-booking-under-contract.dto';
/** Statuses that still occupy the single active-booking slot of a ONE_TIME contract. */
const TERMINAL_BOOKING_STATUSES = ['EXPIRED', 'CANCELLED', 'COMPLETED', 'REJECTED'];
@@ -53,6 +58,18 @@ export interface CreateBookingUnderContractResult {
warnings: string[];
}
/**
* Outstanding split remainder of a contract: what was booked in the first split
* booking's pre-split snapshot MINUS everything currently booked. Container
* contracts report per size; bulk reports one tonnage figure. `null` when the
* contract has no live split chain. Consumed by the remainder-placement engine
* to size the auto-created remainder booking.
*/
export type SplitOutstanding = {
bySize: Map<string, { total: number; outstanding: number }>;
bulk: { total: number; outstanding: number } | null;
};
/**
* The single create path for shipment bookings under a contract.
*
@@ -269,8 +286,8 @@ export class ContractBookingService {
tradeDirection: contract.tradeDirection,
freightType,
cargoTypeId: this.resolveCargoTypeId(contract, dto),
isHazardous: contract.isHazardous,
isReefer: contract.isReefer,
isHazardous: this.resolveShipmentHandlingFlag(contract, dto, 'hazardousQuantity'),
isReefer: this.resolveShipmentHandlingFlag(contract, dto, 'reeferQuantity'),
cargoTotalWeightVgm: this.resolveBulkTons(dto),
firstMilePickupAddress: contract.firstMilePickupAddress ?? null,
firstMilePickupLat: contract.firstMilePickupLat ?? null,
@@ -965,9 +982,11 @@ export class ContractBookingService {
* (CANCELLED / REJECTED / EXPIRED) release their share. Null when the
* contract has no live split booking.
*/
private async splitOutstanding(
contract: Contract,
): Promise<{ bySize: Map<string, { total: number; outstanding: number }>; bulk: { total: number; outstanding: number } | null } | null> {
/**
* Public: the remainder-placement engine reads this to size the auto-created
* remainder booking. Returns `null` when there is no live split chain.
*/
async splitOutstanding(contract: Contract): Promise<SplitOutstanding | null> {
const first = await this.dataSource
.getRepository(Booking)
.createQueryBuilder('b')
@@ -1014,6 +1033,25 @@ export class ContractBookingService {
const probe = await this.buildExportProbe(contract, route, dto, yards);
const report = await this.bookingBatchService.exportSpaceReport(probe);
if (report.scheduleId) return;
// With export split ON a booking no longer has to ride ONE train whole: the
// largest fitting part is offered and the leftover is rebooked on the next
// train. Rejecting on the single-train fit here would block exactly the
// bookings the split exists to serve — including the auto-created remainder,
// which by definition did not fit the train it was split off. Fall back to
// the day total: unbookable only when NO export train that day has room.
if (process.env.FREIGHT_EXPORT_SPLIT === 'true') {
const fitting = await this.bookingBatchService.fittingTrainsForDay(
probe,
eatDay(new Date(dto.scheduledDate)),
'EXPORT',
);
if (fitting.length > 0) return;
throw new BadRequestException(
'No export train on this day has space left — pick another shipment day.',
);
}
throw new BadRequestException(
report.fullMessage ?? 'Not enough train space for this day.',
);
@@ -1053,7 +1091,7 @@ export class ContractBookingService {
bc.quantity = line.quantity;
bc.containerTypeId = ct.id;
bc.containerType = ct;
bc.wagonsRequired = Math.ceil(line.quantity * Number(ct.wagonsPerUnit ?? 1));
bc.wagonsRequired = Math.ceil(line.quantity * wagonsPerUnitForSize(ct.sizeFt));
bc.totalVgmTons = (line.units ?? []).reduce(
(sum, u) => sum + Number(u.vgmTons ?? 0),
0,
@@ -1416,6 +1454,53 @@ export class ContractBookingService {
);
}
/**
* Per-line handling counts. Each physical container carries its own hazardous
* / reefer / return switch (entered next to its VGM), so the count is however
* many units opted in. Forms that predate per-unit switches send line-level
* counts and no unit flags — those are honoured as-is.
*/
private handlingCounts(line: CreateBookingContainerLineDto): {
hazardousQuantity: number;
reeferQuantity: number;
returnQuantity: number;
} {
const units = line.units ?? [];
const flagged = units.some((u) => u.isHazardous || u.isReefer || u.isReturn);
if (!flagged) {
return {
hazardousQuantity: Number(line.hazardousQuantity ?? 0),
reeferQuantity: Number(line.reeferQuantity ?? 0),
returnQuantity: Number(line.returnQuantity ?? 0),
};
}
return {
hazardousQuantity: units.filter((u) => u.isHazardous).length,
reeferQuantity: units.filter((u) => u.isReefer).length,
returnQuantity: units.filter((u) => u.isReturn).length,
};
}
/**
* Booking-level hazardous / reefer flags. The CONTRACT gates the service; the
* per-container opt-ins decide whether THIS shipment actually uses it. A
* container contract that allows hazardous but a booking where nobody ticked
* the switch is not a hazardous booking, and must not fire the surcharge.
* Bulk keeps the contract flag — it has its own bulk*Quantity fields.
*/
private resolveShipmentHandlingFlag(
contract: Contract,
dto: CreateBookingUnderContractDto,
field: 'hazardousQuantity' | 'reeferQuantity',
): boolean {
const gated = field === 'hazardousQuantity' ? contract.isHazardous : contract.isReefer;
if (!gated) return false;
if (contract.freightType !== 'CONTAINER') return true;
const lines = dto.containers ?? [];
if (!lines.length) return Boolean(gated);
return lines.some((l) => this.handlingCounts(l)[field] > 0);
}
/**
* Resolve the booking's equipment return from the per-line return quantities
* (container freight). The CONTRACT gates the service — like hazardous:
@@ -1435,7 +1520,7 @@ export class ContractBookingService {
const lines = dto.containers ?? [];
for (const line of lines) {
const qty = Number(line.returnQuantity ?? 0);
const qty = this.handlingCounts(line).returnQuantity;
if (qty === 0) continue;
if (contract.equipmentReturn !== 'WITH_RETURN') {
throw new BadRequestException(
@@ -1451,7 +1536,7 @@ export class ContractBookingService {
}
if (contract.equipmentReturn === 'WITH_RETURN') {
const anyReturn = lines.some((l) => Number(l.returnQuantity ?? 0) > 0);
const anyReturn = lines.some((l) => this.handlingCounts(l).returnQuantity > 0);
return anyReturn ? 'WITH_RETURN' : 'WITHOUT_RETURN';
}
return legacy;
@@ -1489,9 +1574,10 @@ export class ContractBookingService {
);
}
const counts = this.handlingCounts(line);
const containerType = await this.resolveContainerTypeForSize(
line.containerSize,
contract.isReefer || (line.reeferQuantity ?? 0) > 0,
contract.isReefer || counts.reeferQuantity > 0,
);
const vgmPerUnit = line.units.length
@@ -1505,15 +1591,13 @@ export class ContractBookingService {
containerTypeId: containerType.id,
containerSize: line.containerSize,
quantity: line.quantity,
hazardousQuantity: line.hazardousQuantity ?? 0,
reeferQuantity: line.reeferQuantity ?? 0,
hazardousQuantity: counts.hazardousQuantity,
reeferQuantity: counts.reeferQuantity,
returnQuantity:
contract.equipmentReturn === 'WITH_RETURN'
? (line.returnQuantity ?? 0)
: 0,
contract.equipmentReturn === 'WITH_RETURN' ? counts.returnQuantity : 0,
vgmPerUnitTons: vgmPerUnit,
totalVgmTons: totalVgm,
wagonsRequired: Math.ceil(line.quantity * Number(containerType.wagonsPerUnit ?? 1)),
wagonsRequired: Math.ceil(line.quantity * wagonsPerUnitForSize(containerType.sizeFt)),
isOverweight: false,
overweightExcessTons: null,
} as Partial<BookingContainer>),
@@ -1529,6 +1613,8 @@ export class ContractBookingService {
vgmTons: unit.vgmTons,
isHazardous: unit.isHazardous ?? false,
isReefer: unit.isReefer ?? false,
isReturn:
contract.equipmentReturn === 'WITH_RETURN' && (unit.isReturn ?? false),
sortOrder: sortOrder++,
}),
);
@@ -1629,12 +1715,14 @@ export class ContractBookingService {
paymentCurrency: contract.paymentCurrency,
serviceTypeId: contract.serviceTypeId,
cargoTypeId: this.resolveCargoTypeId(contract, dto),
isHazardous: contract.isHazardous,
isReefer: contract.isReefer,
isHazardous: this.resolveShipmentHandlingFlag(contract, dto, 'hazardousQuantity'),
isReefer: this.resolveShipmentHandlingFlag(contract, dto, 'reeferQuantity'),
equipmentReturn: this.resolveShipmentEquipmentReturn(contract, dto),
isGovernment: contract.isGovernment,
shippingLineId: null,
contractRouteId: route?.id ?? null,
originYardId: route?.originYardId ?? null,
destinationYardId: route?.destinationYardId ?? null,
cargoTotalWeightVgm: this.resolveBulkTons(dto),
firstMilePickupAddress: contract.firstMilePickupAddress ?? null,
lastMileDeliveryAddress: contract.lastMileDeliveryAddress ?? null,
@@ -1643,15 +1731,15 @@ export class ContractBookingService {
containerTypeId: ct.id,
containerSize: line.containerSize,
quantity: line.quantity,
hazardousQuantity: line.hazardousQuantity ?? 0,
reeferQuantity: line.reeferQuantity ?? 0,
hazardousQuantity: this.handlingCounts(line).hazardousQuantity,
reeferQuantity: this.handlingCounts(line).reeferQuantity,
returnQuantity:
contract.equipmentReturn === 'WITH_RETURN'
? (line.returnQuantity ?? 0)
? this.handlingCounts(line).returnQuantity
: 0,
vgmPerUnitTons: line.units.length ? totalVgmTons / line.units.length : 0,
totalVgmTons,
wagonsRequired: Math.ceil(line.quantity * Number(ct.wagonsPerUnit ?? 1)),
wagonsRequired: Math.ceil(line.quantity * wagonsPerUnitForSize(ct.sizeFt)),
}),
),
}) as Booking;

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

@@ -1,4 +1,6 @@
import { Injectable, Logger } from '@nestjs/common';
import { InjectDataSource } from '@nestjs/typeorm';
import { DataSource } from 'typeorm';
import {
NotificationAudience,
NotificationType,
@@ -8,6 +10,7 @@ import {
import { Contract } from './entities/contract.entity';
import { NotificationsService } from '../notifications/notifications.service';
import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
import { resolveCompanyNotifyPhone } from '../notifications/resolve-company-phone.util';
/**
* Customer + staff notifications for the contract lifecycle. Every customer
@@ -24,6 +27,8 @@ export class ContractNotifierService {
constructor(
private readonly notifications: NotificationsService,
private readonly inbox: NotificationInboxService,
@InjectDataSource()
private readonly dataSource: DataSource,
) {}
private ref(c: Contract): string {
@@ -37,7 +42,9 @@ export class ContractNotifierService {
logLabel: string,
): Promise<void> {
this.logger.log(`${logLabel} — ${this.ref(c)}`);
const phone = c.company?.contactPersonPhone ?? c.company?.phone ?? null;
const phone = c.companyId
? await resolveCompanyNotifyPhone(this.dataSource, c.companyId)
: null;
const email = c.company?.email ?? c.company?.generalManagerEmail ?? null;
if (phone) {

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

@@ -4,6 +4,8 @@ import {
Injectable,
Logger,
} from '@nestjs/common';
import { InjectDataSource } from '@nestjs/typeorm';
import { DataSource } from 'typeorm';
import { randomUUID } from 'node:crypto';
import { Readable } from 'stream';
import { insertWithGeneratedReference } from '@edr/api-common';
@@ -102,8 +104,41 @@ export class ContractTransitionService {
private readonly notifier: ContractNotifierService,
private readonly contractTemplates: ContractTemplatesService,
private readonly clearanceFeeService: ClearanceFeeService,
@InjectDataSource()
private readonly dataSource: DataSource,
) {}
/**
* The phone the signing OTP is sent to and verified against: the signer's own
* IAM account number.
*
* H12(b): resolved server-side from the authenticated user id, never from the
* request body — a caller-supplied number would let an attacker point the code
* at their own phone. Ownership is already gated separately by
* {@link ContractsService.assertCustomerCanAccessContract}, so this binds the
* signature to the *person* signing rather than to a company landline that may
* be shared, stale, or imported from eTrade.
*/
private async resolveSignerPhone(signerUserId?: string): Promise<string> {
if (!signerUserId) {
// Unreachable in practice (the ownership gate rejects a missing user
// first), but never fall back to another number if it ever changes.
throw new BadRequestException('Authentication required to sign');
}
const rows: Array<{ phone_number: string | null }> =
await this.dataSource.query(
`SELECT phone_number FROM iam.users WHERE id = $1 AND is_active = true`,
[signerUserId],
);
const phone = rows[0]?.phone_number?.trim();
if (!phone) {
throw new BadRequestException(
'Your account has no registered phone number. Add one in Settings → Account before signing.',
);
}
return phone;
}
/** Customer submits the contract for approval → SUBMITTED; freeze unit rates. */
async submit(contractId: string): Promise<Contract> {
const contract = await this.contractsService.findById(contractId);
@@ -419,6 +454,10 @@ export class ContractTransitionService {
actorId,
'STAFF',
);
// Stop the open-invoice leak: a rejected contract must not leave a payable
// clearance fee invoice open. Mirror the booking cancel path (billing.expirePayable).
await this.clearanceFeeService.expireForContract(contractId);
await this.contractsRepository.update(contractId, {
status: 'REJECTED',
} as never);
@@ -457,6 +496,10 @@ export class ContractTransitionService {
'STAFF',
);
// Stop the open-invoice leak: a rejected contract must not leave a payable
// clearance fee invoice open. Mirror the booking cancel path (billing.expirePayable).
await this.clearanceFeeService.expireForContract(contractId);
await this.contractsRepository.update(contractId, {
status: 'REJECTED',
} as never);
@@ -796,10 +839,10 @@ export class ContractTransitionService {
}
/**
* Send the sudo-mode signing OTP to the CONTRACT COMPANY's registered phone —
* the same number {@link sign} verifies against. The client never picks the
* number (that is the H12(b) trust property): it only asks us to send, and we
* resolve the phone from the contract. Returns a masked hint so the UI can
* Send the sudo-mode signing OTP to the SIGNER's own registered phone — the
* same number {@link sign} verifies against. The client never picks the number
* (that is the H12(b) trust property): it only asks us to send, and we resolve
* the phone from the authenticated user id. Returns a masked hint so the UI can
* say where the code went without exposing the full number.
*/
async sendSigningOtp(
@@ -815,14 +858,9 @@ export class ContractTransitionService {
);
assertContractStatus(contract, ['CONTRACT_READY']);
const companyPhone = contract.company?.phone?.trim();
if (!companyPhone) {
throw new BadRequestException(
'The contract company has no registered phone on file to send the signing OTP to',
);
}
await this.otpService.sendOtp({ phone: companyPhone });
return { sentTo: maskPhone(companyPhone) };
const signerPhone = await this.resolveSignerPhone(options.signerUserId);
await this.otpService.sendOtp({ phone: signerPhone });
return { sentTo: maskPhone(signerPhone) };
}
/** Customer signs the ready contract → SIGNED_CUSTOMER. */
@@ -848,20 +886,18 @@ export class ContractTransitionService {
throw new BadRequestException('Customer has already signed this contract');
}
// Sudo-mode gate: a fresh, single-use OTP must be verified before the
// signature is applied. H12(b): verify against the CONTRACT COMPANY's
// registered phone — never the caller-supplied dto.otpPhone, which an
// attacker could point at their own phone to sign someone else's
// contract. The OTP is issued to the company's registered number.
const companyPhone = contract.company?.phone?.trim();
if (!companyPhone) {
throw new BadRequestException(
'The contract company has no registered phone on file to verify the signing OTP against',
);
}
// signature is applied. H12(b): verify against the SIGNER's own registered
// phone, resolved server-side from the authenticated user id — never a
// caller-supplied number, which an attacker could point at their own
// phone. Ownership is already asserted above, so this proves the specific
// person holding the account is present, not merely that someone reached a
// shared company line. Must resolve identically to sendSigningOtp, or send
// and verify would target different numbers.
const signerPhone = await this.resolveSignerPhone(options.signerUserId);
if (!dto.otp) {
throw new BadRequestException('OTP verification is required to sign the contract');
}
await this.otpService.verifyOtpForAction({ phone: companyPhone }, dto.otp);
await this.otpService.verifyOtpForAction({ phone: signerPhone }, dto.otp);
await this.applySignature(contract, dto, options);
await this.contractsRepository.update(contractId, {
status: 'SIGNED_CUSTOMER',

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

@@ -50,6 +50,15 @@ export class CreateContainerUnitDto {
@IsBoolean()
@Transform(({ value }) => value === 'true' || value === true)
isReefer?: boolean;
@ApiPropertyOptional({
default: false,
description: 'This container ships back empty (equipment return).',
})
@IsOptional()
@IsBoolean()
@Transform(({ value }) => value === 'true' || value === true)
isReturn?: boolean;
}
export class CreateBookingContainerLineDto {

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

@@ -28,17 +28,13 @@ export class SignContractDto {
consentText?: string;
// Sudo-mode OTP challenge. Required when role=CUSTOMER: a fresh 6-digit code
// SMS'd to the signer's phone, verified server-side before the signature is
// applied. `otpPhone` is the number the code was sent to (the signed-in
// customer's registered phone).
// SMS'd to the signer's registered phone, verified server-side before the
// signature is applied. The number itself is deliberately NOT part of this
// DTO — the server resolves it from the authenticated user id, so a caller
// cannot redirect the challenge to a phone they control.
@ApiPropertyOptional({ description: '6-digit OTP; required when role=CUSTOMER' })
@IsOptional()
@IsString()
@Matches(/^\d{6}$/, { message: 'otp must be 6 digits' })
otp?: string;
@ApiPropertyOptional({ description: 'Phone the OTP was sent to; required when role=CUSTOMER' })
@IsOptional()
@IsString()
otpPhone?: string;
}

3
apps/edr-freight-api/src/modules/notification-inbox/notification-inbox.module.ts
View File

@@ -33,6 +33,7 @@ import { WsAuthService } from "./ws-auth.service";
WsAuthService,
NotificationInboxService,
],
exports: [NotificationInboxService],
// WsAuthService is reused by the support-chat gateway for handshake auth.
exports: [NotificationInboxService, WsAuthService],
})
export class NotificationInboxModule {}

11
apps/edr-freight-api/src/modules/notifications/notify-company.util.ts
View File

@@ -1,6 +1,10 @@
import { DataSource } from 'typeorm';
import { NotificationsService } from './notifications.service';
import {
companyNotifyPhoneExpr,
primaryContactUserJoin,
} from './resolve-company-phone.util';
/**
* Best-effort SMS + email fan-out to a company's contacts. Looks up the
@@ -15,9 +19,10 @@ export async function sendCompanyChannels(
): Promise<void> {
const [contact]: Array<{ phone: string | null; email: string | null }> =
await dataSource.query(
`SELECT COALESCE(phone, etrade_phone) AS phone, email
FROM freight.companies
WHERE id = $1 AND deleted_at IS NULL`,
`SELECT ${companyNotifyPhoneExpr('co')} AS phone, co.email
FROM freight.companies co
${primaryContactUserJoin('co')}
WHERE co.id = $1 AND co.deleted_at IS NULL`,
[companyId],
);
if (contact?.phone) {

60
apps/edr-freight-api/src/modules/notifications/resolve-company-phone.util.ts Normal file
View File

@@ -0,0 +1,60 @@
import { DataSource, EntityManager } from "typeorm";
/**
* Where a customer-facing SMS actually goes.
*
* The person who signs up, logs in, and receives OTPs is an IAM user, and
* `iam.users.phone_number` is the number they control and can change themselves
* (see the account settings flow). A company's own `phone` is business contact
* data — often a landline, a shared desk, or a stale eTrade import — so it is
* the fallback, not the source.
*
* `companies.contact_person_phone` is deliberately NOT consulted: the live write
* path stores that value in the `attributes` jsonb and has never populated the
* column, so every reader of it was silently falling through to `phone` anyway.
*/
/**
* LEFT JOIN a company alias to its primary contact's IAM user, exposing
* `pc.phone_number`.
*
* LATERAL + LIMIT 1 rather than a plain join: nothing in the schema stops a
* company having two `is_primary_contact` rows, and a plain join would then
* duplicate the company row — which in a fan-out query means sending the same
* customer the same SMS twice.
*
* `alias` is always a code-controlled literal, never caller input.
*/
export function primaryContactUserJoin(alias: string): string {
return `
LEFT JOIN LATERAL (
SELECT u.phone_number
FROM freight.external_profiles ep
JOIN iam.users u ON u.id = ep.user_id AND u.is_active = true
WHERE ep.company_id = ${alias}.id
AND ep.is_primary_contact = true
AND ep.deleted_at IS NULL
ORDER BY ep.created_at
LIMIT 1
) pc ON true`;
}
/** SQL expression for the company's SMS number, given the joined `pc` alias. */
export function companyNotifyPhoneExpr(alias: string): string {
return `COALESCE(pc.phone_number, ${alias}.phone)`;
}
/** The SMS number for one company, or null when neither source has one. */
export async function resolveCompanyNotifyPhone(
db: DataSource | EntityManager,
companyId: string,
): Promise<string | null> {
const rows: Array<{ phone: string | null }> = await db.query(
`SELECT ${companyNotifyPhoneExpr("co")} AS phone
FROM freight.companies co
${primaryContactUserJoin("co")}
WHERE co.id = $1 AND co.deleted_at IS NULL`,
[companyId],
);
return rows[0]?.phone ?? null;
}

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

@@ -190,12 +190,16 @@ export class PaymentService {
*/
async initiate(input: InitiateIntentInput): Promise<InitiateIntentResult> {
try {
const snapshot = await this.paymentClient.initiate({
service: PaymentServiceEnum.FREIGHT,
referenceType: PaymentReferenceType.SHIPMENT,
referenceId: input.referenceId,
orderRef: input.orderRef,
amountMinor: input.amountMinor,
// amountMinor: input.amountMinor,
amountMinor:1,
currency: input.currency,
provider: input.method as ProviderMethod,
platform: input.platform,

15
apps/edr-freight-api/src/modules/rule-engine/container-type.util.ts Normal file
View File

@@ -0,0 +1,15 @@
/**
* Wagon fraction one container occupies, derived from its size: 40ft = 1 wagon,
* 20ft = 0.5 (two per wagon). Unknown size reads as a whole wagon so counts
* never under-book.
*/
export function wagonsPerUnitForSize(sizeFt?: number | null): number {
const size = Number(sizeFt);
if (!Number.isFinite(size) || size <= 0) return 1;
return size >= 40 ? 1 : 0.5;
}
/** Containers that fit on one wagon for a given container size (inverse of the wagon fraction). */
export function containersPerWagonForSize(sizeFt?: number | null): number {
return Math.max(1, Math.round(1 / wagonsPerUnitForSize(sizeFt)));
}

3
apps/edr-freight-api/src/modules/rule-engine/controllers/priority-configs.controller.ts
View File

@@ -29,8 +29,7 @@ export class PriorityConfigsController {
@Get('next-range')
@RuleEngineView('priority-configs')
@ApiOperation({
summary:
"Where the next contiguous range for a type (and currency) must start, plus the type's ceiling",
summary: 'Where the next contiguous range for a type (and currency) must start',
})
nextRange(
@Query('type') type: 'WAGON' | 'CURRENCY' | 'CUSTOMS',

58
apps/edr-freight-api/src/modules/rule-engine/controllers/rate-change-requests.controller.ts Normal file
View File

@@ -0,0 +1,58 @@
import { Body, Controller, Get, Param, ParseUUIDPipe, Post, Query } from '@nestjs/common';
import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
import { CurrentUser } from '@edr/api-common';
import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
import { isSuperAdmin } from '../../../common/freight-permission.util';
import { RuleEngineApprove, RuleEngineManage, RuleEngineView } from '../../../common/rule-engine-guards';
import { DecideRateChangeDto, SubmitRateChangeDto } from '../dto/rate-change-request.dto';
import { RateChangeStatus } from '../entities/rate-change-request.entity';
import { RateChangeRequestsService } from '../services/rate-change-requests.service';
/**
* Edits to LIVE rates. Staff with `manage` propose (submit); only holders of
* `approve` decide. Until a change is approved the live rate keeps its current
* value, so pricing never moves on an unapproved edit.
*/
@ApiTags('rate-change-requests')
@Controller('rate-change-requests')
@ApiBearerAuth()
export class RateChangeRequestsController {
constructor(private readonly service: RateChangeRequestsService) {}
@Post()
@RuleEngineManage('rates')
@ApiOperation({ summary: 'Propose a change to a LIVE rate' })
submit(@Body() dto: SubmitRateChangeDto, @CurrentUser() user: TCurrentUser) {
return this.service.submit(dto, user?.id);
}
@Get()
@RuleEngineView('rates')
@ApiOperation({ summary: 'List rate change requests, optionally by status' })
list(@Query('status') status?: RateChangeStatus) {
return this.service.list(status);
}
@Post(':id/approve')
@RuleEngineApprove('rates')
@ApiOperation({ summary: 'Approve a rate change and put it into effect' })
approve(
@Param('id', ParseUUIDPipe) id: string,
@Body() dto: DecideRateChangeDto,
@CurrentUser() user: TCurrentUser,
) {
return this.service.approve(id, user?.id, dto.decisionNote, isSuperAdmin(user));
}
@Post(':id/reject')
@RuleEngineApprove('rates')
@ApiOperation({ summary: 'Reject a rate change — the rate keeps its current value' })
reject(
@Param('id', ParseUUIDPipe) id: string,
@Body() dto: DecideRateChangeDto,
@CurrentUser() user: TCurrentUser,
) {
return this.service.reject(id, user?.id, dto.decisionNote);
}
}

8
apps/edr-freight-api/src/modules/rule-engine/dto/create-cargo-type.dto.ts
View File

@@ -37,6 +37,14 @@ export class CreateCargoTypeDto {
@IsBoolean()
requiresDirectorApproval?: boolean;
@ApiPropertyOptional({
default: false,
description: 'When true, bookings of this cargo type incur the flat LASHING surcharge.',
})
@IsOptional()
@IsBoolean()
hasLashing?: boolean;
@ApiPropertyOptional({ default: true })
@IsOptional()
@IsBoolean()

9
apps/edr-freight-api/src/modules/rule-engine/dto/create-container-type.dto.ts
View File

@@ -1,6 +1,5 @@
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { Transform } from 'class-transformer';
import { IsArray, IsBoolean, IsInt, IsNumber, IsOptional, IsString, IsUUID, Max, MaxLength, Min } from 'class-validator';
import { IsArray, IsBoolean, IsInt, IsOptional, IsString, IsUUID, Max, MaxLength, Min } from 'class-validator';
export class CreateContainerTypeDto {
@ApiProperty({ description: 'Customer-facing label, e.g. "20ft Dry Container"', maxLength: 100 })
@@ -14,12 +13,6 @@ export class CreateContainerTypeDto {
@Max(40)
sizeFt!: number;
@ApiProperty({ description: 'Wagon fraction per container: 0.50 for 20ft, 1.00 for 40ft' })
@IsNumber()
@Min(0.01)
@Transform(({ value }) => Number(value))
wagonsPerUnit!: number;
@ApiPropertyOptional({ default: false, description: 'True if this is a reefer (refrigerated) container' })
@IsOptional()
@IsBoolean()

35
apps/edr-freight-api/src/modules/rule-engine/dto/create-rate.dto.ts
View File

@@ -9,6 +9,7 @@ import {
const TRADE_DIRECTIONS = ['IMPORT', 'EXPORT', 'BOTH'] as const;
const CURRENCIES = ['USD'] as const;
export const INTERCITY_KINDS = ['CONTAINER', 'BULK'] as const;
export class CreateRateDto {
@ApiProperty({ enum: RATE_APPLIES_TO, description: 'Friendly category the rate applies to' })
@@ -37,6 +38,31 @@ export class CreateRateDto {
@IsIn([...TRADE_DIRECTIONS])
tradeDirection?: string;
@ApiPropertyOptional({
enum: INTERCITY_KINDS,
description:
'Whether an intercity rate covers containers or bulk. Required when appliesTo = INTERCITY; ignored otherwise. Not stored — it selects the INTERCITY_CONTAINER / INTERCITY_BULK rate type.',
})
@IsOptional()
@IsIn([...INTERCITY_KINDS])
intercityKind?: string;
@ApiPropertyOptional({
description:
'FK to yards.id — origin of the leg this rate prices. Required for base freight (bulk/container/intercity), rejected for surcharges and first/last mile.',
})
@IsOptional()
@IsUUID()
originYardId?: string;
@ApiPropertyOptional({
description:
'FK to yards.id — destination of the leg this rate prices. Required for base freight (bulk/container/intercity), rejected for surcharges and first/last mile.',
})
@IsOptional()
@IsUUID()
destinationYardId?: string;
@ApiPropertyOptional({ enum: CURRENCIES })
@IsOptional()
@IsIn([...CURRENCIES])
@@ -48,9 +74,14 @@ export class CreateRateDto {
@Transform(({ value }) => Number(value))
rateValue!: number;
@ApiProperty({ enum: RATE_UNITS, description: 'Unit basis for the rate' })
@ApiPropertyOptional({
enum: RATE_UNITS,
description:
'Unit basis for the rate. Optional for shapes with a forced unit (overweight is always PER_TON — the admin form hides the field and omits it); required otherwise.',
})
@IsOptional()
@IsIn([...RATE_UNITS])
rateUnit!: string;
rateUnit?: string;
}
export class SubmitRateForApprovalDto {

9
apps/edr-freight-api/src/modules/rule-engine/dto/create-yard.dto.ts
View File

@@ -17,6 +17,15 @@ export class CreateYardDto {
@IsBoolean()
isActive?: boolean;
@ApiPropertyOptional({
default: false,
description:
'This yard can load/unload cargo. Intercity bookings may only be loaded at their origin and unloaded at their destination when it is a facility.',
})
@IsOptional()
@IsBoolean()
hasFacility?: boolean;
@ApiPropertyOptional({ default: 1, description: 'UI display sort order' })
@IsOptional()
@IsInt()

28
apps/edr-freight-api/src/modules/rule-engine/dto/rate-change-request.dto.ts Normal file
View File

@@ -0,0 +1,28 @@
import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
import { Type } from 'class-transformer';
import { IsOptional, IsString, IsUUID, MaxLength, ValidateNested } from 'class-validator';
import { UpdateRateDto } from './update-rate.dto';
export class SubmitRateChangeDto {
@ApiProperty({ description: 'The LIVE rate to reprice' })
@IsUUID()
rateId!: string;
@ApiProperty({
description:
'Proposed field changes. The live rate keeps its current values until this is approved.',
type: UpdateRateDto,
})
@ValidateNested()
@Type(() => UpdateRateDto)
update!: UpdateRateDto;
}
export class DecideRateChangeDto {
@ApiPropertyOptional({ description: 'Optional note shown to the requester' })
@IsOptional()
@IsString()
@MaxLength(1000)
decisionNote?: string;
}

8
apps/edr-freight-api/src/modules/rule-engine/entities/cargo-type.entity.ts
View File

@@ -53,6 +53,14 @@ export class CargoType extends BaseEntity {
@Column({ name: 'requires_director_approval', type: 'boolean', default: false })
requiresDirectorApproval!: boolean;
/**
* When true, any booking of this cargo type incurs the flat LASHING surcharge
* (the LASHING-trigger rate). Set on commodities that need EDR-provided
* lashing/securing; leave false for cargo that ships without it.
*/
@Column({ name: 'has_lashing', type: 'boolean', default: false })
hasLashing!: boolean;
@Column({ name: 'is_active', type: 'boolean', default: true })
isActive!: boolean;

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

@@ -16,9 +16,6 @@ export class ContainerType extends BaseEntity {
@Column({ name: 'size_ft', type: 'smallint', nullable: true })
sizeFt!: number;
@Column({ name: 'wagons_per_unit', type: 'numeric', precision: 4, scale: 2, nullable: true })
wagonsPerUnit!: number;
@Column({ name: 'is_reefer', type: 'boolean', default: false, nullable: true })
isReefer!: boolean;

54
apps/edr-freight-api/src/modules/rule-engine/entities/rate-change-request.entity.ts Normal file
View File

@@ -0,0 +1,54 @@
import { BaseEntity } from '@edr/api-common';
import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
import { Rate } from './rate.entity';
export type RateChangeStatus = 'PENDING' | 'APPROVED' | 'REJECTED';
/**
* One proposed edit to a LIVE rate, awaiting approval.
*
* A LIVE rate is what pricing actually charges, so it is never mutated in
* place: the edit is filed here and the live row keeps its old value until an
* approver applies it. `payload` holds only the changed fields (an
* UpdateRateDto patch), `rateId` the rate being repriced.
*
* DRAFT rates are not covered — nothing prices off a draft, so those still
* edit directly and reach LIVE through the existing submit/approve flow.
*/
@Entity({ schema: 'freight', name: 'rate_change_requests' })
@Index(['status'])
export class RateChangeRequest extends BaseEntity {
@Column({ name: 'rate_id', type: 'uuid' })
rateId!: string;
@ManyToOne(() => Rate, { nullable: false })
@JoinColumn({ name: 'rate_id' })
rate?: Rate | null;
/** Proposed field changes — an UpdateRateDto patch, changed keys only. */
@Column({ name: 'payload', type: 'jsonb' })
payload!: Record<string, unknown>;
/**
* The rate's values at submit time, for the approver's before→after diff.
* Snapshotted because the live row can move on between submit and decision.
*/
@Column({ name: 'previous_values', type: 'jsonb' })
previousValues!: Record<string, unknown>;
@Column({ name: 'status', type: 'varchar', length: 10, default: 'PENDING' })
status!: RateChangeStatus;
@Column({ name: 'requested_by_user_id', type: 'uuid', nullable: true })
requestedByUserId?: string | null;
@Column({ name: 'decided_by_user_id', type: 'uuid', nullable: true })
decidedByUserId?: string | null;
@Column({ name: 'decided_at', type: 'timestamptz', nullable: true })
decidedAt?: Date | null;
@Column({ name: 'decision_note', type: 'text', nullable: true })
decisionNote?: string | null;
}

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

@@ -0,0 +1,28 @@
import { deriveRateType } from './rate-type.util';
describe('deriveRateType — surcharge triggers', () => {
// Every surcharge trigger must land on its own rateType. A trigger with no
// mapping falls through to the base-freight branch and is silently stored as
// CANCELLATION_FEE, which both mislabels the booking's rate snapshot and
// hides the rate from contract pricing (which looks rateTypes up by name).
it.each([
['HAZARDOUS', 'HAZARD_SURCHARGE'],
['REEFER', 'REEFER_SURCHARGE'],
['WITH_RETURN', 'RETURN_SURCHARGE'],
['OVERWEIGHT', 'OVERWEIGHT_PER_TON'],
['SHIPPING_LINE', 'DOUBLE_HANDLING'],
['CONSOLIDATION', 'LASHING'],
['CANCELLATION', 'CANCELLATION_FEE'],
['DEMURRAGE', 'DEMURRAGE'],
['PIL_EXTRA_FEE', 'PIL_EXTRA_FEE'],
['CUSTOMS_CLEARANCE', 'CUSTOMS_CLEARANCE'],
] as const)('maps trigger %s to %s', (trigger, expected) => {
expect(deriveRateType({ appliesTo: 'OTHER', trigger })).toBe(expected);
});
it('does not fall back to CANCELLATION_FEE for the empty-return service', () => {
expect(deriveRateType({ appliesTo: 'OTHER', trigger: 'WITH_RETURN' })).not.toBe(
'CANCELLATION_FEE',
);
});
});

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

@@ -25,11 +25,18 @@ export function deriveRateType(input: {
return 'HAZARD_SURCHARGE';
case 'REEFER':
return 'REEFER_SURCHARGE';
// Empty-container return service. Contract pricing looks this rateType up
// by name, so without the mapping a WITH_RETURN rate fell through to the
// base-freight branch and was stored as CANCELLATION_FEE — invisible to
// the contract, and mislabelled on the booking's snapshot.
case 'WITH_RETURN':
return 'RETURN_SURCHARGE';
case 'OVERWEIGHT':
return 'OVERWEIGHT_PER_TON';
case 'SHIPPING_LINE':
return 'DOUBLE_HANDLING';
case 'CONSOLIDATION':
case 'LASHING':
return 'LASHING';
case 'CANCELLATION':
return 'CANCELLATION_FEE';

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

@@ -36,6 +36,9 @@ export function allowedRateUnits(input: {
case 'CUSTOMS_CLEARANCE':
// Flat per clearance (ONE_TIME contract) / per shipment request (GENERAL).
return ['FLAT'];
case 'LASHING':
// Flat cargo-securing fee, billed once per booking.
return ['FLAT'];
case 'CONSOLIDATION':
return ['PER_CONTAINER', 'FLAT'];
case 'SHIPPING_LINE':

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

@@ -2,6 +2,7 @@ import { BaseEntity } from '@edr/api-common';
import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
import { CargoType } from './cargo-type.entity';
import { ContainerType } from './container-type.entity';
import { Yard } from './yard.entity';
export const RATE_TYPES = [
'CONTAINER_IMPORT',
@@ -77,6 +78,9 @@ export const RATE_TRIGGERS = [
'WITH_RETURN',
'SHIPPING_LINE',
'CONSOLIDATION',
// Cargo securing / lashing. Fires when the booking's cargo type has
// hasLashing = true. Flat fee, billed once per booking.
'LASHING',
'CANCELLATION',
'DEMURRAGE',
'PIL_EXTRA_FEE',
@@ -91,6 +95,8 @@ export type RateTrigger = typeof RATE_TRIGGERS[number];
@Index(['status'])
@Index(['containerTypeId'])
@Index(['trigger'])
@Index(['originYardId'])
@Index(['destinationYardId'])
export class Rate extends BaseEntity {
@Column({ name: 'rate_type', type: 'varchar', length: 50 })
rateType!: RateType;
@@ -118,6 +124,26 @@ export class Rate extends BaseEntity {
@Column({ name: 'trade_direction', type: 'varchar', length: 10, nullable: true })
tradeDirection?: string | null;
/**
* The leg this rate prices. Base freight (trigger = ALWAYS) is quoted per
* route — "container import, Djibouti → Dire Dawa" — so both yards are
* required for BULK/CONTAINER/INTERCITY and NULL for everything else. The
* `CK_rates_yard_scope` DB constraint enforces both halves of that.
*/
@Column({ name: 'origin_yard_id', type: 'uuid', nullable: true })
originYardId?: string | null;
@ManyToOne(() => Yard, { nullable: true, eager: false })
@JoinColumn({ name: 'origin_yard_id' })
originYard?: Yard | null;
@Column({ name: 'destination_yard_id', type: 'uuid', nullable: true })
destinationYardId?: string | null;
@ManyToOne(() => Yard, { nullable: true, eager: false })
@JoinColumn({ name: 'destination_yard_id' })
destinationYard?: Yard | null;
@Column({ name: 'currency', type: 'varchar', length: 5 })
currency!: string;

34
apps/edr-freight-api/src/modules/rule-engine/entities/yard-facility.entity.ts Normal file
View File

@@ -0,0 +1,34 @@
import { BaseEntity } from '@edr/api-common';
import { Column, Entity, Index, JoinColumn, OneToOne } from 'typeorm';
import { Yard } from './yard.entity';
/**
* What a yard's load/unload facility can do. One record per yard flagged
* `has_facility`.
*
* `hasWarehouse` is the line that matters: a facility with a warehouse (Indode
* today) stores cargo and therefore accrues storage/demurrage through the normal
* warehouse flow; the rest only move cargo on and off the train, so they record
* the handling event and its GRN and nothing else.
*/
@Entity({ schema: 'freight', name: 'yard_facilities' })
@Index(['yardId'])
export class YardFacility extends BaseEntity {
@Column({ name: 'yard_id', type: 'uuid' })
yardId!: string;
@OneToOne(() => Yard, { nullable: false, onDelete: 'CASCADE' })
@JoinColumn({ name: 'yard_id' })
yard?: Yard;
/** Cargo can be stored here — enables the warehouse flow (storage, demurrage). */
@Column({ name: 'has_warehouse', type: 'boolean', default: false })
hasWarehouse!: boolean;
@Column({ name: 'equipment_notes', type: 'text', nullable: true })
equipmentNotes?: string | null;
@Column({ name: 'is_active', type: 'boolean', default: true })
isActive!: boolean;
}

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

@@ -22,6 +22,14 @@ export class Yard extends BaseEntity {
@Column({ name: 'is_active', type: 'boolean', default: true })
isActive!: boolean;
/**
* This yard has the equipment to load/unload cargo. Intercity bookings can only
* be loaded at their origin and unloaded at their destination where this is
* true. What the facility can do lives on the YardFacility record.
*/
@Column({ name: 'has_facility', type: 'boolean', default: false })
hasFacility!: boolean;
@Column({ name: 'display_order', type: 'int', default: 1 })
displayOrder!: number;
}

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

@@ -6,12 +6,20 @@ import { Rate } from '../entities/rate.entity';
export interface IRatesRepository {
findById(id: string): Promise<Rate | null>;
findLiveRates(): Promise<Rate[]>;
/**
* LIVE rates with the yard / container / cargo relations eagerly joined, so
* lanes can be rendered with human labels (contract rate schedule). Ordered
* for a stable, readable schedule table.
*/
findLiveRatesDetailed(): Promise<Rate[]>;
findByPattern(pattern: {
rateType: string;
rateUnit: string;
containerTypeId?: string | null;
cargoTypeId?: string | null;
tradeDirection?: string | null;
originYardId?: string | null;
destinationYardId?: string | null;
}): Promise<Rate | null>;
findAll(options?: FindManyOptions<Rate>): Promise<Rate[]>;
findAndCount(options?: FindManyOptions<Rate>): Promise<[Rate[], number]>;

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

@@ -25,6 +25,22 @@ export class RatesRepository implements IRatesRepository {
.getMany();
}
findLiveRatesDetailed(): Promise<Rate[]> {
return this.repo
.createQueryBuilder('rate')
.leftJoinAndSelect('rate.originYard', 'originYard')
.leftJoinAndSelect('rate.destinationYard', 'destinationYard')
.leftJoinAndSelect('rate.containerType', 'containerType')
.leftJoinAndSelect('rate.cargoType', 'cargoType')
.where('rate.status = :status', { status: 'LIVE' })
.orderBy('rate.appliesTo', 'ASC')
.addOrderBy('rate.tradeDirection', 'ASC')
.addOrderBy('originYard.label', 'ASC')
.addOrderBy('destinationYard.label', 'ASC')
.addOrderBy('rate.rateValue', 'ASC')
.getMany();
}
/**
* Find a non-superseded rate matching an identity pattern — the same tuple the
* `UQ_rates_pattern` unique index enforces. Used to reject duplicates before
@@ -37,6 +53,8 @@ export class RatesRepository implements IRatesRepository {
containerTypeId?: string | null;
cargoTypeId?: string | null;
tradeDirection?: string | null;
originYardId?: string | null;
destinationYardId?: string | null;
}): Promise<Rate | null> {
const qb = this.repo
.createQueryBuilder('rate')
@@ -59,6 +77,18 @@ export class RatesRepository implements IRatesRepository {
} else {
qb.andWhere('rate.trade_direction IS NULL');
}
if (pattern.originYardId) {
qb.andWhere('rate.origin_yard_id = :originYardId', { originYardId: pattern.originYardId });
} else {
qb.andWhere('rate.origin_yard_id IS NULL');
}
if (pattern.destinationYardId) {
qb.andWhere('rate.destination_yard_id = :destinationYardId', {
destinationYardId: pattern.destinationYardId,
});
} else {
qb.andWhere('rate.destination_yard_id IS NULL');
}
return qb.getOne();
}
@@ -75,6 +105,10 @@ export class RatesRepository implements IRatesRepository {
findPaged(query: ListRatesQueryDto): Promise<PaginatedResponse<Rate>> {
const qb = this.repo
.createQueryBuilder('rate')
// The admin table shows the leg a base-freight rate prices — without the
// yards joined the route columns have only ids to render.
.leftJoinAndSelect('rate.originYard', 'originYard')
.leftJoinAndSelect('rate.destinationYard', 'destinationYard')
.orderBy('rate.createdAt', query.sortOrder ?? 'DESC');
if (query.status) {

11
apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts
View File

@@ -6,6 +6,7 @@ import { CargoTypesController } from './controllers/cargo-types.controller';
import { ContainerTypesController } from './controllers/container-types.controller';
import { PriorityConfigsController } from './controllers/priority-configs.controller';
import { PriorityRuleChangeRequestsController } from './controllers/priority-rule-change-requests.controller';
import { RateChangeRequestsController } from './controllers/rate-change-requests.controller';
import { RatesController } from './controllers/rates.controller';
import { ServiceTypesController } from './controllers/service-types.controller';
import { ShippingLinesController } from './controllers/shipping-lines.controller';
@@ -17,11 +18,13 @@ import { CargoType } from './entities/cargo-type.entity';
import { ContainerType } from './entities/container-type.entity';
import { PriorityConfig } from './entities/priority-config.entity';
import { PriorityRuleChangeRequest } from './entities/priority-rule-change-request.entity';
import { RateChangeRequest } from './entities/rate-change-request.entity';
import { Rate } from './entities/rate.entity';
import { ServiceType } from './entities/service-type.entity';
import { ShippingLine } from './entities/shipping-line.entity';
import { WeightLimitRule } from './entities/weight-limit-rule.entity';
import { Yard } from './entities/yard.entity';
import { YardFacility } from './entities/yard-facility.entity';
import { APPROVAL_RULES_REPOSITORY } from './interfaces/approval-rules.repository.interface';
import { CARGO_TYPES_REPOSITORY } from './interfaces/cargo-types.repository.interface';
@@ -49,11 +52,13 @@ import { CargoTypesService } from './services/cargo-types.service';
import { ContainerTypesService } from './services/container-types.service';
import { PriorityConfigsService } from './services/priority-configs.service';
import { PriorityRuleChangeRequestsService } from './services/priority-rule-change-requests.service';
import { RateChangeRequestsService } from './services/rate-change-requests.service';
import { RatesService } from './services/rates.service';
import { ServiceTypesService } from './services/service-types.service';
import { ShippingLinesService } from './services/shipping-lines.service';
import { WeightLimitRulesService } from './services/weight-limit-rules.service';
import { YardsService } from './services/yards.service';
import { YardFacilitiesService } from './services/yard-facilities.service';
import { RuleEngineService } from './rule-engine.service';
@@ -72,9 +77,11 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
ContainerType,
PriorityConfig,
PriorityRuleChangeRequest,
RateChangeRequest,
ServiceType,
WeightLimitRule,
Yard,
YardFacility,
ShippingLine,
Rate,
ApprovalRule,
@@ -91,6 +98,7 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
ContainerTypesController,
PriorityConfigsController,
PriorityRuleChangeRequestsController,
RateChangeRequestsController,
ServiceTypesController,
WeightLimitRulesController,
YardsController,
@@ -121,9 +129,11 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
ContainerTypesService,
PriorityConfigsService,
PriorityRuleChangeRequestsService,
RateChangeRequestsService,
ServiceTypesService,
WeightLimitRulesService,
YardsService,
YardFacilitiesService,
ShippingLinesService,
RatesService,
ApprovalRulesService,
@@ -138,6 +148,7 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
WeightLimitRulesService,
PriorityConfigsService,
YardsService,
YardFacilitiesService,
ShippingLinesService,
RatesService,
ApprovalRulesService,

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

@@ -42,6 +42,14 @@ export interface BookingContainerEvalInput {
isReefer?: boolean;
isOverweight?: boolean;
overweightExcessTons?: number | null;
/**
* How many individual containers on this line opted into each handling
* service. PER_CONTAINER surcharges bill these counts, not the line
* quantity — 20 containers with 10 hazardous bill hazard on 10.
*/
hazardousQuantity?: number;
reeferQuantity?: number;
returnQuantity?: number;
}
export interface BookingEvaluationInput {
@@ -61,6 +69,12 @@ export interface BookingEvaluationInput {
isGovernment?: boolean;
allowConsolidation?: boolean;
shippingLineId?: string | null;
/**
* Booking's cargo type needs EDR-provided lashing/securing (cargoType
* hasLashing = true). Fires the flat LASHING surcharge. Resolved by the
* engine from cargoTypeId when omitted.
*/
hasLashing?: boolean;
totalWagons: number;
/**
* Total bulk tonnage on the booking (cargoTotalWeightVgm). Used to scale
@@ -132,12 +146,22 @@ export class RuleEngineService {
requiresDirectorApproval = true;
}
// Lashing is a cargo-type property: a booking incurs the flat LASHING
// surcharge when its cargo type has hasLashing = true. Resolve it here so
// matchesTrigger can fire the LASHING rate. Falls back to an explicit
// input flag when no cargo type is set (e.g. container bookings).
let hasLashing = input.hasLashing === true;
if (input.cargoTypeId) {
const cargoType = await this.cargoTypesRepo.findById(input.cargoTypeId);
if (!cargoType) {
hardBlocked.push(`Cargo type ${input.cargoTypeId} not found`);
} else if (cargoType.requiresDirectorApproval) {
requiresDirectorApproval = true;
} else {
if (cargoType.requiresDirectorApproval) {
requiresDirectorApproval = true;
}
if (cargoType.hasLashing) {
hasLashing = true;
}
}
}
@@ -237,6 +261,7 @@ export class RuleEngineService {
hasOverweight,
shippingLineMapped,
allowConsolidation: input.allowConsolidation ?? false,
hasLashing,
});
if (!triggered) continue;
@@ -253,6 +278,27 @@ export class RuleEngineService {
(sum, r) => sum + (r.overweightExcessTons ?? 0),
0,
);
/**
* Containers that opted into this trigger's handling service, summed
* across lines. null when the trigger isn't per-container handling (or
* no line carries a count) so the caller falls back to the full count.
*/
const optedInCount = (trigger: string | null): number | null => {
const field =
trigger === 'HAZARDOUS'
? 'hazardousQuantity'
: trigger === 'REEFER'
? 'reeferQuantity'
: trigger === 'WITH_RETURN'
? 'returnQuantity'
: null;
if (!field) return null;
const total = input.containers.reduce(
(sum, c) => sum + Number(c[field] ?? 0),
0,
);
return total > 0 ? total : null;
};
let triggerValue: number | null = null;
let calculatedAmount: number;
@@ -268,7 +314,11 @@ export class RuleEngineService {
calculatedAmount = triggerValue * rateValue;
break;
case 'PER_CONTAINER':
triggerValue = containerCount;
// Handling surcharges bill only the containers that opted in, not the
// whole line — 20 containers with 10 hazardous bill hazard on 10.
// Legacy bookings carry no per-container counts (all 0) while their
// booking-level flag is set, so fall back to the full count there.
triggerValue = optedInCount(rate.trigger) ?? containerCount;
calculatedAmount = triggerValue * rateValue;
break;
case 'PER_WAGON':
@@ -466,6 +516,7 @@ export class RuleEngineService {
hasOverweight: boolean;
shippingLineMapped: boolean;
allowConsolidation: boolean;
hasLashing: boolean;
},
): boolean {
// Coerce defensively: a flag may arrive as the string "true"/"false" (e.g.
@@ -484,6 +535,8 @@ export class RuleEngineService {
return truthy(state.shippingLineMapped);
case 'CONSOLIDATION':
return truthy(state.allowConsolidation);
case 'LASHING':
return truthy(state.hasLashing);
// CANCELLATION / DEMURRAGE / PIL_EXTRA_FEE are contextual charges applied
// explicitly elsewhere (not auto-triggered by a booking's cargo flags).
default:

1
apps/edr-freight-api/src/modules/rule-engine/services/container-types.service.ts
View File

@@ -48,7 +48,6 @@ export class ContainerTypesService {
code,
label: dto.label,
sizeFt: dto.sizeFt,
wagonsPerUnit: dto.wagonsPerUnit,
isReefer: dto.isReefer ?? false,
isOpenTop: dto.isOpenTop ?? false,
isActive: dto.isActive ?? true,

46
apps/edr-freight-api/src/modules/rule-engine/services/priority-configs.range.spec.ts
View File

@@ -5,9 +5,8 @@ import { PriorityConfigsService } from './priority-configs.service';
/**
* Contiguous-range rules for priority configs: per type (per currency for
* CURRENCY), ranges run 1..cap with no gaps and no overlaps; the next range
* must start at the lowest uncovered wagon count. Caps: WAGON 50,
* CURRENCY 35, CUSTOMS 15.
* CURRENCY), ranges run from 1 with no gaps and no overlaps; the next range
* must start at the lowest uncovered wagon count. There is no upper ceiling.
*/
describe('PriorityConfigsService range validation', () => {
const rule = (
@@ -118,41 +117,47 @@ describe('PriorityConfigsService range validation', () => {
).rejects.toThrow(/overlaps existing rule/);
});
it('enforces the per-type ceilings (WAGON 50, CURRENCY 35, CUSTOMS 15)', async () => {
it('imposes no upper ceiling on any type', async () => {
await expect(
attempt(serviceWith([]), { minWagonCount: 1, maxWagonCount: 51 }),
).rejects.toThrow(/may not exceed 50/);
attempt(serviceWith([]), { minWagonCount: 1, maxWagonCount: 5000 }),
).resolves.toBeUndefined();
await expect(
attempt(serviceWith([]), {
type: 'CURRENCY',
currency: 'USD',
minWagonCount: 1,
maxWagonCount: 36,
maxWagonCount: 5000,
}),
).rejects.toThrow(/may not exceed 35/);
).resolves.toBeUndefined();
await expect(
attempt(serviceWith([]), {
type: 'CUSTOMS',
minWagonCount: 1,
maxWagonCount: 16,
maxWagonCount: 5000,
}),
).rejects.toThrow(/may not exceed 15/);
).resolves.toBeUndefined();
});
it('rejects any new rule once the chain covers the full range', async () => {
it('keeps extending the chain past the old caps', async () => {
await expect(
attempt(serviceWith([rule('WAGON', 1, 50)]), {
minWagonCount: 51,
maxWagonCount: 51,
maxWagonCount: 120,
}),
).rejects.toThrow(/may not exceed 50/);
).resolves.toBeUndefined();
await expect(
attempt(serviceWith([rule('CUSTOMS', 1, 15)]), {
type: 'CUSTOMS',
minWagonCount: 1,
maxWagonCount: 1,
minWagonCount: 16,
maxWagonCount: 99,
}),
).rejects.toThrow(/already cover the full 1–15 range/);
).resolves.toBeUndefined();
});
it('still rejects a min greater than the max', async () => {
await expect(
attempt(serviceWith([]), { minWagonCount: 9, maxWagonCount: 4 }),
).rejects.toThrow(BadRequestException);
});
it('tracks CURRENCY chains per currency — USD and ETB are independent', async () => {
@@ -214,16 +219,13 @@ describe('PriorityConfigsService range validation', () => {
it('reports the next-range prefill for the form', async () => {
const svc = serviceWith([rule('WAGON', 1, 5), rule('WAGON', 11, 20)]);
await expect(svc.nextRange('WAGON')).resolves.toEqual({
nextMin: 6,
maxCap: 50,
});
await expect(svc.nextRange('WAGON')).resolves.toEqual({ nextMin: 6 });
// Past the old CUSTOMS cap of 15 the chain simply continues.
await expect(
serviceWith([rule('CUSTOMS', 1, 15)]).nextRange('CUSTOMS'),
).resolves.toEqual({ nextMin: null, maxCap: 15 });
).resolves.toEqual({ nextMin: 16 });
await expect(serviceWith([]).nextRange('CURRENCY', 'USD')).resolves.toEqual({
nextMin: 1,
maxCap: 35,
});
});
});

41
apps/edr-freight-api/src/modules/rule-engine/services/priority-configs.service.ts
View File

@@ -10,28 +10,19 @@ import {
} from '../interfaces/priority-configs.repository.interface';
import { DisplayOrderService } from './display-order.service';
/** Hard ceiling of each type's wagon-count chain (1..cap, contiguous). */
export const RANGE_CAPS: Record<'WAGON' | 'CURRENCY' | 'CUSTOMS', number> = {
WAGON: 50,
CURRENCY: 35,
CUSTOMS: 15,
};
/**
* Lowest wagon count ≥ 1 not covered by any of `rules` — where the next range
* must start. Null when the chain is already complete up to the type's cap.
* must start. The chain is unbounded above, so there is always a next start.
*/
function nextRangeStart(
rules: Pick<PriorityConfig, 'type' | 'minWagonCount' | 'maxWagonCount'>[],
): number | null {
const cap = rules.length ? RANGE_CAPS[rules[0].type] : null;
): number {
const sorted = [...rules].sort((a, b) => a.minWagonCount - b.minWagonCount);
let next = 1;
for (const r of sorted) {
if (r.minWagonCount > next) break; // gap before this rule — fill it
next = Math.max(next, r.maxWagonCount + 1);
}
if (cap != null && next > cap) return null;
return next;
}
@@ -102,8 +93,8 @@ export class PriorityConfigsService {
* - ranges never overlap — a booking matches at most one rule per type;
* - ranges are contiguous from 1: a new range must START at the lowest
* wagon count not yet covered (after 1–5 the next is 6–…; deleting a
* middle rule opens a gap and the next create must fill it first);
* - each type has a hard ceiling: WAGON 50, CURRENCY 35, CUSTOMS 15.
* middle rule opens a gap and the next create must fill it first).
* There is no upper ceiling — max wagon count is unbounded.
* Ranges are inclusive on both ends.
*/
async assertNoRangeCollision(input: {
@@ -118,14 +109,6 @@ export class PriorityConfigsService {
'Min wagon count cannot be greater than max wagon count',
);
}
const cap = RANGE_CAPS[input.type];
if (input.maxWagonCount > cap) {
throw new BadRequestException(
`${input.type} ranges may not exceed ${cap} — ` +
`${input.minWagonCount}–${input.maxWagonCount} goes past the ceiling.`,
);
}
const siblings = (
await this.repository.findAll({ where: { type: input.type } })
).filter(
@@ -142,12 +125,6 @@ export class PriorityConfigsService {
const currentStart = input.excludeId
? (await this.repository.findById(input.excludeId))?.minWagonCount ?? null
: null;
if (expectedStart == null && currentStart == null) {
throw new BadRequestException(
`${input.type} rules already cover the full 1–${cap} range — ` +
'delete or shrink an existing rule first.',
);
}
if (
input.minWagonCount !== expectedStart &&
input.minWagonCount !== currentStart
@@ -174,21 +151,21 @@ export class PriorityConfigsService {
}
/**
* Where the next range for a type/currency must start, and the type's
* ceiling — feeds the create form so the min field is auto-filled and
* locked. `nextMin` is null when the chain already covers 1..cap.
* Where the next range for a type/currency must start — feeds the create
* form so the min field is auto-filled and locked. Always a number: the
* chain has no ceiling, so another range always fits.
*/
async nextRange(
type: 'WAGON' | 'CURRENCY' | 'CUSTOMS',
currency?: string | null,
): Promise<{ nextMin: number | null; maxCap: number }> {
): Promise<{ nextMin: number }> {
const siblings = (
await this.repository.findAll({ where: { type } })
).filter(
(s) =>
type !== 'CURRENCY' || (s.currency ?? null) === (currency ?? null),
);
return { nextMin: nextRangeStart(siblings), maxCap: RANGE_CAPS[type] };
return { nextMin: nextRangeStart(siblings) };
}
async remove(id: string): Promise<void> {

213
apps/edr-freight-api/src/modules/rule-engine/services/rate-change-requests.service.spec.ts Normal file
View File

@@ -0,0 +1,213 @@
import { BadRequestException, ConflictException, ForbiddenException } from '@nestjs/common';
import { RateChangeRequest } from '../entities/rate-change-request.entity';
import { Rate } from '../entities/rate.entity';
import { RateChangeRequestsService } from './rate-change-requests.service';
/**
* The guarantee under test: editing a LIVE rate never moves the live value.
* A rate at 100 keeps charging 100 while a change to 200 sits PENDING; only
* approval applies it, and only then through RatesService (so every rate rule
* is re-checked against the state at approval time).
*/
describe('RateChangeRequestsService', () => {
const liveRate = (overrides: Partial<Rate> = {}): Rate =>
({
id: 'rate-1',
status: 'LIVE',
rateType: 'OCEAN_FREIGHT',
appliesTo: 'CONTAINER',
trigger: 'ALWAYS',
currency: 'USD',
// Postgres numeric comes back as a string — the no-op check must cope.
rateValue: '100.0000' as unknown as number,
rateUnit: 'PER_CONTAINER',
containerTypeId: null,
cargoTypeId: null,
tradeDirection: null,
proposedByStaffId: 'staff-1',
...overrides,
}) as unknown as Rate;
const build = (opts: {
rate?: Rate;
pending?: RateChangeRequest | null;
applyThrows?: Error;
} = {}) => {
const rate = opts.rate ?? liveRate();
const saved: RateChangeRequest[] = [];
const repo = {
findOne: jest.fn(async ({ where }: { where: Record<string, unknown> }) => {
if (where.status === 'PENDING' && where.rateId) return opts.pending ?? null;
return saved.find((r) => r.id === where.id) ?? opts.pending ?? null;
}),
create: jest.fn((data: Partial<RateChangeRequest>) => ({ id: 'req-1', ...data })),
save: jest.fn(async (entity: RateChangeRequest) => {
saved.push(entity);
return entity;
}),
find: jest.fn(async () => saved),
};
const rates = {
findById: jest.fn(async () => rate),
assertUpdateValid: jest.fn(async () => undefined),
applyApprovedUpdate: jest.fn(async () => {
if (opts.applyThrows) throw opts.applyThrows;
return rate;
}),
};
const inbox = { notify: jest.fn(async () => undefined) };
const service = new RateChangeRequestsService(
repo as never,
rates as never,
inbox as never,
);
// `pending` is the very object approve/reject mutate — assert on it, not a copy.
return { service, repo, rates, inbox, pending: opts.pending };
};
describe('submit', () => {
it('files a pending request instead of touching the live rate', async () => {
const { service, rates } = build();
const request = await service.submit({ rateId: 'rate-1', update: { rateValue: 200 } });
expect(request.status).toBe('PENDING');
expect(request.payload).toEqual({ rateValue: 200 });
// The old value is snapshotted for the approver's diff...
expect(request.previousValues).toEqual({ rateValue: '100.0000' });
// ...and nothing wrote to the rate itself.
expect(rates.applyApprovedUpdate).not.toHaveBeenCalled();
});
it('keeps only the fields that actually changed', async () => {
const { service } = build();
// A form posts every field back; only rateValue differs from the live rate.
const request = await service.submit({
rateId: 'rate-1',
update: {
rateValue: 200,
currency: 'USD',
rateUnit: 'PER_CONTAINER',
appliesTo: 'CONTAINER',
},
});
expect(request.payload).toEqual({ rateValue: 200 });
});
it('rejects a no-op — 100 posted against a live 100.0000 is not a change', async () => {
const { service } = build();
await expect(
service.submit({ rateId: 'rate-1', update: { rateValue: 100 } }),
).rejects.toThrow(/Nothing changed/);
});
it('refuses a rate that is not LIVE — those edit directly', async () => {
const { service } = build({ rate: liveRate({ status: 'DRAFT' }) });
await expect(
service.submit({ rateId: 'rate-1', update: { rateValue: 200 } }),
).rejects.toThrow(BadRequestException);
});
it('refuses a second pending change for the same rate', async () => {
const { service } = build({
pending: { id: 'req-0', status: 'PENDING' } as unknown as RateChangeRequest,
});
await expect(
service.submit({ rateId: 'rate-1', update: { rateValue: 200 } }),
).rejects.toThrow(ConflictException);
});
it('validates up front so the requester hears about a bad patch, not the approver', async () => {
const { service, rates } = build();
rates.assertUpdateValid.mockRejectedValueOnce(
new BadRequestException('Rate unit "PER_TON" is not valid for this rate.'),
);
await expect(
service.submit({ rateId: 'rate-1', update: { rateUnit: 'PER_TON' } }),
).rejects.toThrow(/not valid for this rate/);
});
});
describe('approve', () => {
const pendingRequest = (): RateChangeRequest =>
({
id: 'req-1',
rateId: 'rate-1',
payload: { rateValue: 200 },
previousValues: { rateValue: '100.0000' },
status: 'PENDING',
requestedByUserId: 'staff-1',
}) as unknown as RateChangeRequest;
it('applies the change through RatesService and marks it approved', async () => {
const { service, rates } = build({ pending: pendingRequest() });
const decided = await service.approve('req-1', 'approver-1', 'Agreed');
expect(rates.applyApprovedUpdate).toHaveBeenCalledWith('rate-1', { rateValue: 200 });
expect(decided.status).toBe('APPROVED');
expect(decided.decidedByUserId).toBe('approver-1');
expect(decided.decisionNote).toBe('Agreed');
});
it('blocks the requester from approving their own change', async () => {
const { service, rates } = build({ pending: pendingRequest() });
await expect(service.approve('req-1', 'staff-1')).rejects.toThrow(ForbiddenException);
expect(rates.applyApprovedUpdate).not.toHaveBeenCalled();
});
it('lets a super admin self-approve', async () => {
const { service } = build({ pending: pendingRequest() });
await expect(service.approve('req-1', 'staff-1', undefined, true)).resolves.toMatchObject({
status: 'APPROVED',
});
});
it('stays PENDING when applying now fails — never marks a change that did not land', async () => {
const { service, pending, repo } = build({
pending: pendingRequest(),
applyThrows: new ConflictException('A rate for this exact combination already exists.'),
});
await expect(service.approve('req-1', 'approver-1')).rejects.toThrow(/already exists/);
// Apply runs first, so a failure leaves the request untouched and re-decidable.
expect(pending!.status).toBe('PENDING');
expect(repo.save).not.toHaveBeenCalled();
});
it('refuses to decide an already-decided request', async () => {
const { service } = build({
pending: { ...pendingRequest(), status: 'APPROVED' } as unknown as RateChangeRequest,
});
await expect(service.approve('req-1', 'approver-1')).rejects.toThrow(ConflictException);
});
});
describe('reject', () => {
it('never touches the rate — it simply keeps its current value', async () => {
const { service, rates } = build({
pending: {
id: 'req-1',
rateId: 'rate-1',
payload: { rateValue: 200 },
previousValues: { rateValue: '100.0000' },
status: 'PENDING',
requestedByUserId: 'staff-1',
} as unknown as RateChangeRequest,
});
const decided = await service.reject('req-1', 'approver-1', 'Too steep');
expect(decided.status).toBe('REJECTED');
expect(decided.decisionNote).toBe('Too steep');
expect(rates.applyApprovedUpdate).not.toHaveBeenCalled();
});
});
});

241
apps/edr-freight-api/src/modules/rule-engine/services/rate-change-requests.service.ts Normal file
View File

@@ -0,0 +1,241 @@
import { NotificationAudience, NotificationType } from '@edr/types';
import {
BadRequestException,
ConflictException,
ForbiddenException,
Injectable,
Logger,
NotFoundException,
} from '@nestjs/common';
import { InjectRepository } from '@nestjs/typeorm';
import { Repository } from 'typeorm';
import { NotificationInboxService } from '../../notification-inbox/notification-inbox.service';
import { SubmitRateChangeDto } from '../dto/rate-change-request.dto';
import { UpdateRateDto } from '../dto/update-rate.dto';
import {
RateChangeRequest,
RateChangeStatus,
} from '../entities/rate-change-request.entity';
import { Rate } from '../entities/rate.entity';
import { RatesService } from './rates.service';
/** Backoffice page where both the queue and the rates live. */
const RATES_LINK = '/dashboard/rules/rates';
/** Fields a change request may carry — anything else in the patch is ignored. */
const DIFFABLE_FIELDS = [
'rateValue',
'currency',
'rateUnit',
'appliesTo',
'trigger',
'tradeDirection',
'containerTypeId',
'cargoTypeId',
] as const;
/**
* Approval workflow for edits to LIVE rates.
*
* A LIVE rate is what pricing charges right now, so it is never edited in
* place. The edit is filed here as a PENDING request and the live row keeps
* its old value — a rate at 100 USD keeps quoting 100 while a change to 200
* waits. Approval replays the edit through RatesService, so every rule
* (unit validity, pattern uniqueness) is re-checked against whatever is true
* at approval time, not at submit time.
*/
@Injectable()
export class RateChangeRequestsService {
private readonly logger = new Logger(RateChangeRequestsService.name);
constructor(
@InjectRepository(RateChangeRequest)
private readonly repo: Repository<RateChangeRequest>,
private readonly rates: RatesService,
private readonly inbox: NotificationInboxService,
) {}
/**
* File an edit against a LIVE rate. Validated up front so the requester
* hears about a bad unit or a pattern clash immediately rather than the
* approver hitting it days later.
*/
async submit(dto: SubmitRateChangeDto, userId?: string | null): Promise<RateChangeRequest> {
const rate = await this.rates.findById(dto.rateId);
if (rate.status !== 'LIVE') {
throw new BadRequestException(
`Only LIVE rates go through approval — this rate is ${rate.status} and can be edited directly.`,
);
}
const payload = this.changedFieldsOnly(rate, dto.update);
if (Object.keys(payload).length === 0) {
throw new BadRequestException('Nothing changed — the proposed values match the live rate.');
}
// One pending edit per rate: two racing requests would both validate, then
// the second would silently overwrite the first on approval.
const inFlight = await this.repo.findOne({
where: { rateId: dto.rateId, status: 'PENDING' },
});
if (inFlight) {
throw new ConflictException(
'This rate already has a change awaiting approval. Have it approved or rejected first.',
);
}
await this.rates.assertUpdateValid(dto.rateId, payload as UpdateRateDto);
const request = await this.repo.save(
this.repo.create({
rateId: dto.rateId,
payload,
previousValues: this.snapshot(rate, payload),
status: 'PENDING',
requestedByUserId: userId ?? null,
}),
);
this.notifyTeam(
'Rate change submitted',
`A change to a LIVE rate was submitted and awaits approval. The current rate stays in effect until it is approved.`,
request,
);
return request;
}
async list(status?: RateChangeStatus): Promise<RateChangeRequest[]> {
return this.repo.find({
where: status ? { status } : {},
relations: { rate: true },
order: { createdAt: 'DESC' },
});
}
/**
* Approve and apply. The live mutation runs FIRST — if it now fails (someone
* created a clashing rate since submit), the request stays PENDING and the
* approver sees the real error instead of a request marked approved that
* never landed.
*/
async approve(
id: string,
userId?: string | null,
decisionNote?: string,
canSelfApprove = false,
): Promise<RateChangeRequest> {
const request = await this.findPending(id);
// Separation of duties: the requester cannot approve their own repricing —
// except super admins, who have full backoffice authority.
if (!canSelfApprove && userId && userId === request.requestedByUserId) {
throw new ForbiddenException('You cannot approve a rate change you submitted');
}
await this.rates.applyApprovedUpdate(request.rateId, request.payload as UpdateRateDto);
request.status = 'APPROVED';
request.decidedByUserId = userId ?? null;
request.decidedAt = new Date();
request.decisionNote = decisionNote ?? null;
const saved = await this.repo.save(request);
this.notifyTeam(
'Rate change approved',
`The rate change was approved and is now live.` +
(decisionNote ? ` Note: ${decisionNote}` : ''),
saved,
);
return saved;
}
/** Reject — the live rate is never touched, so it simply keeps its value. */
async reject(
id: string,
userId?: string | null,
decisionNote?: string,
): Promise<RateChangeRequest> {
const request = await this.findPending(id);
request.status = 'REJECTED';
request.decidedByUserId = userId ?? null;
request.decidedAt = new Date();
request.decisionNote = decisionNote ?? null;
const saved = await this.repo.save(request);
this.notifyTeam(
'Rate change rejected',
`The rate change was rejected — the rate keeps its current value.` +
(decisionNote ? ` Note: ${decisionNote}` : ''),
saved,
);
return saved;
}
/**
* Keep only fields the requester actually changed. A form posts every field
* back, so without this the diff would list untouched values as changes.
*/
private changedFieldsOnly(rate: Rate, update: UpdateRateDto): Record<string, unknown> {
const patch: Record<string, unknown> = {};
for (const field of DIFFABLE_FIELDS) {
const proposed = (update as Record<string, unknown>)[field];
if (proposed === undefined) continue;
if (this.sameValue(proposed, (rate as unknown as Record<string, unknown>)[field])) continue;
patch[field] = proposed;
}
return patch;
}
/** The live values the patch would overwrite — the "before" side of the diff. */
private snapshot(rate: Rate, payload: Record<string, unknown>): Record<string, unknown> {
const before: Record<string, unknown> = {};
for (const field of Object.keys(payload)) {
before[field] = (rate as unknown as Record<string, unknown>)[field] ?? null;
}
return before;
}
/**
* rateValue arrives as a string from Postgres `numeric` but as a number from
* the form, so 100 and "100.0000" must compare equal or every submit would
* look like a change.
*/
private sameValue(a: unknown, b: unknown): boolean {
if (a === b) return true;
if (a == null && b == null) return true;
if (a == null || b == null) return false;
const numA = Number(a);
const numB = Number(b);
if (!Number.isNaN(numA) && !Number.isNaN(numB) && a !== '' && b !== '') {
return numA === numB;
}
return String(a) === String(b);
}
private async findPending(id: string): Promise<RateChangeRequest> {
const request = await this.repo.findOne({ where: { id }, relations: { rate: true } });
if (!request) throw new NotFoundException(`Rate change request ${id} not found`);
if (request.status !== 'PENDING') {
throw new ConflictException(`Rate change request is already ${request.status.toLowerCase()}`);
}
return request;
}
/** Fire-and-forget — a notification failure never blocks the workflow. */
private notifyTeam(title: string, body: string, request: RateChangeRequest): void {
void this.inbox
.notify({
recipients: { allBackoffice: true },
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.REQUEST_SUBMITTED,
title,
body,
link: RATES_LINK,
data: { rateChangeRequestId: request.id, rateId: request.rateId },
})
.catch((err) =>
this.logger.warn(`Rate-change notification failed: ${(err as Error).message}`),
);
}
}

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

@@ -6,7 +6,7 @@ import {
Injectable,
NotFoundException,
} from '@nestjs/common';
import { PaginatedResponse } from '@edr/types';
import { PaginatedResponse, YardCountry } from '@edr/types';
import { CreateRateDto } from '../dto/create-rate.dto';
import { ListRatesQueryDto } from '../dto/list-rule-engine-query.dto';
import { UpdateRateDto } from '../dto/update-rate.dto';
@@ -14,12 +14,24 @@ import { Rate } from '../entities/rate.entity';
import { deriveRateType } from '../entities/rate-type.util';
import { allowedRateUnits, isRateUnitAllowed } from '../entities/rate-unit.util';
import { IRatesRepository, RATES_REPOSITORY } from '../interfaces/rates.repository.interface';
import { IYardsRepository, YARDS_REPOSITORY } from '../interfaces/yards.repository.interface';
/** Categories priced per rail leg — they carry an origin → destination yard pair. */
const BASE_FREIGHT_CATEGORIES: readonly Rate['appliesTo'][] = ['BULK', 'CONTAINER', 'INTERCITY'];
/** The yard pair a rate scopes to, already validated against its direction. */
interface YardScope {
originYardId: string | null;
destinationYardId: string | null;
}
@Injectable()
export class RatesService {
constructor(
@Inject(RATES_REPOSITORY)
private readonly repository: IRatesRepository,
@Inject(YARDS_REPOSITORY)
private readonly yardsRepository: IYardsRepository,
) {}
/** List rates — standard paginated envelope with server-side search. */
@@ -32,6 +44,14 @@ export class RatesService {
return this.repository.findLiveRates();
}
/**
* LIVE rates with yard / container / cargo relations joined — used to render
* the origin → destination rate schedule inside generated contracts.
*/
async findLiveRatesDetailed(): Promise<Rate[]> {
return this.repository.findLiveRatesDetailed();
}
/** Get a rate by ID. */
async findById(id: string): Promise<Rate> {
const entity = await this.repository.findById(id);
@@ -48,20 +68,156 @@ export class RatesService {
private resolveRateUnit(
appliesTo: Rate['appliesTo'],
trigger: Rate['trigger'],
requestedUnit: Rate['rateUnit'],
requestedUnit: Rate['rateUnit'] | undefined,
): Rate['rateUnit'] {
// Overweight is per-ton, full stop.
// 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';
if (!isRateUnitAllowed({ appliesTo, trigger, unit: requestedUnit })) {
const allowed = allowedRateUnits({ appliesTo, trigger }).join(', ');
const allowed = allowedRateUnits({ appliesTo, trigger });
if (!requestedUnit) {
throw new BadRequestException(
`Rate unit "${requestedUnit}" is not valid for this rate. Allowed: ${allowed}.`,
`Pick a rate unit for this rate. Allowed: ${allowed.join(', ')}.`,
);
}
if (!isRateUnitAllowed({ appliesTo, trigger, unit: requestedUnit })) {
throw new BadRequestException(
`Rate unit "${requestedUnit}" is not valid for this rate. Allowed: ${allowed.join(', ')}.`,
);
}
return requestedUnit;
}
/** 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);
}
/**
* 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
* rails inland, export is the reverse, and intercity stays inside Ethiopia.
*/
private expectedYardCountries(
appliesTo: Rate['appliesTo'],
tradeDirection: string | null,
): { origin: YardCountry; destination: YardCountry } {
if (appliesTo === 'INTERCITY') {
return { origin: YardCountry.ETHIOPIA, destination: YardCountry.ETHIOPIA };
}
return tradeDirection === 'EXPORT'
? { origin: YardCountry.ETHIOPIA, destination: YardCountry.DJIBOUTI }
: { origin: YardCountry.DJIBOUTI, destination: YardCountry.ETHIOPIA };
}
/**
* Validate and normalise the leg a rate prices.
*
* Base freight must name both yards and they must match the direction, so a
* "container import" rate cannot be quoted Ethiopia → Ethiopia. Everything
* else (surcharges, first/last mile) is route-agnostic and has its yards
* cleared, mirroring how container/cargo scope is cleared for surcharges.
*/
private async resolveYardScope(input: {
appliesTo: Rate['appliesTo'];
trigger: Rate['trigger'];
tradeDirection: string | null;
originYardId?: string | null;
destinationYardId?: string | null;
}): Promise<YardScope> {
const { appliesTo, trigger, tradeDirection } = input;
if (!this.isBaseFreight(appliesTo, trigger)) {
return { originYardId: null, destinationYardId: null };
}
const originYardId = input.originYardId ?? null;
const destinationYardId = input.destinationYardId ?? null;
if (!originYardId || !destinationYardId) {
throw new BadRequestException(
'Base freight rates are priced per leg — pick both an origin and a destination yard.',
);
}
if (originYardId === destinationYardId) {
throw new BadRequestException('Origin and destination yard must be different.');
}
const [origin, destination] = await Promise.all([
this.yardsRepository.findById(originYardId),
this.yardsRepository.findById(destinationYardId),
]);
if (!origin) throw new BadRequestException(`Origin yard ${originYardId} not found`);
if (!destination) {
throw new BadRequestException(`Destination yard ${destinationYardId} not found`);
}
const expected = this.expectedYardCountries(appliesTo, tradeDirection);
if (origin.country !== expected.origin || destination.country !== expected.destination) {
const shape =
appliesTo === 'INTERCITY' ? 'Intercity' : `${tradeDirection ?? 'Import'} freight`;
throw new BadRequestException(
`${shape} runs ${expected.origin} → ${expected.destination}, but ${origin.label} is in ` +
`${origin.country} and ${destination.label} is in ${destination.country}.`,
);
}
return { originYardId, destinationYardId };
}
/**
* Guard the scope fields a base-freight category needs before we derive its
* rateType: import/export must say which, and intercity must say whether it
* carries containers or bulk (the two price differently and an unstated kind
* would silently file the rate as one of them).
*/
private assertScopeCoherent(input: {
appliesTo: Rate['appliesTo'];
trigger: Rate['trigger'];
tradeDirection: string | null;
intercityKind: string | null;
containerTypeId: string | null;
cargoTypeId: string | null;
}): void {
const { appliesTo, trigger, tradeDirection, intercityKind } = input;
const { containerTypeId, cargoTypeId } = input;
if (!this.isBaseFreight(appliesTo, trigger)) return;
if (appliesTo === 'INTERCITY') {
if (intercityKind !== 'CONTAINER' && intercityKind !== 'BULK') {
throw new BadRequestException(
'An intercity rate must say whether it covers containers or bulk.',
);
}
// The scope field has to agree with the kind, or the rate would advertise
// one cargo kind and narrow by the other.
if (intercityKind === 'CONTAINER' && cargoTypeId) {
throw new BadRequestException(
'An intercity container rate cannot be scoped to a bulk cargo type.',
);
}
if (intercityKind === 'BULK' && containerTypeId) {
throw new BadRequestException(
'An intercity bulk rate cannot be scoped to a container type.',
);
}
return;
}
if (tradeDirection !== 'IMPORT' && tradeDirection !== 'EXPORT') {
throw new BadRequestException(
`${appliesTo === 'BULK' ? 'Bulk' : 'Container'} freight must be either IMPORT or EXPORT.`,
);
}
}
/**
* Whether a rate covers bulk cargo — the flag `deriveRateType` splits
* INTERCITY_BULK from INTERCITY_CONTAINER on. Intercity states its kind
* explicitly; for BULK/CONTAINER the category already says it.
*/
private resolvesToBulk(appliesTo: Rate['appliesTo'], intercityKind: string | null): boolean {
return appliesTo === 'INTERCITY' ? intercityKind === 'BULK' : appliesTo === 'BULK';
}
/**
* 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
@@ -73,12 +229,14 @@ export class RatesService {
containerTypeId: string | null;
cargoTypeId: string | null;
tradeDirection: string | null;
originYardId: string | null;
destinationYardId: string | null;
ignoreId?: string;
}): Promise<void> {
const existing = await this.repository.findByPattern(pattern);
if (existing && existing.id !== pattern.ignoreId) {
throw new ConflictException(
'A rate for this exact combination already exists. Edit or delete the existing rate instead of creating a duplicate.',
'A rate for this exact combination already exists on this route. Edit or delete the existing rate instead of creating a duplicate.',
);
}
}
@@ -92,17 +250,49 @@ export class RatesService {
const isSurcharge = trigger !== 'ALWAYS';
const containerTypeId = isSurcharge ? null : (dto.containerTypeId ?? null);
const cargoTypeId = isSurcharge ? null : (dto.cargoTypeId ?? null);
const tradeDirection = isSurcharge ? null : (dto.tradeDirection ?? null);
// Intercity never leaves Ethiopia, so it has no trade direction to store —
// its yard pair already says where it runs.
const tradeDirection =
isSurcharge || appliesTo === 'INTERCITY' ? null : (dto.tradeDirection ?? null);
const intercityKind = dto.intercityKind ?? null;
this.assertScopeCoherent({
appliesTo,
trigger,
tradeDirection,
intercityKind,
containerTypeId,
cargoTypeId,
});
const { originYardId, destinationYardId } = await this.resolveYardScope({
appliesTo,
trigger,
tradeDirection,
originYardId: dto.originYardId,
destinationYardId: dto.destinationYardId,
});
const rateType = deriveRateType({
appliesTo,
trigger,
tradeDirection,
isBulk: Boolean(cargoTypeId),
isBulk: this.resolvesToBulk(appliesTo, intercityKind),
});
const rateUnit = this.resolveRateUnit(appliesTo, trigger, dto.rateUnit as Rate['rateUnit']);
const rateUnit = this.resolveRateUnit(
appliesTo,
trigger,
dto.rateUnit as Rate['rateUnit'] | undefined,
);
await this.assertNoDuplicatePattern({ rateType, rateUnit, containerTypeId, cargoTypeId, tradeDirection });
await this.assertNoDuplicatePattern({
rateType,
rateUnit,
containerTypeId,
cargoTypeId,
tradeDirection,
originYardId,
destinationYardId,
});
return this.repository.create({
appliesTo,
@@ -111,6 +301,8 @@ export class RatesService {
containerTypeId,
cargoTypeId,
tradeDirection,
originYardId,
destinationYardId,
currency: dto.currency ?? 'USD',
rateValue: dto.rateValue,
rateUnit,
@@ -119,12 +311,62 @@ export class RatesService {
});
}
/** Update a DRAFT rate. */
/**
* Update a DRAFT rate in place. Nothing prices off a draft, so a direct edit
* is safe. A LIVE rate cannot take this path — see `applyApprovedUpdate`.
*/
async update(id: string, dto: UpdateRateDto): Promise<Rate> {
const existing = await this.findById(id);
if (existing.status !== 'DRAFT') {
throw new BadRequestException('Only DRAFT rates can be updated');
throw new BadRequestException(
existing.status === 'LIVE'
? 'A LIVE rate cannot be edited directly — file a rate change request so an approver can apply it.'
: 'Only DRAFT rates can be updated',
);
}
return this.applyUpdate(existing, dto);
}
/**
* Apply an approved change request to a LIVE rate. Same validation as a
* DRAFT edit — it just skips the DRAFT guard, because a LIVE rate reaching
* here has already been through approval. Only ever called by
* RateChangeRequestsService.approve.
*/
async applyApprovedUpdate(id: string, dto: UpdateRateDto): Promise<Rate> {
const existing = await this.findById(id);
if (existing.status !== 'LIVE') {
throw new BadRequestException(
`Rate change requests apply to LIVE rates only — this rate is ${existing.status}.`,
);
}
return this.applyUpdate(existing, dto);
}
/**
* Validate a proposed patch against a rate without writing anything — lets a
* change request be refused at submit time instead of surprising the
* approver. Throws exactly what applying it would throw.
*/
async assertUpdateValid(id: string, dto: UpdateRateDto): Promise<void> {
await this.buildUpdate(await this.findById(id), dto);
}
private async applyUpdate(existing: Rate, dto: UpdateRateDto): Promise<Rate> {
const updates = await this.buildUpdate(existing, dto);
const updated = await this.repository.update(existing.id, updates);
if (!updated) throw new NotFoundException(`Rate ${existing.id} not found`);
return updated;
}
/**
* The shared edit body: re-derives rateType, re-validates the unit against
* the (possibly changed) shape, and guards pattern uniqueness. Status is
* never touched — an approved edit to a LIVE rate stays LIVE. Pure apart
* from the uniqueness read, so it doubles as the dry-run validator.
*/
private async buildUpdate(existing: Rate, dto: UpdateRateDto): Promise<Partial<Rate>> {
const id = existing.id;
const updates: Partial<Rate> = {};
const appliesTo = (dto.appliesTo as Rate['appliesTo']) ?? existing.appliesTo;
@@ -144,21 +386,52 @@ export class RatesService {
: dto.cargoTypeId !== undefined
? dto.cargoTypeId
: existing.cargoTypeId;
const tradeDirection = isSurcharge
? null
: dto.tradeDirection !== undefined
? dto.tradeDirection
: existing.tradeDirection;
const tradeDirection =
isSurcharge || appliesTo === 'INTERCITY'
? null
: dto.tradeDirection !== undefined
? dto.tradeDirection
: existing.tradeDirection;
updates.containerTypeId = containerTypeId ?? null;
updates.cargoTypeId = cargoTypeId ?? null;
updates.tradeDirection = tradeDirection ?? null;
// A patch that leaves the cargo kind unsaid keeps the one the rate already
// has — read back off its rateType, the only place it is recorded.
const intercityKind =
dto.intercityKind ?? (existing.rateType === 'INTERCITY_BULK' ? 'BULK' : 'CONTAINER');
this.assertScopeCoherent({
appliesTo,
trigger,
tradeDirection: updates.tradeDirection,
intercityKind,
containerTypeId: updates.containerTypeId,
cargoTypeId: updates.cargoTypeId,
});
// Re-validate the leg: changing direction can invalidate a yard pair that
// was legal under the old one (an import route is not an export route).
const yardScope = await this.resolveYardScope({
appliesTo,
trigger,
tradeDirection: updates.tradeDirection,
originYardId:
dto.originYardId !== undefined ? dto.originYardId : existing.originYardId,
destinationYardId:
dto.destinationYardId !== undefined
? dto.destinationYardId
: existing.destinationYardId,
});
updates.originYardId = yardScope.originYardId;
updates.destinationYardId = yardScope.destinationYardId;
// Keep the derived rateType in sync with whatever changed.
const rateType = deriveRateType({
appliesTo,
trigger,
tradeDirection,
isBulk: Boolean(cargoTypeId),
isBulk: this.resolvesToBulk(appliesTo, intercityKind),
});
updates.rateType = rateType;
@@ -174,14 +447,14 @@ export class RatesService {
containerTypeId: updates.containerTypeId,
cargoTypeId: updates.cargoTypeId,
tradeDirection: updates.tradeDirection,
originYardId: updates.originYardId,
destinationYardId: updates.destinationYardId,
ignoreId: id,
});
updates.currency = dto.currency ?? existing.currency ?? 'USD';
if (dto.rateValue !== undefined) updates.rateValue = dto.rateValue;
const updated = await this.repository.update(id, updates);
if (!updated) throw new NotFoundException(`Rate ${id} not found`);
return updated;
return updates;
}
/** Submit a DRAFT rate for CEO approval. */

89
apps/edr-freight-api/src/modules/rule-engine/services/yard-facilities.service.ts Normal file
View File

@@ -0,0 +1,89 @@
import { Injectable } from '@nestjs/common';
import { DataSource } from 'typeorm';
/** A yard's load/unload capability, resolved for the handling flows. */
export interface YardFacilityInfo {
yardId: string;
yardCode: string | null;
yardLabel: string | null;
/** The yard can load/unload cargo at all. */
hasFacility: boolean;
/** The facility stores cargo — enables the warehouse flow (storage, demurrage). */
hasWarehouse: boolean;
}
/**
* Which yards can handle cargo, and how.
*
* A yard is a load/unload point when `yards.has_facility` is set; the matching
* `yard_facilities` record says whether it also stores cargo. Facilities without a
* warehouse move cargo on and off the train and nothing more — no storage, no
* demurrage. This is the single resolver the journey and handling flows use, so
* they can't drift on what a facility is.
*/
@Injectable()
export class YardFacilitiesService {
constructor(private readonly dataSource: DataSource) {}
/** Resolve a yard's handling capability. Null when the yard doesn't exist. */
async facilityForYard(yardId: string): Promise<YardFacilityInfo | null> {
const [row]: Array<{
yardId: string;
yardCode: string | null;
yardLabel: string | null;
hasFacility: boolean;
hasWarehouse: boolean | null;
}> = await this.dataSource.query(
`SELECT y.id AS "yardId",
y.code AS "yardCode",
y.label AS "yardLabel",
y.has_facility AS "hasFacility",
f.has_warehouse AS "hasWarehouse"
FROM freight.yards y
LEFT JOIN freight.yard_facilities f
ON f.yard_id = y.id AND f.deleted_at IS NULL AND f.is_active = true
WHERE y.id = $1 AND y.deleted_at IS NULL`,
[yardId],
);
if (!row) return null;
return {
yardId: row.yardId,
yardCode: row.yardCode,
yardLabel: row.yardLabel,
hasFacility: Boolean(row.hasFacility),
// No facility record means no warehouse, whatever the flag says.
hasWarehouse: Boolean(row.hasFacility) && Boolean(row.hasWarehouse),
};
}
/** Every yard that can load/unload, for pickers and the intercity queues. */
async listFacilityYards(): Promise<YardFacilityInfo[]> {
const rows: Array<{
yardId: string;
yardCode: string | null;
yardLabel: string | null;
hasFacility: boolean;
hasWarehouse: boolean | null;
}> = await this.dataSource.query(
`SELECT y.id AS "yardId",
y.code AS "yardCode",
y.label AS "yardLabel",
y.has_facility AS "hasFacility",
f.has_warehouse AS "hasWarehouse"
FROM freight.yards y
LEFT JOIN freight.yard_facilities f
ON f.yard_id = y.id AND f.deleted_at IS NULL AND f.is_active = true
WHERE y.deleted_at IS NULL
AND y.is_active = true
AND y.has_facility = true
ORDER BY y.display_order ASC, y.label ASC`,
);
return rows.map((r) => ({
yardId: r.yardId,
yardCode: r.yardCode,
yardLabel: r.yardLabel,
hasFacility: true,
hasWarehouse: Boolean(r.hasWarehouse),
}));
}
}

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

@@ -45,6 +45,7 @@ export class YardsService {
label: dto.label,
country: dto.country,
isActive: dto.isActive ?? true,
hasFacility: dto.hasFacility ?? false,
displayOrder,
});
}

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