# Decisions — everything settled in this session

Two kinds of decision are listed here:

- **OWNER** — the owner (or the boss, through the owner) decided it. Do not re-open it.
- **IMPLEMENTER** — Claude chose it while building. Some were confirmed later and are marked ✅. The rest are
  reasonable defaults the owner has not explicitly approved; if you change one, say so to the owner.

The plan's own log ([lead-journey-implementation-plan.md §7](../lead-journey-implementation-plan.md), items #1–#19)
covers 10-03 in more detail. This list includes those items and everything after them.

---

## A. Business rules of the sales flow (OWNER)

| # | Decision | When |
|---|---|---|
| A1 | The sales team's objective: on login, every sales admin or agent sees clearly what to do (→ **My Work**). The boss can track it (→ Journey board, Sunday report, Time with Leads). | 10-03 |
| A2 | **4 funnels** matter: "Trust Nurturing - Property Investment" = the **Preview** webinar (first layer); "Property Closing" = the **Project** webinar; "After Sales Service - Reno & Tenant" and "Property Knowledge Sharing" = bonus. Funnels 7 / 8 / 10 (Cochrane VSL, Cochrane Webinar, HK) are ignored for now; the owner will move them under 1 or 2 later. That is why the journey is **opt-in per funnel** (funnel form → "Sales flow"). | 10-03 |
| A3 | **"Paid?" = what THAT slot sells.** Preview webinar paid = a **membership** item. Project webinar paid = the **project-fee** item (e.g. ViiA RM 299 via Stripe, which auto-opens the engagement). The owner will set each slot's offer: Funnel → Automation → step ③ → Add offer → Project fee + project. | 10-03, 10-04 |
| A4 | **Closing = Booked** (the booking fee is paid to the DEVELOPER, never through us; a human marks it). **Converted = SPA signed.** | 10-03 |
| A5 | ~~Stage 1 human call: everyone the AI did not get useful info from goes to a person by round robin.~~ **Superseded 10-08 by A25** (every answered AI call needs human contact, useful or not). Still valid: "Not clicked" → hand to a human after **6 h**, never later than **3 h before the webinar**. | 10-03 |
| A6 | Preview → Project webinar is **NOT automatic**. Registering pushes the person to Zoom and Zoom emails them, so the admin reviews a candidate list first (**From Preview**; attended people are pre-ticked). The CSV import stays as the fallback. | 10-03 |
| A7 | The Retell daily budget: the owner raises it. AND the Project webinar's no-show AI call goes **only to people who attended a Preview**; the other no-shows get WhatsApp only. | 10-03 |
| A8 | **Lead reps:** one lead → many staff, with interaction time each. **The account manager is always one of the reps.** | 10-03 |
| A9 | Role change in two steps: sales staff go from super-admin to sales-agent with `view-leads-all` first, and are tightened later. | 10-03 |
| A10 | Paid-check timing: paid branch at once on the webhook; the "unpaid" branch waits **2 h after the webinar ends**. | 10-03 |
| A11 | Past Zoom meetings show the **actual** length everywhere, never the booked length. | 10-03 |
| A12 | The landing checkbox "AI 打给你" (`ai_call_opt_in`) governs only the WELCOME AI call. A repeat registrant getting the welcome AI call again is fine. | 10-02 |
| A13 | **All admins can read all leads.** Sales agents and leaders get view-all, **including the Sales Dashboard's company-wide orders and commission** (option "A. 全部打开"). Migration `2026_10_05_100001_grant_view_all_leads_to_sales_roles`. | 10-04 |
| A14 | 20-minute grace before the automation hands a lead to a colleague: a late registrant's AI call may still be running. | 10-04 |
| A15 | **One REP source** = `lead_reps`. The **top REP = the most engaged** (spoken time → WhatsApp → tasks + appointments → latest contact). The list's REP column, its sort and the `top_rep` filter all read it. *(10-11, D7: "most engaged" is now the score — spoken seconds + staff WhatsApp × 10 s — first; see B17.)* | 10-05 |
| A16 | If someone ON the round-robin list has spoken to the lead **more than** the account manager, they **become** the account manager (`TopRepOwnership`). Someone NOT on the list (e.g. Support) never takes over. *(10-11, D8/D9: by score, only when clearly ahead — > 20 % and ≥ 300 s — and also at the moment of payment; see B17.)* | 10-05 |
| A17 | **Round robin:** ONE company-wide list the boss edits freely; order + repeats = weighting. It names the account manager of **every new lead with none, from any source**. **No second rotation after payment: the account manager IS the REP.** List off = nothing auto-assigns or switches. | 10-05 |
| A18 | Submit the 4 new WhatsApp templates to Meta from local (same Cloud channel as production). | 10-05 |
| A19 | **The sales flow guide lives ONLY in the CRM** (`/manage/my-work/sales-flow`, `salesFlowGuide.js`). The claude.ai artifact page is retired; do not make an outside copy. | 10-06 |
| A20 | My Work gets two tabs: **My Work** + **Sales flow guide**; the flow chart sits on the guide's 流程 tab. *(Superseded by the 10-12 row at the end of this table: four strip tabs; the guide's charts are "Live flow & actions" and "How the three stages work".)* | 10-06 |
| A21 | **Retire `/manage/action-items`.** My Work is the ONE task list. KEEP the lead's Action items tab. MOVE Team Tasks + Completed History into My Work (Done view; "Tasks nobody holds" for leaders). REMOVE the Hub sign-in "My Checklist" modal. My Work shows only tasks on leads the viewer can still see. *(In code: the board's PERSON's visibility; the leader's "Tasks nobody holds" view uses the viewer's.)* | 10-06 |
| A22 | **Calendar** = its own sidebar entry, **every admin can open it**. Writes still need `manage-calendar`, which every sales admin has. The **Dashboard** sidebar menu = super admin only. | 10-06 |
| A23 | Show where a lead is on the flow: **both** a 3-stage bar (lead page, lead modal, Leads list) **and** the flow chart on the Journey tab (passed green, current blue, rest grey). | 10-06 |
| A24 | Commit + push everything to `dev-shawn`. | 10-07 |
| A25 | **Human contact is mandatory**: every answered AI call still needs a colleague's contact, useful answers or not; attendance, payment or a new registration never close an unfinished contact task. Supersedes A5's "useful → no human" and B2. | 10-08 (morning) |
| D1 | **Stage structure = the owner's three images.** Stage 1 *Registration → Preview webinar* (incl. a human "Invite to a Preview" box above the landing). Stage 2 *After Preview → Project webinar*: Attended? → Paid (Membership)? → payment WA → auto-assign REP (DATA 3+4) → Human Zoom → R1; unpaid / no-show → WA → AI call → DATA 3 → Human Call / Zoom (DATA 4) → R1 → Project webinar. Stage 3 *After Project webinar → Closing*: the same split with the Project fee, REP (DATA 5) → Human Zoom → Closing; unpaid → … → Closing; Closing → Won (keep following up until converted) / Not closed + reason. Replaces Codex's re-labelling (unpaid-after-Project as "Stage 2"). Member preparation (consent · questions · WhoPay) and consultation belong to Stage 2's paid branch; paid Project opportunities to Stage 3's. | 10-08 |
| D2 | **A colleague's registration starts no automation** — the agreed-Session modal, From Preview, admin add, CSV import: no AI call, no M2, no journey opened at registration, no automatic task, and no M1 welcome — except From Preview, which still sends the Session's welcome WhatsApp with the Zoom link. The customer waits for the webinar (R1) and is **not** human work in My Work. Only landing-page registrations run the journey. | 10-08 |
| D3 | **Re-contact window.** A suggestion recorded as "Spoke to them" / "Cannot be reached" with no agreed date returns after `FUNNEL_RECONTACT_AFTER_DAYS` days (default **30**). An agreed date is a task on that date. "Not closed" never returns. | 10-08 |
| D4 | **Record contact on every human box**, incl. paid-member service (preparation / Zoom / meeting) and every Stage 3 step. On a service step a contact **never completes** the step — only the real record does (FPA, a booked / held consultation, a deal Won / Not closed); it shows as "Last contact". | 10-08 |
| D4b | **Stage 3 unpaid closing decision**: on `project_no_show` / `project_unpaid` / `project_after_call`, "Spoke to them" also records **Still following up** (default) or **Not closed** + a required reason from `Engagement::LOST_REASONS`; Not closed puts that customer × Project in the Not closed box. | 10-08 |
| D5 | **Who may record**: the lead's account manager, the opportunity's sales owner (Stage 3), a holder of the task, and super admins. Whoever records it, every person's My Work and every board treat the obligation as recorded. | 10-08 |
| D6 | **Stage 1 is open.** Any sales admin (active, manage role, `sales-execution`) who can see the lead may Record contact on a **Stage 1** step (`preview_invite`, `preview_call`) of a customer still in Stage 1. Stage 2/3 keep D5. The stage is verified server-side (`FollowUpAccess::canRecord()` + `JourneyWorkQueue::owedOpenQueue()`), never taken from the posted queue name. | 10-11 |
| D7 | **Top REP score** = phone + Zoom + F2F seconds + **10 s per staff-written WhatsApp message** (not automation / OTP / test sends). Record contact is not scored. | 10-11 |
| D8 | The account-manager seat follows the Top REP at any time (rollup every 15 min), but only when the challenger leads by **> 20 % AND ≥ 5 min**; the displayed Top rep uses the same measure. | 10-11 |
| D9 | At **every payment**, recompute that lead's reps at once and seat the Top REP as account manager (the Stage 3 Zoom closer still comes first). | 10-11 |
| D10 | My Work → Sales steps **Help team**: colleagues' **overdue** Stage 1 To do. | 10-11 |
| D11 | Help team also lists **new** Stage 1 customers whose account manager was assigned ≥ 3 days ago (window 30 days) and nobody has contacted since (config `lead_distribution.help_team`). It is a shortcut list, **never a permission** — D6 already lets any sales admin contact any Stage 1 customer. (Code and handbooks label both kinds "D10".) | 10-11 |
| — | **Names and tabs (owner, 10-12):** "My Work" is shown as **My Workspace** (URLs and code names unchanged); its strip = **My Task** · Calendar · My Sales · Sales flow guide; Calendar left the Operations sidebar (kept only for admins with no lead level); the work tabs read **Sales steps** and **Action Item**; the Schedule & messages tab is hidden (`my_work.schedule_panel`). | 10-12 |

## B. Implementer decisions (✅ = later confirmed by the owner)

| # | Decision | Where |
|---|---|---|
| B1 | The journey is a NEW layer (`Src\Lead\Journey`), not the Appointment Engine. The AE has its own lead list, is per agency and is not webinar-aware. | plan §2 |
| B2 | ~~"Useful information" from the AI call = profile-2 extracted `will_attend` AND `buy_intent` (not `unknown`). Useful → no task; the lead is listed under "AI handled".~~ **Superseded 10-08 (A25):** every answered call becomes a task; "useful" only picks the hand-off reason and the outcome's "did we learn it" flag. | plan #10 |
| B3 | The post-call "thanks" WhatsApp stays. M1's "Yes, 我已进群了" button reply is caught by the template-menu bot. No-show but paid → the paid path wins. | plan #7–9 |
| B4 | Stage 3 human action = book the 1-1 sales Zoom, not "remind to join". | plan #12 |
| B5 | Client Success roles (Analyst / Caller / Closer) now GRANT lead visibility, by making the holder a rep. This changes the 2026-09-19 rule. | 10-03 |
| B6 | A former account manager is RETIRED from reps when the lead moves, unless still tied to it (open task, closer, Client Success role). ✅ The owner was fine with it once all admins could read all leads; it now only keeps "my leads" lists correct. | 10-04 |
| B7 | A Project journey closes on a deal Booked/Lost ONLY when that deal's payment is on the journey (`journeyOwnsDeal`). ✅ The owner will set slot offers to make the match exact. | 10-04 |
| B8 | The source name "From Preview"; the plan's "review task" became a My Work reminder card, because a task needs a lead. | 10-04 |
| B9 | The REP is assigned on the scan AFTER payment, because the deal is not open yet at the payment moment. `pickRep` = the deal's Zoom closer if set and able, else `pickPerson` (account manager, or a round-robin turn). | 10-04 / 10-05 |
| B10 | The "one missed-call message per lead per day" cap also covers M4. | 10-04 |
| B11 | The AI-call pacer defaults to 10 per minute (`RETELL_CALLS_PER_MINUTE`). A refusal for too many concurrent calls is retried once after 10 min. A Retell-refused call now counts as "not placed". | 10-04 |
| B12 | The Journey board counts two groups. FLOW = journeys opened in the range. WORK = every running journey, whenever it opened, so an overdue task never hides behind a date range. | 10-04 |
| B13 | The Pay attention `journey_overdue` flag waits **one extra day** past due; the board flags overdue at once. The owner was asked whether to align them; no answer. | 10-04 |
| B14 | The report is called "Sales flow board", not "Lead journey", because that name is taken. It is OFF until the boss enables it. | 10-04 |
| B15 | Time with Leads is cumulative; use Sales Engagement for this week. | 10-04 |
| B16 | Phase 6: the Summary prompt was not changed, because changing it marks every Summary stale. Only "Yes" answers count for readiness. AI judgements (interest level, suspected agent, time-waster) are not answers. AI field → readiness mapping: budget → Cash; viewing / purpose / area → Need; project feel → Property fit. | 10-05 |
| B17 | ~~Top-talker switch: **spoken seconds only** (phone + Zoom + F2F). WhatsApp and tasks do not count, otherwise whoever answers the inbox would grab leads.~~ **Superseded 2026-10-11 by owner decisions D7/D8:** the seat follows the top-rep SCORE (spoken seconds + each staff-written WhatsApp message × 10 s; tasks still not scored) and moves only when the challenger is > 120 % of the manager's score AND ≥ 300 s ahead; D9 also runs it at payment time. Still true: never across groups; leavers are excluded; already-assigned tasks stay with their holder; `--keep-managers` skips the switch (and `--preview` now lists moves without making them). | 10-05 → 10-11 |
| B18 | Round-robin assignment waits **60 s after the lead is created** (after commit), so a way in that names its own manager (self-add, import with a manager, the journey) wins and costs nobody a turn. | 10-05 |
| B19 | `scheduled_report_recipients` is never copied by the local DB sync: it holds the boss's real contacts, and the local scheduler could send. | 10-06 |
| B20 | Calendar for an admin without `manage-calendar` (only Wayne and App Review Demo): view only. No staff list, no Booking-page button, no edit/delete on activities or meetings. | 10-06 |
| B21 | Sales-flow chart: a 4th state, **orange "没做到"** (reached but not done: refused AI call, a task expired or superseded). A stage with no record shows **pale grey "没有记录"**. The **list chip follows the bar's journey** (`lead_flow.journey_uuid`). None of these was asked; all were reported to the owner on 10-06 with no objection yet. | 10-06 |
| B22 | The bar's stage comes from the BOX the lead is in, never from `flow_stage`, which is wrong for paid-before-verdict leads. `flowStage()` stays, because DATA-point routing depends on it. | 10-06 |
| B23 | Git: `dev-shawn` was fast-forwarded to master and the work restored from GitHub Desktop's stash commit (see the session log, 10-07). | 10-07 |

Implementation details of D1–D5 (what each package built, the review fixes): [09](09-session-2026-10-08-claude.md);
behaviour: the [Sales flow chart](../../modules_handbook/shared/sales-flow-chart/readMe.md) and
[Record contact](../../modules_handbook/shared/sales-flow-chart/record-contact.md) handbooks.

## C. Things the owner explicitly said NOT to do (or not yet)

- Do not auto-register Preview people on the Project webinar (A6).
- Ignore funnels 7 / 8 / 10 for now (A2).
- 10-02, deferred: the reopened deal keeps its cancelled booking (still unfixed). The Team Performance leak and the
  payment-link-only receipts were fixed later in Phases 0 and 4.
- No outside copy of the sales guide (A19).
