feat(eims): surface filing state in backoffice and alert on failures

Two gaps that only bite in production: nobody could see an invoice's filing
state, and a blocked chain was visible only in the logs.

A failed filing now notifies the staff who can act on it. An ambiguous result
is HIGH priority because it blocks every further invoice for the system number
until someone resolves it, and nothing else would surface that -- the sweep
just goes quiet. A deterministic rejection affects one invoice, so it is
normal priority. The alert never throws: it must not mask the filing outcome.

The backoffice invoice detail page gains an EIMS card showing status, IRN,
counter, submitted and acknowledged timestamps, and the gateway's own error
message, with actions gated on invoices:eims_register. FAILED offers "File
again" -- the reservation model already allows re-registering a rejected
invoice, so retry needed no new endpoint. UNKNOWN offers no re-file button at
all, since resubmitting risks a duplicate registration, and instead explains
that a supervisor must record the IRN or discard the attempt.

Also aligns the migration class name with its renamed file. The DDL is
idempotent, so re-applying under the new name is a no-op against the columns;
it leaves one superseded row in freight.migrations.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.spec.ts

@@ -6,6 +6,7 @@ import { EimsConfig } from "../../config/eims.config";
 import { Invoice } from "../billing/entities/invoice.entity";
 import { EimsInvoiceRequest } from "../billing/eims-invoice.mapper";
 import { eimsInvoiceConfig } from "./eims-test-fixtures";
+import { NotificationInboxService } from "../notification-inbox/notification-inbox.service";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsClientService } from "./eims-client.service";
 import { EimsApiException } from "./eims.errors";
@@ -147,13 +148,17 @@ const build = (
   postSigned: jest.Mock,
   cfg: EimsConfig = config(),
   postBearer: jest.Mock = jest.fn(),
-  getSessionContext: jest.Mock = jest.fn().mockResolvedValue(SESSION),
+  getSessionContext: jest.Mock | undefined = undefined,
+  notify: jest.Mock = jest.fn().mockResolvedValue(undefined),
 ) =>
   new EimsInvoiceRegistrationService(
     db.asDataSource(),
     { get: () => cfg } as unknown as ConfigService,
     { postSigned, postBearer } as unknown as EimsClientService,
-    { getSessionContext } as unknown as EimsAuthService,
+    {
+      getSessionContext: getSessionContext ?? jest.fn().mockResolvedValue(SESSION),
+    } as unknown as EimsAuthService,
+    { notify } as unknown as NotificationInboxService,
   );
 
 /** Document number the fixtures register under; `/v1/verify` must echo it back. */
@@ -409,6 +414,64 @@ describe("EimsInvoiceRegistrationService.registerInvoiceWithEims", () => {
   });
 });
 
+describe("EimsInvoiceRegistrationService staff alerting", () => {
+  it("raises a high-priority alert when a result is ambiguous, because all filing is blocked", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const notify = jest.fn().mockResolvedValue(undefined);
+    const postSigned = jest.fn().mockRejectedValue(apiError("TIMEOUT"));
+
+    await expect(
+      build(db, postSigned, config(), jest.fn(), undefined, notify).registerInvoiceWithEims(
+        INVOICE_ID,
+      ),
+    ).rejects.toBeInstanceOf(EimsApiException);
+
+    expect(notify).toHaveBeenCalledTimes(1);
+    const sent = notify.mock.calls[0][0];
+    expect(sent.priority).toBe("HIGH");
+    expect(sent.title).toMatch(/blocked/i);
+    expect(sent.recipients.permissionKeys).toContain("edr_freight_app:invoices:eims_resolve");
+  });
+
+  it("raises a normal-priority alert for a deterministic rejection", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const notify = jest.fn().mockResolvedValue(undefined);
+    const postSigned = jest.fn().mockRejectedValue(apiError("RULE_VALIDATION", 406));
+
+    await expect(
+      build(db, postSigned, config(), jest.fn(), undefined, notify).registerInvoiceWithEims(
+        INVOICE_ID,
+      ),
+    ).rejects.toBeInstanceOf(EimsApiException);
+
+    expect(notify.mock.calls[0][0].priority).toBe("NORMAL");
+  });
+
+  it("does not alert on a successful filing", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const notify = jest.fn();
+
+    await build(db, jest.fn().mockResolvedValue(okResponse()), config(), jest.fn(), undefined, notify)
+      .registerInvoiceWithEims(INVOICE_ID);
+
+    expect(notify).not.toHaveBeenCalled();
+  });
+
+  it("lets the filing outcome stand even if the alert itself fails", async () => {
+    const db = new FakeDb([invoiceRow()]);
+    const notify = jest.fn().mockRejectedValue(new Error("inbox down"));
+    const postSigned = jest.fn().mockRejectedValue(apiError("RULE_VALIDATION", 406));
+
+    await expect(
+      build(db, postSigned, config(), jest.fn(), undefined, notify).registerInvoiceWithEims(
+        INVOICE_ID,
+      ),
+    ).rejects.toThrow(/EIMS register failed \(406\)/);
+
+    expect(db.invoices.get(INVOICE_ID)!.eimsStatus).toBe(EimsInvoiceStatus.Failed);
+  });
+});
+
 describe("EimsInvoiceRegistrationService.verifyInvoiceWithEims", () => {
   it("verifies the stored IRN over the unsigned bearer transport", async () => {
     const db = new FakeDb([invoiceRow({ eimsIrn: IRN })]);

apps/edr-freight-api/src/modules/eims/eims-invoice-registration.service.ts

@@ -17,6 +17,9 @@ import {
   EimsMapperLine,
   toEimsInvoice,
 } from "../billing/eims-invoice.mapper";
+import { NotificationAudience, NotificationPriority, NotificationType } from "@edr/types";
+import { NotificationInboxService } from "../notification-inbox/notification-inbox.service";
+import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsClientService } from "./eims-client.service";
 import { EimsApiException } from "./eims.errors";
@@ -72,6 +75,7 @@ export class EimsInvoiceRegistrationService {
     private readonly config: ConfigService,
     private readonly client: EimsClientService,
     private readonly auth: EimsAuthService,
+    private readonly inbox: NotificationInboxService,
   ) {}
 
   private get cfg(): EimsConfig {
@@ -397,6 +401,41 @@ export class EimsInvoiceRegistrationService {
     });
 
     this.logger.error(`Invoice ${invoiceId} EIMS registration ${status}: ${lastError.message}`);
+    await this.alertStaff(invoiceId, status, lastError, deterministic);
+  }
+
+  /**
+   * Tell the people who can act about a failed filing.
+   *
+   * An ambiguous result is the urgent one: it blocks *every* further invoice for this system
+   * number until a human resolves it, and nothing else in the system would surface that — the
+   * sweep just goes quiet. A deterministic rejection affects one invoice, so it is normal
+   * priority. Never throws: an alert that fails must not mask the filing outcome.
+   */
+  private async alertStaff(
+    invoiceId: string,
+    status: EimsInvoiceStatus,
+    error: EimsInvoiceError,
+    deterministic: boolean,
+  ): Promise<void> {
+    try {
+      await this.inbox.notify({
+        recipients: { permissionKeys: [FREIGHT_PERMS.invoices.eimsResolve] },
+        audience: NotificationAudience.BACKOFFICE,
+        type: NotificationType.GENERIC,
+        priority: deterministic ? NotificationPriority.NORMAL : NotificationPriority.HIGH,
+        title: deterministic
+          ? "EIMS rejected an invoice"
+          : "EIMS filing unresolved — all further filing is blocked",
+        body: deterministic
+          ? `MoR rejected the filing (${error.kind}): ${error.message}. The invoice is marked FAILED; correct it and file again.`
+          : `A submission was sent but never acknowledged (${error.kind}). Its IRN is unknown, so no further invoice can be filed until it is resolved with MoR.`,
+        link: `/dashboard/invoices/${invoiceId}`,
+        data: { invoiceId, eimsStatus: status, kind: error.kind, action: "EIMS_FILING_FAILED" },
+      });
+    } catch (err) {
+      this.logger.warn(`EIMS staff alert failed for invoice ${invoiceId}: ${(err as Error).message}`);
+    }
   }
 
   // ── internals ────────────────────────────────────────────────────────────────────────────────

apps/edr-freight-api/src/modules/eims/eims.module.ts

@@ -3,6 +3,7 @@ import { Module } from "@nestjs/common";
 import { TypeOrmModule } from "@nestjs/typeorm";
 
 import { Invoice } from "../billing/entities/invoice.entity";
+import { NotificationInboxModule } from "../notification-inbox/notification-inbox.module";
 import { EimsAuthService } from "./eims-auth.service";
 import { EimsAutoSubmitService } from "./eims-auto-submit.service";
 import { EimsClientService } from "./eims-client.service";
@@ -22,6 +23,7 @@ import { EimsSystemState } from "./entities/eims-system-state.entity";
   imports: [
     HttpModule.register({ timeout: Number(process.env.EIMS_HTTP_TIMEOUT_MS) || 30_000 }),
     TypeOrmModule.forFeature([EimsSystemState, Invoice]),
+    NotificationInboxModule,
   ],
   controllers: [EimsInvoiceController],
   providers: [