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/app/api/v1/expenses/scan-receipt/route.ts

@@ -2,24 +2,62 @@ import { NextResponse } from 'next/server';
 
 import { withAuth, withPermission } from '@/lib/api/helpers';
 import { errorResponse } from '@/lib/errors';
-import { scanReceipt } from '@/lib/services/receipt-scanner';
+import { logger } from '@/lib/logger';
+import { getResolvedOcrConfig } from '@/lib/services/ocr-config.service';
+import { runOcr, type ParsedReceipt } from '@/lib/services/ocr-providers';
+
+const EMPTY: ParsedReceipt = {
+  establishment: null,
+  date: null,
+  amount: null,
+  currency: null,
+  lineItems: [],
+  confidence: 0,
+};
 
 export const POST = withAuth(
-  withPermission('expenses', 'create', async (req, _ctx) => {
+  withPermission('expenses', 'create', async (req, ctx) => {
     try {
       const formData = await req.formData();
       const file = formData.get('file') as File | null;
-
       if (!file) {
         return NextResponse.json({ error: 'No file provided' }, { status: 400 });
       }
-
       const buffer = Buffer.from(await file.arrayBuffer());
       const mimeType = file.type || 'image/jpeg';
 
-      const result = await scanReceipt(buffer, mimeType);
+      const config = await getResolvedOcrConfig(ctx.portId);
+      if (!config.apiKey) {
+        // Manual-entry path — no OCR configured. Frontend will show the
+        // verify form with empty fields so the user can fill it in.
+        return NextResponse.json({
+          data: { parsed: EMPTY, source: 'manual', reason: 'no-ocr-configured' },
+        });
+      }
 
-      return NextResponse.json({ data: result });
+      try {
+        const parsed = await runOcr({
+          provider: config.provider,
+          model: config.model,
+          apiKey: config.apiKey,
+          imageBuffer: buffer,
+          mimeType,
+        });
+        return NextResponse.json({
+          data: { parsed, source: 'ai', provider: config.provider, model: config.model },
+        });
+      } catch (err) {
+        logger.error({ err, provider: config.provider }, 'OCR provider call failed');
+        // Provider hiccup — degrade to manual entry rather than 500-ing.
+        return NextResponse.json({
+          data: {
+            parsed: EMPTY,
+            source: 'manual',
+            reason: 'provider-error',
+            providerError: err instanceof Error ? err.message.slice(0, 200) : 'Unknown error',
+          },
+        });
+      }
     } catch (error) {
       return errorResponse(error);
     }