feat(pipeline): 9→7 stage refactor + v1.1 hardening wave

Replaces the legacy 9-stage pipeline with 7 canonical stages
(enquiry → qualified → eoi → reservation → deposit_paid → contract →
nurturing) plus three doc sub-status columns (eoi_doc_status,
reservation_doc_status, contract_doc_status) that track sent/signed
within a single stage instead of branching it.

Schema (migration 0062):
- interests gains assigned_to, deposit_expected_amount/currency,
  three doc-status columns, two documenso-id columns, and
  date_reservation_signed.
- New tables: qualification_criteria (per-port admin-configurable),
  interest_qualifications (per-interest state), payments (deposit /
  balance / refund records keyed to interest + client).
- Default qualification criteria seeded for every existing port.
- Dummy-data UPDATEs collapse Sent/Signed pairs and 'completed' into
  the new stage + doc-status + outcome shape.

Migration 0063 adds interest_contact_log.voice_transcript and
template_used columns for v1.1-A/B (quick-template buttons + voice
transcription via Web Speech API).

v1.1 phase work bundled here:
- A/B: Quick-template buttons (Call / Visit / Email) + mic toggle on
       the contact-log compose dialog (useVoiceTranscription hook).
- C:   berth-rules-engine wraps state writes in pg_advisory_xact_lock
       with an idempotent re-read; emits rule_evaluated audit traces.
- D:   Documenso webhook: reservation/contract sub-status stamping
       moved out of the PDF-download try-block so a download failure
       no longer swallows the stamp. New integration test coverage.
- E:   /admin/qualification-criteria CRUD page + admin component.
- F:   default_new_interest_owner exposed in System Settings.
- G:   recentActivityCount + active_engagement deal-pulse signal
       surfaced as a chip on interests + hot-deals card.
- H:   interest_assigned notification on assignedTo change (skips
       self-assign, uses a dedupe key).

Plus the supporting components: AssignedToChip, DealPulseChip,
PaymentsSection, QualificationChecklist, MultiEoiChip,
SkipAheadBanner, WonStatusPanel, InterestBerthStatusBanner,
SupplementalInfoRequestButton, UserPicker.

Tests: 1370/1370 vitest pass (added deal-health unit suite +
expanded constants/validators/pipeline-transitions coverage). tsc
clean, eslint clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/app/api/v1/admin/qualification-criteria/[id]/route.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { updateQualificationCriterionSchema } from '@/lib/validators/qualification';
+import { deleteCriterion, updateCriterion } from '@/lib/services/qualification.service';
+
+export const PATCH = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updateQualificationCriterionSchema);
+      const row = await updateCriterion(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: row });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('admin', 'manage_settings', async (_req, ctx, params) => {
+    try {
+      await deleteCriterion(params.id!, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/admin/qualification-criteria/route.ts

@@ -0,0 +1,33 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { createQualificationCriterionSchema } from '@/lib/validators/qualification';
+import { createCriterion, listCriteriaForPort } from '@/lib/services/qualification.service';
+
+export const GET = withAuth(async (_req, ctx) => {
+  try {
+    const data = await listCriteriaForPort(ctx.portId);
+    return NextResponse.json({ data });
+  } catch (error) {
+    return errorResponse(error);
+  }
+});
+
+export const POST = withAuth(
+  withPermission('admin', 'manage_settings', async (req, ctx) => {
+    try {
+      const body = await parseBody(req, createQualificationCriterionSchema);
+      const row = await createCriterion(ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: row }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/contact-log/[id]/route.ts

@@ -15,6 +15,8 @@ export const PATCH = withAuth(
         channel: body.channel,
         direction: body.direction,
         summary: body.summary,
+        voiceTranscript: body.voiceTranscript,
+        templateUsed: body.templateUsed,
         followUpAt: body.followUpAt,
       });
       return NextResponse.json({ data: entry });

src/app/api/v1/interests/[id]/contact-log/route.ts

@@ -27,6 +27,8 @@ export const POST = withAuth(
         channel: body.channel,
         direction: body.direction,
         summary: body.summary,
+        voiceTranscript: body.voiceTranscript ?? null,
+        templateUsed: body.templateUsed ?? null,
         followUpAt: body.followUpAt ?? null,
       });
       return NextResponse.json({ data: entry }, { status: 201 });

src/app/api/v1/interests/[id]/payments/route.ts

@@ -0,0 +1,51 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { createPaymentSchema } from '@/lib/validators/payments';
+import {
+  createPayment,
+  getDepositTotalForInterest,
+  listPaymentsForInterest,
+} from '@/lib/services/payments.service';
+
+export const GET = withAuth(
+  withPermission('interests', 'view', async (_req, ctx, params) => {
+    try {
+      const interestId = params.id!;
+      const [payments, depositTotal] = await Promise.all([
+        listPaymentsForInterest(interestId, ctx.portId),
+        getDepositTotalForInterest(interestId, ctx.portId),
+      ]);
+      return NextResponse.json({ data: { payments, depositTotal } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const POST = withAuth(
+  withPermission('invoices', 'record_payment', async (req, ctx, params) => {
+    try {
+      // Body's interestId must match the URL param — defense-in-depth against
+      // a client that sends one ID in the URL but another in the body.
+      const body = await parseBody(req, createPaymentSchema);
+      if (body.interestId !== params.id) {
+        return NextResponse.json(
+          { error: 'interestId in body must match URL parameter' },
+          { status: 400 },
+        );
+      }
+      const payment = await createPayment(ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: payment }, { status: 201 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/interests/[id]/qualifications/route.ts

@@ -0,0 +1,44 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { setInterestQualificationSchema } from '@/lib/validators/qualification';
+import {
+  isInterestFullyQualified,
+  listInterestQualifications,
+  setInterestQualification,
+} from '@/lib/services/qualification.service';
+
+export const GET = withAuth(
+  withPermission('interests', 'view', async (_req, ctx, params) => {
+    try {
+      const interestId = params.id!;
+      const [criteria, fullyQualified] = await Promise.all([
+        listInterestQualifications(interestId, ctx.portId),
+        isInterestFullyQualified(interestId, ctx.portId),
+      ]);
+      return NextResponse.json({ data: { criteria, fullyQualified } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const PUT = withAuth(
+  withPermission('interests', 'edit', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, setInterestQualificationSchema);
+      const criteria = await setInterestQualification(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      const fullyQualified = criteria.every((c) => c.confirmed);
+      return NextResponse.json({ data: { criteria, fullyQualified } });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);

src/app/api/v1/payments/[id]/route.ts

@@ -0,0 +1,40 @@
+import { NextResponse } from 'next/server';
+
+import { withAuth, withPermission } from '@/lib/api/helpers';
+import { parseBody } from '@/lib/api/route-helpers';
+import { errorResponse } from '@/lib/errors';
+import { updatePaymentSchema } from '@/lib/validators/payments';
+import { deletePayment, updatePayment } from '@/lib/services/payments.service';
+
+export const PATCH = withAuth(
+  withPermission('invoices', 'record_payment', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, updatePaymentSchema);
+      const payment = await updatePayment(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: payment });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('invoices', 'record_payment', async (_req, ctx, params) => {
+    try {
+      await deletePayment(params.id!, ctx.portId, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return new NextResponse(null, { status: 204 });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);