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

fix(audit): interests/pipeline — M1 (outcome terminal guard), M3 (single-UPDATE + milestone gating), L1 (dead 'completed'), L2 (nurturing edge), L24 (deposit re-lock on refund)

Browse Source 
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Matt
2026-06-02 12:52:24 +02:00
parent 0ed4323826
commit 49f5c3165b
3 changed files with 146 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
src/lib/constants.ts
View File

@@ -138,7 +138,9 @@ export const STAGE_WEIGHTS: Record<PipelineStage, number> = {
* and can re-enter the EOI path when supply opens up.
*/
export const STAGE_TRANSITIONS: Record<PipelineStage, readonly PipelineStage[]> = {
enquiry: ['qualified', 'eoi'],
// L2: include `nurturing` so a fresh enquiry can be parked straight into
// the nurturing column without first round-tripping through `qualified`.
enquiry: ['qualified', 'nurturing', 'eoi'],
qualified: ['enquiry', 'nurturing', 'eoi'],
nurturing: ['qualified', 'eoi'],
eoi: ['qualified', 'reservation', 'deposit_paid'],

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

@@ -38,6 +38,7 @@ import {
PIPELINE_STAGES,
STAGE_LABELS,
canTransitionStage,
canonicalizeStage,
type PipelineStage,
} from '@/lib/constants';
import type {
@@ -1067,7 +1068,17 @@ export async function changeInterestStage(
portId: string,
data: ChangeStageInput,
meta: AuditMeta,
// M3: distinguishes a manual/UI stage move (the /stage route + bulk route
// call this directly) from a lifecycle/signing-driven advance routed
// through advanceStageIfBehind (EOI sent/signed, deposit met, contract
// signed, reservation signed, custom-doc upload). For signing-driven
// advances the milestone date is owned by the doc-send/sign flow that
// already stamped the real event timestamp - auto-stamping `now` here on
// top of it back-dates "sent → signed" to ~0. So we only auto-populate
// milestone columns when `lifecycleDriven` is false (manual/UI move).
options?: { lifecycleDriven?: boolean },
) {
const lifecycleDriven = options?.lifecycleDriven ?? false;
const existing = await db.query.interests.findFirst({
where: eq(interests.id, id),
});
@@ -1137,31 +1148,32 @@ export async function changeInterestStage(
const oldStage = existing.pipelineStage;
const [updated] = await db
.update(interests)
.set({ pipelineStage: data.pipelineStage, updatedAt: new Date() })
.where(and(eq(interests.id, id), eq(interests.portId, portId)))
.returning();
// BR-133: Auto-populate milestones based on stage. The rep can override the
// stamp via `milestoneDate` when they're back-dating a real event (e.g.
// "deposit landed yesterday"); we still default to now when omitted.
const milestoneDate = data.milestoneDate ? new Date(data.milestoneDate) : new Date();
//
// M3: only stamp milestone columns for manual/UI moves. Lifecycle/signing-
// driven advances (routed through advanceStageIfBehind) get their milestone
// dates from the doc-send/sign flow that already recorded the true event
// timestamp; auto-stamping `now` here on top of that back-dates intervals
// like "contract sent → signed" to ~0. Folding this into the same UPDATE as
// the stage change also removes the previous non-transactional double-write.
const milestoneUpdates: Record<string, unknown> = {};
// For doc-bearing stages (eoi/reservation/contract) the milestone date is
// owned by the doc-send/sign flow, not the stage move - these only fire
// when the rep stamps a date manually via override.
if (data.pipelineStage === 'eoi') milestoneUpdates.dateEoiSent = milestoneDate;
if (data.pipelineStage === 'reservation') milestoneUpdates.dateReservationSigned = milestoneDate;
if (data.pipelineStage === 'deposit_paid') milestoneUpdates.dateDepositReceived = milestoneDate;
if (data.pipelineStage === 'contract') milestoneUpdates.dateContractSent = milestoneDate;
if (Object.keys(milestoneUpdates).length > 0) {
await db
.update(interests)
.set({ ...milestoneUpdates, updatedAt: new Date() })
.where(eq(interests.id, id));
if (!lifecycleDriven) {
const milestoneDate = data.milestoneDate ? new Date(data.milestoneDate) : new Date();
if (data.pipelineStage === 'eoi') milestoneUpdates.dateEoiSent = milestoneDate;
if (data.pipelineStage === 'reservation')
milestoneUpdates.dateReservationSigned = milestoneDate;
if (data.pipelineStage === 'deposit_paid') milestoneUpdates.dateDepositReceived = milestoneDate;
if (data.pipelineStage === 'contract') milestoneUpdates.dateContractSent = milestoneDate;
}
const [updated] = await db
.update(interests)
.set({ pipelineStage: data.pipelineStage, ...milestoneUpdates, updatedAt: new Date() })
.where(and(eq(interests.id, id), eq(interests.portId, portId)))
.returning();
void createAuditLog({
userId: meta.userId,
portId,
@@ -1280,7 +1292,14 @@ export async function advanceStageIfBehind(
return false;
}
await changeInterestStage(interestId, portId, { pipelineStage: target, reason }, meta);
// M3: this helper is the single funnel for every lifecycle/signing-driven
// advance (EOI sent/signed, deposit met, contract signed, reservation
// signed, custom-doc upload). Flag the move so changeInterestStage does not
// auto-stamp milestone dates - those are owned by the doc-send/sign flow,
// which already recorded the real event timestamp.
await changeInterestStage(interestId, portId, { pipelineStage: target, reason }, meta, {
lifecycleDriven: true,
});
return true;
}
@@ -1366,6 +1385,19 @@ export async function setInterestOutcome(
});
if (!existing) throw new NotFoundError('Interest');
// M1: terminal-state guard. Once an outcome is set this method must not run
// again - re-firing it (won→lost flip, double-submit, an idempotent webhook
// retry) would re-evaluate the berth rule, rename the document folder, write
// a duplicate audit row, re-emit the socket event and re-fire the Umami
// event. Mirrors clearInterestOutcome's `if (!existing.outcome)` guard:
// changing a recorded outcome requires clearing it first (which reopens the
// deal), so the side effects only ever run on a genuine close transition.
if (existing.outcome) {
throw new ConflictError(
'Interest already has an outcome. Clear the current outcome before setting a new one.',
);
}
const oldOutcome = existing.outcome;
const stageAtOutcome = existing.pipelineStage;
@@ -1453,16 +1485,17 @@ export async function clearInterestOutcome(
// Reopen-stage logic:
// - If the caller passed `data.reopenStage`, honor it (rep override).
// - Else if the current stage is the legacy 'completed' sentinel,
// default to 'qualified' (closest analog of the pre-refactor
// 'in_communication' which would have lived there).
// - Else preserve the current stage - post-refactor setOutcome stops
// touching pipelineStage, so the deal already knows where it was
// when the rep closed it. Reopening should drop the rep back into
// that same column on the kanban.
const reopenStage =
data.reopenStage ??
(existing.pipelineStage === 'completed' ? 'qualified' : existing.pipelineStage);
// L1: the dead `pipelineStage === 'completed' ? 'qualified'` branch is
// removed (the 'completed' sentinel was dropped in the 9→7 migration).
// Any legacy stage value still on the row is folded to its canonical
// 7-stage equivalent via canonicalizeStage so a pre-migration
// 'completed' row reopens to `contract` (its true pre-close stage) and
// never re-enters the kanban with a non-canonical value.
const reopenStage = data.reopenStage ?? canonicalizeStage(existing.pipelineStage);
const now = new Date();
await db
.update(interests)

86
src/lib/services/payments.service.ts
View File

@@ -11,7 +11,7 @@
import { and, asc, desc, eq, sql } from 'drizzle-orm';
import { db } from '@/lib/db';
import { interests, payments } from '@/lib/db/schema';
import { berths, interests, payments } from '@/lib/db/schema';
import { createAuditLog, type AuditMeta } from '@/lib/audit';
import { NotFoundError, ValidationError } from '@/lib/errors';
import { emitToRoom } from '@/lib/socket/server';
@@ -102,6 +102,10 @@ export async function createPayment(portId: string, data: CreatePaymentInput, me
depositExpectedAmount: true,
depositExpectedCurrency: true,
pipelineStage: true,
// L24: needed to tell whether the deposit gate had previously fired
// (so a later refund can recompute it and re-lock if net drops below
// expected).
dateDepositReceived: true,
},
});
if (!interest) throw new NotFoundError('Interest');
@@ -164,7 +168,9 @@ export async function createPayment(portId: string, data: CreatePaymentInput, me
const expectedCurrency = interest.depositExpectedCurrency ?? 'EUR';
const { total } = await getDepositTotalForInterest(data.interestId, portId, expectedCurrency);
const expected = interest.depositExpectedAmount ? Number(interest.depositExpectedAmount) : null;
if (expected !== null && Number.isFinite(expected) && Number(total) >= expected) {
const gateMet = expected !== null && Number.isFinite(expected) && Number(total) >= expected;
if (gateMet) {
const { advanceStageIfBehindGated } = await import('@/lib/services/interests.service');
void advanceStageIfBehindGated(
data.interestId,
@@ -185,6 +191,82 @@ export async function createPayment(portId: string, data: CreatePaymentInput, me
// Berth rule fires via the same hook the legacy invoices.ts path uses.
const { evaluateRule } = await import('@/lib/services/berth-rules-engine');
void evaluateRule('deposit_received', data.interestId, portId, meta);
} else if (
data.paymentType === 'refund' &&
expected !== null &&
Number.isFinite(expected) &&
interest.dateDepositReceived !== null
) {
// L24 — lower-bound re-lock. A prior deposit tripped the gate (stamping
// dateDepositReceived and, via the deposit_received rule, flipping the
// primary berth to 'sold'). This refund just dropped the net deposit
// (in the expected currency) BACK below the expected amount, so the
// "deposit met" state is no longer true. Reverse the deposit-driven
// side effects conservatively:
//
// 1. Un-stamp dateDepositReceived — the timeline/reports must stop
// claiming the deposit was met.
// 2. Revert the primary berth 'sold' → 'under_offer', but ONLY when
// it is currently 'sold' AND that status was set automatically by
// the rules engine (statusOverrideMode='automated'). We never undo
// a 'sold' an admin set by hand, and we never touch a berth a
// different deal/contract subsequently moved on.
//
// We deliberately do NOT auto-regress the pipeline stage here: stage is
// monotonic-forward by design (advanceStageIfBehind never moves a deal
// backwards) and a contract may already have been signed off this deal.
// Reversing the stage is left to a rep via the manual /stage path. The
// un-stamp + berth re-lock are the conservative, non-destructive subset
// that stops the underpaid deposit from reading as fully met.
await db
.update(interests)
.set({ dateDepositReceived: null, updatedAt: new Date() })
.where(eq(interests.id, data.interestId));
const { getPrimaryBerth } = await import('@/lib/services/interest-berths.service');
const primaryBerth = await getPrimaryBerth(data.interestId);
if (primaryBerth?.berthId) {
const [reverted] = await db
.update(berths)
.set({
status: 'under_offer',
statusLastChangedBy: meta.userId,
statusLastChangedReason: `Deposit refunded — net (${total} ${expectedCurrency}) fell below expected; auto-reverted from sold`,
statusLastModified: new Date(),
statusOverrideMode: 'automated',
updatedAt: new Date(),
})
.where(
and(
eq(berths.id, primaryBerth.berthId),
eq(berths.portId, portId),
eq(berths.status, 'sold'),
eq(berths.statusOverrideMode, 'automated'),
),
)
.returning({ id: berths.id });
if (reverted) {
void createAuditLog({
userId: meta.userId,
portId,
action: 'update',
entityType: 'berth',
entityId: reverted.id,
oldValue: { status: 'sold' },
newValue: { status: 'under_offer' },
metadata: { type: 'deposit_refund_relock', interestId: data.interestId },
ipAddress: meta.ipAddress,
userAgent: meta.userAgent,
});
emitToRoom(`port:${portId}`, 'berth:statusChanged', {
berthId: reverted.id,
newStatus: 'under_offer',
triggeredBy: meta.userId,
trigger: 'deposit_refund_relock',
});
}
}
}
}