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

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