feat(pipeline): 9→7 stage refactor + v1.1 hardening wave
Replaces the legacy 9-stage pipeline with 7 canonical stages
(enquiry → qualified → eoi → reservation → deposit_paid → contract →
nurturing) plus three doc sub-status columns (eoi_doc_status,
reservation_doc_status, contract_doc_status) that track sent/signed
within a single stage instead of branching it.
Schema (migration 0062):
- interests gains assigned_to, deposit_expected_amount/currency,
three doc-status columns, two documenso-id columns, and
date_reservation_signed.
- New tables: qualification_criteria (per-port admin-configurable),
interest_qualifications (per-interest state), payments (deposit /
balance / refund records keyed to interest + client).
- Default qualification criteria seeded for every existing port.
- Dummy-data UPDATEs collapse Sent/Signed pairs and 'completed' into
the new stage + doc-status + outcome shape.
Migration 0063 adds interest_contact_log.voice_transcript and
template_used columns for v1.1-A/B (quick-template buttons + voice
transcription via Web Speech API).
v1.1 phase work bundled here:
- A/B: Quick-template buttons (Call / Visit / Email) + mic toggle on
the contact-log compose dialog (useVoiceTranscription hook).
- C: berth-rules-engine wraps state writes in pg_advisory_xact_lock
with an idempotent re-read; emits rule_evaluated audit traces.
- D: Documenso webhook: reservation/contract sub-status stamping
moved out of the PDF-download try-block so a download failure
no longer swallows the stamp. New integration test coverage.
- E: /admin/qualification-criteria CRUD page + admin component.
- F: default_new_interest_owner exposed in System Settings.
- G: recentActivityCount + active_engagement deal-pulse signal
surfaced as a chip on interests + hot-deals card.
- H: interest_assigned notification on assignedTo change (skips
self-assign, uses a dedupe key).
Plus the supporting components: AssignedToChip, DealPulseChip,
PaymentsSection, QualificationChecklist, MultiEoiChip,
SkipAheadBanner, WonStatusPanel, InterestBerthStatusBanner,
SupplementalInfoRequestButton, UserPicker.
Tests: 1370/1370 vitest pass (added deal-health unit suite +
expanded constants/validators/pipeline-transitions coverage). tsc
clean, eslint clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -1,97 +1,102 @@
|
||||
// ─── Pipeline Stages ─────────────────────────────────────────────────────────
|
||||
//
|
||||
// 7 canonical stages (one optional). Document-signing stages (EOI, Reservation,
|
||||
// Contract) collapse "Sent + Signed" into one stage; the sub-status lives on
|
||||
// per-stage doc-status columns (`eoi_doc_status`, etc.) and is rendered as a
|
||||
// badge inside the kanban card.
|
||||
//
|
||||
// `nurturing` is built but disabled-by-default for ports that don't have
|
||||
// supply constraints (e.g. Port Nimara pre-launch). Admins enable it per port.
|
||||
|
||||
export const PIPELINE_STAGES = [
|
||||
'open',
|
||||
'details_sent',
|
||||
'in_communication',
|
||||
'eoi_sent',
|
||||
'eoi_signed',
|
||||
'deposit_10pct',
|
||||
'contract_sent',
|
||||
'contract_signed',
|
||||
'completed',
|
||||
'enquiry',
|
||||
'qualified',
|
||||
'nurturing',
|
||||
'eoi',
|
||||
'reservation',
|
||||
'deposit_paid',
|
||||
'contract',
|
||||
] as const;
|
||||
|
||||
export type PipelineStage = (typeof PIPELINE_STAGES)[number];
|
||||
|
||||
/**
|
||||
* Sub-status values for document-signing stages (EOI, Reservation, Contract).
|
||||
* Stored on per-stage columns `eoi_doc_status` / `reservation_doc_status` /
|
||||
* `contract_doc_status` on the interests table.
|
||||
*/
|
||||
export const DOC_STATUSES = ['pending', 'sent', 'signed', 'declined', 'voided'] as const;
|
||||
export type DocStatus = (typeof DOC_STATUSES)[number];
|
||||
|
||||
export const STAGE_LABELS: Record<PipelineStage, string> = {
|
||||
open: 'Open',
|
||||
details_sent: 'Details Sent',
|
||||
in_communication: 'In Comms',
|
||||
eoi_sent: 'EOI Sent',
|
||||
eoi_signed: 'EOI Signed',
|
||||
deposit_10pct: 'Deposit 10%',
|
||||
contract_sent: 'Contract Sent',
|
||||
contract_signed: 'Contract Signed',
|
||||
completed: 'Completed',
|
||||
enquiry: 'New Enquiry',
|
||||
qualified: 'Qualified',
|
||||
nurturing: 'Nurturing',
|
||||
eoi: 'EOI',
|
||||
reservation: 'Reservation',
|
||||
deposit_paid: 'Deposit Paid',
|
||||
contract: 'Contract',
|
||||
};
|
||||
|
||||
// Compact labels for cramped contexts (mobile chart axes, dense tables).
|
||||
export const STAGE_SHORT_LABELS: Record<PipelineStage, string> = {
|
||||
open: 'Open',
|
||||
details_sent: 'Details',
|
||||
in_communication: 'Comms',
|
||||
eoi_sent: 'EOI →',
|
||||
eoi_signed: 'EOI ✓',
|
||||
deposit_10pct: 'Dep.',
|
||||
contract_sent: 'Ctr →',
|
||||
contract_signed: 'Ctr ✓',
|
||||
completed: 'Done',
|
||||
enquiry: 'Enquiry',
|
||||
qualified: 'Qual.',
|
||||
nurturing: 'Nurt.',
|
||||
eoi: 'EOI',
|
||||
reservation: 'Resv.',
|
||||
deposit_paid: 'Dep.',
|
||||
contract: 'Contract',
|
||||
};
|
||||
|
||||
export const STAGE_BADGE: Record<PipelineStage, string> = {
|
||||
open: 'bg-slate-100 text-slate-700',
|
||||
details_sent: 'bg-blue-100 text-blue-700',
|
||||
in_communication: 'bg-sky-100 text-sky-700',
|
||||
eoi_sent: 'bg-indigo-100 text-indigo-700',
|
||||
eoi_signed: 'bg-amber-100 text-amber-700',
|
||||
deposit_10pct: 'bg-orange-100 text-orange-700',
|
||||
contract_sent: 'bg-yellow-100 text-yellow-700',
|
||||
contract_signed: 'bg-green-100 text-green-700',
|
||||
completed: 'bg-emerald-100 text-emerald-700',
|
||||
enquiry: 'bg-slate-100 text-slate-700',
|
||||
qualified: 'bg-blue-100 text-blue-700',
|
||||
nurturing: 'bg-purple-100 text-purple-700',
|
||||
eoi: 'bg-indigo-100 text-indigo-700',
|
||||
reservation: 'bg-amber-100 text-amber-700',
|
||||
deposit_paid: 'bg-orange-100 text-orange-700',
|
||||
contract: 'bg-green-100 text-green-700',
|
||||
};
|
||||
|
||||
export const STAGE_DOT: Record<PipelineStage, string> = {
|
||||
open: 'bg-slate-400',
|
||||
details_sent: 'bg-blue-500',
|
||||
in_communication: 'bg-sky-500',
|
||||
eoi_sent: 'bg-indigo-500',
|
||||
eoi_signed: 'bg-amber-500',
|
||||
deposit_10pct: 'bg-orange-500',
|
||||
contract_sent: 'bg-yellow-500',
|
||||
contract_signed: 'bg-green-500',
|
||||
completed: 'bg-emerald-500',
|
||||
enquiry: 'bg-slate-400',
|
||||
qualified: 'bg-blue-500',
|
||||
nurturing: 'bg-purple-500',
|
||||
eoi: 'bg-indigo-500',
|
||||
reservation: 'bg-amber-500',
|
||||
deposit_paid: 'bg-orange-500',
|
||||
contract: 'bg-green-500',
|
||||
};
|
||||
|
||||
// Default revenue-forecast probability weights per stage (0–1).
|
||||
// Editable per port via settings (`pipeline_weights`); these are the fallbacks.
|
||||
export const STAGE_WEIGHTS: Record<PipelineStage, number> = {
|
||||
open: 0.05,
|
||||
details_sent: 0.1,
|
||||
in_communication: 0.2,
|
||||
eoi_sent: 0.4,
|
||||
eoi_signed: 0.6,
|
||||
deposit_10pct: 0.75,
|
||||
contract_sent: 0.85,
|
||||
contract_signed: 0.95,
|
||||
completed: 1.0,
|
||||
enquiry: 0.05,
|
||||
qualified: 0.15,
|
||||
nurturing: 0.15,
|
||||
eoi: 0.4,
|
||||
reservation: 0.7,
|
||||
deposit_paid: 0.85,
|
||||
contract: 0.95,
|
||||
};
|
||||
|
||||
// Allowed transitions out of each stage. Used by changeInterestStage to guard
|
||||
// against accidental skips (e.g. dragging a card from Completed back to Open,
|
||||
// or jumping Open straight to Completed). Forward moves of 1-2 stages are
|
||||
// permitted; backward moves are limited to the immediate predecessor unless
|
||||
// the lifecycle (EOI/contract chain) needs an explicit rewind.
|
||||
/**
|
||||
* Allowed transitions out of each stage. Skip-aheads (e.g. enquiry →
|
||||
* deposit_paid) are gated by the explicit `override:true` path in
|
||||
* `changeInterestStage` and surface as a backfill banner on the interest.
|
||||
*
|
||||
* Nurturing is bidirectional with qualified (deal pauses → reopens),
|
||||
* and can re-enter the EOI path when supply opens up.
|
||||
*/
|
||||
export const STAGE_TRANSITIONS: Record<PipelineStage, readonly PipelineStage[]> = {
|
||||
open: ['details_sent', 'in_communication', 'eoi_sent', 'eoi_signed'],
|
||||
details_sent: ['open', 'in_communication', 'eoi_sent', 'eoi_signed'],
|
||||
in_communication: ['open', 'details_sent', 'eoi_sent', 'eoi_signed'],
|
||||
eoi_sent: ['in_communication', 'eoi_signed', 'deposit_10pct'],
|
||||
eoi_signed: ['eoi_sent', 'deposit_10pct', 'contract_sent', 'contract_signed'],
|
||||
deposit_10pct: ['eoi_signed', 'contract_sent', 'contract_signed'],
|
||||
contract_sent: ['eoi_signed', 'deposit_10pct', 'contract_signed'],
|
||||
contract_signed: ['contract_sent', 'deposit_10pct', 'completed'],
|
||||
completed: ['contract_signed'],
|
||||
enquiry: ['qualified', 'eoi'],
|
||||
qualified: ['enquiry', 'nurturing', 'eoi'],
|
||||
nurturing: ['qualified', 'eoi'],
|
||||
eoi: ['qualified', 'reservation', 'deposit_paid'],
|
||||
reservation: ['eoi', 'deposit_paid'],
|
||||
deposit_paid: ['reservation', 'contract'],
|
||||
contract: ['deposit_paid'],
|
||||
};
|
||||
|
||||
export function canTransitionStage(from: string, to: string): boolean {
|
||||
@@ -102,7 +107,7 @@ export function canTransitionStage(from: string, to: string): boolean {
|
||||
}
|
||||
|
||||
export function safeStage(value: string | null | undefined): PipelineStage {
|
||||
return PIPELINE_STAGES.includes(value as PipelineStage) ? (value as PipelineStage) : 'open';
|
||||
return PIPELINE_STAGES.includes(value as PipelineStage) ? (value as PipelineStage) : 'enquiry';
|
||||
}
|
||||
|
||||
export function stageLabel(stage: string | null | undefined): string {
|
||||
|
||||
Reference in New Issue
Block a user