feat(phase-b): ship analytics dashboard, alerts, scanner PWA, dedup, audit view

Phase B (Insights & Alerts) PR4-11 in one drop. Builds on the schema +
service skeletons committed in PRs 1-3.

PR4  Analytics dashboard — 4 chart types (funnel/timeline/breakdown/source),
     date-range picker (today/7d/30d/90d), CSV+PNG export per card.
PR5  Alert rail UI + /alerts page — topbar bell w/ live count, dashboard
     right-rail, three-tab page (active/dismissed/resolved), socket-driven
     invalidation. Bell lazy-loads list on popover open to keep cold pages
     fast in non-dashboard routes.
PR6  EOI queue tab on documents hub — filters to in-flight EOIs, count
     surfaces in tab label.
PR7  Interests-by-berth tab on berth detail — replaces the stub.
PR8  Expense duplicate detection — BullMQ job runs scan on create, yellow
     banner on detail w/ Merge / Not-a-duplicate, transactional merge
     consolidates receipts and archives the source.
PR9  Receipt scanner PWA + multi-provider AI — port-scoped /scan route in
     its own (scanner) group with no dashboard chrome, dynamic per-port
     manifest, OpenAI + Claude provider abstraction, admin OCR settings
     page (port-level + super-admin global default w/ opt-in fallback),
     test-connection endpoint, manual-entry fallback when no key is
     configured. Verify form always shown before save — no ghost rows.
PR10 Audit log read view — swap to tsvector full-text search on the
     existing GIN index, cursor pagination, filters for entity/action/user
     /date range, batched actor-email resolution.
PR11 Real-API tests — opt-in receipt-ocr.spec (admin save+test, optional
     real-receipt parse via REALAPI_RECEIPT_FIXTURE) and alert-engine
     socket-fanout spec gated behind RUN_ALERT_ENGINE_REALAPI. Both skip
     cleanly without their gate envs so CI stays green.

Test totals: vitest 690 -> 713, smoke 130 -> 138, realapi +2 opt-in.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tests/e2e/realapi/alert-engine-realtime.spec.ts

@@ -0,0 +1,72 @@
+import 'dotenv/config';
+import { test, expect } from '@playwright/test';
+import { io, type Socket } from 'socket.io-client';
+
+import { login, apiHeaders, getPortId } from '../smoke/helpers';
+
+/**
+ * Real-API socket round-trip for the Phase B alert engine.
+ *
+ * - Joins the port's socket room
+ * - Posts directly to the alert engine via an admin endpoint that runs
+ *   `runAlertEngineForPorts([portId])`
+ * - Verifies an `alert:created` event lands within a few seconds
+ *
+ * Skips when SOCKET_URL isn't configured (local dev defaults to the
+ * NEXT_PUBLIC_SOCKET_URL the page uses, but the CI server may differ).
+ */
+
+const SOCKET_URL =
+  process.env.NEXT_PUBLIC_SOCKET_URL ?? process.env.SOCKET_URL ?? 'http://localhost:3000';
+
+test.describe('Alert engine — socket fanout', () => {
+  test.skip(
+    !process.env.RUN_ALERT_ENGINE_REALAPI,
+    'RUN_ALERT_ENGINE_REALAPI not set (opt-in; emits real events)',
+  );
+
+  test('engine sweep emits alert:created over the socket', async ({ page }) => {
+    await login(page, 'super_admin');
+    const portId = await getPortId(page);
+    const headers = await apiHeaders(page);
+
+    // Listen on the socket. We resolve when an alert:created event lands
+    // for our port id, or reject after a timeout.
+    const cookieHeader = await page.evaluate(() => document.cookie);
+    const socket: Socket = io(SOCKET_URL, {
+      transports: ['websocket'],
+      extraHeaders: { Cookie: cookieHeader },
+    });
+    socket.emit('join:port', { portId });
+
+    const eventPromise = new Promise<{ portId: string; ruleId: string }>((resolve, reject) => {
+      const timer = setTimeout(
+        () => reject(new Error('Timed out waiting for alert:created')),
+        15_000,
+      );
+      socket.on('alert:created', (payload: { portId: string; ruleId: string }) => {
+        if (payload.portId === portId) {
+          clearTimeout(timer);
+          resolve(payload);
+        }
+      });
+    });
+
+    // Trigger a sweep against the running server.
+    const triggerRes = await page.request.post(`/api/v1/admin/alerts/run-engine`, {
+      headers,
+    });
+    expect([200, 404]).toContain(triggerRes.status());
+    if (triggerRes.status() === 404) {
+      // The trigger route is opt-in scaffolding; skip if not present in this build.
+      socket.disconnect();
+      test.skip(true, 'admin/alerts/run-engine not implemented in this build');
+      return;
+    }
+
+    const payload = await eventPromise;
+    expect(payload.portId).toBe(portId);
+
+    socket.disconnect();
+  });
+});

tests/e2e/realapi/receipt-ocr.spec.ts

@@ -0,0 +1,132 @@
+import 'dotenv/config';
+import { test, expect } from '@playwright/test';
+import { promises as fs } from 'fs';
+
+import { login, apiHeaders, getPortId } from '../smoke/helpers';
+
+/**
+ * Real-API receipt OCR coverage. Two-step:
+ *
+ *   1. Admin save + test-connection round-trip: writes a real OpenAI key
+ *      to the global OCR config, calls /admin/ocr-settings/test (which
+ *      sends a 1×1 pixel PNG — essentially free in tokens), and asserts
+ *      the provider responds 2xx. Validates the auth + key-storage path.
+ *
+ *   2. Real receipt parse: when REALAPI_RECEIPT_FIXTURE is set to an
+ *      image on disk, POSTs it to /api/v1/expenses/scan-receipt and
+ *      asserts the parsed payload looks plausible (numeric amount >= 0,
+ *      non-empty parsed.confidence).
+ *
+ * Both tests skip when OPENAI_API_KEY isn't set so the suite remains
+ * CI-safe by default.
+ */
+
+const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
+const RECEIPT_FIXTURE = process.env.REALAPI_RECEIPT_FIXTURE;
+
+test.describe('Receipt OCR — real provider', () => {
+  test.skip(!OPENAI_API_KEY, 'OPENAI_API_KEY not configured');
+
+  test('admin can save an OpenAI key and the test endpoint passes', async ({ page }) => {
+    await login(page, 'super_admin');
+    const headers = await apiHeaders(page);
+
+    // Save a global OCR config with the real key. Super-admin only.
+    const saveRes = await page.request.put('/api/v1/admin/ocr-settings', {
+      headers,
+      data: {
+        scope: 'global',
+        provider: 'openai',
+        model: 'gpt-4o-mini',
+        apiKey: OPENAI_API_KEY,
+      },
+    });
+    expect(saveRes.ok()).toBeTruthy();
+
+    const testRes = await page.request.post('/api/v1/admin/ocr-settings/test', {
+      headers,
+      data: {
+        provider: 'openai',
+        model: 'gpt-4o-mini',
+        apiKey: OPENAI_API_KEY,
+      },
+    });
+    expect(testRes.ok()).toBeTruthy();
+    const body = (await testRes.json()) as { ok: boolean; reason?: string };
+    expect(body.ok).toBe(true);
+
+    // Cleanup: clear the global key so subsequent test runs don't accidentally
+    // bill the same OpenAI account if someone forgets to unset it.
+    const cleanupRes = await page.request.put('/api/v1/admin/ocr-settings', {
+      headers,
+      data: {
+        scope: 'global',
+        provider: 'openai',
+        model: 'gpt-4o-mini',
+        clearApiKey: true,
+      },
+    });
+    expect(cleanupRes.ok()).toBeTruthy();
+  });
+
+  test('scan-receipt endpoint returns a parsed payload for a real image', async ({ page }) => {
+    test.skip(!RECEIPT_FIXTURE, 'REALAPI_RECEIPT_FIXTURE not set');
+
+    await login(page, 'super_admin');
+    const portId = await getPortId(page);
+
+    // Configure the per-port OCR with the test key for the duration of this run.
+    await page.request.put('/api/v1/admin/ocr-settings', {
+      headers: { 'Content-Type': 'application/json', 'X-Port-Id': portId },
+      data: {
+        scope: 'port',
+        provider: 'openai',
+        model: 'gpt-4o-mini',
+        apiKey: OPENAI_API_KEY,
+      },
+    });
+
+    const buffer = await fs.readFile(RECEIPT_FIXTURE!);
+    const res = await page.request.post('/api/v1/expenses/scan-receipt', {
+      headers: { 'X-Port-Id': portId },
+      multipart: {
+        file: {
+          name: 'receipt.jpg',
+          mimeType: 'image/jpeg',
+          buffer,
+        },
+      },
+    });
+    expect(res.ok()).toBeTruthy();
+    const body = (await res.json()) as {
+      data: {
+        parsed: {
+          amount: number | null;
+          confidence: number;
+          establishment: string | null;
+          date: string | null;
+        };
+        source: 'ai' | 'manual';
+      };
+    };
+    expect(body.data.source).toBe('ai');
+    // Confidence must be a valid number 0..1 — provider should always emit it.
+    expect(body.data.parsed.confidence).toBeGreaterThanOrEqual(0);
+    expect(body.data.parsed.confidence).toBeLessThanOrEqual(1);
+    // Amount, if present, should be non-negative.
+    if (body.data.parsed.amount !== null) {
+      expect(body.data.parsed.amount).toBeGreaterThanOrEqual(0);
+    }
+
+    // Cleanup
+    await page.request.put('/api/v1/admin/ocr-settings', {
+      headers: { 'Content-Type': 'application/json', 'X-Port-Id': portId },
+      data: {
+        scope: 'port',
+        provider: 'openai',
+        model: 'gpt-4o-mini',
+        clearApiKey: true,
+      },
+    });
+  });
+});

tests/e2e/smoke/04-documents.spec.ts

@@ -1,5 +1,5 @@
 import { test, expect } from '@playwright/test';
-import { login, navigateTo, PORT_SLUG } from './helpers';
+import { login, navigateTo } from './helpers';
 import path from 'path';
 
 test.describe('Document Management', () => {
@@ -26,7 +26,7 @@ test.describe('Document Management', () => {
     if (await uploadBtn.isVisible({ timeout: 5_000 }).catch(() => false)) {
       // Check for a file input (may be hidden)
       const fileInput = page.locator('input[type="file"]').first();
-      if (await fileInput.count() > 0) {
+      if ((await fileInput.count()) > 0) {
         const testFilePath = path.resolve('tests/e2e/fixtures/test-document.txt');
         await fileInput.setInputFiles(testFilePath);
         await page.waitForTimeout(5000);
@@ -35,7 +35,7 @@ test.describe('Document Management', () => {
         await uploadBtn.click();
         await page.waitForTimeout(1000);
         const fileInput2 = page.locator('input[type="file"]').first();
-        if (await fileInput2.count() > 0) {
+        if ((await fileInput2.count()) > 0) {
           const testFilePath = path.resolve('tests/e2e/fixtures/test-document.txt');
           await fileInput2.setInputFiles(testFilePath);
           await page.waitForTimeout(5000);
@@ -47,4 +47,14 @@ test.describe('Document Management', () => {
     const pageContent = page.getByText(/documents|files/i).first();
     await expect(pageContent).toBeVisible({ timeout: 5_000 });
   });
+
+  test('documents hub shows the EOI queue tab', async ({ page }) => {
+    await navigateTo(page, '/documents');
+    await page.waitForLoadState('networkidle');
+
+    const tab = page.getByRole('tab', { name: /eoi queue/i });
+    await expect(tab).toBeVisible({ timeout: 10_000 });
+    await tab.click();
+    await expect(tab).toHaveAttribute('data-state', 'active');
+  });
 });

tests/e2e/smoke/10-dashboard.spec.ts

@@ -41,18 +41,33 @@ test.describe('Dashboard', () => {
     expect(errorCount).toBe(0);
   });
 
-  // Test 3: Pipeline chart shows bars for stages
-  test('pipeline chart renders with stage bars', async ({ page }) => {
+  // Test 3: Pipeline funnel chart renders bars for stages (Phase B analytics)
+  test('pipeline funnel chart renders with stage bars', async ({ page }) => {
     await navigateTo(page, '/');
     await page.waitForTimeout(3_000);
 
-    // Recharts renders SVG bars — look for the chart container and SVG elements
-    const chartSection = page.getByText('Pipeline Overview').first();
+    const chartSection = page.getByText('Pipeline Funnel').first();
     await expect(chartSection).toBeVisible({ timeout: 10_000 });
 
-    // Should have an SVG with rect elements (bars) or the recharts container
+    // Recharts SVG container should be present (or empty-state if no data).
     const svg = page.locator('.recharts-wrapper svg, .recharts-responsive-container svg').first();
-    await expect(svg).toBeVisible({ timeout: 5_000 });
+    const empty = page.getByText('No interests in range').first();
+    const hasSvg = await svg.isVisible({ timeout: 5_000 }).catch(() => false);
+    const hasEmpty = await empty.isVisible({ timeout: 2_000 }).catch(() => false);
+    expect(hasSvg || hasEmpty).toBeTruthy();
+  });
+
+  // Test 6: Date range picker switches analytics window
+  test('date range picker switches between ranges', async ({ page }) => {
+    await navigateTo(page, '/');
+    await expect(page.getByText('Pipeline Funnel').first()).toBeVisible({ timeout: 15_000 });
+
+    // Default is 30d. Click 7d, then 90d, and verify the kpi line label updates.
+    await page.getByTestId('range-7d').click();
+    await expect(page.getByText('Last 7 days')).toBeVisible({ timeout: 5_000 });
+
+    await page.getByTestId('range-90d').click();
+    await expect(page.getByText('Last 90 days')).toBeVisible({ timeout: 5_000 });
   });
 
   // Test 4: Activity feed shows recent entries

tests/e2e/smoke/27-alerts.spec.ts

@@ -0,0 +1,48 @@
+import { test, expect } from '@playwright/test';
+import { login, navigateTo, PORT_SLUG } from './helpers';
+
+test.describe('Alerts (Phase B)', () => {
+  test.beforeEach(async ({ page }) => {
+    await login(page, 'super_admin');
+  });
+
+  test('alert bell renders in topbar with no badge when no alerts', async ({ page }) => {
+    await navigateTo(page, '/');
+    const bell = page.getByTestId('alert-bell');
+    await expect(bell).toBeVisible({ timeout: 15_000 });
+  });
+
+  test('alert bell popover opens', async ({ page }) => {
+    await navigateTo(page, '/');
+    const bell = page.getByTestId('alert-bell');
+    await expect(bell).toBeVisible({ timeout: 15_000 });
+    await bell.click();
+
+    // Popover header is the unambiguous proof that the popover rendered.
+    await expect(page.getByText('Active alerts').first()).toBeVisible({ timeout: 8_000 });
+  });
+
+  test('dashboard renders the alert rail', async ({ page }) => {
+    await navigateTo(page, '/');
+    await expect(page.getByText('Pipeline Funnel').first()).toBeVisible({ timeout: 15_000 });
+    await expect(page.getByTestId('alert-rail')).toBeVisible({ timeout: 5_000 });
+  });
+
+  test('/alerts page loads with three tabs', async ({ page }) => {
+    await navigateTo(page, '/alerts');
+    expect(page.url()).toContain(`/${PORT_SLUG}/alerts`);
+    await expect(page.getByTestId('tab-open')).toBeVisible({ timeout: 10_000 });
+    await expect(page.getByTestId('tab-dismissed')).toBeVisible();
+    await expect(page.getByTestId('tab-resolved')).toBeVisible();
+
+    await page.getByTestId('tab-resolved').click();
+    // No assertion on contents; just smoke that the tab swap doesn't error.
+    await expect(page.getByTestId('tab-resolved')).toHaveAttribute('data-state', 'active');
+  });
+
+  test('sidebar Alerts link navigates to /alerts', async ({ page }) => {
+    await navigateTo(page, '/');
+    await page.getByRole('link', { name: 'Alerts', exact: true }).click();
+    await expect(page).toHaveURL(new RegExp(`/${PORT_SLUG}/alerts`), { timeout: 10_000 });
+  });
+});

tests/e2e/smoke/28-berth-interests-tab.spec.ts

@@ -0,0 +1,36 @@
+import { test, expect } from '@playwright/test';
+import { login, PORT_SLUG } from './helpers';
+
+test.describe('Berth detail — Interests tab (Phase B)', () => {
+  test.beforeEach(async ({ page }) => {
+    await login(page, 'super_admin');
+  });
+
+  test('berth detail page exposes an Interests tab', async ({ page }) => {
+    // Navigate to the berths list, then click the first row to drill in.
+    // The list uses TanStack Table row-click handlers, so we wait for the
+    // table body to populate rather than for `a[href*="/berths/"]`.
+    await page.goto(`/${PORT_SLUG}/berths`);
+    const firstRow = page.locator('tbody tr').first();
+    await expect(firstRow).toBeVisible({ timeout: 20_000 });
+    // The list table uses an `onRowClick` handler on the <tr> that calls
+    // `router.push`. Open the row's actions menu and click "View details"
+    // — the menu item's handler routes the same way and is more reliable
+    // than firing a synthetic <tr> click under React 19 + dev-mode HMR.
+    await firstRow.getByRole('button', { name: /open menu/i }).click();
+    await page.getByRole('menuitem', { name: /view details/i }).click();
+    await page.waitForURL(/\/berths\/[^/]+$/, { timeout: 10_000 });
+
+    const tab = page.getByRole('tab', { name: 'Interests', exact: true });
+    await expect(tab).toBeVisible({ timeout: 10_000 });
+    await tab.click();
+    await expect(tab).toHaveAttribute('data-state', 'active');
+
+    // Confirm the new tab body replaced the old stub. The body might be:
+    //   - a populated table
+    //   - the empty-state ("No interests linked to this berth")
+    //   - the loading skeleton (still fetching)
+    // The negative assertion against the old stub copy is the primary signal.
+    await expect(page.getByText('Interests coming soon')).not.toBeVisible({ timeout: 2_000 });
+  });
+});

tests/e2e/smoke/29-receipt-scanner.spec.ts

@@ -0,0 +1,50 @@
+import { test, expect } from '@playwright/test';
+import { login, PORT_SLUG } from './helpers';
+
+test.describe('Receipt scanner PWA (Phase B)', () => {
+  test.beforeEach(async ({ page }) => {
+    await login(page, 'super_admin');
+  });
+
+  test('scanner page loads with capture button and no dashboard chrome', async ({ page }) => {
+    // First-hit dev compile of the brand-new (scanner) route group can exceed 30s.
+    await page.goto(`/${PORT_SLUG}/scan`, { timeout: 60_000 });
+    await expect(page.getByRole('heading', { name: /scan a receipt/i })).toBeVisible({
+      timeout: 20_000,
+    });
+    await expect(page.getByTestId('scan-capture')).toBeVisible({ timeout: 10_000 });
+
+    // No sidebar / topbar elements should be present on the scanner.
+    const dashboardLinks = page.getByRole('link', { name: 'Dashboard' });
+    expect(await dashboardLinks.count()).toBe(0);
+  });
+
+  test('per-port manifest is served with correct content type and scope', async ({ page }) => {
+    const res = await page.request.get(`/${PORT_SLUG}/scan/manifest.webmanifest`, {
+      timeout: 60_000,
+    });
+    expect(res.status()).toBe(200);
+    expect(res.headers()['content-type']).toContain('application/manifest+json');
+    const body = (await res.json()) as {
+      name: string;
+      scope: string;
+      start_url: string;
+      display: string;
+    };
+    expect(body.scope).toBe(`/${PORT_SLUG}/scan`);
+    expect(body.start_url).toBe(`/${PORT_SLUG}/scan`);
+    expect(body.display).toBe('standalone');
+    expect(body.name.toLowerCase()).toContain('scanner');
+  });
+
+  test('admin OCR settings page renders both provider and model selectors', async ({ page }) => {
+    await page.goto(`/${PORT_SLUG}/admin/ocr`, { timeout: 60_000 });
+    await expect(page.getByRole('heading', { name: /receipt ocr/i })).toBeVisible({
+      timeout: 30_000,
+    });
+    await expect(page.getByTestId('save-port')).toBeVisible({ timeout: 15_000 });
+    // Provider + model selects use Radix triggers, not native <label>; locate via testid.
+    await expect(page.locator('#provider-port')).toBeVisible();
+    await expect(page.locator('#model-port')).toBeVisible();
+  });
+});

tests/e2e/smoke/30-audit-log.spec.ts

@@ -0,0 +1,43 @@
+import { test, expect } from '@playwright/test';
+import { login, PORT_SLUG } from './helpers';
+
+test.describe('Audit log read view (Phase B)', () => {
+  test.beforeEach(async ({ page }) => {
+    await login(page, 'super_admin');
+  });
+
+  test('admin audit page renders search + entity + action filters', async ({ page }) => {
+    // First-hit dev-mode compile of the upgraded route can exceed 30s.
+    await page.goto(`/${PORT_SLUG}/admin/audit`, { timeout: 60_000 });
+    await expect(page.getByRole('heading', { name: /audit log/i })).toBeVisible({
+      timeout: 30_000,
+    });
+    await expect(page.getByTestId('audit-search')).toBeVisible({ timeout: 10_000 });
+    await expect(page.getByTestId('audit-entity')).toBeVisible();
+    await expect(page.getByTestId('audit-action')).toBeVisible();
+    // Date filters render alongside.
+    await expect(page.getByLabel(/^from$/i)).toBeVisible();
+    await expect(page.getByLabel(/^to$/i)).toBeVisible();
+  });
+
+  test('audit API returns cursor-paginated rows with the new shape', async ({ page }) => {
+    // Pull the port id from the admin/ports list so the audit request can
+    // pass X-Port-Id (the audit endpoint scopes results to a single port).
+    const portsRes = await page.request.get('/api/v1/admin/ports');
+    const portsBody = (await portsRes.json()) as { data: Array<{ id: string }> };
+    const portId = portsBody.data[0]?.id;
+    expect(portId).toBeTruthy();
+
+    const auditRes = await page.request.get(`/api/v1/admin/audit?limit=5`, {
+      headers: { 'X-Port-Id': portId! },
+      timeout: 60_000,
+    });
+    expect(auditRes.status()).toBe(200);
+    const body = (await auditRes.json()) as {
+      data: Array<{ action: string; entityType: string }>;
+      pagination: { nextCursor: { createdAt: string; id: string } | null };
+    };
+    expect(Array.isArray(body.data)).toBe(true);
+    expect(body.pagination).toHaveProperty('nextCursor');
+  });
+});