feat(warehouses): map GRN numbers to the goods owner

GRN-<DIR>-<DATE>-<REF8> carried no owner, so a note couldn't be
identified by who owns the cargo. Add an owner segment sourced from the
booking's company at every generation point (import, export, facility,
manual receive), keep REF8 for uniqueness, and label the GRN document
row Owner's Name.

apps/edr-freight-api/src/common/grn.util.spec.ts

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

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

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