letsbe/pn-new-crm
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Matt Ciaccio
2026-05-02 00:01:33 +02:00
parent 886119cbde
commit ba5fb6db5e
21 changed files with 10995 additions and 112 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
src/lib/db/migrations/0019_lazy_vampiro.sql Normal file
View File

@@ -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");

10240
src/lib/db/migrations/meta/0019_snapshot.json Normal file
View File

File diff suppressed because it is too large Load Diff

7
src/lib/db/migrations/meta/_journal.json
View File

@@ -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
}
]
}

9
src/lib/db/schema/financial.ts
View File

@@ -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),
],
);

13
src/lib/db/schema/interests.ts
View File

@@ -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),
],
);

37
src/lib/services/analytics.service.ts
View File

@@ -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(

14
src/lib/services/dashboard.service.ts
View File

@@ -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`,
),
);

106
src/lib/services/interests.service.ts
View File

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

60
src/lib/services/invoices.ts
View File

@@ -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;
}

6
src/lib/socket/events.ts
View File

@@ -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;

24
src/lib/validators/interests.ts
View File

@@ -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>;

19
src/lib/validators/invoices.ts
View File

@@ -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>;