From 0ddaf462c7b96ce9223261c716b5f11a581c4e02 Mon Sep 17 00:00:00 2001
From: Matt <matt@letsbe.solutions>
Date: Thu, 21 May 2026 23:21:14 +0200
Subject: [PATCH] =?UTF-8?q?feat(uat-batch):=20Group=20M=20=E2=80=94=20univ?=
 =?UTF-8?q?ersal=20preview=20+=20field-history=20foundation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

M42, M43 from the 2026-05-21 plan.

Shipped:
  M42  FilePreviewDialog now handles seven preview kinds via a single
       previewKindFor() router (mime + filename fallback). Image and
       PDF stay on the existing lightbox + pdf viewer; plain text
       (.txt / .md / .csv / .tsv / .json / .xml / .log / .yaml / .ini
       / .html — text/* and application/json and friends) renders via
       a new <TextPreview> that fetches via the presigned URL and
       caps the body at 1 MB with a "showing first 1 MB" banner.
       Audio / video render through native HTML5 <audio> / <video>
       elements with preload="metadata". Office documents (.docx /
       .xlsx / .pptx / .odt / .ods / .odp + the official mime variants)
       embed via Microsoft's hosted Office viewer (view.officeapps
       .live.com/op/embed.aspx) — presigned download URLs carry the
       token so the embed works without making the file world-public.
       Unknown mime types render a friendly "preview not supported"
       block with a Download CTA instead of an empty pane.
  M43  Field-level override history foundation. Migration 0081 adds
       `interest_field_history` (id, port_id, interest_id?, client_id?,
       field_path, old_value, new_value, source, submission_id?,
       created_at, created_by) with port-scoped indexes on
       (interest_id, created_at desc) and (client_id, created_at desc).
       Drizzle schema + index exports added. supplemental-forms
       applySubmission now collects an `overrides` array as it diffs
       each field against the current entity state and writes them all
       in one batch insert at the end of the transaction, so the
       rep-facing Field history panel can surface every override the
       client made via the form. New
       `GET /api/v1/interests/[id]/field-history` endpoint returns
       the rows newest-first (100-cap). Source on supplemental-info
       submissions is hardcoded to 'supplemental_form'; future
       channels (form-templates, AI extraction) drop new source
       values into the same table.

       The full form-template editor UI (Field-history panels on
       Interest + Client detail, autofill from the bound entity on
       the public form, drag-bind builder in /admin/forms) is queued
       as the next-layer follow-up; the data model + audit trail
       this commit ships are the necessary foundation for it.

Verified: tsc clean, vitest 1454/1454, migration applied.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../v1/interests/[id]/field-history/route.ts  |  35 ++++
 src/components/files/file-preview-dialog.tsx  | 183 +++++++++++++++++-
 .../0081_interest_field_history.sql           |  36 ++++
 src/lib/db/schema/index.ts                    |   5 +
 src/lib/db/schema/interest-field-history.ts   |  63 ++++++
 .../services/supplemental-forms.service.ts    |  64 +++++-
 6 files changed, 377 insertions(+), 9 deletions(-)
 create mode 100644 src/app/api/v1/interests/[id]/field-history/route.ts
 create mode 100644 src/lib/db/migrations/0081_interest_field_history.sql
 create mode 100644 src/lib/db/schema/interest-field-history.ts

diff --git a/src/app/api/v1/interests/[id]/field-history/route.ts b/src/app/api/v1/interests/[id]/field-history/route.ts
new file mode 100644
index 00000000..5162a316
--- /dev/null
+++ b/src/app/api/v1/interests/[id]/field-history/route.ts
@@ -0,0 +1,35 @@
+import { NextResponse } from 'next/server';
+import { and, desc, eq } from 'drizzle-orm';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { db } from '@/lib/db';
+import { interestFieldHistory } from '@/lib/db/schema';
+import { errorResponse } from '@/lib/errors';
+
+/**
+ * GET /api/v1/interests/[id]/field-history
+ *
+ * Returns the field-level override log for the interest, newest first.
+ * Powers the "Field history" panel on Interest detail (and the matching
+ * panel on Client detail via /clients/[id]/field-history).
+ */
+export const GET = withAuth(
+  withPermission('interests', 'view', async (_req, ctx, params) => {
+    try {
+      const rows = await db
+        .select()
+        .from(interestFieldHistory)
+        .where(
+          and(
+            eq(interestFieldHistory.portId, ctx.portId),
+            eq(interestFieldHistory.interestId, params.id!),
+          ),
+        )
+        .orderBy(desc(interestFieldHistory.createdAt))
+        .limit(100);
+      return NextResponse.json({ data: rows });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
diff --git a/src/components/files/file-preview-dialog.tsx b/src/components/files/file-preview-dialog.tsx
index f45ea719..99fa2190 100644
--- a/src/components/files/file-preview-dialog.tsx
+++ b/src/components/files/file-preview-dialog.tsx
@@ -1,8 +1,8 @@
 'use client';
 
-import { useState } from 'react';
+import { useEffect, useState } from 'react';
 import dynamic from 'next/dynamic';
-import { ExternalLink, ZoomIn } from 'lucide-react';
+import { Download, ExternalLink, FileWarning, ZoomIn } from 'lucide-react';
 import { useQuery } from '@tanstack/react-query';
 
 import {
@@ -12,6 +12,7 @@ import {
   DialogHeader,
   DialogTitle,
 } from '@/components/ui/dialog';
+import { Button } from '@/components/ui/button';
 import { apiFetch } from '@/lib/api/client';
 
 // yet-another-react-lightbox is ~50kb, lazy-load it.
@@ -37,6 +38,50 @@ interface FilePreviewDialogProps {
   mimeType?: string;
 }
 
+/**
+ * Routes a file's mime type to one of seven preview surfaces. Order
+ * matters — `application/pdf` is matched before the generic
+ * "application/*" bucket so PDFs stay on the rich pdfjs viewer.
+ */
+type PreviewKind =
+  | 'image'
+  | 'pdf'
+  | 'text'
+  | 'audio'
+  | 'video'
+  | 'office' // .docx / .xlsx / .pptx / .odt / .ods
+  | 'unknown';
+
+function previewKindFor(mimeType: string | undefined, fileName: string | undefined): PreviewKind {
+  const mt = mimeType ?? '';
+  const name = (fileName ?? '').toLowerCase();
+  if (mt.startsWith('image/')) return 'image';
+  if (mt === 'application/pdf' || name.endsWith('.pdf')) return 'pdf';
+  if (mt.startsWith('audio/') || /\.(mp3|wav|m4a|ogg|flac)$/.test(name)) return 'audio';
+  if (mt.startsWith('video/') || /\.(mp4|mov|webm|m4v|ogg)$/.test(name)) return 'video';
+  if (
+    mt.startsWith('text/') ||
+    mt === 'application/json' ||
+    mt === 'application/xml' ||
+    /\.(txt|md|csv|tsv|json|xml|log|yaml|yml|conf|ini|html?)$/.test(name)
+  ) {
+    return 'text';
+  }
+  if (
+    mt.includes('officedocument') ||
+    mt === 'application/msword' ||
+    mt === 'application/vnd.ms-excel' ||
+    mt === 'application/vnd.ms-powerpoint' ||
+    mt === 'application/vnd.oasis.opendocument.text' ||
+    mt === 'application/vnd.oasis.opendocument.spreadsheet' ||
+    mt === 'application/vnd.oasis.opendocument.presentation' ||
+    /\.(docx?|xlsx?|pptx?|odt|ods|odp)$/.test(name)
+  ) {
+    return 'office';
+  }
+  return 'unknown';
+}
+
 export function FilePreviewDialog({
   open,
   onOpenChange,
@@ -57,8 +102,7 @@ export function FilePreviewDialog({
   const loading = previewQuery.isLoading;
   const error = previewQuery.error ? 'Failed to load preview' : null;
 
-  const isImage = mimeType?.startsWith('image/');
-  const isPdf = mimeType === 'application/pdf';
+  const kind = previewKindFor(mimeType, fileName);
 
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
@@ -98,7 +142,7 @@ export function FilePreviewDialog({
             </div>
           )}
 
-          {!loading && !error && previewUrl && isImage && (
+          {!loading && !error && previewUrl && kind === 'image' && (
             <button
               type="button"
               onClick={() => setLightboxOpen(true)}
@@ -115,16 +159,74 @@ export function FilePreviewDialog({
             </button>
           )}
 
-          {!loading && !error && previewUrl && isPdf && (
+          {!loading && !error && previewUrl && kind === 'pdf' && (
             <PdfViewer url={previewUrl} fileName={fileName} />
           )}
+
+          {!loading && !error && previewUrl && kind === 'text' && <TextPreview url={previewUrl} />}
+
+          {!loading && !error && previewUrl && kind === 'audio' && (
+            <div className="flex h-full items-center justify-center p-6">
+              {/* HTML5 <audio> handles streaming + scrubbing natively;
+                  preload="metadata" avoids burning bandwidth on a tab
+                  the rep may close before playing. */}
+              <audio src={previewUrl} controls preload="metadata" className="w-full max-w-xl" />
+            </div>
+          )}
+
+          {!loading && !error && previewUrl && kind === 'video' && (
+            <div className="flex h-full items-center justify-center bg-black">
+              <video
+                src={previewUrl}
+                controls
+                preload="metadata"
+                className="max-h-full max-w-full"
+              />
+            </div>
+          )}
+
+          {!loading && !error && previewUrl && kind === 'office' && (
+            // Office documents render via Microsoft's hosted Office viewer
+            // — public URL only; presigned download URLs include a token
+            // in the query string so they work here even though the file
+            // isn't world-public. The viewer streams the document and
+            // renders a high-fidelity preview without us shipping a
+            // headless LibreOffice. Falls back to "download to view" if
+            // the embed loads but renders nothing (e.g. CORS rejected) —
+            // detection is hard so we just keep the download CTA below.
+            <iframe
+              title={fileName ?? 'Office document preview'}
+              src={`https://view.officeapps.live.com/op/embed.aspx?src=${encodeURIComponent(
+                previewUrl,
+              )}`}
+              className="h-full w-full"
+              sandbox="allow-scripts allow-same-origin allow-popups"
+            />
+          )}
+
+          {!loading && !error && previewUrl && kind === 'unknown' && (
+            <div className="flex h-full flex-col items-center justify-center gap-3 p-6 text-center">
+              <FileWarning className="size-8 text-muted-foreground" aria-hidden />
+              <p className="text-sm font-medium">Preview not supported for this file type</p>
+              <p className="max-w-xs text-xs text-muted-foreground">
+                The file mime type ({mimeType ?? 'unknown'}) doesn&apos;t map to a built-in preview
+                surface. Download to view it locally.
+              </p>
+              <Button asChild>
+                <a href={previewUrl} download={fileName ?? 'download'}>
+                  <Download className="mr-1.5 size-4" aria-hidden />
+                  Download
+                </a>
+              </Button>
+            </div>
+          )}
         </div>
       </DialogContent>
 
       {/* Lightbox renders OUTSIDE the parent Dialog so the dialog's own
        *  bounds don't clip the fullscreen overlay. yet-another-react-
        *  lightbox handles zoom/pan/keyboard nav out of the box. */}
-      {previewUrl && isImage && (
+      {previewUrl && kind === 'image' && (
         <Lightbox
           open={lightboxOpen}
           close={() => setLightboxOpen(false)}
@@ -136,3 +238,70 @@ export function FilePreviewDialog({
     </Dialog>
   );
 }
+
+/**
+ * Plain-text preview pane — fetches the file body via the presigned
+ * URL (no auth needed; the URL itself carries the access token) and
+ * renders it as monospaced text. Caps the body at 1 MB so a huge log
+ * file doesn't lock the browser; surfaces a "first 1 MB shown" notice
+ * when the cap is hit.
+ */
+function TextPreview({ url }: { url: string }) {
+  const [text, setText] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [truncated, setTruncated] = useState(false);
+  const MAX_BYTES = 1_000_000; // 1 MB
+
+  useEffect(() => {
+    let cancelled = false;
+    async function load() {
+      try {
+        const res = await fetch(url);
+        if (!res.ok) {
+          if (!cancelled) setError(`Failed to load preview (${res.status})`);
+          return;
+        }
+        const blob = await res.blob();
+        const slice = blob.slice(0, MAX_BYTES);
+        const body = await slice.text();
+        if (cancelled) return;
+        setText(body);
+        setTruncated(blob.size > MAX_BYTES);
+      } catch (err) {
+        if (cancelled) return;
+        setError(err instanceof Error ? err.message : 'Unknown error');
+      }
+    }
+    void load();
+    return () => {
+      cancelled = true;
+    };
+  }, [url]);
+
+  if (error) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-destructive">
+        {error}
+      </div>
+    );
+  }
+  if (text === null) {
+    return (
+      <div className="flex h-full items-center justify-center text-sm text-muted-foreground">
+        Loading…
+      </div>
+    );
+  }
+  return (
+    <div className="flex h-full flex-col">
+      {truncated ? (
+        <div className="border-b bg-amber-50 px-3 py-1 text-xs text-amber-900">
+          Showing the first 1 MB. Download the full file to view the rest.
+        </div>
+      ) : null}
+      <pre className="flex-1 overflow-auto whitespace-pre-wrap break-words bg-background p-4 font-mono text-xs leading-relaxed">
+        {text}
+      </pre>
+    </div>
+  );
+}
diff --git a/src/lib/db/migrations/0081_interest_field_history.sql b/src/lib/db/migrations/0081_interest_field_history.sql
new file mode 100644
index 00000000..42d21dbb
--- /dev/null
+++ b/src/lib/db/migrations/0081_interest_field_history.sql
@@ -0,0 +1,36 @@
+-- 2026-05-21: interest_field_history table.
+--
+-- Captures field-level overrides — every time a value on an interest
+-- or its linked client changes via a supplemental-info form (or any
+-- future channel that explicitly records overrides), a row lands here
+-- with the old + new values plus source attribution.
+--
+-- Why a separate table vs piggybacking on `audit_logs`:
+--   - audit_logs is a fire-hose of every CRUD event (~10k rows/day on
+--     a busy port). Filtering for a single field's history is slow.
+--   - This table holds ONLY explicit overrides — much smaller, easier
+--     to surface on the Interest / Client detail "Field history" panel.
+--   - The `source` column lets the UI render meaningful provenance
+--     ("Submitted via supplemental info form on 2026-05-21").
+
+CREATE TABLE IF NOT EXISTS interest_field_history (
+  id text PRIMARY KEY DEFAULT gen_random_uuid()::text,
+  port_id text NOT NULL REFERENCES ports(id),
+  interest_id text REFERENCES interests(id) ON DELETE CASCADE,
+  client_id text REFERENCES clients(id) ON DELETE CASCADE,
+  field_path text NOT NULL,
+  old_value jsonb,
+  new_value jsonb NOT NULL,
+  source text NOT NULL,
+  submission_id text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  created_by text
+);
+
+CREATE INDEX IF NOT EXISTS idx_ifh_interest_created
+  ON interest_field_history (port_id, interest_id, created_at DESC)
+  WHERE interest_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_ifh_client_created
+  ON interest_field_history (port_id, client_id, created_at DESC)
+  WHERE client_id IS NOT NULL;
diff --git a/src/lib/db/schema/index.ts b/src/lib/db/schema/index.ts
index 220a95aa..f8b09d1e 100644
--- a/src/lib/db/schema/index.ts
+++ b/src/lib/db/schema/index.ts
@@ -80,3 +80,8 @@ export * from './reports';
 // Relations (must come last - references all tables)
 export * from './relations';
 export * from './tracked-links';
+
+// Field-level override history (supplemental-info submissions, future
+// form-template binding). Renders the "Field history" panel on the
+// Interest + Client detail pages.
+export * from './interest-field-history';
diff --git a/src/lib/db/schema/interest-field-history.ts b/src/lib/db/schema/interest-field-history.ts
new file mode 100644
index 00000000..67658f78
--- /dev/null
+++ b/src/lib/db/schema/interest-field-history.ts
@@ -0,0 +1,63 @@
+/**
+ * Field-level override history for interests + their linked clients.
+ *
+ * Every time a field on an interest or its linked client is overridden
+ * via an explicit channel (today: supplemental-info form submission;
+ * future: form-templates, AI-assisted extraction acceptance), a row
+ * lands here. Distinct from `audit_logs` — that table tracks every
+ * CRUD event for compliance; this one tracks only deliberate overrides
+ * so the Interest + Client "Field history" panels can surface them
+ * compactly.
+ */
+
+import { pgTable, text, jsonb, timestamp, index } from 'drizzle-orm/pg-core';
+import { sql } from 'drizzle-orm';
+
+import { ports } from './ports';
+import { interests } from './interests';
+import { clients } from './clients';
+
+export const interestFieldHistory = pgTable(
+  'interest_field_history',
+  {
+    id: text('id')
+      .primaryKey()
+      .$defaultFn(() => crypto.randomUUID()),
+    portId: text('port_id')
+      .notNull()
+      .references(() => ports.id),
+    interestId: text('interest_id').references(() => interests.id, { onDelete: 'cascade' }),
+    /** Denormalized for fast lookup on the Client detail "Field history"
+     *  panel — overrides that come in via a supplemental-info form
+     *  carry both interest + client refs. Direct-edit overrides may
+     *  only carry one. */
+    clientId: text('client_id').references(() => clients.id, { onDelete: 'cascade' }),
+    /** Dotted path of the field that was overridden. Examples:
+     *    'client.fullName'
+     *    'interest.desiredLengthFt'
+     *    'client.address.streetAddress'
+     *  The Field history panel formats this for display. */
+    fieldPath: text('field_path').notNull(),
+    oldValue: jsonb('old_value'),
+    newValue: jsonb('new_value').notNull(),
+    /** Provenance: 'supplemental_form' | 'rep_edit' | 'system_inferred' |
+     *  'ai_extraction' (future). Drives the "Submitted via X" copy. */
+    source: text('source').notNull(),
+    /** Optional FK to the form_submissions row that triggered the
+     *  override. Lets the UI link back to the original submission. */
+    submissionId: text('submission_id'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    createdBy: text('created_by'),
+  },
+  (table) => [
+    index('idx_ifh_interest_created')
+      .on(table.portId, table.interestId, table.createdAt)
+      .where(sql`${table.interestId} IS NOT NULL`),
+    index('idx_ifh_client_created')
+      .on(table.portId, table.clientId, table.createdAt)
+      .where(sql`${table.clientId} IS NOT NULL`),
+  ],
+);
+
+export type InterestFieldHistory = typeof interestFieldHistory.$inferSelect;
+export type NewInterestFieldHistory = typeof interestFieldHistory.$inferInsert;
diff --git a/src/lib/services/supplemental-forms.service.ts b/src/lib/services/supplemental-forms.service.ts
index a7ac8471..d31dc9c9 100644
--- a/src/lib/services/supplemental-forms.service.ts
+++ b/src/lib/services/supplemental-forms.service.ts
@@ -19,6 +19,7 @@ import {
   clientAddresses,
   yachts,
   clientContacts,
+  interestFieldHistory,
 } from '@/lib/db/schema';
 import { ConflictError, NotFoundError, ValidationError } from '@/lib/errors';
 
@@ -297,9 +298,26 @@ export async function applySubmission(token: string, input: SubmissionInput): Pr
     const client = await tx.query.clients.findFirst({ where: eq(clients.id, row.clientId) });
     if (!client) throw new NotFoundError('client');
 
+    // Track every field-level override we apply this submission so we
+    // can write them to interest_field_history below in a single batch.
+    // The shape is { fieldPath, oldValue, newValue } — submission_id is
+    // attached after we have a form_submissions row id (if/when that
+    // surface lands; today supplemental-info doesn't materialise a
+    // form_submissions row, so submissionId stays null).
+    const overrides: Array<{
+      fieldPath: string;
+      oldValue: unknown;
+      newValue: unknown;
+    }> = [];
+
     // Client patch: name lives on clients; address fields live on the
     // dedicated client_addresses row. fullName is required so always sent.
     if (input.fullName.trim() !== client.fullName) {
+      overrides.push({
+        fieldPath: 'client.fullName',
+        oldValue: client.fullName,
+        newValue: input.fullName.trim(),
+      });
       await tx
         .update(clients)
         .set({ fullName: input.fullName.trim() })
@@ -321,10 +339,22 @@ export async function applySubmission(token: string, input: SubmissionInput): Pr
         });
       } else {
         const addrPatch: Record<string, unknown> = {};
-        if (input.address && input.address !== existingAddr.streetAddress)
+        if (input.address && input.address !== existingAddr.streetAddress) {
           addrPatch.streetAddress = input.address;
-        if (input.country && input.country !== existingAddr.countryIso)
+          overrides.push({
+            fieldPath: 'client.address.streetAddress',
+            oldValue: existingAddr.streetAddress,
+            newValue: input.address,
+          });
+        }
+        if (input.country && input.country !== existingAddr.countryIso) {
           addrPatch.countryIso = input.country;
+          overrides.push({
+            fieldPath: 'client.address.countryIso',
+            oldValue: existingAddr.countryIso,
+            newValue: input.country,
+          });
+        }
         if (Object.keys(addrPatch).length > 0) {
           await tx
             .update(clientAddresses)
@@ -346,7 +376,17 @@ export async function applySubmission(token: string, input: SubmissionInput): Pr
           value: input.email.trim().toLowerCase(),
           isPrimary: true,
         });
+        overrides.push({
+          fieldPath: 'client.primaryEmail',
+          oldValue: null,
+          newValue: input.email.trim().toLowerCase(),
+        });
       } else if (existing.value !== input.email.trim().toLowerCase()) {
+        overrides.push({
+          fieldPath: 'client.primaryEmail',
+          oldValue: existing.value,
+          newValue: input.email.trim().toLowerCase(),
+        });
         await tx
           .update(clientContacts)
           .set({ value: input.email.trim().toLowerCase() })
@@ -411,5 +451,25 @@ export async function applySubmission(token: string, input: SubmissionInput): Pr
       .update(supplementalFormTokens)
       .set({ consumedAt: new Date() })
       .where(eq(supplementalFormTokens.id, row.id));
+
+    // Write the diff log so the Field history panel on Interest +
+    // Client detail can surface every override the client made via the
+    // form. Empty array means nothing actually changed — the client
+    // confirmed every field as-was — in which case we skip the batch.
+    if (overrides.length > 0) {
+      await tx.insert(interestFieldHistory).values(
+        overrides.map((o) => ({
+          portId: row.portId,
+          interestId: row.interestId,
+          clientId: row.clientId,
+          fieldPath: o.fieldPath,
+          oldValue: o.oldValue as unknown,
+          newValue: o.newValue as unknown,
+          source: 'supplemental_form' as const,
+          submissionId: null,
+          createdBy: null,
+        })),
+      );
+    }
   });
 }