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>

src/components/admin/audit/audit-log-list.tsx

@@ -1,14 +1,16 @@
 'use client';
 
-import { useState, useEffect, useCallback } from 'react';
+import { useEffect, useState, useCallback, useMemo } from 'react';
 import { type ColumnDef } from '@tanstack/react-table';
 import { formatDistanceToNow } from 'date-fns';
-import { Search } from 'lucide-react';
+import { Search, X } from 'lucide-react';
 
 import { DataTable } from '@/components/shared/data-table';
 import { PageHeader } from '@/components/shared/page-header';
 import { Badge } from '@/components/ui/badge';
 import { Input } from '@/components/ui/input';
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
 import {
   Select,
   SelectContent,
@@ -23,13 +25,19 @@ interface AuditEntry {
   userId: string | null;
   action: string;
   entityType: string;
-  entityId: string;
+  entityId: string | null;
   fieldChanged: string | null;
   oldValue: Record<string, unknown> | null;
   newValue: Record<string, unknown> | null;
   metadata: Record<string, unknown> | null;
   ipAddress: string | null;
   createdAt: string;
+  actor: { id: string; email: string; name: string } | null;
+}
+
+interface AuditResponse {
+  data: AuditEntry[];
+  pagination: { nextCursor: { createdAt: string; id: string } | null };
 }
 
 const ACTION_COLORS: Record<string, string> = {
@@ -40,6 +48,8 @@ const ACTION_COLORS: Record<string, string> = {
   restore: 'bg-teal-500',
   login: 'bg-gray-500',
   permission_denied: 'bg-red-800',
+  merge: 'bg-purple-500',
+  revert: 'bg-amber-500',
 };
 
 const ENTITY_TYPES = [
@@ -58,40 +68,96 @@ const ENTITY_TYPES = [
   'webhook',
 ];
 
+function useDebounced<T>(value: T, ms = 300): T {
+  const [v, setV] = useState(value);
+  useEffect(() => {
+    const t = setTimeout(() => setV(value), ms);
+    return () => clearTimeout(t);
+  }, [value, ms]);
+  return v;
+}
+
 export function AuditLogList() {
   const [entries, setEntries] = useState<AuditEntry[]>([]);
+  const [nextCursor, setNextCursor] = useState<{
+    createdAt: string;
+    id: string;
+  } | null>(null);
   const [loading, setLoading] = useState(true);
-  const [total, setTotal] = useState(0);
-  const [page, setPage] = useState(1);
-  const [entityTypeFilter, setEntityTypeFilter] = useState<string>('all');
-  const [actionFilter, setActionFilter] = useState<string>('all');
-  const [search, setSearch] = useState('');
+  const [loadingMore, setLoadingMore] = useState(false);
 
-  const fetchLogs = useCallback(async () => {
+  // Filter state — debounce text inputs.
+  const [search, setSearch] = useState('');
+  const [entityType, setEntityType] = useState<string>('all');
+  const [action, setAction] = useState<string>('all');
+  const [userId, setUserId] = useState('');
+  const [dateFrom, setDateFrom] = useState('');
+  const [dateTo, setDateTo] = useState('');
+
+  const debouncedSearch = useDebounced(search);
+  const debouncedUserId = useDebounced(userId);
+
+  const queryString = useMemo(() => {
+    const params = new URLSearchParams({ limit: '50' });
+    if (entityType !== 'all') params.set('entityType', entityType);
+    if (action !== 'all') params.set('action', action);
+    if (debouncedSearch) params.set('search', debouncedSearch);
+    if (debouncedUserId) params.set('userId', debouncedUserId);
+    if (dateFrom) params.set('dateFrom', new Date(dateFrom).toISOString());
+    if (dateTo) {
+      const end = new Date(dateTo);
+      end.setHours(23, 59, 59, 999);
+      params.set('dateTo', end.toISOString());
+    }
+    return params.toString();
+  }, [entityType, action, debouncedSearch, debouncedUserId, dateFrom, dateTo]);
+
+  const fetchFirstPage = useCallback(async () => {
     setLoading(true);
     try {
-      const params = new URLSearchParams({
-        page: String(page),
-        limit: '50',
-      });
-      if (entityTypeFilter !== 'all') params.set('entityType', entityTypeFilter);
-      if (actionFilter !== 'all') params.set('action', actionFilter);
-      if (search) params.set('search', search);
-
-      const res = await apiFetch<{
-        data: AuditEntry[];
-        pagination: { total: number };
-      }>(`/api/v1/admin/audit?${params}`);
+      const res = await apiFetch<AuditResponse>(`/api/v1/admin/audit?${queryString}`);
       setEntries(res.data);
-      setTotal(res.pagination.total);
+      setNextCursor(res.pagination.nextCursor);
     } finally {
       setLoading(false);
     }
-  }, [page, entityTypeFilter, actionFilter, search]);
+  }, [queryString]);
+
+  const loadMore = useCallback(async () => {
+    if (!nextCursor) return;
+    setLoadingMore(true);
+    try {
+      const params = new URLSearchParams(queryString);
+      params.set('cursorAt', nextCursor.createdAt);
+      params.set('cursorId', nextCursor.id);
+      const res = await apiFetch<AuditResponse>(`/api/v1/admin/audit?${params}`);
+      setEntries((prev) => [...prev, ...res.data]);
+      setNextCursor(res.pagination.nextCursor);
+    } finally {
+      setLoadingMore(false);
+    }
+  }, [queryString, nextCursor]);
 
   useEffect(() => {
-    void fetchLogs();
-  }, [fetchLogs]);
+    void fetchFirstPage();
+  }, [fetchFirstPage]);
+
+  function clearFilters() {
+    setSearch('');
+    setEntityType('all');
+    setAction('all');
+    setUserId('');
+    setDateFrom('');
+    setDateTo('');
+  }
+
+  const hasActiveFilter =
+    Boolean(search) ||
+    entityType !== 'all' ||
+    action !== 'all' ||
+    Boolean(userId) ||
+    Boolean(dateFrom) ||
+    Boolean(dateTo);
 
   const columns: ColumnDef<AuditEntry, unknown>[] = [
     {
@@ -117,7 +183,7 @@ export function AuditLogList() {
           {row.original.action}
         </Badge>
       ),
-      size: 100,
+      size: 110,
     },
     {
       accessorKey: 'entityType',
@@ -125,9 +191,11 @@ export function AuditLogList() {
       cell: ({ row }) => (
         <div>
           <span className="font-medium capitalize">{row.original.entityType}</span>
-          <code className="ml-2 text-xs text-muted-foreground">
-            {row.original.entityId.slice(0, 8)}...
-          </code>
+          {row.original.entityId ? (
+            <code className="ml-2 text-xs text-muted-foreground">
+              {row.original.entityId.slice(0, 8)}…
+            </code>
+          ) : null}
         </div>
       ),
     },
@@ -150,108 +218,166 @@ export function AuditLogList() {
       },
     },
     {
-      accessorKey: 'userId',
-      header: 'User',
-      cell: ({ row }) => (
-        <code className="text-xs">
-          {row.original.userId ? row.original.userId.slice(0, 8) + '...' : 'system'}
-        </code>
-      ),
-      size: 100,
+      id: 'actor',
+      header: 'Actor',
+      cell: ({ row }) => {
+        const { actor, userId: rawId } = row.original;
+        if (actor) {
+          return (
+            <div className="text-sm">
+              <div className="font-medium">{actor.name}</div>
+              <div className="text-xs text-muted-foreground">{actor.email}</div>
+            </div>
+          );
+        }
+        if (rawId) {
+          return <code className="text-xs">{rawId.slice(0, 8)}…</code>;
+        }
+        return <span className="text-xs text-muted-foreground">system</span>;
+      },
+      size: 200,
     },
   ];
 
   return (
     <div>
-      <PageHeader title="Audit Log" description={`${total} entries`} />
-
-      <div className="flex items-center gap-3 mb-4">
-        <div className="relative flex-1 max-w-sm">
-          <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
-          <Input
-            className="pl-9"
-            placeholder="Search..."
-            value={search}
-            onChange={(e) => {
-              setSearch(e.target.value);
-              setPage(1);
-            }}
-          />
-        </div>
-        <Select
-          value={entityTypeFilter}
-          onValueChange={(v) => {
-            setEntityTypeFilter(v);
-            setPage(1);
-          }}
-        >
-          <SelectTrigger className="w-36">
-            <SelectValue />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectItem value="all">All Entities</SelectItem>
-            {ENTITY_TYPES.map((t) => (
-              <SelectItem key={t} value={t}>
-                {t.charAt(0).toUpperCase() + t.slice(1)}
-              </SelectItem>
-            ))}
-          </SelectContent>
-        </Select>
-        <Select
-          value={actionFilter}
-          onValueChange={(v) => {
-            setActionFilter(v);
-            setPage(1);
-          }}
-        >
-          <SelectTrigger className="w-36">
-            <SelectValue />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectItem value="all">All Actions</SelectItem>
-            <SelectItem value="create">Create</SelectItem>
-            <SelectItem value="update">Update</SelectItem>
-            <SelectItem value="delete">Delete</SelectItem>
-            <SelectItem value="archive">Archive</SelectItem>
-            <SelectItem value="restore">Restore</SelectItem>
-            <SelectItem value="permission_denied">Permission Denied</SelectItem>
-          </SelectContent>
-        </Select>
-      </div>
-
-      <DataTable
-        columns={columns}
-        data={entries}
-        isLoading={loading}
-        getRowId={(row) => row.id}
-        emptyState={
-          <div className="text-center py-8">
-            <p className="text-muted-foreground">No audit log entries found.</p>
-          </div>
-        }
+      <PageHeader
+        title="Audit Log"
+        eyebrow="Admin"
+        description="Every state change in this port — fully searchable."
+        variant="gradient"
       />
 
-      {total > 50 && (
-        <div className="flex items-center justify-center gap-2 mt-4">
-          <button
-            className="text-sm text-muted-foreground hover:text-foreground disabled:opacity-50"
-            disabled={page <= 1}
-            onClick={() => setPage((p) => p - 1)}
-          >
-            Previous
-          </button>
-          <span className="text-sm text-muted-foreground">
-            Page {page} of {Math.ceil(total / 50)}
-          </span>
-          <button
-            className="text-sm text-muted-foreground hover:text-foreground disabled:opacity-50"
-            disabled={page >= Math.ceil(total / 50)}
-            onClick={() => setPage((p) => p + 1)}
-          >
-            Next
-          </button>
+      <div className="mt-4 flex flex-wrap items-end gap-3">
+        <div className="space-y-1.5">
+          <Label htmlFor="audit-search" className="text-xs">
+            Search
+          </Label>
+          <div className="relative w-72">
+            <Search className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-muted-foreground" />
+            <Input
+              id="audit-search"
+              className="pl-9"
+              placeholder="entity id, action, vendor…"
+              value={search}
+              onChange={(e) => setSearch(e.target.value)}
+              data-testid="audit-search"
+            />
+          </div>
         </div>
-      )}
+
+        <div className="space-y-1.5">
+          <Label className="text-xs">Entity</Label>
+          <Select value={entityType} onValueChange={setEntityType}>
+            <SelectTrigger className="w-36" data-testid="audit-entity">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="all">All entities</SelectItem>
+              {ENTITY_TYPES.map((t) => (
+                <SelectItem key={t} value={t}>
+                  {t.charAt(0).toUpperCase() + t.slice(1)}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+
+        <div className="space-y-1.5">
+          <Label className="text-xs">Action</Label>
+          <Select value={action} onValueChange={setAction}>
+            <SelectTrigger className="w-36" data-testid="audit-action">
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              <SelectItem value="all">All actions</SelectItem>
+              <SelectItem value="create">Create</SelectItem>
+              <SelectItem value="update">Update</SelectItem>
+              <SelectItem value="delete">Delete</SelectItem>
+              <SelectItem value="archive">Archive</SelectItem>
+              <SelectItem value="restore">Restore</SelectItem>
+              <SelectItem value="merge">Merge</SelectItem>
+              <SelectItem value="revert">Revert</SelectItem>
+              <SelectItem value="login">Login</SelectItem>
+              <SelectItem value="permission_denied">Permission denied</SelectItem>
+            </SelectContent>
+          </Select>
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="audit-user" className="text-xs">
+            User id
+          </Label>
+          <Input
+            id="audit-user"
+            className="w-44"
+            placeholder="exact user id"
+            value={userId}
+            onChange={(e) => setUserId(e.target.value)}
+          />
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="audit-from" className="text-xs">
+            From
+          </Label>
+          <Input
+            id="audit-from"
+            type="date"
+            className="w-36"
+            value={dateFrom}
+            onChange={(e) => setDateFrom(e.target.value)}
+          />
+        </div>
+
+        <div className="space-y-1.5">
+          <Label htmlFor="audit-to" className="text-xs">
+            To
+          </Label>
+          <Input
+            id="audit-to"
+            type="date"
+            className="w-36"
+            value={dateTo}
+            onChange={(e) => setDateTo(e.target.value)}
+          />
+        </div>
+
+        {hasActiveFilter ? (
+          <Button variant="ghost" size="sm" onClick={clearFilters} className="ml-auto">
+            <X className="mr-1.5 h-3 w-3" />
+            Clear
+          </Button>
+        ) : null}
+      </div>
+
+      <div className="mt-4">
+        <DataTable
+          columns={columns}
+          data={entries}
+          isLoading={loading}
+          getRowId={(row) => row.id}
+          emptyState={
+            <div className="text-center py-8">
+              <p className="text-muted-foreground">No audit log entries found.</p>
+            </div>
+          }
+        />
+      </div>
+
+      {nextCursor ? (
+        <div className="mt-4 flex justify-center">
+          <Button
+            variant="outline"
+            size="sm"
+            disabled={loadingMore}
+            onClick={() => void loadMore()}
+            data-testid="audit-load-more"
+          >
+            {loadingMore ? 'Loading…' : 'Load more'}
+          </Button>
+        </div>
+      ) : null}
     </div>
   );
 }