# Stage 3: paid Project opportunities and Closing

Part of the [Sales flow chart](/docs/modules_handbook/shared/sales-flow-chart/readMe.md). Image 3 ("After the
Project webinar → Closing") has two branches:

- **Paid** (Project fee) → payment received → auto-assign REP (DATA 5) → Human Zoom → Closing. Its counts come from
  the read-only **`ClosingJourneyBoard`** (board key `closing`), described below.
- **Unpaid / no-show** → WhatsApp → AI call → DATA 3 → Human Call / Zoom (DATA 4) → Closing. Its counts come from the
  Project funnel's **`ProjectJourneyBoard`** (`project:no_show`, `project:attended`) and it ends with the colleague's
  **closing decision** (owner decision D4b) — see *The unpaid branch's closing decision* below.

Both branches end in the **Closing** box: **Won** (Booked → keep following up until it converts) or **Not closed**
with the reason recorded (`Engagement::LOST_REASONS`, e.g. not ready to buy, no loan eligibility). A deal that
**moved to another project** (Engagement Swing) is neither: both boards count it beside Not closed, never in it
(owner, 2026-10-13) — see *Won without a Project fee, and Swing* below.

The company view is `/manage/my-work/sales-flow?guide=live&jstage=3` (legacy `jstage=closing`); its roster default
board is `closing`. A Project funnel's Journey tab shows Stage 3 with its own `project` chips (`project:won` in Won,
`project:swung` among the extras); the paid boxes link to the company view, and the Stage 3 extras `closing:swung`,
`closing:review` and `closing:refunded` are simply hidden there (not linked). Opening the chart sends no message,
creates no task or appointment, and does not repair, restore or reopen an opportunity.

## Paid opportunities — population and counting

- Apply `LeadVisibility`, exclude internal staff, and apply `GroupScope` to the Sales Project before selecting
  receipts, opportunities or counts. A Funnel registration is not required: direct and legacy payments need the
  same service.
- An Active, non-deleted Project receipt enters the current paid cohort. Refunded-only opportunities form the
  separate `refunded` reference and are never added to the current total.
- The unit is an **opportunity**, with a separate count of distinct customers (`customers` on the board and on each
  node). One customer may have several Projects and several deals in one Project. Node counts partition
  opportunities; per-node customer counts can overlap.
- A receipt explicitly linked to a matching lead and Project belongs to that engagement. A receipt without such a
  link belongs only to the oldest live deal for that lead/Project (`Engagement::primaryFor`). It never pays for every
  additional unit, and several receipts for one opportunity make one opportunity.
- No deal yet → a stable `pending:{lead}:{project}` entry waits for handoff. An explicitly linked removed deal is
  review-only; the chart does not undo its deletion. Unpaid deals are outside this cohort — a fee-less deal Booked or
  Converted is the Project board's `project:won` instead (below).
- Payment summaries deduplicate receipt ids and keep currencies separate; amounts need `view-sales`. A legacy
  receipt with no currency counts as MYR (`PurchaseHistory::currency_code`, 2026-10-13 — it used to be a separate
  "Unknown" amount).

## Current position (one node per opportunity)

| Node | Evidence | Service step (`SERVICE_QUEUE`) |
|---|---|---|
| `handoff` · Assign the sales owner | No opportunity, or no `zoom_closer_id` / closer assignment | `project_handoff` |
| `preparation` · Complete financial preparation | Consent, financial questions or WhoPay incomplete (lead-level, reused) | `project_preparation` |
| `booking` · Confirm consultation time | No qualifying consultation, or a cancelled / missed one needs a new time | `project_zoom` |
| `meeting` · Conduct the sales consultation | A future or due Sales Zoom / appointment exists for this opportunity | `project_meeting` |
| `closing` · Follow through to a booking | The consultation has actual completion evidence | `project_close` |
| `booked` · Booked | Engagement Booked (incl. retired Following Up) with a live Booking | `project_close` |
| `converted` · Converted | Engagement Converted (`Engagement::STATUS_COMPLETED`) with a live Booking | — |
| `lost` · Not closed | Engagement Lost, with its structured reason, remark, stage and date | — |
| `swung` · Moved to another project | Engagement Swing — not company-wide loss; drawn beside Not closed ("Paid · moved to another project"), never in it | — |
| `review` · Check the records | Removed paid deal, elapsed consultation without evidence, a consultation that is not a Sales meeting, booked / converted without a live Booking; also every refunded-only opportunity (the `refunded` reference) | — |

Recorded sales outcomes win over earlier preparation; pending handoff precedes preparation; preparation precedes
consultation work. Each row still shows its separate preparation and consultation facts.

`MyWorkConsultations` supplies the consultation states (also used by My Work). An exact engagement identity or a
confirmed opportunity link stops one Project's meeting completing another; Calendar outcomes win over stale
duplicate Zoom records; elapsed time alone is not completion. `FpaProgress` calls the questionnaire answered when
salary and a goal are present, and a WhoPay report is preparation, not loan approval. For Loan and Property fit only
this opportunity's own live bookings count. Converted is `Engagement::STATUS_COMPLETED`, not
`Booking::STATUS_COMPLETED`; conversion can still need SPA / LO and commission follow-up in
[Sales Projects closeout](/docs/modules_handbook/manage/engagement/closeout.md).

## Rows, tasks and Pending / Done

Each opportunity row is its open tasks plus one **record item** for its current step
(`ClosingJourneyBoard::recordItem()`):

- `queue` = the node's service step (table above); none for an ended, refunded or review opportunity.
- `state`: Converted → done (nothing to record); Booked → to do ("keep following up until it converts"); Not closed /
  Swing / Review → review; a scheduled meeting → scheduled; else to do.
- `action_context` = `{funnel_uuid: null, event_uuid: null, queue, project_uuid, engagement_uuid}`. Paid Project
  service is company-wide, so it names the Project and opportunity and **never a funnel** — the receipt Session's
  funnel may be of any kind, and the endpoint ignores a funnel for these queues anyway.
- `due_label` = the consultation time as My Work words it — "Zoom call · 14 Oct, 8:00pm" in `app.user_timezone`
  (2026-10-13; it used to print the raw ISO timestamp); none without a consultation.
- `last_contact` = the contact anyone recorded on this step (`FunnelFollowUpState`, key `lead:0:0:project:queue`).
- Recording a contact here **never completes the step** (D4): only the real record does — a named sales owner, saved
  preparation, a booked / held consultation, the deal's Won / Not closed in Sales Projects.

Task items: a frozen `handoff_context.engagement_id` attaches a task exactly; a task naming only a Project attaches
only when the customer has at most one live deal there, so filtering never makes an ambiguous task unambiguous. A
task's `work.outcome_url` is offered while it is open to its holders **and** to anyone D5 lets record
(`LeadActionItem::canRecordOutcomeFor()`: the lead's account manager, the opportunity's sales owner, a super admin).
Stage 3 is never opened to the whole team: D6 covers Stage 1 steps only.
Work filters count opportunities with matching open tasks; `unassigned` = no active assignee who can still see the
customer. Suggestions are next actions, never tasks created on page load.

The owner filter uses the **sales owner** (`zoom_closer_id`, else the closer assignment), falling back to the
account manager for **any** opportunity without a sales owner — awaiting handoff, but also a booked, lost, swung or
review one nobody was named on. The viewer's lead and Project permissions remain the outer boundary.

Links: opportunity → its Sales Project, `/manage/sales-projects/{project uuid}?tab=pipeline` (the Project's uuid, not
the opportunity's; Project access); financial preparation →
`/manage/leads/{uuid}?tab=portal&ptab=fpa`; tasks → the customer's Action items; evidence →
`/manage/leads/{uuid}?tab=sales&stab=journey`. There is no standalone Engagement detail page. (The rosters and My
Work open these lead-page links as the lead quick-view modal on that tab — see
[Journey work cells](/docs/modules_handbook/shared/journey-work/readMe.md).)

## The unpaid branch's closing decision (D4b)

On the queues `LeadActionItem::CLOSING_DECISION_QUEUES` (`project_no_show`, `project_unpaid`, `project_after_call`)
a **Spoke to them** outcome also asks the closing decision: **Still following up** (default) or **Not closed** with
a required reason from `Engagement::LOST_REASONS`. It is stored on `lead_action_item_outcomes.closing_decision` /
`lost_reason_code` (`LeadActionItemOutcome::CLOSING_FOLLOWING` / `CLOSING_NOT_CLOSED`); "Not closed" refuses an
agreed next date. Contract: [record-contact.md](/docs/modules_handbook/shared/sales-flow-chart/record-contact.md).

A recorded Not closed puts that customer × Project context on the Project board's `lost` node with its reason
(`ProjectJourneyContexts::notClosed()`, outcome source `contact`) — the `project:lost` chip in the Not closed box,
beside `closing:lost` for paid deals. D3 does not apply to it: the suggestion never returns by itself. Across
the three closing queues the context's **newest outcome that carries a decision** wins
(`FunnelFollowUpState` `closing_outcome_id`): a later **Spoke to them** on any of them reopens it — its decision
defaults to **Still following up** (`HandoffOutcome`) unless Not closed is chosen again — but a later No
answer — or any outcome without a decision — on another queue never hides it (2026-10-13; before, the newest outcome
of any kind won). A **Lost** deal or a stopped / lost journey lands on the same node with its own reason. Recording
Not closed does **not** touch any engagement: a paid opportunity records its outcome on the deal.

## Won without a Project fee, and Swing (owner, 2026-10-13)

`ProjectJourneyContexts::resolve()`, for a customer × Project context of a Project funnel (registered for, or
attended, its webinar):

- A deal on that Project **Booked, Following Up or Converted** while the customer has no active fee for that Project →
  `project:won` ("Booked · no Project fee"), a chip in the **Won** box beside `closing:booked` / `closing:converted`.
  With an active fee attributed to this funnel the context is `paid` first, and a fee paid through another funnel stays `review`: either way the deal
  is the Closing board's, so nothing is counted twice. Its roster item is done, badged "Won". It is no My Workspace
  step: Sales Projects follows the deal. (Before: `review`, "Check the payment record".)
- Every deal on that Project ended, and none of them **Lost** — i.e. they all ended with a **Swing** →
  `project:swung` ("Unpaid · moved to another project"), an extra chip beside `closing:swung`. A Lost deal, a recorded
  Not closed or a stopped / lost journey stays `lost`; a recorded Not closed wins over a Swing, a Swing over a
  stopped journey. Its roster item is done, badged "Moved to another project". (Before: `lost`, "Not closed · Moved
  to another project".)

## My Work

`MyWorkResponsibilities::closingEntries()` reads the same `ClosingJourneyBoard::population()` for the person (sales
owner, or account manager while pending) and maps each node to its Stage 3 queue: `handoff` → `project_handoff`,
`preparation` → `project_preparation` (with its checklist), `booking` → `project_zoom`, `meeting` → `project_meeting`,
`closing` / `booked` → `project_close` (to do — keep following up until converted), `converted` / `lost` / `swung` →
`project_close` done. A removed opportunity gets no record target. The unpaid branch
(`MyWorkResponsibilities::projectEntries()`): a `lost` context is a Done item "Not closed" with its reason; a `swung`
one is a Done item "Moved to another project" (on the step of its last call, else no-show / unpaid by attendance); a
`won` one has no step. See [My Work](/docs/modules_handbook/manage/my-work/readMe.md).

## Files and checks

- `src/Lead/Journey/ClosingJourneyBoard.php`; `src/Lead/Journey/ProjectJourneyContexts.php` (`notClosed()`)
- `app/Http/Controllers/Manage/MyWorkController.php` (`salesFlow`)
- `src/Lead/Services/MyWorkResponsibilities.php` (`closingEntries`)
- `tests/Feature/Lead/ClosingJourneyBoardTest.php`, `tests/Feature/Lead/FunnelFollowUpTest.php`

The tests cover receipt and opportunity deduplication, several Projects and units, direct fees without a Funnel,
refunds, consultation evidence, distinct Booked / Converted outcomes, exact task identity, viewer / owner isolation,
the consultation's due label, and recording a contact or a Not closed decision (`ProjectJourneyBoardTest` covers a
later No answer on another closing queue, a Swing that is not Not closed, and a fee-less Booked deal counted as Won
once); `ClosingJourneyBoardTest` also pins that an unknown `jnode` returns counts only on all three boards.
