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>

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) {