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>
This commit is contained in:
Matt Ciaccio
2026-04-28 17:21:55 +02:00
parent 2fa70f4582
commit f52d21df83
63 changed files with 4459 additions and 206 deletions

View File

@@ -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>
);
}

View File

@@ -0,0 +1,290 @@
'use client';
import { useEffect, useState } from 'react';
import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
import { CheckCircle2, Eye, EyeOff, Loader2, XCircle } from 'lucide-react';
import { PageHeader } from '@/components/shared/page-header';
import { Button } from '@/components/ui/button';
import { Input } from '@/components/ui/input';
import { Label } from '@/components/ui/label';
import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
import {
Select,
SelectContent,
SelectItem,
SelectTrigger,
SelectValue,
} from '@/components/ui/select';
import { Checkbox } from '@/components/ui/checkbox';
import { usePermissions } from '@/hooks/use-permissions';
import { apiFetch } from '@/lib/api/client';
type Provider = 'openai' | 'claude';
interface ConfigResp {
data: {
provider: Provider;
model: string;
hasApiKey: boolean;
useGlobal: boolean;
};
models: Record<Provider, string[]>;
}
type Scope = 'port' | 'global';
interface SettingsBlockProps {
scope: Scope;
title: string;
description: string;
/** Hide the "use global" checkbox on the global tab. */
showUseGlobal?: boolean;
}
function SettingsBlock({ scope, title, description, showUseGlobal }: SettingsBlockProps) {
const queryClient = useQueryClient();
const queryKey = ['ocr-settings', scope];
const { data, isLoading } = useQuery<ConfigResp>({
queryKey,
queryFn: () => apiFetch<ConfigResp>(`/api/v1/admin/ocr-settings?scope=${scope}`),
});
const [provider, setProvider] = useState<Provider>('openai');
const [model, setModel] = useState<string>('gpt-4o-mini');
const [apiKey, setApiKey] = useState('');
const [showKey, setShowKey] = useState(false);
const [useGlobal, setUseGlobal] = useState(false);
const [testStatus, setTestStatus] = useState<null | { ok: true } | { ok: false; reason: string }>(
null,
);
useEffect(() => {
if (!data?.data) return;
setProvider(data.data.provider);
setModel(data.data.model);
setUseGlobal(data.data.useGlobal);
}, [data?.data]);
const save = useMutation({
mutationFn: (clearApiKey?: boolean) =>
apiFetch('/api/v1/admin/ocr-settings', {
method: 'PUT',
body: {
scope,
provider,
model,
apiKey: apiKey.length > 0 ? apiKey : undefined,
clearApiKey: Boolean(clearApiKey),
useGlobal: scope === 'global' ? false : useGlobal,
},
}),
onSuccess: () => {
setApiKey('');
queryClient.invalidateQueries({ queryKey });
},
});
const test = useMutation({
mutationFn: () =>
apiFetch<{ ok: boolean; reason?: string }>(`/api/v1/admin/ocr-settings/test`, {
method: 'POST',
body: { provider, model, apiKey },
}),
onSuccess: (res) =>
setTestStatus(res.ok ? { ok: true } : { ok: false, reason: res.reason ?? 'Unknown' }),
onError: (err: unknown) =>
setTestStatus({
ok: false,
reason: err instanceof Error ? err.message : 'Network error',
}),
});
const models = data?.models[provider] ?? [];
const hasKey = data?.data.hasApiKey ?? false;
if (isLoading) {
return (
<Card>
<CardHeader>
<CardTitle>{title}</CardTitle>
</CardHeader>
<CardContent className="flex items-center gap-2 text-sm text-muted-foreground">
<Loader2 className="h-4 w-4 animate-spin" /> Loading
</CardContent>
</Card>
);
}
return (
<Card>
<CardHeader>
<CardTitle>{title}</CardTitle>
<p className="text-sm text-muted-foreground">{description}</p>
</CardHeader>
<CardContent className="space-y-4">
{showUseGlobal ? (
<div className="flex items-start gap-2 rounded-lg border border-border bg-muted/30 p-3">
<Checkbox
id={`useGlobal-${scope}`}
checked={useGlobal}
onCheckedChange={(v) => setUseGlobal(v === true)}
/>
<div className="space-y-0.5">
<Label htmlFor={`useGlobal-${scope}`} className="text-sm font-medium">
Use the global API key for this port
</Label>
<p className="text-xs text-muted-foreground">
When enabled, this port falls back to the system-wide OCR settings. Per-port
provider/model/key are ignored.
</p>
</div>
</div>
) : null}
<div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
<div className="space-y-1.5">
<Label htmlFor={`provider-${scope}`}>Provider</Label>
<Select
value={provider}
onValueChange={(v) => {
const p = v as Provider;
setProvider(p);
setModel(data?.models[p][0] ?? '');
setTestStatus(null);
}}
>
<SelectTrigger id={`provider-${scope}`}>
<SelectValue />
</SelectTrigger>
<SelectContent>
<SelectItem value="openai">OpenAI</SelectItem>
<SelectItem value="claude">Claude (Anthropic)</SelectItem>
</SelectContent>
</Select>
</div>
<div className="space-y-1.5">
<Label htmlFor={`model-${scope}`}>Model</Label>
<Select value={model} onValueChange={setModel}>
<SelectTrigger id={`model-${scope}`}>
<SelectValue />
</SelectTrigger>
<SelectContent>
{models.map((m) => (
<SelectItem key={m} value={m}>
{m}
</SelectItem>
))}
</SelectContent>
</Select>
</div>
</div>
<div className="space-y-1.5">
<Label htmlFor={`apiKey-${scope}`}>API key</Label>
<div className="flex gap-2">
<Input
id={`apiKey-${scope}`}
type={showKey ? 'text' : 'password'}
autoComplete="off"
placeholder={hasKey ? '•••••• (saved — leave blank to keep)' : 'sk-…'}
value={apiKey}
onChange={(e) => {
setApiKey(e.target.value);
setTestStatus(null);
}}
/>
<Button
type="button"
variant="outline"
size="icon"
onClick={() => setShowKey((v) => !v)}
aria-label={showKey ? 'Hide key' : 'Show key'}
>
{showKey ? <EyeOff className="h-4 w-4" /> : <Eye className="h-4 w-4" />}
</Button>
</div>
<p className="text-xs text-muted-foreground">
Stored encrypted at rest. Never re-displayed after saving.
</p>
</div>
<div className="flex flex-wrap items-center gap-2">
<Button
onClick={() => save.mutate(false)}
disabled={save.isPending}
data-testid={`save-${scope}`}
>
{save.isPending ? <Loader2 className="mr-1.5 h-3 w-3 animate-spin" /> : null}
Save settings
</Button>
<Button
type="button"
variant="outline"
onClick={() => test.mutate()}
disabled={test.isPending || apiKey.length === 0}
>
{test.isPending ? <Loader2 className="mr-1.5 h-3 w-3 animate-spin" /> : null}
Test connection
</Button>
{hasKey ? (
<Button
type="button"
variant="ghost"
onClick={() => save.mutate(true)}
disabled={save.isPending}
className="text-destructive"
>
Clear stored key
</Button>
) : null}
{testStatus?.ok ? (
<span className="inline-flex items-center gap-1 text-sm text-green-700">
<CheckCircle2 className="h-4 w-4" />
Connection OK
</span>
) : null}
{testStatus && !testStatus.ok ? (
<span className="inline-flex items-center gap-1 text-sm text-destructive">
<XCircle className="h-4 w-4" />
{testStatus.reason}
</span>
) : null}
</div>
</CardContent>
</Card>
);
}
export function OcrSettingsForm() {
const { isSuperAdmin } = usePermissions();
return (
<div className="space-y-6">
<PageHeader
title="Receipt OCR"
eyebrow="Admin"
description="Configure the AI provider used to read receipts captured via the mobile scanner."
variant="gradient"
/>
<SettingsBlock
scope="port"
title="This port"
description="Provider and key used when staff at this port scan a receipt."
showUseGlobal
/>
{isSuperAdmin ? (
<SettingsBlock
scope="global"
title="Global default"
description="Used by any port that opted into the global key. Super-admin only."
/>
) : null}
</div>
);
}