feat(sales): EOI queue route + invoice→deposit auto-advance + won/lost outcomes

Three independent strengthenings of the sales spine that the prior coherence sweep made it possible to do cleanly. 1. EOI queue page - Sidebar entry under Documents → "EOI queue". - Route /[port]/documents/eoi renders DocumentsHub with the existing eoi_queue tab pre-selected (filters in-flight EOIs only). - .gitignore: tightened root-only `eoi/` ignore so the documents/eoi route is no longer silently excluded. 2. Invoice ↔ deposit link - invoices.interestId (FK, ON DELETE SET NULL) + invoices.kind ('general' | 'deposit'). Indexed on (port_id, interest_id). - createInvoiceSchema requires interestId when kind === 'deposit'; the service validates the linked interest belongs to the same port before insert. - recordPayment auto-advances pipelineStage to deposit_10pct (via advanceStageIfBehind) when a paid invoice is kind=deposit and has an interestId. No-op if the interest is already further along. - "Create deposit invoice" link added to the Deposit milestone on the interest detail. Links to /invoices/new?interestId=…&kind=deposit; the form prefills the billing entity from the linked interest's client and shows a context banner. 3. Won / lost terminal outcomes - interests.outcome ('won' | 'lost_other_marina' | 'lost_unqualified' | 'lost_no_response' | 'cancelled') + outcomeReason text + outcomeAt timestamp. Indexed on (port_id, outcome). - setInterestOutcome / clearInterestOutcome services + POST/DELETE /api/v1/interests/:id/outcome endpoints (gated by change_stage permission). Setting an outcome moves the interest to `completed` in the same write; clearing reopens to `in_communication` (or a caller-specified stage). - Mark Won / Mark Lost icon buttons on the interest detail header, plus an outcome badge that replaces the stage pill once a terminal outcome is set, plus a Reopen button. - Funnel + dashboard math updated to exclude lost/cancelled outcomes from active calculations (KPIs.activeInterests, pipelineValueUsd, getPipelineCounts, computePipelineFunnel, getRevenueForecast). The funnel now also returns a `lost` summary so callers can surface leakage without polluting conversion percentages. Schema changes shipped via 0019_lazy_vampiro.sql; applied to dev DB manually via psql because drizzle-kit push hits a pre-existing zod parsing issue on the companies index. Dev server may need a restart to flush prepared-statement caches. tsc clean. vitest 832/832 pass. ESLint clean on every file touched. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-02 00:01:33 +02:00
parent 886119cbde
commit ba5fb6db5e
21 changed files with 10995 additions and 112 deletions
--- a/.gitignore
+++ b/.gitignore
@@ -20,7 +20,8 @@ tsconfig.tsbuildinfo
 docker-compose.override.yml
 .remember/
 .DS_Store
-eoi/
+# Root-only ad-hoc EOI scratch dir; routes under src/app/.../eoi/ must NOT match.
+/eoi/

 # Brainstorming companion mockup files
 .superpowers/
--- a/src/app/(dashboard)/[portSlug]/documents/eoi/page.tsx
+++ b/src/app/(dashboard)/[portSlug]/documents/eoi/page.tsx
@@ -0,0 +1,10 @@
+import { DocumentsHub } from '@/components/documents/documents-hub';
+
+interface PageProps {
+  params: Promise<{ portSlug: string }>;
+}
+
+export default async function EoiQueuePage({ params }: PageProps) {
+  const { portSlug } = await params;
+  return <DocumentsHub portSlug={portSlug} initialTab="eoi_queue" />;
+}
--- a/src/app/(dashboard)/[portSlug]/invoices/new/page.tsx
+++ b/src/app/(dashboard)/[portSlug]/invoices/new/page.tsx
@@ -1,11 +1,11 @@
 'use client';

 import { useEffect, useState } from 'react';
-import { useParams, useRouter } from 'next/navigation';
+import { useParams, useRouter, useSearchParams } from 'next/navigation';
 import { useForm, FormProvider } from 'react-hook-form';
 import { zodResolver } from '@hookform/resolvers/zod';
-import { useMutation } from '@tanstack/react-query';
-import { ChevronLeft, ChevronRight, Check, Loader2 } from 'lucide-react';
+import { useMutation, useQuery } from '@tanstack/react-query';
+import { ChevronLeft, ChevronRight, Check, Loader2, Wallet } from 'lucide-react';

 import { useMobileChrome } from '@/components/layout/mobile/mobile-layout-provider';

@@ -45,6 +45,10 @@ export default function NewInvoicePage() {
  const params = useParams<{ portSlug: string }>();
  const portSlug = params?.portSlug ?? '';
  const router = useRouter();
+  const searchParams = useSearchParams();
+  const prefilledInterestId = searchParams.get('interestId') ?? undefined;
+  const prefilledKind =
+    searchParams.get('kind') === 'deposit' ? ('deposit' as const) : ('general' as const);

  const [step, setStep] = useState(1);

@@ -54,6 +58,22 @@ export default function NewInvoicePage() {
    return () => setChrome({ title: null, showBackButton: false });
  }, [setChrome]);

+  // When the form is launched from an interest detail with `?interestId=…&kind=deposit`,
+  // fetch enough of the interest to display "Deposit for {client} — Berth {n}" in
+  // the review step. Doubles as the source of truth for the billing entity prefill.
+  const { data: prefilledInterest } = useQuery<{
+    data: {
+      id: string;
+      clientId: string;
+      clientName: string | null;
+      berthMooringNumber: string | null;
+    };
+  }>({
+    queryKey: ['interest-prefill', prefilledInterestId],
+    queryFn: () => apiFetch(`/api/v1/interests/${prefilledInterestId}`),
+    enabled: !!prefilledInterestId,
+  });
+
  const methods = useForm<CreateInvoiceInput>({
    resolver: zodResolver(createInvoiceSchema),
    defaultValues: {
@@ -61,6 +81,8 @@ export default function NewInvoicePage() {
      currency: 'USD',
      lineItems: [],
      expenseIds: [],
+      interestId: prefilledInterestId,
+      kind: prefilledKind,
    },
  });

@@ -73,6 +95,21 @@ export default function NewInvoicePage() {
  } = methods;

  const watchedValues = watch();
+  const isDepositInvoice = watchedValues.kind === 'deposit';
+
+  // Pre-fill the billing entity from the linked interest's client on launch.
+  useEffect(() => {
+    if (prefilledInterest?.data && !watchedValues.billingEntity) {
+      setValue(
+        'billingEntity',
+        { type: 'client', id: prefilledInterest.data.clientId },
+        { shouldValidate: true },
+      );
+    }
+    // We only want this to run when the interest data first arrives.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [prefilledInterest?.data?.clientId]);
+
  const lineItems = watchedValues.lineItems ?? [];
  const subtotal = lineItems.reduce(
    (sum, li) => sum + (Number(li.quantity) || 0) * (Number(li.unitPrice) || 0),
@@ -165,6 +202,23 @@ export default function NewInvoicePage() {
                <CardTitle className="text-base">Client Information</CardTitle>
              </CardHeader>
              <CardContent className="space-y-4">
+                {isDepositInvoice ? (
+                  <div className="flex items-start gap-3 rounded-md border border-amber-200 bg-amber-50 px-3 py-2 text-sm text-amber-900">
+                    <Wallet className="mt-0.5 h-4 w-4 shrink-0" />
+                    <div className="min-w-0">
+                      <p className="font-medium">Deposit invoice</p>
+                      <p className="text-xs text-amber-800">
+                        {prefilledInterest?.data
+                          ? `Linked to ${prefilledInterest.data.clientName ?? 'interest'}${
+                              prefilledInterest.data.berthMooringNumber
+                                ? ` — Berth ${prefilledInterest.data.berthMooringNumber}`
+                                : ''
+                            }. Marking this invoice as paid will advance the interest to "Deposit 10%".`
+                          : 'Marking this invoice as paid will advance the linked interest to "Deposit 10%".'}
+                      </p>
+                    </div>
+                  </div>
+                ) : null}
                <div className="space-y-2">
                  <Label>
                    Billing entity <span className="text-destructive">*</span>
--- a/src/app/api/v1/interests/[id]/outcome/route.ts
+++ b/src/app/api/v1/interests/[id]/outcome/route.ts
@@ -0,0 +1,41 @@
+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 { clearInterestOutcome, setInterestOutcome } from '@/lib/services/interests.service';
+import { clearOutcomeSchema, setOutcomeSchema } from '@/lib/validators/interests';
+
+export const POST = withAuth(
+  withPermission('interests', 'change_stage', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, setOutcomeSchema);
+      const result = await setInterestOutcome(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: result });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
+
+export const DELETE = withAuth(
+  withPermission('interests', 'change_stage', async (req, ctx, params) => {
+    try {
+      const body = await parseBody(req, clearOutcomeSchema);
+      const result = await clearInterestOutcome(params.id!, ctx.portId, body, {
+        userId: ctx.userId,
+        portId: ctx.portId,
+        ipAddress: ctx.ipAddress,
+        userAgent: ctx.userAgent,
+      });
+      return NextResponse.json({ data: result });
+    } catch (error) {
+      return errorResponse(error);
+    }
+  }),
+);
--- a/src/components/documents/documents-hub.tsx
+++ b/src/components/documents/documents-hub.tsx
@@ -76,10 +76,11 @@ const STATUS_PILL_MAP: Record<string, StatusPillStatus> = {

 interface DocumentsHubProps {
  portSlug: string;
+  initialTab?: DocumentsHubTab;
 }

-export function DocumentsHub({ portSlug }: DocumentsHubProps) {
-  const [tab, setTab] = useState<DocumentsHubTab>('all');
+export function DocumentsHub({ portSlug, initialTab = 'all' }: DocumentsHubProps) {
+  const [tab, setTab] = useState<DocumentsHubTab>(initialTab);
  const [search, setSearch] = useState('');
  const [typeFilter, setTypeFilter] = useState<string>('all');
  const [signatureOnly, setSignatureOnly] = useState(true);
--- a/src/components/interests/interest-detail-header.tsx
+++ b/src/components/interests/interest-detail-header.tsx
@@ -2,43 +2,30 @@

 import { useState } from 'react';
 import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { Pencil, Archive, RotateCcw, TrendingUp } from 'lucide-react';
+import { Pencil, Archive, RotateCcw, Trophy, XCircle, RefreshCcw } from 'lucide-react';
 import Link from 'next/link';

-import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
 import { TagBadge } from '@/components/shared/tag-badge';
 import { ArchiveConfirmDialog } from '@/components/shared/archive-confirm-dialog';
 import { DetailHeaderStrip } from '@/components/shared/detail-header-strip';
 import { PermissionGate } from '@/components/shared/permission-gate';
 import { InterestForm } from '@/components/interests/interest-form';
-import { InterestStagePicker } from '@/components/interests/interest-stage-picker';
+import { InlineStagePicker } from '@/components/interests/inline-stage-picker';
+import { InterestOutcomeDialog } from '@/components/interests/interest-outcome-dialog';
 import { apiFetch } from '@/lib/api/client';
+import { cn } from '@/lib/utils';

-const STAGE_LABELS: Record<string, string> = {
-  open: 'Open',
-  details_sent: 'Details Sent',
-  in_communication: 'In Communication',
-  visited: 'Visited',
-  signed_eoi_nda: 'Signed EOI/NDA',
-  deposit_10pct: 'Deposit 10%',
-  contract: 'Contract',
-  completed: 'Completed',
-};
-
-const STAGE_COLORS: Record<string, string> = {
-  open: 'bg-slate-100 text-slate-700',
-  details_sent: 'bg-blue-100 text-blue-700',
-  in_communication: 'bg-sky-100 text-sky-700',
-  visited: 'bg-violet-100 text-violet-700',
-  signed_eoi_nda: 'bg-amber-100 text-amber-700',
-  deposit_10pct: 'bg-orange-100 text-orange-700',
-  contract: 'bg-green-100 text-green-700',
-  completed: 'bg-emerald-100 text-emerald-700',
+const OUTCOME_BADGE: Record<string, { label: string; className: string }> = {
+  won: { label: 'Won', className: 'bg-emerald-100 text-emerald-700' },
+  lost_other_marina: { label: 'Lost — other marina', className: 'bg-rose-100 text-rose-700' },
+  lost_unqualified: { label: 'Lost — unqualified', className: 'bg-rose-100 text-rose-700' },
+  lost_no_response: { label: 'Lost — no response', className: 'bg-rose-100 text-rose-700' },
+  cancelled: { label: 'Cancelled', className: 'bg-slate-200 text-slate-700' },
 };

 const CATEGORY_LABELS: Record<string, string> = {
-  general_interest: 'General Interest',
+  general_interest: 'General',
  specific_qualified: 'Specific Qualified',
  hot_lead: 'Hot Lead',
 };
@@ -58,6 +45,8 @@ interface InterestDetailHeaderProps {
    reminderEnabled: boolean;
    reminderDays: number | null;
    archivedAt: string | null;
+    outcome?: string | null;
+    outcomeReason?: string | null;
    tags?: Array<{ id: string; name: string; color: string }>;
  };
 }
@@ -66,9 +55,20 @@ export function InterestDetailHeader({ portSlug, interest }: InterestDetailHeade
  const queryClient = useQueryClient();
  const [editOpen, setEditOpen] = useState(false);
  const [archiveOpen, setArchiveOpen] = useState(false);
-  const [stageOpen, setStageOpen] = useState(false);
+  const [outcomeDialog, setOutcomeDialog] = useState<null | 'won' | 'lost'>(null);

  const isArchived = !!interest.archivedAt;
+  const outcomeBadge = interest.outcome ? OUTCOME_BADGE[interest.outcome] : null;
+  const isClosed = !!interest.outcome;
+
+  const reopenMutation = useMutation({
+    mutationFn: () =>
+      apiFetch(`/api/v1/interests/${interest.id}/outcome`, { method: 'DELETE', body: {} }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['interests', interest.id] });
+      queryClient.invalidateQueries({ queryKey: ['interests'] });
+    },
+  });

  const archiveMutation = useMutation({
    mutationFn: () => apiFetch(`/api/v1/interests/${interest.id}`, { method: 'DELETE' }),
@@ -88,13 +88,40 @@ export function InterestDetailHeader({ portSlug, interest }: InterestDetailHeade
    },
  });

+  const meta: Array<{ key: string; node: React.ReactNode }> = [];
+  if (interest.berthMooringNumber) {
+    meta.push({
+      key: 'berth',
+      node: (
+        <Link
+          href={`/${portSlug}/berths/${interest.berthId}`}
+          className="text-foreground hover:underline"
+        >
+          Berth {interest.berthMooringNumber}
+        </Link>
+      ),
+    });
+  }
+  if (interest.leadCategory) {
+    meta.push({
+      key: 'cat',
+      node: <span>{CATEGORY_LABELS[interest.leadCategory] ?? interest.leadCategory}</span>,
+    });
+  }
+  if (interest.source) {
+    meta.push({
+      key: 'src',
+      node: <span className="capitalize">{interest.source}</span>,
+    });
+  }
+
  return (
    <>
      <DetailHeaderStrip>
-        <div className="flex items-start gap-3 flex-wrap">
-          <div className="flex-1 min-w-0">
+        <div className="flex items-start gap-2">
+          <div className="min-w-0 flex-1 space-y-1.5">
            <div className="flex items-center gap-2 flex-wrap">
-              <h1 className="text-2xl font-bold text-foreground">
+              <h1 className="truncate text-lg font-bold text-foreground sm:text-xl">
                {interest.clientName ?? 'Unknown Client'}
              </h1>
              {isArchived && (
@@ -102,42 +129,52 @@ export function InterestDetailHeader({ portSlug, interest }: InterestDetailHeade
                  Archived
                </Badge>
              )}
-              <span
-                className={`inline-flex items-center rounded-full px-2.5 py-0.5 text-sm font-medium ${STAGE_COLORS[interest.pipelineStage] ?? 'bg-gray-100 text-gray-700'}`}
-              >
-                {STAGE_LABELS[interest.pipelineStage] ?? interest.pipelineStage}
-              </span>
+              {outcomeBadge ? (
+                <span
+                  className={cn(
+                    'inline-flex items-center rounded-full px-2.5 py-0.5 text-xs font-medium',
+                    outcomeBadge.className,
+                  )}
+                  title={interest.outcomeReason ?? undefined}
+                >
+                  {outcomeBadge.label}
+                </span>
+              ) : (
+                <PermissionGate
+                  resource="interests"
+                  action="change_stage"
+                  fallback={
+                    <span className="inline-flex items-center rounded-full bg-gray-100 px-2.5 py-0.5 text-xs font-medium text-gray-700">
+                      {interest.pipelineStage}
+                    </span>
+                  }
+                >
+                  <InlineStagePicker
+                    interestId={interest.id}
+                    currentStage={interest.pipelineStage}
+                    className="-ml-2.5"
+                  />
+                </PermissionGate>
+              )}
            </div>

-            <div className="flex items-center gap-4 mt-2 flex-wrap text-sm text-muted-foreground">
-              {interest.berthMooringNumber && (
-                <span>
-                  Berth:{' '}
-                  <Link
-                    href={`/${portSlug}/berths/${interest.berthId}`}
-                    className="text-foreground hover:underline"
-                  >
-                    {interest.berthMooringNumber}
-                  </Link>
-                </span>
-              )}
-              {interest.leadCategory && (
-                <span>
-                  Category:{' '}
-                  <span className="text-foreground">
-                    {CATEGORY_LABELS[interest.leadCategory] ?? interest.leadCategory}
+            {meta.length > 0 ? (
+              <p className="text-xs text-muted-foreground sm:text-sm">
+                {meta.map((m, i) => (
+                  <span key={m.key}>
+                    {i > 0 ? (
+                      <span aria-hidden className="mx-1.5">
+                        ·
+                      </span>
+                    ) : null}
+                    {m.node}
                  </span>
-                </span>
-              )}
-              {interest.source && (
-                <span>
-                  Source: <span className="text-foreground capitalize">{interest.source}</span>
-                </span>
-              )}
-            </div>
+                ))}
+              </p>
+            ) : null}

            {interest.tags && interest.tags.length > 0 && (
-              <div className="flex flex-wrap gap-1 mt-2">
+              <div className="flex flex-wrap gap-1 pt-0.5">
                {interest.tags.map((tag) => (
                  <TagBadge key={tag.id} name={tag.name} color={tag.color} />
                ))}
@@ -145,52 +182,101 @@ export function InterestDetailHeader({ portSlug, interest }: InterestDetailHeade
            )}
          </div>

-          {/* Actions */}
-          <div className="flex items-center gap-2 flex-wrap">
-            <PermissionGate resource="interests" action="edit">
-              <Button variant="outline" size="sm" onClick={() => setEditOpen(true)}>
-                <Pencil className="mr-1.5 h-3.5 w-3.5" />
-                Edit
-              </Button>
-            </PermissionGate>
+          {/* Top-right icon-only actions — no stacking, no labels eating room. */}
+          <div className="flex shrink-0 items-center gap-0.5">
            <PermissionGate resource="interests" action="change_stage">
-              <Button variant="outline" size="sm" onClick={() => setStageOpen(true)}>
-                <TrendingUp className="mr-1.5 h-3.5 w-3.5" />
-                Change Stage
-              </Button>
+              {isClosed ? (
+                <button
+                  type="button"
+                  onClick={() => reopenMutation.mutate()}
+                  disabled={reopenMutation.isPending}
+                  aria-label="Reopen interest"
+                  title="Reopen interest"
+                  className={cn(
+                    'rounded-md p-1.5 text-muted-foreground/70 transition-colors',
+                    'hover:bg-foreground/5 hover:text-foreground',
+                    'disabled:opacity-50',
+                  )}
+                >
+                  <RefreshCcw className="size-4" />
+                </button>
+              ) : (
+                <>
+                  <button
+                    type="button"
+                    onClick={() => setOutcomeDialog('won')}
+                    aria-label="Mark as won"
+                    title="Mark as won"
+                    className={cn(
+                      'rounded-md p-1.5 text-muted-foreground/70 transition-colors',
+                      'hover:bg-emerald-50 hover:text-emerald-700',
+                    )}
+                  >
+                    <Trophy className="size-4" />
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => setOutcomeDialog('lost')}
+                    aria-label="Close as lost"
+                    title="Close as lost"
+                    className={cn(
+                      'rounded-md p-1.5 text-muted-foreground/70 transition-colors',
+                      'hover:bg-rose-50 hover:text-rose-700',
+                    )}
+                  >
+                    <XCircle className="size-4" />
+                  </button>
+                </>
+              )}
+            </PermissionGate>
+            <PermissionGate resource="interests" action="edit">
+              <button
+                type="button"
+                onClick={() => setEditOpen(true)}
+                aria-label="Edit interest"
+                title="Edit interest"
+                className={cn(
+                  'rounded-md p-1.5 text-muted-foreground/70 transition-colors',
+                  'hover:bg-foreground/5 hover:text-foreground',
+                )}
+              >
+                <Pencil className="size-4" />
+              </button>
            </PermissionGate>
            <PermissionGate resource="interests" action="delete">
-              <Button variant="outline" size="sm" onClick={() => setArchiveOpen(true)}>
-                {isArchived ? (
-                  <>
-                    <RotateCcw className="mr-1.5 h-3.5 w-3.5" />
-                    Restore
-                  </>
-                ) : (
-                  <>
-                    <Archive className="mr-1.5 h-3.5 w-3.5" />
-                    Archive
-                  </>
+              <button
+                type="button"
+                onClick={() => setArchiveOpen(true)}
+                aria-label={isArchived ? 'Restore interest' : 'Archive interest'}
+                title={isArchived ? 'Restore interest' : 'Archive interest'}
+                className={cn(
+                  'rounded-md p-1.5 text-muted-foreground/70 transition-colors',
+                  'hover:bg-foreground/5',
+                  isArchived ? 'hover:text-foreground' : 'hover:text-destructive',
                )}
-              </Button>
+              >
+                {isArchived ? <RotateCcw className="size-4" /> : <Archive className="size-4" />}
+              </button>
            </PermissionGate>
          </div>
        </div>
      </DetailHeaderStrip>

+      {outcomeDialog && (
+        <InterestOutcomeDialog
+          interestId={interest.id}
+          mode={outcomeDialog}
+          open={outcomeDialog !== null}
+          onOpenChange={(open) => !open && setOutcomeDialog(null)}
+        />
+      )}
+
      <InterestForm
        open={editOpen}
        onOpenChange={setEditOpen}
        interest={interest as unknown as Parameters<typeof InterestForm>[0]['interest']}
      />

-      <InterestStagePicker
-        open={stageOpen}
-        onOpenChange={setStageOpen}
-        interestId={interest.id}
-        currentStage={interest.pipelineStage}
-      />
-
      <ArchiveConfirmDialog
        open={archiveOpen}
        onOpenChange={setArchiveOpen}
--- a/src/components/interests/interest-outcome-dialog.tsx
+++ b/src/components/interests/interest-outcome-dialog.tsx
@@ -0,0 +1,156 @@
+'use client';
+
+import { useState } from 'react';
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { Loader2, Trophy, XCircle } from 'lucide-react';
+
+import { Button } from '@/components/ui/button';
+import { Label } from '@/components/ui/label';
+import { Textarea } from '@/components/ui/textarea';
+import {
+  Dialog,
+  DialogContent,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@/components/ui/dialog';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select';
+import { apiFetch } from '@/lib/api/client';
+import { type InterestOutcome } from '@/lib/validators/interests';
+
+const OUTCOME_LABELS: Record<InterestOutcome, string> = {
+  won: 'Won',
+  lost_other_marina: 'Lost — went to another marina',
+  lost_unqualified: 'Lost — unqualified',
+  lost_no_response: 'Lost — no response',
+  cancelled: 'Cancelled',
+};
+
+const LOST_OUTCOMES: InterestOutcome[] = [
+  'lost_other_marina',
+  'lost_unqualified',
+  'lost_no_response',
+  'cancelled',
+];
+
+interface Props {
+  interestId: string;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Determines which outcomes are offered. 'won' opens with just the Won option preselected. */
+  mode: 'won' | 'lost';
+}
+
+export function InterestOutcomeDialog({ interestId, open, onOpenChange, mode }: Props) {
+  const queryClient = useQueryClient();
+  const choices: InterestOutcome[] = mode === 'won' ? ['won'] : LOST_OUTCOMES;
+  const [outcome, setOutcome] = useState<InterestOutcome>(choices[0]!);
+  const [reason, setReason] = useState('');
+
+  const mutation = useMutation({
+    mutationFn: () =>
+      apiFetch(`/api/v1/interests/${interestId}/outcome`, {
+        method: 'POST',
+        body: { outcome, reason: reason || undefined },
+      }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['interests', interestId] });
+      queryClient.invalidateQueries({ queryKey: ['interests'] });
+      onOpenChange(false);
+      setReason('');
+    },
+  });
+
+  function handleOpenChange(next: boolean) {
+    if (!next) {
+      setReason('');
+      setOutcome(choices[0]!);
+    }
+    onOpenChange(next);
+  }
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle className="flex items-center gap-2">
+            {mode === 'won' ? (
+              <Trophy className="h-4 w-4 text-emerald-600" />
+            ) : (
+              <XCircle className="h-4 w-4 text-rose-600" />
+            )}
+            {mode === 'won' ? 'Mark interest as won' : 'Close interest as lost'}
+          </DialogTitle>
+        </DialogHeader>
+
+        <div className="space-y-4 py-2">
+          {mode === 'lost' ? (
+            <div className="space-y-1">
+              <Label>Reason</Label>
+              <Select value={outcome} onValueChange={(v) => setOutcome(v as InterestOutcome)}>
+                <SelectTrigger>
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  {LOST_OUTCOMES.map((o) => (
+                    <SelectItem key={o} value={o}>
+                      {OUTCOME_LABELS[o]}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </div>
+          ) : null}
+
+          <div className="space-y-1">
+            <Label htmlFor="outcome-reason">Notes (optional)</Label>
+            <Textarea
+              id="outcome-reason"
+              value={reason}
+              onChange={(e) => setReason(e.target.value)}
+              placeholder={
+                mode === 'won'
+                  ? 'Anything notable about the win? (visible in timeline + reports)'
+                  : 'What happened? (visible in timeline + reports)'
+              }
+              rows={3}
+            />
+          </div>
+
+          <p className="text-xs text-muted-foreground">
+            This will move the interest to <strong>Completed</strong> and stamp the outcome. You can
+            reopen it later.
+          </p>
+        </div>
+
+        <DialogFooter>
+          <Button
+            variant="outline"
+            onClick={() => handleOpenChange(false)}
+            disabled={mutation.isPending}
+          >
+            Cancel
+          </Button>
+          <Button
+            onClick={() => mutation.mutate()}
+            disabled={mutation.isPending}
+            className={
+              mode === 'won'
+                ? 'bg-emerald-600 hover:bg-emerald-700'
+                : 'bg-rose-600 hover:bg-rose-700'
+            }
+          >
+            {mutation.isPending && <Loader2 className="mr-2 h-4 w-4 animate-spin" />}
+            {mode === 'won' ? 'Mark as won' : 'Close as lost'}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
--- a/src/components/interests/interest-tabs.tsx
+++ b/src/components/interests/interest-tabs.tsx
@@ -1,8 +1,10 @@
 'use client';

+import Link from 'next/link';
+import { useParams } from 'next/navigation';
 import { format, formatDistanceToNowStrict } from 'date-fns';
 import { useMutation, useQueryClient } from '@tanstack/react-query';
-import { CheckCircle2, Circle, FileSignature, Send, Wallet } from 'lucide-react';
+import { CheckCircle2, Circle, FileSignature, Plus, Send, Wallet } from 'lucide-react';

 import type { DetailTab } from '@/components/shared/detail-layout';
 import { Button } from '@/components/ui/button';
@@ -122,6 +124,8 @@ interface MilestoneSectionProps {
  status: string | null;
  onAdvance: (stage: string) => void;
  isPending: boolean;
+  /** Extra nodes (e.g. "Create deposit invoice" link) rendered below the steps. */
+  footer?: React.ReactNode;
 }

 /**
@@ -139,6 +143,7 @@ function MilestoneSection({
  status,
  onAdvance,
  isPending,
+  footer,
 }: MilestoneSectionProps) {
  const firstUnsetIdx = steps.findIndex((s) => !s.date);

@@ -209,6 +214,7 @@ function MilestoneSection({
          );
        })}
      </ol>
+      {footer ? <div className="mt-3 border-t pt-3 text-xs">{footer}</div> : null}
    </section>
  );
 }
@@ -220,6 +226,8 @@ function OverviewTab({
  interestId: string;
  interest: InterestTabsOptions['interest'];
 }) {
+  const params = useParams<{ portSlug: string }>();
+  const portSlug = params?.portSlug ?? '';
  const mutation = useInterestPatch(interestId);
  const stageMutation = useStageMutation(interestId);
  const save = (field: InterestPatchField) => async (next: string | null) => {
@@ -271,6 +279,17 @@ function OverviewTab({
              actionLabel: 'Mark deposit received',
            },
          ]}
+          footer={
+            !interest.dateDepositReceived ? (
+              <Link
+                href={`/${portSlug}/invoices/new?interestId=${interestId}&kind=deposit`}
+                className="inline-flex items-center gap-1.5 text-foreground/80 hover:text-foreground"
+              >
+                <Plus className="size-3.5" />
+                Create deposit invoice
+              </Link>
+            ) : null
+          }
        />
        <MilestoneSection
          title="Contract"
--- a/src/components/layout/sidebar.tsx
+++ b/src/components/layout/sidebar.tsx
@@ -12,6 +12,7 @@ import {
  Building2,
  Receipt,
  FileText,
+  FileSignature,
  FolderOpen,
  Mail,
  Bell,
@@ -97,6 +98,7 @@ function buildNavSections(portSlug: string | undefined): NavSection[] {
      marinaRequired: true,
      items: [
        { href: `${base}/documents`, label: 'Documents', icon: FileText },
+        { href: `${base}/documents/eoi`, label: 'EOI queue', icon: FileSignature },
        { href: `${base}/documents/files`, label: 'Files', icon: FolderOpen },
      ],
    },
--- a/src/lib/db/migrations/0019_lazy_vampiro.sql
+++ b/src/lib/db/migrations/0019_lazy_vampiro.sql
@@ -0,0 +1,8 @@
+ALTER TABLE "invoices" ADD COLUMN "interest_id" text;--> statement-breakpoint
+ALTER TABLE "invoices" ADD COLUMN "kind" text DEFAULT 'general' NOT NULL;--> statement-breakpoint
+ALTER TABLE "interests" ADD COLUMN "outcome" text;--> statement-breakpoint
+ALTER TABLE "interests" ADD COLUMN "outcome_reason" text;--> statement-breakpoint
+ALTER TABLE "interests" ADD COLUMN "outcome_at" timestamp with time zone;--> statement-breakpoint
+ALTER TABLE "invoices" ADD CONSTRAINT "invoices_interest_id_interests_id_fk" FOREIGN KEY ("interest_id") REFERENCES "public"."interests"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+CREATE INDEX "idx_invoices_interest" ON "invoices" USING btree ("port_id","interest_id");--> statement-breakpoint
+CREATE INDEX "idx_interests_outcome" ON "interests" USING btree ("port_id","outcome");
--- a/src/lib/db/migrations/meta/0019_snapshot.json
+++ b/src/lib/db/migrations/meta/0019_snapshot.json
--- a/src/lib/db/migrations/meta/_journal.json
+++ b/src/lib/db/migrations/meta/_journal.json
@@ -134,6 +134,13 @@
      "when": 1777399135032,
      "tag": "0018_stormy_spencer_smythe",
      "breakpoints": true
+    },
+    {
+      "idx": 19,
+      "version": "7",
+      "when": 1777671562738,
+      "tag": "0019_lazy_vampiro",
+      "breakpoints": true
    }
  ]
 }
--- a/src/lib/db/schema/financial.ts
+++ b/src/lib/db/schema/financial.ts
@@ -14,6 +14,7 @@ import {
 import { sql } from 'drizzle-orm';
 import { ports } from './ports';
 import { files } from './documents';
+import { interests } from './interests';

 export const expenses = pgTable(
  'expenses',
@@ -98,6 +99,13 @@ export const invoices = pgTable(
    paymentMethod: text('payment_method'),
    paymentReference: text('payment_reference'),
    pdfFileId: text('pdf_file_id').references(() => files.id),
+    /** Optional link to a sales interest. When the invoice is paid and `kind`
+     *  is 'deposit', recordPayment auto-advances the interest's pipelineStage
+     *  to deposit_10pct (no-op if already further along). */
+    interestId: text('interest_id').references(() => interests.id, { onDelete: 'set null' }),
+    /** Invoice kind. 'general' (default) is everyday billing; 'deposit' marks
+     *  the 10% berth-purchase deposit and is what triggers the stage advance. */
+    kind: text('kind').notNull().default('general'), // 'general' | 'deposit'
    notes: text('notes'),
    createdBy: text('created_by').notNull(),
    archivedAt: timestamp('archived_at', { withTimezone: true }),
@@ -113,6 +121,7 @@ export const invoices = pgTable(
      table.billingEntityType,
      table.billingEntityId,
    ),
+    index('idx_invoices_interest').on(table.portId, table.interestId),
  ],
 );

--- a/src/lib/db/schema/interests.ts
+++ b/src/lib/db/schema/interests.ts
@@ -2,7 +2,7 @@ import { pgTable, text, boolean, integer, timestamp, primaryKey, index } from 'd
 import { ports } from './ports';
 import { clients } from './clients';

-// Pipeline stages: open, details_sent, in_communication, visited, signed_eoi_nda, deposit_10pct, contract, completed
+// Pipeline stages: open, details_sent, in_communication, eoi_sent, eoi_signed, deposit_10pct, contract_sent, contract_signed, completed

 export const interests = pgTable(
  'interests',
@@ -36,6 +36,16 @@ export const interests = pgTable(
    reminderEnabled: boolean('reminder_enabled').notNull().default(false),
    reminderDays: integer('reminder_days'),
    reminderLastFired: timestamp('reminder_last_fired', { withTimezone: true }),
+    /** Terminal outcome. Independent of pipelineStage — `outcome` is set
+     *  alongside the stage transition to `completed` to distinguish won
+     *  deals from the various lost variants. NULL while the interest is
+     *  still active. */
+    outcome: text('outcome'), // 'won' | 'lost_other_marina' | 'lost_unqualified' | 'lost_no_response' | 'cancelled'
+    /** Free-text reason captured at the time the outcome is set. Surfaces
+     *  in the timeline + reports. */
+    outcomeReason: text('outcome_reason'),
+    /** When the outcome was decided. Lets us age 'how long ago did we lose'. */
+    outcomeAt: timestamp('outcome_at', { withTimezone: true }),
    notes: text('notes'),
    archivedAt: timestamp('archived_at', { withTimezone: true }),
    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
@@ -48,6 +58,7 @@ export const interests = pgTable(
    index('idx_interests_yacht').on(table.yachtId),
    index('idx_interests_stage').on(table.portId, table.pipelineStage),
    index('idx_interests_archived').on(table.portId, table.archivedAt),
+    index('idx_interests_outcome').on(table.portId, table.outcome),
  ],
 );

--- a/src/lib/services/analytics.service.ts
+++ b/src/lib/services/analytics.service.ts
@@ -38,6 +38,10 @@ export const SNAPSHOT_TTL_MS = 15 * 60 * 1000; // 15 minutes

 export interface PipelineFunnelData {
  stages: Array<{ stage: string; count: number; conversionPct: number }>;
+  /** Counts of terminal lost/cancelled outcomes in the range. Surfaces below
+   *  the funnel so users can see leakage without it polluting the conversion
+   *  math. Total = sum of these counts. */
+  lost: { count: number; byOutcome: Record<string, number> };
 }

 export interface OccupancyTimelineData {
@@ -123,7 +127,11 @@ export async function computePipelineFunnel(
  range: DateRange,
 ): Promise<PipelineFunnelData> {
  const cutoff = rangeToCutoff(range);
-  const rows = await db
+
+  // Stage counts EXCLUDE lost/cancelled outcomes — those never become
+  // conversions, so polluting the funnel with them gives meaningless math.
+  // Lost is reported separately in the `lost` block.
+  const stageRows = await db
    .select({ stage: interests.pipelineStage, count: sql<number>`count(*)::int` })
    .from(interests)
    .where(
@@ -131,11 +139,12 @@ export async function computePipelineFunnel(
        eq(interests.portId, portId),
        isNull(interests.archivedAt),
        gte(interests.createdAt, cutoff),
+        sql`(${interests.outcome} IS NULL OR ${interests.outcome} = 'won')`,
      ),
    )
    .groupBy(interests.pipelineStage);

-  const counts = new Map(rows.map((r) => [r.stage, r.count]));
+  const counts = new Map(stageRows.map((r) => [r.stage, r.count]));
  const top = counts.get('open') ?? 0;

  const stages = PIPELINE_STAGES.map((stage) => {
@@ -144,7 +153,29 @@ export async function computePipelineFunnel(
    return { stage, count, conversionPct };
  });

-  return { stages };
+  // Lost / cancelled summary. Same date-range filter as the funnel.
+  const lostRows = await db
+    .select({ outcome: interests.outcome, count: sql<number>`count(*)::int` })
+    .from(interests)
+    .where(
+      and(
+        eq(interests.portId, portId),
+        isNull(interests.archivedAt),
+        gte(interests.createdAt, cutoff),
+        sql`${interests.outcome} IS NOT NULL AND ${interests.outcome} != 'won'`,
+      ),
+    )
+    .groupBy(interests.outcome);
+
+  const byOutcome: Record<string, number> = {};
+  let lostTotal = 0;
+  for (const row of lostRows) {
+    if (!row.outcome) continue;
+    byOutcome[row.outcome] = row.count;
+    lostTotal += row.count;
+  }
+
+  return { stages, lost: { count: lostTotal, byOutcome } };
 }

 export async function computeOccupancyTimeline(
--- a/src/lib/services/dashboard.service.ts
+++ b/src/lib/services/dashboard.service.ts
@@ -9,6 +9,11 @@ import { PIPELINE_STAGES, STAGE_WEIGHTS } from '@/lib/constants';

 const DEFAULT_PIPELINE_WEIGHTS: Record<string, number> = STAGE_WEIGHTS;

+// "Active" = not archived AND not closed as lost/cancelled. Won interests are
+// still counted because they represent revenue. Used everywhere KPIs say
+// "active interests" or "pipeline value".
+const isActiveInterest = sql`(${interests.outcome} IS NULL OR ${interests.outcome} = 'won')`;
+
 // ─── KPIs ─────────────────────────────────────────────────────────────────────

 export async function getKpis(portId: string) {
@@ -20,7 +25,7 @@ export async function getKpis(portId: string) {
  const [activeInterestsRow] = await db
    .select({ value: count() })
    .from(interests)
-    .where(and(eq(interests.portId, portId), isNull(interests.archivedAt)));
+    .where(and(eq(interests.portId, portId), isNull(interests.archivedAt), isActiveInterest));

  // Pipeline value: SUM berths.price via JOIN from non-archived interests with berthId
  const pipelineRows = await db
@@ -31,6 +36,7 @@ export async function getKpis(portId: string) {
      and(
        eq(interests.portId, portId),
        isNull(interests.archivedAt),
+        isActiveInterest,
        sql`${interests.berthId} IS NOT NULL`,
      ),
    );
@@ -68,7 +74,7 @@ export async function getPipelineCounts(portId: string) {
      count: sql<number>`count(*)::int`,
    })
    .from(interests)
-    .where(and(eq(interests.portId, portId), isNull(interests.archivedAt)))
+    .where(and(eq(interests.portId, portId), isNull(interests.archivedAt), isActiveInterest))
    .groupBy(interests.pipelineStage);

  const countsByStage = Object.fromEntries(rows.map((r) => [r.stage, r.count]));
@@ -102,7 +108,8 @@ export async function getRevenueForecast(portId: string) {
    }
  }

-  // Fetch all non-archived interests with a linked berth and its price
+  // Forecast excludes lost/cancelled — only currently-active or won-out
+  // interests should affect the weighted pipeline value.
  const interestRows = await db
    .select({
      id: interests.id,
@@ -115,6 +122,7 @@ export async function getRevenueForecast(portId: string) {
      and(
        eq(interests.portId, portId),
        isNull(interests.archivedAt),
+        isActiveInterest,
        sql`${interests.berthId} IS NOT NULL`,
      ),
    );
--- a/src/lib/services/interests.service.ts
+++ b/src/lib/services/interests.service.ts
@@ -20,6 +20,8 @@ import type {
  UpdateInterestInput,
  ChangeStageInput,
  ListInterestsInput,
+  SetOutcomeInput,
+  ClearOutcomeInput,
 } from '@/lib/validators/interests';

 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -578,6 +580,110 @@ export async function advanceStageIfBehind(
  return true;
 }

+// ─── Set Outcome (Won / Lost) ────────────────────────────────────────────────
+//
+// Records a terminal outcome for the interest and moves the pipelineStage to
+// `completed` so the funnel/kanban reflect the final state. The outcome
+// distinguishes won deals (they made it through) from lost variants — funnel
+// math and reports key off the `outcome` column to compute true conversion.
+//
+// Both the stage advance and the outcome write happen in one transaction so
+// the timeline doesn't end up showing one without the other.
+export async function setInterestOutcome(
+  id: string,
+  portId: string,
+  data: SetOutcomeInput,
+  meta: AuditMeta,
+) {
+  const existing = await db.query.interests.findFirst({
+    where: and(eq(interests.id, id), eq(interests.portId, portId)),
+  });
+  if (!existing) throw new NotFoundError('Interest');
+
+  const oldOutcome = existing.outcome;
+  const oldStage = existing.pipelineStage;
+
+  const now = new Date();
+  await db
+    .update(interests)
+    .set({
+      outcome: data.outcome,
+      outcomeReason: data.reason ?? null,
+      outcomeAt: now,
+      pipelineStage: 'completed',
+      updatedAt: now,
+    })
+    .where(and(eq(interests.id, id), eq(interests.portId, portId)));
+
+  void createAuditLog({
+    userId: meta.userId,
+    portId,
+    action: 'update',
+    entityType: 'interest',
+    entityId: id,
+    oldValue: { outcome: oldOutcome, pipelineStage: oldStage },
+    newValue: { outcome: data.outcome, pipelineStage: 'completed', reason: data.reason },
+    metadata: { type: 'outcome_set' },
+    ipAddress: meta.ipAddress,
+    userAgent: meta.userAgent,
+  });
+
+  emitToRoom(`port:${portId}`, 'interest:outcomeSet', {
+    interestId: id,
+    outcome: data.outcome,
+    oldStage,
+  });
+
+  return { ok: true as const };
+}
+
+// Clears a terminal outcome and reopens the interest. Used when an outcome
+// was set in error or a "lost" deal comes back to life.
+export async function clearInterestOutcome(
+  id: string,
+  portId: string,
+  data: ClearOutcomeInput,
+  meta: AuditMeta,
+) {
+  const existing = await db.query.interests.findFirst({
+    where: and(eq(interests.id, id), eq(interests.portId, portId)),
+  });
+  if (!existing) throw new NotFoundError('Interest');
+  if (!existing.outcome) {
+    throw new ValidationError('Interest has no outcome to clear');
+  }
+
+  const reopenStage = data.reopenStage ?? 'in_communication';
+  const now = new Date();
+  await db
+    .update(interests)
+    .set({
+      outcome: null,
+      outcomeReason: null,
+      outcomeAt: null,
+      pipelineStage: reopenStage,
+      updatedAt: now,
+    })
+    .where(and(eq(interests.id, id), eq(interests.portId, portId)));
+
+  void createAuditLog({
+    userId: meta.userId,
+    portId,
+    action: 'update',
+    entityType: 'interest',
+    entityId: id,
+    oldValue: { outcome: existing.outcome, pipelineStage: existing.pipelineStage },
+    newValue: { outcome: null, pipelineStage: reopenStage },
+    metadata: { type: 'outcome_cleared' },
+    ipAddress: meta.ipAddress,
+    userAgent: meta.userAgent,
+  });
+
+  emitToRoom(`port:${portId}`, 'interest:outcomeCleared', { interestId: id });
+
+  return { ok: true as const };
+}
+
 // ─── Archive / Restore ────────────────────────────────────────────────────────

 export async function archiveInterest(id: string, portId: string, meta: AuditMeta) {
--- a/src/lib/services/invoices.ts
+++ b/src/lib/services/invoices.ts
@@ -249,7 +249,7 @@ export async function createInvoice(portId: string, data: CreateInvoiceInput, me

    // Calculate subtotal from line items
    const lineItemsData = data.lineItems ?? [];
-    const subtotal = lineItemsData.reduce((sum, li) => sum + li.quantity * li.unitPrice, 0);
+    const subtotal = lineItemsData.reduce((sum, li) => sum + (li.quantity ?? 1) * li.unitPrice, 0);

    // BR-042: net10 discount — read from systemSettings
    let discountPct = 0;
@@ -294,6 +294,20 @@ export async function createInvoice(portId: string, data: CreateInvoiceInput, me
      }
    }

+    // Sanity-check the optional interest link: must belong to the same port.
+    // Foreign-port ids fail with ValidationError before the insert.
+    if (data.interestId) {
+      const { interests } = await import('@/lib/db/schema/interests');
+      const [interestRow] = await tx
+        .select({ portId: interests.portId })
+        .from(interests)
+        .where(eq(interests.id, data.interestId))
+        .limit(1);
+      if (!interestRow || interestRow.portId !== portId) {
+        throw new ValidationError('interestId not found in this port');
+      }
+    }
+
    const [newInvoice] = await tx
      .insert(invoices)
      .values({
@@ -315,6 +329,8 @@ export async function createInvoice(portId: string, data: CreateInvoiceInput, me
        total: String(total),
        status: 'draft',
        paymentStatus: 'unpaid',
+        interestId: data.interestId ?? null,
+        kind: data.kind ?? 'general',
        notes: data.notes ?? null,
        createdBy: meta.userId,
      })
@@ -328,9 +344,9 @@ export async function createInvoice(portId: string, data: CreateInvoiceInput, me
        lineItemsData.map((li, idx) => ({
          invoiceId: newInvoice.id,
          description: li.description,
-          quantity: String(li.quantity),
+          quantity: String(li.quantity ?? 1),
          unitPrice: String(li.unitPrice),
-          total: String(li.quantity * li.unitPrice),
+          total: String((li.quantity ?? 1) * li.unitPrice),
          sortOrder: idx,
        })),
      );
@@ -393,11 +409,29 @@ export async function updateInvoice(
    if (data.paymentTerms !== undefined) updateData.paymentTerms = data.paymentTerms;
    if (data.currency !== undefined) updateData.currency = data.currency;
    if (data.notes !== undefined) updateData.notes = data.notes;
+    if (data.interestId !== undefined) {
+      if (data.interestId !== null) {
+        const { interests } = await import('@/lib/db/schema/interests');
+        const [interestRow] = await tx
+          .select({ portId: interests.portId })
+          .from(interests)
+          .where(eq(interests.id, data.interestId))
+          .limit(1);
+        if (!interestRow || interestRow.portId !== portId) {
+          throw new ValidationError('interestId not found in this port');
+        }
+      }
+      updateData.interestId = data.interestId;
+    }
+    if (data.kind !== undefined) updateData.kind = data.kind;

    // Recalculate totals if line items changed
    if (data.lineItems !== undefined) {
      const lineItemsData = data.lineItems;
-      const subtotal = lineItemsData.reduce((sum, li) => sum + li.quantity * li.unitPrice, 0);
+      const subtotal = lineItemsData.reduce(
+        (sum, li) => sum + (li.quantity ?? 1) * li.unitPrice,
+        0,
+      );

      const paymentTerms = data.paymentTerms ?? existing.paymentTerms;
      let discountPct = 0;
@@ -434,9 +468,9 @@ export async function updateInvoice(
          lineItemsData.map((li, idx) => ({
            invoiceId: id,
            description: li.description,
-            quantity: String(li.quantity),
+            quantity: String(li.quantity ?? 1),
            unitPrice: String(li.unitPrice),
-            total: String(li.quantity * li.unitPrice),
+            total: String((li.quantity ?? 1) * li.unitPrice),
            sortOrder: idx,
          })),
        );
@@ -693,6 +727,20 @@ export async function recordPayment(
    amount: Number(existing.total),
  });

+  // Deposit invoices linked to a sales interest auto-advance the pipeline.
+  // Only advances forward — no-op if the interest has already moved past
+  // deposit_10pct (e.g. straight-to-contract flows).
+  if (updated.kind === 'deposit' && updated.interestId) {
+    const { advanceStageIfBehind } = await import('@/lib/services/interests.service');
+    void advanceStageIfBehind(
+      updated.interestId,
+      portId,
+      'deposit_10pct',
+      meta,
+      `Deposit invoice ${existing.invoiceNumber} paid`,
+    );
+  }
+
  return updated;
 }

--- a/src/lib/socket/events.ts
+++ b/src/lib/socket/events.ts
@@ -53,6 +53,12 @@ export interface ServerToClientEvents {
  'interest:berthLinked': (payload: { interestId: string; berthId: string }) => void;
  'interest:berthUnlinked': (payload: { interestId: string; berthId: string }) => void;
  'interest:archived': (payload: { interestId: string }) => void;
+  'interest:outcomeSet': (payload: {
+    interestId: string;
+    outcome: string;
+    oldStage: string;
+  }) => void;
+  'interest:outcomeCleared': (payload: { interestId: string }) => void;
  'interest:noteAdded': (payload: {
    interestId: string;
    noteId: string;
--- a/src/lib/validators/interests.ts
+++ b/src/lib/validators/interests.ts
@@ -36,6 +36,28 @@ export const changeStageSchema = z.object({
  reason: z.string().optional(),
 });

+// ─── Outcome (Won / Lost) ─────────────────────────────────────────────────────
+
+export const INTEREST_OUTCOMES = [
+  'won',
+  'lost_other_marina',
+  'lost_unqualified',
+  'lost_no_response',
+  'cancelled',
+] as const;
+
+export type InterestOutcome = (typeof INTEREST_OUTCOMES)[number];
+
+export const setOutcomeSchema = z.object({
+  outcome: z.enum(INTEREST_OUTCOMES),
+  reason: z.string().max(2000).optional(),
+});
+
+export const clearOutcomeSchema = z.object({
+  // Stage to revert to when reopening (defaults to in_communication).
+  reopenStage: z.enum(PIPELINE_STAGES).optional(),
+});
+
 // ─── List ─────────────────────────────────────────────────────────────────────

 export const listInterestsSchema = baseListQuerySchema.extend({
@@ -168,3 +190,5 @@ export type ListInterestsInput = z.infer<typeof listInterestsSchema>;
 export type WaitingListAddInput = z.infer<typeof waitingListAddSchema>;
 export type PublicInterestInput = z.infer<typeof publicInterestSchema>;
 export type ReorderWaitingListInput = z.infer<typeof reorderWaitingListSchema>;
+export type SetOutcomeInput = z.infer<typeof setOutcomeSchema>;
+export type ClearOutcomeInput = z.infer<typeof clearOutcomeSchema>;
--- a/src/lib/validators/invoices.ts
+++ b/src/lib/validators/invoices.ts
@@ -1,6 +1,9 @@
 import { z } from 'zod';
 import { baseListQuerySchema } from '@/lib/api/route-helpers';

+export const INVOICE_KINDS = ['general', 'deposit'] as const;
+export type InvoiceKind = (typeof INVOICE_KINDS)[number];
+
 export const createInvoiceSchema = z
  .object({
    billingEntity: z.object({
@@ -15,6 +18,9 @@ export const createInvoiceSchema = z
      .default('net30'),
    currency: z.string().length(3).default('USD'),
    notes: z.string().max(2000).optional(),
+    /** Optional link to a sales interest. Required when kind === 'deposit'. */
+    interestId: z.string().min(1).optional(),
+    kind: z.enum(INVOICE_KINDS).default('general'),
    lineItems: z
      .array(
        z.object({
@@ -26,6 +32,10 @@ export const createInvoiceSchema = z
      .optional(),
    expenseIds: z.array(z.string()).optional(),
  })
+  .refine((data) => data.kind !== 'deposit' || !!data.interestId, {
+    message: 'Deposit invoices must be linked to an interest',
+    path: ['interestId'],
+  })
  .refine(
    (data) =>
      (data.lineItems && data.lineItems.length > 0) ||
@@ -41,6 +51,8 @@ export const updateInvoiceSchema = z.object({
  paymentTerms: z.enum(['immediate', 'net10', 'net15', 'net30', 'net45', 'net60']).optional(),
  currency: z.string().length(3).optional(),
  notes: z.string().max(2000).optional(),
+  interestId: z.string().min(1).nullable().optional(),
+  kind: z.enum(INVOICE_KINDS).optional(),
  lineItems: z
    .array(
      z.object({
@@ -68,7 +80,10 @@ export const listInvoicesSchema = baseListQuerySchema.extend({
  billingEntityId: z.string().optional(),
 });

-export type CreateInvoiceInput = z.infer<typeof createInvoiceSchema>;
-export type UpdateInvoiceInput = z.infer<typeof updateInvoiceSchema>;
+// `z.input` keeps fields with `.default()` (paymentTerms, currency, kind)
+// optional from the caller's perspective. The schema parser still fills in
+// the defaults, so the service body can rely on them being present at runtime.
+export type CreateInvoiceInput = z.input<typeof createInvoiceSchema>;
+export type UpdateInvoiceInput = z.input<typeof updateInvoiceSchema>;
 export type RecordPaymentInput = z.infer<typeof recordPaymentSchema>;
 export type ListInvoicesInput = z.infer<typeof listInvoicesSchema>;