Module: Closing (Phase 4)

The sales pipeline where interested targets become contracts. Tightly coupled to the rest of the funnel, so we build it (rather than bolting on Pipedrive/HubSpot) — a drag-drop CRM is cheap to build well with Next.js + React and keeps everything on one target lifecycle.

Responsibilities

• A drag-and-drop Kanban pipeline of targets across the closing stages.
• Round-robin assignment of scheduled appointments to Closing-Agents; a Closing-Agent sees only their assigned targets.
• Appointments (scheduling, held / no-show / cancelled tracking).
• Notes and contract records; contract send via SignRequest e-signature.
• Payment collection via GoCardless after a contract closes.
• Closing-Agent commissions.
• A warm handoff — hand a non-cold follow-up back to the call team as a distinct job type from cold-call shifts, so KPIs stay clean.

The 8-stage closing pipeline

Drag-drop Kanban built from shared React/shadcn components. Moving a card transitions the underlying target's lifecycle and is written to the audit trail.

New target (validation pre-stage)
  → Appointment scheduled
  → Follow-up
  → First meeting
  → Follow-up meeting
  → Sold (end)
  → Not sold (end)
  → Unqualified (end)

The New target pre-stage validates the handed-off target before it enters the live pipeline; Sold, Not sold, and Unqualified are terminal.

Assignment & scoping

• Appointments arriving from Connect are round-robin distributed to Closing-Agents.
• Authorization scopes a Closing-Agent to only their round-robin-assigned targets (per-resource checks).

Appointments & no-show

• Each target in closing can schedule appointments (scheduled / held / no_show / cancelled).
• No-show tracking feeds Controlling and can trigger a warm handoff back to the call team.
• A warm-handoff flag distinguishes warm follow-ups from cold-call shifts (keeps Connect KPIs clean).

Contracts, e-signature & payment

• A Sold target produces a contract (signed date, value, document reference).
• Contract send goes out through SignRequest (e-signature), behind its own mockable NestJS integration module.
• After the contract closes, payment collection is set up via GoCardless.
• Closing-Agent commission derives from Sold targets × the agent's commission rate.

Key services

• MoveTargetStage — drag-drop stage change → target transition + audit log.
• AssignAppointmentRoundRobin — distribute a new appointment to the next Closing-Agent.
• ScheduleAppointment / MarkAppointmentOutcome (held / no-show / cancelled).
• SendContract (SignRequest) / RecordContract.
• CollectPayment (GoCardless) — after close.
• HandBackAsWarmJob — create a warm follow-up job, distinct from a cold-call shift.
• CalculateClosingAgentCommission.

Business logic lives in NestJS services; input validated via DTOs (class-validator) / zod. Every stage transition and contract/settings change lands in the immutable audit_logs.

Acceptance

• An interested / appointment-scheduled target appears in the pipeline, round-robin assigned to a Closing-Agent who sees only their own targets; dragging it across stages transitions the target and logs it.
• Appointments track held / no-show; no-shows can hand back as warm jobs.
• A Sold target sends a contract via SignRequest, records the contract, sets up GoCardless payment, and computes the Closing-Agent commission.
• Tests cover stage transitions, no-show handling, and commission math with faked SignRequest / GoCardless clients — no real API calls in CI.

Screens (see 04-design-workflow)

• Closing Pipeline — the drag-drop Kanban (prototype priority), built from shared React/shadcn components.