Merge feat/dedup-migration: client dedup library + NocoDB migration script + admin queue

# Conflicts:
#	.gitignore
#	src/lib/db/migrations/meta/_journal.json

tests/integration/dedup/client-merge.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Client merge service — end-to-end integration test.
+ *
+ * Spins up two real clients in a real port via the factory helpers,
+ * attaches a few satellites (interest, contact, address, note),
+ * merges them, and asserts everything survived in the right place
+ * with the merge log written.
+ */
+import { describe, expect, it } from 'vitest';
+import { eq } from 'drizzle-orm';
+
+import { db } from '@/lib/db';
+import { clients, clientContacts, clientNotes, clientMergeLog } from '@/lib/db/schema/clients';
+import { interests } from '@/lib/db/schema/interests';
+import { mergeClients } from '@/lib/services/client-merge.service';
+import { makeClient, makePort, makeBerth } from '../../helpers/factories';
+
+describe('mergeClients', () => {
+  it('moves interests and contacts from loser to winner; archives loser; writes merge log', async () => {
+    const port = await makePort();
+    const winner = await makeClient({
+      portId: port.id,
+      overrides: { fullName: 'Marcus Laurent' },
+    });
+    const loser = await makeClient({
+      portId: port.id,
+      overrides: { fullName: 'Marcus Laurent (dup)' },
+    });
+
+    // Attach contact + interest to loser
+    await db.insert(clientContacts).values({
+      clientId: loser.id,
+      channel: 'email',
+      value: 'marcus@example.com',
+      isPrimary: true,
+    });
+    await db.insert(clientNotes).values({
+      clientId: loser.id,
+      authorId: 'test-user',
+      content: 'Loser-side note',
+    });
+    const berth = await makeBerth({ portId: port.id });
+    await db.insert(interests).values({
+      portId: port.id,
+      clientId: loser.id,
+      berthId: berth.id,
+      pipelineStage: 'open',
+      leadCategory: 'general_interest',
+    });
+
+    // ── Merge ─────────────────────────────────────────────────────────────
+    const result = await mergeClients({
+      winnerId: winner.id,
+      loserId: loser.id,
+      mergedBy: 'test-user',
+    });
+
+    expect(result.movedRows.interests).toBe(1);
+    expect(result.movedRows.contacts).toBe(1);
+    expect(result.movedRows.notes).toBe(1);
+
+    // ── Loser should be archived with mergedIntoClientId set ──────────────
+    const [archivedLoser] = await db.select().from(clients).where(eq(clients.id, loser.id));
+    expect(archivedLoser?.archivedAt).not.toBeNull();
+    expect(archivedLoser?.mergedIntoClientId).toBe(winner.id);
+
+    // ── All loser-side rows now point at the winner ───────────────────────
+    const winnerInterests = await db
+      .select()
+      .from(interests)
+      .where(eq(interests.clientId, winner.id));
+    expect(winnerInterests).toHaveLength(1);
+
+    const winnerContacts = await db
+      .select()
+      .from(clientContacts)
+      .where(eq(clientContacts.clientId, winner.id));
+    expect(winnerContacts.find((c) => c.value === 'marcus@example.com')).toBeDefined();
+
+    const winnerNotes = await db
+      .select()
+      .from(clientNotes)
+      .where(eq(clientNotes.clientId, winner.id));
+    expect(winnerNotes.find((n) => n.content === 'Loser-side note')).toBeDefined();
+
+    // ── Merge log row exists with snapshot ────────────────────────────────
+    const [log] = await db
+      .select()
+      .from(clientMergeLog)
+      .where(eq(clientMergeLog.id, result.mergeLogId));
+    expect(log?.survivingClientId).toBe(winner.id);
+    expect(log?.mergedClientId).toBe(loser.id);
+    expect(log?.mergedBy).toBe('test-user');
+    expect(log?.mergeDetails).toBeDefined();
+  });
+
+  it('refuses to merge a client into itself', async () => {
+    const port = await makePort();
+    const c = await makeClient({ portId: port.id });
+    await expect(mergeClients({ winnerId: c.id, loserId: c.id, mergedBy: 'u' })).rejects.toThrow(
+      /itself/i,
+    );
+  });
+
+  it('refuses to merge across different ports', async () => {
+    const portA = await makePort();
+    const portB = await makePort();
+    const a = await makeClient({ portId: portA.id });
+    const b = await makeClient({ portId: portB.id });
+    await expect(mergeClients({ winnerId: a.id, loserId: b.id, mergedBy: 'u' })).rejects.toThrow(
+      /different ports/i,
+    );
+  });
+
+  it('refuses to merge a client that has already been merged', async () => {
+    const port = await makePort();
+    const winner = await makeClient({ portId: port.id });
+    const loser = await makeClient({ portId: port.id });
+    // First merge succeeds.
+    await mergeClients({ winnerId: winner.id, loserId: loser.id, mergedBy: 'u' });
+    // Second merge of the same loser should refuse.
+    const winner2 = await makeClient({ portId: port.id });
+    await expect(
+      mergeClients({ winnerId: winner2.id, loserId: loser.id, mergedBy: 'u' }),
+    ).rejects.toThrow(/already merged/i);
+  });
+
+  it('drops duplicate contact rows during reattach', async () => {
+    const port = await makePort();
+    const winner = await makeClient({ portId: port.id });
+    const loser = await makeClient({ portId: port.id });
+
+    // Both have the same email contact.
+    await db.insert(clientContacts).values({
+      clientId: winner.id,
+      channel: 'email',
+      value: 'same@example.com',
+      isPrimary: true,
+    });
+    await db.insert(clientContacts).values({
+      clientId: loser.id,
+      channel: 'email',
+      value: 'same@example.com',
+      isPrimary: true,
+    });
+
+    const result = await mergeClients({
+      winnerId: winner.id,
+      loserId: loser.id,
+      mergedBy: 'u',
+    });
+
+    expect(result.movedRows.contacts).toBe(0); // duplicate dropped
+    const winnerEmails = await db
+      .select()
+      .from(clientContacts)
+      .where(eq(clientContacts.clientId, winner.id));
+    // Winner kept exactly one copy of the shared email.
+    expect(winnerEmails.filter((c) => c.value === 'same@example.com')).toHaveLength(1);
+  });
+
+  it('applies fieldChoices to copy loser values onto the winner', async () => {
+    const port = await makePort();
+    const winner = await makeClient({
+      portId: port.id,
+      overrides: { fullName: 'Marcus L.' },
+    });
+    const loser = await makeClient({
+      portId: port.id,
+      overrides: { fullName: 'Marcus Laurent' },
+    });
+
+    await mergeClients({
+      winnerId: winner.id,
+      loserId: loser.id,
+      mergedBy: 'u',
+      fieldChoices: { fullName: 'loser' },
+    });
+
+    const [updatedWinner] = await db.select().from(clients).where(eq(clients.id, winner.id));
+    expect(updatedWinner?.fullName).toBe('Marcus Laurent');
+  });
+});

tests/integration/dedup/match-candidates-api.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Match-candidates API — integration test.
+ *
+ * Exercises the GET /api/v1/clients/match-candidates handler against a
+ * real port + clients pool. Verifies the dedup library's at-create
+ * suggestion path returns the right candidates and confidence tiers
+ * for the "use existing client?" form interruption.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { db } from '@/lib/db';
+import { clientContacts } from '@/lib/db/schema/clients';
+import { getMatchCandidatesHandler } from '@/app/api/v1/clients/match-candidates/handlers';
+import { makeMockCtx, makeMockRequest } from '../../helpers/route-tester';
+import { makeClient, makePort } from '../../helpers/factories';
+
+interface MatchData {
+  clientId: string;
+  fullName: string;
+  score: number;
+  confidence: 'high' | 'medium' | 'low';
+  reasons: string[];
+  interestCount: number;
+}
+
+async function callHandler(
+  ctx: ReturnType<typeof makeMockCtx>,
+  query: Record<string, string>,
+): Promise<MatchData[]> {
+  const url = new URL('http://localhost/api/v1/clients/match-candidates');
+  for (const [k, v] of Object.entries(query)) url.searchParams.set(k, v);
+  const req = makeMockRequest('GET', url.toString());
+  const res = await getMatchCandidatesHandler(req, ctx);
+  expect(res.status).toBe(200);
+  const body = await res.json();
+  return body.data as MatchData[];
+}
+
+describe('GET /api/v1/clients/match-candidates', () => {
+  it('returns empty when nothing actionable was provided', async () => {
+    const port = await makePort();
+    const ctx = makeMockCtx({ portId: port.id });
+    const data = await callHandler(ctx, {});
+    expect(data).toEqual([]);
+  });
+
+  it('finds an existing client by exact email match (high confidence)', async () => {
+    const port = await makePort();
+    const ctx = makeMockCtx({ portId: port.id });
+    const existing = await makeClient({
+      portId: port.id,
+      overrides: { fullName: 'Marcus Laurent' },
+    });
+    await db.insert(clientContacts).values({
+      clientId: existing.id,
+      channel: 'email',
+      value: 'marcus@example.com',
+      isPrimary: true,
+    });
+    await db.insert(clientContacts).values({
+      clientId: existing.id,
+      channel: 'phone',
+      value: '+15551234567',
+      valueE164: '+15551234567',
+      isPrimary: true,
+    });
+
+    const data = await callHandler(ctx, {
+      email: 'Marcus@example.com',
+      phone: '+15551234567',
+      name: 'Marcus Laurent',
+    });
+
+    expect(data).toHaveLength(1);
+    expect(data[0]!.clientId).toBe(existing.id);
+    expect(data[0]!.confidence).toBe('high');
+    expect(data[0]!.reasons).toEqual(expect.arrayContaining(['email match', 'phone match']));
+  });
+
+  it('does not surface unrelated clients in the same port', async () => {
+    const port = await makePort();
+    const ctx = makeMockCtx({ portId: port.id });
+    const target = await makeClient({
+      portId: port.id,
+      overrides: { fullName: 'Marcus Laurent' },
+    });
+    await db.insert(clientContacts).values({
+      clientId: target.id,
+      channel: 'email',
+      value: 'marcus@example.com',
+      isPrimary: true,
+    });
+    // An unrelated client.
+    const unrelated = await makeClient({
+      portId: port.id,
+      overrides: { fullName: 'Bob Smith' },
+    });
+    await db.insert(clientContacts).values({
+      clientId: unrelated.id,
+      channel: 'email',
+      value: 'bob@example.org',
+      isPrimary: true,
+    });
+
+    const data = await callHandler(ctx, { email: 'marcus@example.com' });
+    expect(data.map((d) => d.clientId)).toEqual([target.id]);
+  });
+
+  it('returns medium-confidence partial matches', async () => {
+    // Same name, different contact info — Pattern F territory.
+    const port = await makePort();
+    const ctx = makeMockCtx({ portId: port.id });
+    const existing = await makeClient({
+      portId: port.id,
+      overrides: { fullName: 'Etiennette Clamouze' },
+    });
+    await db.insert(clientContacts).values({
+      clientId: existing.id,
+      channel: 'email',
+      value: 'clamouze.etiennette@gmail.com',
+      isPrimary: true,
+    });
+
+    const data = await callHandler(ctx, {
+      // Different email + phone, same name.
+      email: 'etiennette@the-manoah.com',
+      name: 'Etiennette Clamouze',
+    });
+
+    // Either no match (low confidence filtered out) or a medium one —
+    // either is fine. Critically, NOT high.
+    if (data.length > 0) {
+      expect(data[0]!.confidence).not.toBe('high');
+    }
+  });
+
+  it('does not leak across ports', async () => {
+    const portA = await makePort();
+    const portB = await makePort();
+
+    const ctxA = makeMockCtx({ portId: portA.id });
+    const inB = await makeClient({
+      portId: portB.id,
+      overrides: { fullName: 'In Port B' },
+    });
+    await db.insert(clientContacts).values({
+      clientId: inB.id,
+      channel: 'email',
+      value: 'b@example.com',
+      isPrimary: true,
+    });
+
+    // Caller is in port A, asking for an email that lives in port B.
+    const data = await callHandler(ctxA, { email: 'b@example.com' });
+    expect(data).toEqual([]);
+  });
+});