# The sales workflow — as agreed and as BUILT (2026-10-07)

> **Superseded in parts on 2026-10-08 (owner decisions D1–D5, see [02](02-decisions.md) and
> [09](09-session-2026-10-08-claude.md)).** Stage banding now follows the owner's three **images**: Stage 1
> *Registration → Preview webinar*, Stage 2 *After Preview → Project webinar* (incl. the paid member's REP and Human
> Zoom), Stage 3 *After Project webinar → Closing* (incl. the unpaid follow-up, which ends in Won or Not closed +
> reason). Every answered AI call now needs a human contact; a colleague's registration starts no automation; every
> human box records a contact. The live charts and My Work are documented in the handbook —
> [Sales flow chart](../../modules_handbook/shared/sales-flow-chart/readMe.md),
> [Record contact](../../modules_handbook/shared/sales-flow-chart/record-contact.md),
> [My Work](../../modules_handbook/manage/my-work/readMe.md). The guide is no longer `FLOW_CHART` / `STAGES`: the
> charts are `salesFlowOperations.js` (`FLOW_CHART` only draws the per-lead map). Where this file disagrees, the
> handbook and the code win.
>
> **Known stale statements below (checked against the code 2026-10-13, see [10](10-code-study-and-fixes-2026-10-13.md)):**
> - §1 step 5 / §2 table / §8 row 1 "useful AI call → *AI handled* / *AI followed up*, no task" — since A25 every
>   answered AI call becomes a human call task; `reminders` / `followed_up` are unreachable (nothing records `ai_handled`).
> - §1 step 7 "a Call task on My Work … press **Log the call**" — sales-flow tasks are listed only in My Workspace →
>   **Sales steps** and are closed with **Record contact**; "No answer" moves the task to tomorrow, or today when the
>   webinar is within a day.
> - §1 step 8 "the task closes as *Not called in time* / *No longer needed*" — the call task stays OPEN (A25); the
>   journey box reads "Not called before the webinar"; only the REP's Zoom task is ever closed by the system.
> - §2 "Register selected … opens their Project journey (source `preview_candidate`)" — From Preview only logs
>   `candidate_marked` on the Preview journey and sends the Session welcome (D2); a journey opens later, on demand.
> - §0 / §6 "Call questions per funnel; the REP form uses the AI-call questions" — question sets are per **Slot** and
>   moment (before / after / paid), the paid moment reads the Slot's Paid set first.

This is the complete lead workflow the session built, step by step: who does each step, what the system sends, how
long it waits, and when a person gets a task. It is the result of three inputs:

- the owner's flowchart ([07-owner-flowchart-original.md](07-owner-flowchart-original.md));
- the owner's answers ([02-decisions.md](02-decisions.md));
- what the code does today.

**Where else this lives:**
- **The sales team's copy (Chinese):** CRM → My Work → **Sales flow guide** (`/manage/my-work/sales-flow`). It is the
  ONE copy shown to staff. Its text lives in `resources/js/Pages/Manage/MyWork/Partials/salesFlowGuide.js`:
  - `FLOW_CHART` — the chart: 23 boxes in 3 bands;
  - `STAGES` — the step cards;
  - `ROUTINE`, `CALL_FORM`, `PAGES`, `TERMS`.

  When the flow changes, change that file. A change to `FLOW_CHART` also needs `SalesFlowChartPath` (PHP) to stay in
  step; a unit test enforces the parity.
- **The engine's exact rules:**
  [funnel-journey handbook](../../modules_handbook/manage/leads/funnel-journey/readMe.md) §1–§5. This file
  summarises them; the handbook and the code win if they disagree.

Who does a step:

| Label | Who |
|---|---|
| 系统 SYS | Automatic |
| AI | The Retell AI voice agent |
| 你 YOU | The lead's account manager / sales admin |
| REP | The person who books the 1-1 Zoom after payment = the account manager |
| 管理员 ADMIN | Ops / boss |

---

## 0. Before anything: the set-up (once)

- Two funnels have **Sales flow** switched on (funnel form):
  - "Trust Nurturing - Property Investment" = **Preview webinar**;
  - "Property Closing" = **Project webinar**, with **Candidates come from** = the Preview funnel.
- Funnels without Sales flow (the bonus funnels, 7 / 8 / 10) are not tracked at all.
- **What each slot sells** (`event_series_offers`): Preview → memberships; each Project slot → its project fee.
- **The company Round Robin** list is ON.
- **Call questions** are written per funnel. Until then, the AI call's own questions are used.
- **Messages:**
  - M1 / M2 / M3 already exist;
  - M4 + 3 more templates were submitted to Meta on 10-05 (see the table in §5).
  - The R1 / R2 reminders are ordinary funnel automation rules the owner sets on the Automation tab (§4).

## 1. 第 1 段 — Landing sign-up → Preview webinar

1. **SYS** — The lead registers on the landing page. The journey opens at *Registered*.
   - Only a LANDING registration opens a journey at once. An import, admin add or Zoom-side registration opens it
     later, at the first reminder or the attendance verdict. Nothing welcomes or calls those people, and they never
     show the "landing sign-up" box.
2. **SYS** — **Account manager by Round Robin**, if the lead has none, from any source.
   - It runs 60 s after the lead is created, so a self-add or import that names a manager wins.
   - The manager is also the lead's first REP.
3. **SYS** — **M1 welcome WhatsApp** (button "Yes, 我已进群了"; the reply is caught by the template-menu bot).
4. Did the lead tick "OK for AI call"?
   - **Yes:** **AI** calls (DATA 1: will they attend, what do they want to buy, …).
   - **No:** **SYS** sends **M2** "让 AI 打给你" about 2 min later. A click → the AI calls.
5. Answered?
   - **Answered + useful** (the profile extracted BOTH `will_attend` and `buy_intent`): *AI handled* → *Reminders*.
     **No task.** The lead is listed for its owner under "AI handled" on My Work.
   - **Answered but not useful:** hand-off at once.
   - **Missed:** **SYS** sends **M3** (missed-call WhatsApp + callback button; max one per lead per day).
     - A click → **AI** calls back.
     - No click → wait.
6. **The hand-off rule** (scanner, every 5 min):
   - **Wait** 6 h (`handoff_hours`) with no useful outcome or click, **but never later than 3 h before the webinar**
     (`handoff_cutoff_hours`).
   - **Never sooner than 20 min** after the lead entered the box (`automation_grace_minutes`), so a late
     registrant's AI call can finish.
   - Also: a landing registrant stuck at Registered / Welcome (no AI call ever reached them) is handed over.
7. **YOU** — a **Call task** on My Work (and on the lead's Action items tab). You call, then press **Log the call**
   → "How did the call go?" (DATA 2):

   | Answer | What the system does |
   |---|---|
   | **Spoke to them** | You fill in the funnel's questions; the task closes; the journey moves on |
   | **No answer** | The attempt is logged; the task stays and moves to tomorrow |
   | **Cannot be reached** | The task closes |

   Two extras on the form:
   - "They will skip this session and join next time" → **mutes this session's reminders**; the lead stays registered.
   - "Agreed a time to talk again" → a new task on that day.
8. **If the webinar starts before anyone called:** the task closes as **Not called in time** (`human_expired`).
   - Any other event that moves the lead on first (paid, attended, re-registered) closes it as **No longer needed**
     (superseded).
9. **SYS** — **R1 reminders** (owner-configured rules):
   - 24 h before: WhatsApp private message;
   - 5 h before: WhatsApp group post (can be set once per slot, "every session of a slot");
   - 3 h before: WhatsApp private message;
   - 30 min before: SMS.
10. **Preview webinar.** **R2** during it:
    - +15 min: an AI-call rule with the after-start trigger, "no-shows only" (calls people who have not joined);
    - +60 min: a staff **reminder to post a screenshot** in the group (Notify event `events.webinar_screenshot`,
      opt-in on Manage → Notifications).

## 2. 第 2 段 — After the Preview webinar → Project webinar

**Attendance:**
- It comes from Zoom attendance or the door check-in.
- 30 min after the real end with still no verdict → an **inferred no-show**. A real verdict arriving later still wins.

**"Paid?"** = a **membership** payment. Two timings:
- **Paid:** the paid branch fires at once on the payment webhook (even before the verdict).
- **Not paid:** waits until **2 h after the webinar ENDS** before going to *Unpaid*.

Three branches:

| Did not come (no-show) | Came, did not pay | Paid a membership |
|---|---|---|
| **SYS** "这次没看到你" WhatsApp (`webinar_no_show_followup_v1`) | **SYS** follow-up WhatsApp, "what do you most want to know" (`webinar_attended_followup_v1`) | **SYS** payment receipt (`payment_received_v3`; also for portal / manual payments when exactly one payment link sells that item) |
| **AI** calls (DATA 3); missed → **M4** (`ai_caller_missed_after_v1`) with the callback button | **AI** calls (DATA 3); missed → **M4** | **SYS** names the **REP** on the next scan: the deal's Zoom closer, else the **account manager** (no separate rotation), else a round-robin turn |
| Still not useful / no click after the wait → **YOU** get a call task (DATA 4). It never expires after a webinar | same → **YOU** call (DATA 4) | **REP** gets a HIGH-priority "**Book the member's 1-1 Zoom**" task + a phone alert, and calls to book (DATA 3+4) |
| A useful AI follow-up → *AI followed up* (no task) | same | Booking the Zoom closes the task automatically; the meeting ending → *Sales Zoom held* |

**Rules that apply to every branch:**
- No-show **but paid** → the paid path wins.
- The after-webinar AI-call rules can be limited to attended / paid conditions.
- The "useful" test after a webinar = `buy_intent` alone.

**Into the Project webinar:**
- **ADMIN** opens the Project session → Registrations → **From Preview**. The list shows everyone from the Preview
  since the previous Project session, not yet registered; attended people are pre-ticked.
- **Opening the list registers nobody.** Registering pushes the person to Zoom, and Zoom emails at once, so the
  admin's click is the approval.
- **Register selected** sends the session's welcome and Zoom link, opens their Project journey (source
  `preview_candidate`) and logs *candidate_marked* on the Preview journey. My Work reminds ops of Project sessions
  with nobody picked yet.
- The CSV import remains the fallback.

## 3. 第 3 段 — After the Project webinar → Closing

**"Paid?"** = the slot's **project fee** (e.g. ViiA RM 299 via Stripe).
- Paying auto-opens the project's engagement (deal) in the sales pipeline. That part existed before.
- Same paid / unpaid timings as 第 2 段.

| Did not come, or came and did not pay the project fee | Paid the project fee |
|---|---|
| **SYS** WhatsApp follow-up | **SYS** receipt; **SYS** names the REP (the deal's Zoom closer if set, else the account manager) |
| **AI** call — **only for people who ATTENDED a Preview** (owner rule); everyone else gets the WhatsApp only and no task ("cold no-shows") | **REP** "**Book the 1-1 sales Zoom**" task → calls → books the sales Zoom (DATA 5) |
| Missed → **M4**; still nothing → **YOU** call task (DATA 4, stored as stage-3 `data_4b`) | 1-1 sales Zoom: asks the lead to pay the **booking fee to the DEVELOPER** (never through us) |
| | **REP** marks the deal **Booked** (= Closing), or **Not closed** with a reason code → the Project journey ENDS (won / lost) |

**After closing:**
- **Booked → Converted** (SPA signed) is the existing pipeline; the journey does not track it.
- A deal closes the journey only with evidence: the payment is on that journey, or the slot's offers list the
  deal's project. A Booked deal created by hand with no payment leaves the journey open.

## 4. The reminders and other rules the OWNER configures (not code)

| What | Where | Status |
|---|---|---|
| R1: 24 h WA PM, 5 h WA group, 3 h WA PM, 30 min SMS | Funnel → Automation (WhatsApp / SMS rules; group post "every session of a slot") | Mechanism exists; rules are the owner's to set |
| R2: +15 min AI call to people not yet joined | AI-call rule, after-start trigger, no-shows only | Exists (built 10-01) |
| R2: +60 min screenshot to the group | Notify event `events.webinar_screenshot` (a reminder to a person) | Built; staff opt in |
| After-webinar WhatsApps + AI calls (§2, §3) | Funnel → Automation, "after the session ends" rules with attended / paid / Preview-attendee conditions; M4 in the AI-call rule's missed-call field | Built; the templates must be approved and wired |
| Call questions (DATA 2 / 4 / 3+4 / 5) | Funnel page → Call questions (3 kinds: before the webinar, after the webinar, REP after payment) | Built; questions not written yet |
| What each slot sells | Funnel → Automation → step ③ → Add offer | Empty in production on 10-03 |

## 5. Messages

| Code | What | Template / source | State (10-07) |
|---|---|---|---|
| M1 | Welcome + group link + login link + the lead's own Zoom link; button "Yes, 我已进群了" | the funnel's on-register WhatsApp rule | live |
| M2 | "让 AI 打给你" for people who unticked the AI call | `ai_caller_optout_v1` | live |
| M3 | Missed AI call before the webinar + callback button | `ai_caller_missed_v2` | live (one per lead per day) |
| M4 | Missed AI call after the webinar + callback button | `ai_caller_missed_after_v1` | submitted to Meta 10-05, Pending; production must "Sync from Meta" |
| — | Payment received | `payment_received_v3` | submitted, Pending |
| — | Why didn't you attend | `webinar_no_show_followup_v1` (`{{1}}` name, `{{2}}` webinar) | submitted, Pending (may become MARKETING) |
| — | Attended, not paid follow-up | `webinar_attended_followup_v1` (`{{1}}` name, `{{2}}` webinar) | submitted, Pending (may become MARKETING) |
| — | "Thanks for picking up" after an answered AI call | `ai_caller_thanks_v2` | live, kept (decision B3) |

## 6. DATA points (what each call learns)

All of these are stored in `funnel_journey_answers` (`FunnelJourneyAnswer::POINT_*`; the stage-3 rows print as "DATA 3 / DATA 4 · Stage 3"). They show on the lead's Journey tab under "What they told us",
are quoted in the Discussion feed, and answers about money / need / decision-maker turn READINESS **amber**.

| DATA | Stage | Who | Stored as |
|---|---|---|---|
| 1 | 第 1 段 | AI call | `data_1` |
| 2 | 第 1 段 | You (Log the call) | `data_2` |
| 3 | 第 2 段 | AI follow-up call | `data_3` |
| 4 | 第 2 段 | You | `data_4` |
| 3+4 | 第 2 段, paid | REP | `data_34` |
| 3 / 4 | 第 3 段 | AI / you | `data_3b` / `data_4b` (labels say "Stage 3 · …") |
| 5 | 第 3 段, paid | REP | `data_5` |

Note: the REP's DATA 3+4 / DATA 5 question sets (profiles 7 / 8) are not wired to the REP form yet; it uses the
funnel's AI-call questions.

## 7. A sales admin's day (the guide's 每天怎么做)

1. Open **My Work**. Do overdue tasks first, then today's.
2. Click the lead's name. Read **Sales → Journey** first: where they are, and what the AI and colleagues already
   learnt. The **3-stage bar** on top shows 第几段 at a glance.
3. Call. Afterwards press **Log the call**; do not just tick the task.
4. Answer WhatsApps in **Messages**, including button taps.
5. Before going home: **Leads** → Pay attention → "Sales flow task overdue" (one day of grace).

**The boss and leaders use:**
- the funnel page → **Journey** tab: counts per box, time in box, each colleague's tasks and overdue;
- **Call questions** on the funnel page;
- **Round Robin**;
- **From Preview**;
- CEO → Reports → **Sales flow board** (Sunday 23:00, off until enabled);
- **Time with Leads**;
- My Work → pick a colleague, or **"Tasks nobody holds"**.

## 8. Where the built flow DIFFERS from the original flowchart (and why)

| Original spec | Built | Why / who decided |
|---|---|---|
| Picked up → human call / Zoom for everyone | A human call only when the AI did NOT get useful info (both `will_attend` + `buy_intent`) | Owner 10-03 (A5) + implementer B2. 686 sign-ups per session cannot all be called |
| "AI call: action item — generate an appointment for Human Call / Zoom" | **Not built.** The AI call records answers; the scanner makes a call TASK. No appointment is booked by the AI | Structural: funnel AI calls only record outcomes. Possible future work |
| Stage 1 human action: "remind them to join the webinar" | A call task with the funnel's questions; the "will join next time" mute | — |
| Stage 2/3 "Paid?" undefined | Preview = membership; Project = the slot's project fee | Owner A3 |
| Attended? No → AI call for everyone | Project no-show AI call only for Preview attendees; cold no-shows get WhatsApp only | Owner A7 |
| Paid → "system auto-assigns a REP" | REP = the deal's Zoom closer, else the account manager (no separate rotation) | Owner A17 |
| Stage 3 human action "remind them to join project sharing webinar" (spec open question) | Book the 1-1 sales Zoom / push to booking | Implementer B4 |
| Stage 3 DATA reused 3 / 4 (spec open question) | Kept the labels; stored as `data_3b` / `data_4b` | Plan decision #11 |
| Preview people → Project webinar (implied automatic) | Admin-reviewed "From Preview" list; nothing is registered until the admin clicks | Owner A6 |
| Not closed → "system must record the reason" | A lost-reason code on the deal → the journey's `lost_reason_code` | Built (master `af7add521` + Phase 4) |
| Round robin only for the human call | One company Round Robin names the account manager of EVERY new lead; the top talker on the list can take over | Owner A16, A17 |
| R1 group reminder per session | A group post can target "every session of a slot" | Phase 3 |
| — | **Not in the spec, added:** 20-min grace; "Not called in time" / "No longer needed" task closes; inferred no-show; AI-call pacer; My Work; the Journey board; the 3-stage bar + chart | Implementer, reported to the owner |

## 9. How the flow is SHOWN per lead (the bar + chart)

- **The bar** (lead page, lead modal) shows 第 1 / 2 / 3 段:

  | Colour | Meaning |
  |---|---|
  | Green | done |
  | Blue | 现在 (current) |
  | Grey | not yet |
  | Pale grey | 没有记录 (no record) |
  | Green / slate | Booked / Not closed |

  It also says the box the lead is in now. **看流程图 →** opens the Journey tab.
- **The chart** (Journey tab): the guide's chart with the lead's path. Passed boxes are green with a tick, the
  current one blue with 现在, reached-but-not-done boxes orange (没做到: a refused AI call, an expired or superseded
  task), the rest grey, and walked arrows green.
- **The Leads list:** 3 small pills beside the Journey chip.
- **Mapping journey → boxes:** `SalesFlowChartPath`. Design: [04](04-sales-flow-chart-path-design.md).
  **Review findings (fixed 2026-10-13):** [05](05-review-findings-2026-10-07.md).
