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

feat: scope notification to permission actions

Browse Source
This commit is contained in:
Nathnael
2026-08-07 12:42:33 +00:00
parent 1e9149ce00
commit 116b479bb0
19 changed files with 486 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -76,6 +76,7 @@ import { FileUploadSettingsSeeder } from "./seed/file-upload-settings.seeder";
// import { ExportDjiboutiInterchangeDemoSeeder } from "./seed/export-djibouti-interchange-demo.seeder";
// import { MarshallingDemoTrainsSeeder } from "./seed/marshalling-demo-trains.seeder";
import { FreightPermissionKeyMigrationSeeder } from "./seed/freight-permission-key-migration.seeder";
import { FreightNotificationPermissionsSeeder } from "./seed/freight-notification-permissions.seeder";
// import { DemoFreightDataSeeder } from "./seed/demo-freight-data.seeder";
// import { GovCompaniesSeeder } from "./seed/gov-companies.seeder";
import { ApprovedFirstLastMileDemoBookingsSeeder } from "./seed/approved-first-lastmile-demo-bookings.seeder";
@@ -257,6 +258,7 @@ if (!process.env.APPLICATION_NAME) {
FileUploadSettingsSeeder,
// YardFacilitiesSeeder,
FreightPermissionKeyMigrationSeeder,
FreightNotificationPermissionsSeeder,
// Disabled seeds — providers commented out (imports/injection/run too):
// DemoUsersSeeder,
// FreightStaffUsersSeeder,
@@ -287,6 +289,7 @@ export class AppModule implements OnApplicationBootstrap {
private readonly fileUploadSettingsSeeder: FileUploadSettingsSeeder,
// private readonly yardFacilitiesSeeder: YardFacilitiesSeeder,
private readonly freightPermissionKeyMigrationSeeder: FreightPermissionKeyMigrationSeeder,
private readonly freightNotificationPermissionsSeeder: FreightNotificationPermissionsSeeder,
// Disabled seeds — injections commented out (imports/provider/run too):
// private readonly demoUsersSeeder: DemoUsersSeeder,
// private readonly freightStaffUsersSeeder: FreightStaffUsersSeeder,
@@ -328,6 +331,16 @@ export class AppModule implements OnApplicationBootstrap {
await this.edrOrgSeeder.run();
await this.iamBaselineSeeder.run();
await this.freightPositionsSeeder.run();
// freightNotificationPermissions → seeds the <module>:get_notification
// keys and backfills them onto whoever
// already holds each desk's anchor
// permission. Runs LAST in this block so
// it sees a freshly-seeded catalog and
// freshly-seeded positions. Unlike the
// seeders above it is NOT gated behind
// SEED_EDR_ORG — without it every staff
// notification resolves to no one.
await this.freightNotificationPermissionsSeeder.run();
// File upload settings — keep enabled.
await this.fileUploadSettingsSeeder.run();

72
apps/edr-freight-api/src/modules/backoffice/backoffice.service.ts
View File

@@ -46,7 +46,8 @@ export class BackofficeService {
/**
* IAM user ids of every current employee across all organizations — used by
* the notification recipients resolver's `allBackoffice` selector.
* support chat for staff room membership. Notifications deliberately do NOT
* use this: they target a desk via `getEmployeeUserIdsByPermission`.
*/
async getAllCurrentEmployeeUserIds(): Promise<string[]> {
const employees = await this.employeeRepository.find({
@@ -63,24 +64,67 @@ export class BackofficeService {
* IAM user ids of current employees (any org) holding ANY of the given
* permission keys — used by the notification recipients resolver's
* `permissionKeys` selector for department/role-scoped targeting.
*
* This MUST agree with the request-time guard (`hasFreightPermission`,
* common/freight-permission.util.ts), which counts four grant carriers plus
* the super_admin bypass. Counting fewer silently drops legitimate
* recipients: an earlier version joined only direct position permissions, on
* which `bookings:view` resolved to 2 users — against 21 through position
* TYPES, which is where admin-created positions actually keep their grants.
*
* Raw SQL rather than QueryBuilder because `Position.positionTypePermissions`
* declares its inverse side against PositionType, so a relation join emits
* `ptp.position_type_id = position.id` and silently matches nothing. Same
* approach as FreightMeService's position-type lookups.
*/
async getEmployeeUserIdsByPermission(
permissionKeys: string[],
): Promise<string[]> {
if (!permissionKeys.length) return [];
const rows: { userId: string | null }[] = await this.employeeRepository
.createQueryBuilder("employee")
.innerJoin("employee.employeePositions", "employeePosition")
.innerJoin("employeePosition.position", "position")
.innerJoin("position.positionPermission", "positionPermission")
.innerJoin("positionPermission.permission", "permission")
.where("employee.isCurrent = :isCurrent", { isCurrent: true })
.andWhere("permission.key IN (:...permissionKeys)", { permissionKeys })
.select("DISTINCT employee.user_id", "userId")
.getRawMany();
return rows
.map((r) => r.userId)
.filter((id): id is string => Boolean(id));
const rows: { userId: string }[] = await this.dataSource.query(
`WITH target AS (SELECT id FROM iam.permissions WHERE key = ANY($1))
-- 1. IAM role grants (user_roles -> role_permissions).
SELECT e.user_id AS "userId"
FROM iam.employees e
JOIN iam.user_roles ur ON ur.user_id = e.user_id
JOIN iam.role_permissions rp ON rp.role_id = ur.role_id
WHERE e.is_current AND e.user_id IS NOT NULL
AND rp.permission_id IN (SELECT id FROM target)
UNION
-- 2. Direct position grants. A delegate keeps their own position AND
-- gains the one they stand in for, so both columns count.
SELECT e.user_id
FROM iam.employees e
JOIN iam.employee_positions ep
ON ep.employee_id = e.id AND ep.is_current
JOIN iam.position_permissions pp
ON pp.position_id IN (ep.position_id, ep.delegatee_position_id)
WHERE e.is_current AND e.user_id IS NOT NULL
AND pp.permission_id IN (SELECT id FROM target)
UNION
-- 3. Position TYPE grants — where admin-created positions keep theirs.
SELECT e.user_id
FROM iam.employees e
JOIN iam.employee_positions ep
ON ep.employee_id = e.id AND ep.is_current
JOIN iam.positions p
ON p.id IN (ep.position_id, ep.delegatee_position_id)
JOIN iam.position_type_permissions ptp
ON ptp.position_type_id = p.position_type_id
WHERE e.is_current AND e.user_id IS NOT NULL
AND ptp.permission_id IN (SELECT id FROM target)
UNION
-- 4. super_admin passes every freight permission check, so mirror that
-- here or admins go blind on desks nobody else has been granted yet.
SELECT e.user_id
FROM iam.employees e
JOIN iam.user_roles ur ON ur.user_id = e.user_id
JOIN iam.roles r ON r.id = ur.role_id
WHERE e.is_current AND e.user_id IS NOT NULL
AND r.key = 'super_admin'`,
[permissionKeys],
);
return rows.map((r) => r.userId);
}
async createOrganizationUser(

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

@@ -1,5 +1,6 @@
import { BookingLifecycleNotifierService } from './booking-lifecycle-notifier.service';
import type { Booking } from './entities/booking.entity';
import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
/**
* Who hears "Operations wants changes" depends on who owns the booking. A
@@ -74,3 +75,39 @@ describe('BookingLifecycleNotifierService — operation changes requested', () =
expect(inbox.notify.mock.calls[0][0].recipients).toEqual({ companyId: 'co-1' });
});
});
/**
* Staff notifications used to go to every employee in every organization. They
* now target a desk — and the two desks are disjoint: the GL presets hold no
* bookings:view and no intake keys, so intake pings would be noise they cannot
* act on. Both branches run through the same `inAppStaff` helper, which is the
* easy place to lose the distinction again.
*/
describe('BookingLifecycleNotifierService — staff desk targeting', () => {
const booking = () =>
({ id: 'b-1', reference: 'BKG-0001', companyId: 'co-1' }) as Booking;
let inbox: { notify: jest.Mock };
let service: BookingLifecycleNotifierService;
beforeEach(() => {
inbox = { notify: jest.fn().mockResolvedValue(undefined) };
service = new BookingLifecycleNotifierService(
{ directSend: jest.fn().mockResolvedValue(undefined) } as never,
inbox as never,
{ query: jest.fn().mockResolvedValue([]) } as never,
);
});
it('routes intake items to the booking desk and clearance items to the clearance desk', () => {
service.submittedToStaff(booking());
service.clearanceDocsUploadedToStaff(booking());
expect(inbox.notify.mock.calls[0][0].recipients).toEqual({
permissionKeys: [FREIGHT_PERMS.bookings.getNotification],
});
expect(inbox.notify.mock.calls[1][0].recipients).toEqual({
permissionKeys: [FREIGHT_PERMS.bookings.clearanceGetNotification],
});
});
});

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

@@ -11,6 +11,16 @@ 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';
import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
/**
* Clearance items are worked by the GL desks, which hold no bookings:view and
* no intake keys — so they take their own selector rather than the booking
* desk's. Every override using this deep-links to a clearance page.
*/
const CLEARANCE_DESK = {
permissionKeys: [FREIGHT_PERMS.bookings.clearanceGetNotification],
};
/**
* Customer + staff notifications for the booking lifecycle: review, clearance
@@ -89,7 +99,11 @@ export class BookingLifecycleNotifierService {
});
}
/** Persist + push an in-app item to every backoffice staff user. */
/**
* Persist + push an in-app item to the booking desk — staff holding
* `bookings:get_notification`. Callers whose item belongs to a different desk
* override `recipients` (see {@link CLEARANCE_DESK}).
*/
private inAppStaff(
b: Booking,
title: string,
@@ -97,7 +111,7 @@ export class BookingLifecycleNotifierService {
overrides: Partial<NotifyInput> = {},
): void {
void this.inbox.notify({
recipients: { allBackoffice: true },
recipients: { permissionKeys: [FREIGHT_PERMS.bookings.getNotification] },
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.REQUEST_SUBMITTED,
title,
@@ -274,6 +288,7 @@ export class BookingLifecycleNotifierService {
`the customs declaration can be filed.${note ? ` Note: "${note}"` : ''}`;
this.logger.log(`TRANSIT ASSIGNEE REQUESTED — ${this.ref(b)}`);
this.inAppStaff(b, `Transit assignee needed — ${b.reference}`, msg, {
recipients: CLEARANCE_DESK,
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/gl-djibouti/clearance/${b.id}`,
});
@@ -288,6 +303,7 @@ export class BookingLifecycleNotifierService {
`The customs declaration can now be filed.`;
this.logger.log(`TRANSIT ASSIGNEE ASSIGNED — ${this.ref(b)}`);
this.inAppStaff(b, `Transit assignee set — ${b.reference}`, msg, {
recipients: CLEARANCE_DESK,
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/bookings/${b.id}/clearance`,
});
@@ -395,6 +411,7 @@ export class BookingLifecycleNotifierService {
'Clearance documents uploaded',
`Customer uploaded clearance documents for booking ${this.ref(b)} — review them in the clearance queue.`,
{
recipients: CLEARANCE_DESK,
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/bookings/${b.id}/clearance`,
},
@@ -422,6 +439,7 @@ export class BookingLifecycleNotifierService {
`The customer requested a change to the draft declaration on booking ${this.ref(b)}: ` +
`"${note}". Send a corrected draft from the clearance page.`;
this.inAppStaff(b, `Draft declaration change requested — ${this.ref(b)}`, msg, {
recipients: CLEARANCE_DESK,
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/bookings/${b.id}/clearance`,
});
@@ -440,6 +458,7 @@ export class BookingLifecycleNotifierService {
'Payment slip uploaded',
`Customer uploaded the ${label} payment slip for booking ${this.ref(b)}.`,
{
recipients: CLEARANCE_DESK,
type: NotificationType.PAYMENT_RECEIVED,
link: `/dashboard/bookings/${b.id}/clearance`,
},

6
apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts
View File

@@ -1112,12 +1112,14 @@ export class BookingWagonCancellationService {
private notifyStaff(booking: Booking, title: string, body: string): void {
void this.inbox.notify({
recipients: { allBackoffice: true },
recipients: { permissionKeys: [FREIGHT_PERMS.bookings.getNotification] },
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.BOOKING_STATUS,
title,
body,
link: `/bookings/${booking.id}`,
// The portal path `/bookings/:id` used to be sent here, which 404s in the
// dashboard. The staff view of these lives on the queue page.
link: '/dashboard/wagon-cancellations',
data: { bookingId: booking.id, reference: booking.reference },
});
}

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

@@ -11,6 +11,7 @@ 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";
import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
/** Account statuses that lock the customer out and therefore must be told to them. */
const PUNITIVE_STATUSES: readonly CompanyStatus[] = [
@@ -175,12 +176,9 @@ export class CompanyNotifierService {
// ── Backoffice-facing: work has arrived back in the review queue ────────────
/**
* Persist + push an in-app item to every backoffice staff user, deep-linked to
* the customer's detail page.
*
* The recipient resolver has no role/permission targeting (see
* `notification-recipients.service.ts`) — `allBackoffice` is the narrowest
* selector available, so marketing is reached by notifying all staff.
* Persist + push an in-app item to the customer desk — staff holding
* `customers:get_notification` — deep-linked to the customer's detail page,
* which is itself gated on `customers:view`.
*/
private notifyStaff(
company: Company,
@@ -189,7 +187,7 @@ export class CompanyNotifierService {
data: Record<string, unknown> = {},
): void {
void this.inbox.notify({
recipients: { allBackoffice: true },
recipients: { permissionKeys: [FREIGHT_PERMS.customers.getNotification] },
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.REQUEST_SUBMITTED,
title,

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

@@ -1,5 +1,6 @@
import { ContractExpiryService } from './contract-expiry.service';
import type { Contract } from './entities/contract.entity';
import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
/**
* The reminder must warn each customer once, ten days out, and must never let a
@@ -60,4 +61,18 @@ describe('ContractExpiryService — expiry reminder', () => {
inbox.notify.mockRejectedValue(new Error('inbox down'));
await expect(service.remindExpiringContracts()).resolves.toBeUndefined();
});
// The sweep-failure alert is staff-facing. It used to go to every employee;
// it belongs to the people who would notice expired contracts still listed
// as active, i.e. the contract desk.
it('alerts the contract desk when the sweep itself fails', async () => {
repo.expireLapsedContracts.mockRejectedValue(new Error('deadlock'));
await service.expireLapsedContracts();
expect(inbox.notify).toHaveBeenCalledTimes(1);
expect(inbox.notify.mock.calls[0][0].recipients).toEqual({
permissionKeys: [FREIGHT_PERMS.contracts.getNotification],
});
});
});

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

@@ -4,6 +4,7 @@ import { NotificationAudience, NotificationType } from '@edr/types';
import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
import { ContractsRepository } from './contracts.repository';
import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
/**
* How many days before a contract lapses the customer is reminded. Mirrored by
@@ -79,7 +80,11 @@ export class ContractExpiryService {
);
try {
await this.inbox.notify({
recipients: { allBackoffice: true },
// The people who would notice expired contracts still listed as
// active are the ones working the contract desk.
recipients: {
permissionKeys: [FREIGHT_PERMS.contracts.getNotification],
},
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.GENERIC,
title: 'Contract expiry sweep failed',

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

@@ -11,6 +11,16 @@ 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';
import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
/**
* Clearance items are worked by the GL desks, which hold no intake keys — so
* they take their own selector rather than the contract desk's. Every override
* using this deep-links to a clearance or shipment-request page.
*/
const CLEARANCE_DESK = {
permissionKeys: [FREIGHT_PERMS.contracts.clearanceGetNotification],
};
/**
* Customer + staff notifications for the contract lifecycle. Every customer
@@ -86,7 +96,11 @@ export class ContractNotifierService {
});
}
/** Persist + push an in-app item to every backoffice staff user. */
/**
* Persist + push an in-app item to the contract desk — staff holding
* `contracts:get_notification`. Callers whose item belongs to a different
* desk override `recipients` (see {@link CLEARANCE_DESK}).
*/
private inAppStaff(
c: Contract,
title: string,
@@ -94,7 +108,7 @@ export class ContractNotifierService {
overrides: Partial<NotifyInput> = {},
): void {
void this.inbox.notify({
recipients: { allBackoffice: true },
recipients: { permissionKeys: [FREIGHT_PERMS.contracts.getNotification] },
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.REQUEST_SUBMITTED,
title,
@@ -230,6 +244,7 @@ export class ContractNotifierService {
`the customs declaration can be filed.${note ? ` Note: "${note}"` : ''}`;
this.logger.log(`TRANSIT ASSIGNEE REQUESTED — ${c.reference}`);
this.inAppStaff(c, `Transit assignee needed — ${c.reference}`, msg, {
recipients: CLEARANCE_DESK,
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/gl-djibouti/clearance/${c.id}`,
});
@@ -248,6 +263,7 @@ export class ContractNotifierService {
`The customs declaration can now be filed.`;
this.logger.log(`TRANSIT ASSIGNEE ASSIGNED — ${c.reference}`);
this.inAppStaff(c, `Transit assignee set — ${c.reference}`, msg, {
recipients: CLEARANCE_DESK,
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/contracts/clearance/${c.id}`,
});
@@ -264,6 +280,7 @@ export class ContractNotifierService {
`"${note}". Review and re-advise the amount on the clearance page.`;
this.logger.log(`DUTY DISPUTED — ${c.reference}`);
this.inAppStaff(c, `Duty disputed on ${c.reference}`, msg, {
recipients: CLEARANCE_DESK,
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/contracts/clearance/${c.id}`,
});
@@ -321,6 +338,7 @@ export class ContractNotifierService {
'Clearance documents uploaded',
`Customer uploaded clearance documents for contract ${this.ref(c)} — review them in the clearance queue.`,
{
recipients: CLEARANCE_DESK,
type: NotificationType.CLEARANCE_REVIEW,
link: `/dashboard/contracts/clearance/${c.id}`,
},
@@ -334,6 +352,7 @@ export class ContractNotifierService {
'Duty slip uploaded',
`Customer uploaded the duty & tax payment slip for contract ${this.ref(c)}.`,
{
recipients: CLEARANCE_DESK,
type: NotificationType.PAYMENT_RECEIVED,
link: `/dashboard/contracts/clearance/${c.id}`,
},
@@ -347,6 +366,9 @@ export class ContractNotifierService {
'New shipment request',
`Shipment request ${requestRef} was filed under contract ${this.ref(c)} and awaits GL review.`,
{
// GL reviews these, and the shipment-requests page is gated on
// contracts:create_booking — a key only the GL Ethiopia preset holds.
recipients: CLEARANCE_DESK,
link: `/dashboard/shipment-requests/${requestId}`,
data: { contractId: c.id, requestId, reference: requestRef },
},

5
apps/edr-freight-api/src/modules/maintenance/maintenance-due-alert.spec.ts
View File

@@ -1,6 +1,7 @@
import { NotificationAudience } from '@edr/types';
import { MaintenanceService } from './maintenance.service';
import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
/**
* The daily due-alert: a SCHEDULED item that crossed its km or date threshold
@@ -37,6 +38,10 @@ describe('MaintenanceService.sendDueAlerts', () => {
expect(notify).toHaveBeenCalledWith(
expect.objectContaining({
audience: NotificationAudience.BACKOFFICE,
// The fleet desk, not every employee in the company.
recipients: {
permissionKeys: [FREIGHT_PERMS.maintenance.getNotification],
},
title: 'Maintenance due — ET-9875',
body: expect.stringContaining('driven 50200 km (due at 50000 km)'),
}),

5
apps/edr-freight-api/src/modules/maintenance/maintenance.service.ts
View File

@@ -15,6 +15,7 @@ import {
UpsertMaintenanceIntervalDto,
} from './dto/create-maintenance.dto';
import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
@Injectable()
export class MaintenanceService {
@@ -53,7 +54,9 @@ export class MaintenanceService {
? `driven ${item.currentKm} km (due at ${item.nextDueKm} km)`
: `due ${new Date(item.nextDueDate as Date).toLocaleDateString()}`;
await this.inbox.notify({
recipients: { allBackoffice: true },
recipients: {
permissionKeys: [FREIGHT_PERMS.maintenance.getNotification],
},
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.GENERIC,
title: `Maintenance due — ${item.plateNumber}`,

16
apps/edr-freight-api/src/modules/notification-inbox/notification-recipients.service.ts
View File

@@ -14,7 +14,9 @@ import { ExternalProfileRepository } from "../companies/external-profile.reposit
* - `companyProfileId` → resolved to its company, then to that company's users.
* - `organizationId` → all current employees of the org (backoffice staff).
* - `permissionKeys` → current employees (any org) holding any of these
* permission keys (e.g. department/role-scoped targeting).
* permission keys — how every staff-facing notification is targeted. There is
* deliberately no "all backoffice" selector: staff notifications belong to a
* desk, and the `<module>:get_notification` keys name which one.
*/
@Injectable()
export class NotificationRecipientsService {
@@ -69,18 +71,6 @@ export class NotificationRecipientsService {
}
}
if (recipients.allBackoffice) {
try {
for (const uid of await this.backoffice.getAllCurrentEmployeeUserIds()) {
ids.add(uid);
}
} catch (err) {
this.logger.warn(
`Failed to resolve allBackoffice recipients: ${(err as Error).message}`,
);
}
}
if (recipients.permissionKeys?.length) {
try {
for (const uid of await this.backoffice.getEmployeeUserIdsByPermission(

5
apps/edr-freight-api/src/modules/rule-engine/services/priority-rule-change-requests.service.ts
View File

@@ -22,6 +22,7 @@ import {
PriorityRuleChangeStatus,
} from '../entities/priority-rule-change-request.entity';
import { PriorityConfigsService } from './priority-configs.service';
import { FREIGHT_PERMS } from '../../../seed/freight-permissions.registry';
/** Backoffice rule-engine page — where both queue and rules live. */
const RULES_LINK = '/dashboard/rules/priority-configs';
@@ -221,7 +222,9 @@ export class PriorityRuleChangeRequestsService {
): void {
void this.inbox
.notify({
recipients: { allBackoffice: true },
recipients: {
permissionKeys: [FREIGHT_PERMS.ruleEngine.getNotification],
},
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.REQUEST_SUBMITTED,
title,

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

@@ -19,6 +19,7 @@ import {
} from '../entities/rate-change-request.entity';
import { Rate } from '../entities/rate.entity';
import { RatesService } from './rates.service';
import { FREIGHT_PERMS } from '../../../seed/freight-permissions.registry';
/** Backoffice page where both the queue and the rates live. */
const RATES_LINK = '/dashboard/rules/rates';
@@ -234,7 +235,9 @@ export class RateChangeRequestsService {
private notifyTeam(title: string, body: string, request: RateChangeRequest): void {
void this.inbox
.notify({
recipients: { allBackoffice: true },
recipients: {
permissionKeys: [FREIGHT_PERMS.ruleEngine.getNotification],
},
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.REQUEST_SUBMITTED,
title,

7
apps/edr-freight-api/src/modules/warehouses/warehouse-fee.service.ts
View File

@@ -8,6 +8,7 @@ import { NotificationInboxService } from '../notification-inbox/notification-inb
import { CreateFeeRuleDto, UpdateFeeRuleDto } from './dto/fee-rule.dto';
import { FeeRuleBasis, FeeRuleType, WarehouseFeeRule, WarehouseFeeTier } from './entities/warehouse-fee-rule.entity';
import { WarehouseFeeRuleRepository } from './warehouse-fee-rule.repository';
import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
interface ItemAttributes {
arrivedAt: Date | null;
@@ -178,7 +179,11 @@ export class WarehouseFeeService {
const total = alerts.reduce((sum, r) => sum + r.accruedAmount, 0);
try {
await this.inbox.notify({
recipients: { allBackoffice: true },
recipients: {
permissionKeys: [
FREIGHT_PERMS.warehouseFeeInvoices.getNotification,
],
},
audience: NotificationAudience.BACKOFFICE,
type: NotificationType.BOOKING_STATUS,
title: 'Warehouse fee accruals need attention',

103
apps/edr-freight-api/src/seed/freight-notification-permissions.seeder.ts Normal file
View File

@@ -0,0 +1,103 @@
import { Injectable, Logger } from '@nestjs/common';
import { Application, Permission } from '@tria-plc/iamapi-common';
import { DataSource } from 'typeorm';
import {
NOTIFICATION_PERMISSIONS,
NOTIFICATION_PERMISSION_ANCHORS,
} from './freight-permissions.registry';
const EDR_FREIGHT_APP_KEY = 'edr_freight_app';
/**
* The three tables a permission grant can arrive on, with the column naming
* the grantee. These are compile-time constants — the only values interpolated
* into the SQL below.
*/
const CARRIERS = [
['iam.position_permissions', 'position_id'],
['iam.position_type_permissions', 'position_type_id'],
['iam.role_permissions', 'role_id'],
] as const;
/**
* Backfills the `<module>:get_notification` keys.
*
* Those keys are new, so on deploy nobody holds them and every staff
* notification would resolve to zero recipients — silently, because
* `NotificationInboxService.notify` logs an empty resolve at debug level. This
* grants each new key to whoever already holds that desk's anchor key (the
* permission gating the page the notification links to), across all three
* carriers.
*
* Deliberately NOT gated behind SEED_EDR_ORG: that flag is off everywhere
* except e2e/integration, and this has to run wherever the notifications do.
* For the same reason it inserts the permission rows itself rather than
* trusting EdrOrgSeeder. Idempotent — safe on every boot, and safe to leave in
* place permanently.
*/
@Injectable()
export class FreightNotificationPermissionsSeeder {
private readonly logger = new Logger(FreightNotificationPermissionsSeeder.name);
constructor(private readonly dataSource: DataSource) {}
async run(): Promise<void> {
const application = await this.dataSource
.getRepository(Application)
.findOne({ where: { key: EDR_FREIGHT_APP_KEY }, select: { id: true } });
if (!application?.id) {
this.logger.warn(
`Application '${EDR_FREIGHT_APP_KEY}' not found — notification permission backfill skipped`,
);
return;
}
// Ids are left to the column default and never sent: iam.permissions has
// two unique columns (PK id, UQ key) and ON CONFLICT can only target one,
// so a hand-minted id that some retired key already owns would slip past
// ON CONFLICT (key) and die on the PK. Same reasoning as EdrOrgSeeder.
await this.dataSource
.getRepository(Permission)
.createQueryBuilder()
.insert()
.values(
NOTIFICATION_PERMISSIONS.map((permission) => ({
key: permission.key,
name: { ...permission.name },
applicationId: application.id as string,
})),
)
.orIgnore()
.execute();
let granted = 0;
for (const [key, anchors] of Object.entries(
NOTIFICATION_PERMISSION_ANCHORS,
)) {
for (const [table, granteeColumn] of CARRIERS) {
const result: unknown = await this.dataSource.query(
`INSERT INTO ${table} (${granteeColumn}, permission_id)
SELECT DISTINCT g.${granteeColumn}, target.id
FROM ${table} g
JOIN iam.permissions anchor
ON anchor.id = g.permission_id AND anchor.key = ANY($1)
JOIN iam.permissions target ON target.key = $2
WHERE NOT EXISTS (
SELECT 1
FROM ${table} existing
WHERE existing.${granteeColumn} = g.${granteeColumn}
AND existing.permission_id = target.id)`,
[anchors, key],
);
// node-postgres returns [rows, rowCount] for a bare INSERT.
granted += (Array.isArray(result) ? (result[1] as number) : 0) ?? 0;
}
}
this.logger.log(
`Ensured ${NOTIFICATION_PERMISSIONS.length} notification permissions, backfilled ${granted} grant(s)`,
);
}
}

39
apps/edr-freight-api/src/seed/freight-permissions.registry.spec.ts
View File

@@ -1,5 +1,9 @@
import { EDR_FREIGHT_PERMISSIONS } from './edr-freight.seed';
import { readTwinOf } from './freight-permissions.registry';
import {
NOTIFICATION_PERMISSIONS,
NOTIFICATION_PERMISSION_ANCHORS,
readTwinOf,
} from './freight-permissions.registry';
describe('EDR_FREIGHT_PERMISSIONS', () => {
// The seeder inserts the whole catalog in one ON CONFLICT (key) DO UPDATE
@@ -48,3 +52,36 @@ describe('EDR_FREIGHT_PERMISSIONS', () => {
}
});
});
describe('NOTIFICATION_PERMISSION_ANCHORS', () => {
const catalog = new Set(EDR_FREIGHT_PERMISSIONS.map((p) => p.key));
// FreightNotificationPermissionsSeeder backfills each get_notification key
// onto whoever holds its anchor. A typo'd anchor matches no permission row,
// so the key is granted to nobody and every notification on that desk
// silently resolves to zero recipients — notify() logs that at debug level.
it('anchors every notification key on keys that exist', () => {
const missing = Object.values(NOTIFICATION_PERMISSION_ANCHORS)
.flat()
.filter((key) => !catalog.has(key));
expect(missing).toEqual([]);
});
it('seeds every notification key into the catalog', () => {
const missing = NOTIFICATION_PERMISSIONS.map((p) => p.key).filter(
(key) => !catalog.has(key),
);
expect(missing).toEqual([]);
});
it('gives every notification key an anchor to backfill from', () => {
const anchored = new Set(Object.keys(NOTIFICATION_PERMISSION_ANCHORS));
const unanchored = NOTIFICATION_PERMISSIONS.map((p) => p.key).filter(
(key) => !anchored.has(key),
);
expect(unanchored).toEqual([]);
});
});

128
apps/edr-freight-api/src/seed/freight-permissions.registry.ts
View File

@@ -1335,6 +1335,54 @@ export const AUDIENCE_GAP_PERMISSIONS: FreightPermissionSeed[] = [
),
];
// O. Notification recipient selectors. NOT route guards — these are never
// passed to FreightPermissionGuard/assertFreightPermission and never appear in
// the frontend's RequirePermission. They exist so ops can tune who gets pinged
// WITHOUT changing who can open the page. Before them every staff notification
// used the `allBackoffice` selector, i.e. every current employee in every org.
export const NOTIFICATION_PERMISSIONS: FreightPermissionSeed[] = [
perm(
"f3a00001-0001-4000-8000-000000000001",
"edr_freight_app:bookings:get_notification",
"Receive booking desk notifications",
),
perm(
"f3a00001-0001-4000-8000-000000000002",
"edr_freight_app:bookings:clearance_get_notification",
"Receive booking clearance notifications",
),
perm(
"f3a00001-0001-4000-8000-000000000003",
"edr_freight_app:contracts:get_notification",
"Receive contract desk notifications",
),
perm(
"f3a00001-0001-4000-8000-000000000004",
"edr_freight_app:contracts:clearance_get_notification",
"Receive contract clearance notifications",
),
perm(
"f3a00001-0001-4000-8000-000000000005",
"edr_freight_app:customers:get_notification",
"Receive customer desk notifications",
),
perm(
"f3a00001-0001-4000-8000-000000000006",
"edr_freight_app:maintenance:get_notification",
"Receive maintenance due notifications",
),
perm(
"f3a00001-0001-4000-8000-000000000007",
"edr_freight_app:rule_engine:get_notification",
"Receive rule-change approval notifications",
),
perm(
"f3a00001-0001-4000-8000-000000000008",
"edr_freight_app:warehouse_fee_invoices:get_notification",
"Receive warehouse fee accrual notifications",
),
];
export const ADVANCED_BACKOFFICE_PERMISSIONS: FreightPermissionSeed[] = [
...CUSTOMER_PERMISSIONS,
...FINANCE_PERMISSIONS,
@@ -1348,6 +1396,7 @@ export const ADVANCED_BACKOFFICE_PERMISSIONS: FreightPermissionSeed[] = [
...STAFF_IAM_PERMISSIONS,
...AUDIENCE_GAP_PERMISSIONS,
...GRANULAR_SPLIT_PERMISSIONS,
...NOTIFICATION_PERMISSIONS,
];
export const BOOKING_RULE_ENGINE_PERMISSIONS = [
@@ -1439,6 +1488,10 @@ export const FREIGHT_PERMS = {
wagonCancellationVoid: "edr_freight_app:bookings:wagon_cancellation_void",
wagonCancellationRebook:
"edr_freight_app:bookings:wagon_cancellation_rebook",
// Notification selectors, not route guards — see NOTIFICATION_PERMISSIONS.
getNotification: "edr_freight_app:bookings:get_notification",
clearanceGetNotification:
"edr_freight_app:bookings:clearance_get_notification",
},
contracts: {
view: "edr_freight_app:contracts:view",
@@ -1475,6 +1528,10 @@ export const FREIGHT_PERMS = {
editDocument: "edr_freight_app:contracts:edit_document",
finalInvoiceRaise: "edr_freight_app:contracts:final_invoice_raise",
finalInvoiceConfirm: "edr_freight_app:contracts:final_invoice_confirm",
// Notification selectors, not route guards — see NOTIFICATION_PERMISSIONS.
getNotification: "edr_freight_app:contracts:get_notification",
clearanceGetNotification:
"edr_freight_app:contracts:clearance_get_notification",
},
trainScheduling: {
view: "edr_freight_app:train_scheduling:view",
@@ -1503,6 +1560,10 @@ export const FREIGHT_PERMS = {
`edr_freight_app:rule_engine:${slugToResourceKey(slug)}:delete`,
approve: (slug: RuleEngineApprovableSlug) =>
`edr_freight_app:rule_engine:${slugToResourceKey(slug)}:approve`,
// Notification selector, not a route guard — see NOTIFICATION_PERMISSIONS.
// One key for the whole rules desk: every preset grants the rule-engine
// view keys as a block, and both producers link to /dashboard/rules/*.
getNotification: "edr_freight_app:rule_engine:get_notification",
},
allocation: {
manage: "edr_freight_app:allocation:manage",
@@ -1514,6 +1575,8 @@ export const FREIGHT_PERMS = {
deactivate: "edr_freight_app:customers:deactivate",
verify: "edr_freight_app:customers:verify",
resetPassword: "edr_freight_app:customers:reset-password",
// Notification selector, not a route guard — see NOTIFICATION_PERMISSIONS.
getNotification: "edr_freight_app:customers:get_notification",
},
payments: {
view: "edr_freight_app:payments:view",
@@ -1637,6 +1700,8 @@ export const FREIGHT_PERMS = {
create: "edr_freight_app:maintenance:create",
update: "edr_freight_app:maintenance:update",
delete: "edr_freight_app:maintenance:delete",
// Notification selector, not a route guard — see NOTIFICATION_PERMISSIONS.
getNotification: "edr_freight_app:maintenance:get_notification",
},
fleetReports: {
view: "edr_freight_app:fleet_reports:view",
@@ -1706,6 +1771,8 @@ export const FREIGHT_PERMS = {
generate: "edr_freight_app:warehouse_fee_invoices:generate",
cancel: "edr_freight_app:warehouse_fee_invoices:cancel",
pay: "edr_freight_app:warehouse_fee_invoices:pay",
// Notification selector, not a route guard — see NOTIFICATION_PERMISSIONS.
getNotification: "edr_freight_app:warehouse_fee_invoices:get_notification",
},
settings: {
fileUpload: {
@@ -1810,6 +1877,40 @@ export const FREIGHT_PERMS = {
},
} as const;
/**
* Backfill sources for the `<module>:get_notification` keys: a new key is
* granted to whoever already holds ANY of its anchors. The anchor is the key
* that gates the page the notification deep-links to — if you cannot open the
* page, you were never the intended recipient. The rule-engine desk has no page
* of its own, so it anchors on the keys that let you ACT on a filed change.
*
* Consumed only by FreightNotificationPermissionsSeeder. Keeping it here means
* the registry spec can assert every anchor still exists in the catalog — a
* typo'd anchor backfills nobody, silently.
*/
export const NOTIFICATION_PERMISSION_ANCHORS: Record<string, string[]> = {
[FREIGHT_PERMS.bookings.getNotification]: [FREIGHT_PERMS.bookings.view],
[FREIGHT_PERMS.bookings.clearanceGetNotification]: [
FREIGHT_PERMS.bookings.clearanceView,
],
[FREIGHT_PERMS.contracts.getNotification]: [FREIGHT_PERMS.contracts.view],
[FREIGHT_PERMS.contracts.clearanceGetNotification]: [
FREIGHT_PERMS.contracts.clearanceReview,
FREIGHT_PERMS.contracts.clearanceEtActions,
FREIGHT_PERMS.contracts.clearanceDjActions,
FREIGHT_PERMS.contracts.opsClearanceReview,
],
[FREIGHT_PERMS.customers.getNotification]: [FREIGHT_PERMS.customers.view],
[FREIGHT_PERMS.maintenance.getNotification]: [FREIGHT_PERMS.maintenance.view],
[FREIGHT_PERMS.ruleEngine.getNotification]: [
FREIGHT_PERMS.ruleEngine.approve("rates"),
FREIGHT_PERMS.ruleEngine.update("priority-configs"),
],
[FREIGHT_PERMS.warehouseFeeInvoices.getNotification]: [
FREIGHT_PERMS.warehouseFeeInvoices.view,
],
};
/** Both arms of a freight-type-split permission (for one-of route guards). */
export const bothFreightTypes = (p: {
bulk: string;
@@ -1867,6 +1968,19 @@ const STAFF_DASHBOARD_KEYS: string[] = [
FREIGHT_PERMS.reports.view,
];
// Notification desks — recipient selectors, not access. A preset gets a desk
// key only where it actually works that queue, which is why the GL presets take
// the clearance pair and nothing else: they hold no bookings:view and no intake
// keys, so intake pings would only be noise they cannot act on.
const BOOKING_DESK_NOTIFICATION_KEYS: string[] = [
FREIGHT_PERMS.bookings.getNotification,
FREIGHT_PERMS.contracts.getNotification,
];
const CLEARANCE_DESK_NOTIFICATION_KEYS: string[] = [
FREIGHT_PERMS.bookings.clearanceGetNotification,
FREIGHT_PERMS.contracts.clearanceGetNotification,
];
export const ROLE_PERMISSION_PRESETS = {
// Marketing / line staff: drives a booking from intake through line-staff
// approval and contract generation/signing — i.e. until the contract is ready
@@ -1889,6 +2003,8 @@ export const ROLE_PERMISSION_PRESETS = {
FREIGHT_PERMS.contracts.approveLineStaff,
FREIGHT_PERMS.contracts.editDocument,
...allRuleEngineViewKeys(),
...BOOKING_DESK_NOTIFICATION_KEYS,
FREIGHT_PERMS.ruleEngine.getNotification,
],
// Operations Officer: train scheduling + wagon allocation + transit/complete
// + fleet management (wagons, trains, locomotives, routes, containers, cargo).
@@ -1921,6 +2037,11 @@ export const ROLE_PERMISSION_PRESETS = {
FREIGHT_PERMS.bookings.reviewDocuments,
FREIGHT_PERMS.bookings.finalizeClearance,
...allRuleEngineViewKeys(),
...BOOKING_DESK_NOTIFICATION_KEYS,
// They run Path A clearance review from the booking detail, so the booking
// clearance desk is theirs too — but not the contract one, which is GL's.
FREIGHT_PERMS.bookings.clearanceGetNotification,
FREIGHT_PERMS.ruleEngine.getNotification,
],
director: [
...STAFF_DASHBOARD_KEYS,
@@ -1932,6 +2053,7 @@ export const ROLE_PERMISSION_PRESETS = {
FREIGHT_PERMS.contracts.approveDirector,
FREIGHT_PERMS.contracts.generateContract,
...allRuleEngineViewKeys(),
...BOOKING_DESK_NOTIFICATION_KEYS,
],
ceo: [
...STAFF_DASHBOARD_KEYS,
@@ -1941,6 +2063,7 @@ export const ROLE_PERMISSION_PRESETS = {
FREIGHT_PERMS.contracts.view,
FREIGHT_PERMS.contracts.approveCeo,
...allRuleEngineViewKeys(),
...BOOKING_DESK_NOTIFICATION_KEYS,
],
finance: [
...STAFF_DASHBOARD_KEYS,
@@ -1972,6 +2095,7 @@ export const ROLE_PERMISSION_PRESETS = {
FREIGHT_PERMS.bookings.uploadClearanceOutput,
FREIGHT_PERMS.bookings.finalizeClearance,
FREIGHT_PERMS.bookings.operations,
...CLEARANCE_DESK_NOTIFICATION_KEYS,
],
// GL Djibouti (edr_gl_djibouti): DO/RO collection, gatepass, loading milestones,
// damage reports. Read-only on the contract; no booking creation.
@@ -1983,6 +2107,7 @@ export const ROLE_PERMISSION_PRESETS = {
FREIGHT_PERMS.bookings.clearanceView,
FREIGHT_PERMS.bookings.uploadClearanceOutput,
FREIGHT_PERMS.bookings.operations,
...CLEARANCE_DESK_NOTIFICATION_KEYS,
],
// Marketing handles intake through contract (same as line staff here) and,
// for non-customs bookings, reviews/finalizes the customer's clearance
@@ -2012,6 +2137,7 @@ export const ROLE_PERMISSION_PRESETS = {
...bothFreightTypes(FREIGHT_PERMS.contracts.signStaff),
FREIGHT_PERMS.contracts.suspend,
FREIGHT_PERMS.contracts.editDocument,
...BOOKING_DESK_NOTIFICATION_KEYS,
],
orgManager: [...BOOKING_RULE_ENGINE_PERMISSION_KEYS],
} as const;
@@ -2038,6 +2164,8 @@ export const POSITION_PERMISSION_PRESETS = {
FREIGHT_PERMS.customers.view,
FREIGHT_PERMS.customers.verify,
FREIGHT_PERMS.customers.deactivate,
// …and therefore the profile-review pings company-notifier emits.
FREIGHT_PERMS.customers.getNotification,
// The chief also owns the customer-facing support inbox.
FREIGHT_PERMS.support.agentView,
FREIGHT_PERMS.support.agentSend,

13
packages/types/src/freight/notifications.ts
View File

@@ -90,13 +90,16 @@ export interface NotificationRecipients {
companyProfileId?: string;
/** Backoffice: all current employees of this organization. */
organizationId?: string;
/** Backoffice: every current employee across all organizations. */
allBackoffice?: boolean;
/**
* Backoffice: current employees (any org) who hold ANY of these permission
* keys — e.g. notify only marketing, not every employee. Super/org admins
* are not implicitly included; add `allBackoffice`/explicit userIds too if
* admins should also see it.
* keys. Resolution mirrors the request-time guard `hasFreightPermission` —
* IAM role grants, direct position grants, position TYPE grants, delegated
* positions, and the `super_admin` bypass. `organization_admin` is NOT
* implicitly included (it only bypasses approval steps, not permission
* checks); grant it a key explicitly if it should be notified.
*
* Prefer the dedicated `<module>:get_notification` keys over reusing a domain
* key: they let ops tune who gets pinged without touching who has access.
*/
permissionKeys?: string[];
}