# Review findings — SalesFlowChartPath + the sales-flow bar/chart (FIXED 2026-10-13)

**Status (2026-10-13):** every confirmed and unverified finding below was re-checked against the code of 2026-10-13
with an in-memory scenario, reproduced, and **fixed** (uncommitted, branch `dev-shawn`). Each fix has one regression
test: `tests/Unit/Lead/SalesFlowChartPathTest.php` (C2, C3, U1–U4, merge) and
`tests/Feature/Lead/FunnelJourneyTest.php::test_the_leads_list_puts_a_lead_on_the_same_journey_as_the_lead_page`
(C1 scenario B, through the real list query). The handbook's account of the rules is
[funnel-journey readMe §6d](../../modules_handbook/manage/leads/funnel-journey/readMe.md).

Two premises below changed after 2026-10-07 and were taken into account: `recordForLead()` has no callers any more
(offer / callback events are written on the journey of the send that caused them), and since D2 the From-Preview
pick opens **no** Project journey — one opens on demand at its first reminder or verdict, with no `registered`
event, so its cycle starts at its first event.

**Status (2026-10-07, historical):** none of these was fixed. They were found AFTER commit `20e1678cb` was made, so
that commit shipped the bugs.

**How they were found:** an adversarial review workflow (run `wf_a3d3e0b2-e4d`, 2026-10-06 night). Three finders
looked at it from different angles: *rules* (does the walk match the design), *robust* (N+1, crashes, determinism)
and *ui* (payload ↔ Vue). Then one skeptic per finding tried to REFUTE it, using in-memory scripts with no DB.

**Verification status:**
- 5 findings survived verification ("CONFIRMED").
- 4 were never verified, because the session hit its usage limit ("UNVERIFIED"). Treat these as likely but unproven.
- 2 were refuted.

The throwaway proof scripts lived in the session scratchpad and are gone. Each scenario below is written so you can
rebuild it as an in-memory test in `tests/Unit/Lead/SalesFlowChartPathTest.php`. That file already builds
`FunnelJourney` / `FunnelJourneyEvent` models without a database; copy its helpers.

**Files involved:**
- `src/Lead/Journey/Support/SalesFlowChartPath.php` (~1,539 lines)
- `src/Lead/Journey/FunnelJourney.php` (`chipsForLeads()`)
- `resources/js/Components/Leads/SalesFlowProgress.vue`
- `resources/js/Pages/Manage/Leads/Partials/JourneyCell.vue`

Background: [04-sales-flow-chart-path-design.md](04-sales-flow-chart-path-design.md) and
[funnel-journey handbook §6](../../modules_handbook/manage/leads/funnel-journey/readMe.md).

---

## Root cause shared by C1 + C2 (fix this first)

The lead page and the Leads list can choose **different journeys** for the same lead, so the list's pills and chip
contradict the page's bar. `forLead()` picks between the Preview walk and the Project walk with `orderKey()`
(around line 493–500):

```
[$pathKnown ? $walk->cycleEventId : 0, step_since, id]
```

- **The page** (`LeadsController::journeyPayload()`) loads `events`, so it orders the two walks by the id of the
  event that started each journey's current cycle.
- **The list** (`FunnelJourney::chipsForLeads()` → `forLead($journeys, false)`) loads no events, so `cycleEventId`
  is 0 there and `step_since` decides. On a tie, the journey id decides.

Any later move on the older journey therefore flips the list's choice, but not the page's. Since 2026-10-06 the list
chip follows `lead_flow.journey_uuid`, so the chip text flips with it.

---

## CONFIRMED

### C1 · medium · List and page pick different journeys → pills/chip contradict the bar
- **Where:** `SalesFlowChartPath.php` ~496 (`orderKey`), `FunnelJourney.php` ~377 (`chipsForLeads`).
- **Scenario B (the commonest):**
  1. Preview: attended → unpaid → task2 (`human_pending`).
  2. An admin picks the lead From Preview. The Project journey is registered with `data.source = preview_candidate`, and `candidate_marked` is logged on the Preview journey.
  3. The Project deal is Booked (Project `status = WON`, `step_since` = 10-04).
  4. The next day the colleague ticks the still-open Preview task2 in My Work. The Preview journey moves `human_pending → human_done`, with `step_since` = 10-05.
  - **Page result:** bar `[done, done, won]`, band 3, outcome won.
  - **List result:** chip "Preview webinar / Colleague called / Active", pills `[done, current, todo]`, band 2.

  This is exactly the "old Preview journey beside a Booked deal" mismatch the chip change was meant to fix.
- **Scenario A:**
  1. An old Project journey stays active at `no_show`.
  2. The lead re-registers on the Preview landing and reaches `offer_sent` at 10:05.
  3. At 12:00 `UnpaidAfterWebinar` moves the Project journey `no_show → unpaid`.
  - **Page result:** current `clicked`, band 1.
  - **List result:** current `follow3`, band 3.
- **Tie case:** `offer_sent` and `callback_clicked` are written to every active journey in the same second through `recordForLead`. The list then takes the higher journey id, while the page takes the later cycle. Page: `project`, band 2. List: `clicked`, band 1.
- **Suggested fix (verified as sound by the skeptic):** give the list the same cycle-start key, read in the SAME query with no N+1.
  1. In `chipsForLeads()`, add:
     ```php
     ->withMax(['events as cycle_event_id' => fn ($q) => $q
         ->whereIn('event', [FunnelJourneyEvent::EVENT_REGISTERED, FunnelJourneyEvent::EVENT_REOPENED])
         ->where('to_step', self::STEP_REGISTERED)], 'id')
     ->withMin('events as first_event_id', 'id')
     ```
  2. In `SalesFlowChartPath::walk()`, in the step-only branch, set
     `$walk->cycleEventId = (int) ($journey->getAttribute('cycle_event_id') ?? $journey->getAttribute('first_event_id') ?? 0);`.
     This mirrors `replay()`'s fallback to the first event.
  3. In `orderKey()`/`forLead()`, decide by `cycleEventId` whenever BOTH walks have one (> 0), not only when `$pathKnown`.
  4. Regression test: scenario B, asserting that `forLead($j, false)['journey_uuid']` and `['band']` equal `forLead($j)`'s.
- **Watch:** combine with C2's fix, because C2 changes the PAGE's rule too. The list and the page must end up on the same rule.
- **FIXED 2026-10-13 (with C2 — one rule for both).** `chipsForLeads()` now adds, in its one query,
  `SalesFlowChartPath::withListKeys()`: per journey the id of its cycle-start event, its first event, its last MOVE
  and its last `candidate_marked`. `forLead()` gives the lead to the Preview journey only when its cycle start is
  after the Project journey's last move — on the page from the log, on the list from those keys; only a journey with
  neither falls back to `step_since`. `orderKey()` is gone. Scenario B now reads band 3 / won on both
  (`FunnelJourneyTest::test_the_leads_list_puts_a_lead_on_the_same_journey_as_the_lead_page`). **Scenario A** now
  reads the PROJECT journey (follow3, band 3) on both, because the Project journey moved (no_show → unpaid) after the
  Preview sign-up — that is C2's rule, not a bug. **The tie case** no longer occurs: `recordForLead()` has no callers,
  and the rule compares event ids, which never tie.

### C2 · medium · A Preview re-registration outranks a Project journey that moved later
- **Where:** `SalesFlowChartPath.php` ~493 (`orderKey`) and ~409–413 (owner choice in `forLead`).
- **Scenario:**
  1. Preview landing → attended → unpaid → task2 → human_done.
  2. An admin picks the lead to the Project webinar.
  3. Days later the lead signs up again on the Preview landing. `registered` is accepted from `human_done`, so a new Preview cycle starts, plus a welcome.
  4. After that the lead attends the Project webinar, pays the project fee, gets a REP, and a Zoom is booked (Project step `zoom_pending`).
  - **Page result:** current `welcome`, band 1, bands `[current, todo, todo]`. A paying project customer with a booked Zoom is shown at 第1段.
  - **List result:** `rep2`, band 3.
  - The same happens for an IMPORTED Project journey: its "cycle start" is just its first reminder, so any later Preview sign-up outranks it for good.
- **Expected** (design correction [skeptic 1]): the Preview journey owns the lead only when its cycle start is after the Project journey's LAST MOVE.
- **Suggested fix:**
  1. In `replay()`, track `lastMoveId`: the id of the latest cycle event with `to_step !== from_step`, defaulting to `cycleEventId`.
  2. In `forLead()`, when the path is known: `$owner = $previewWalk->cycleEventId > $projectWalk->lastMoveId ? $previewWalk : $projectWalk;`.
  3. The existing test `test_an_old_active_project_journey_loses_to_a_preview_cycle_started_later` still passes. Add one regression test for this scenario.
  4. For the list, `last_move_id` can come from another `withMax` on events where `to_step <> from_step` (needs a raw column comparison), or you can use `step_since` as the Project's last-move proxy.
- **FIXED 2026-10-13** as suggested: `replay()` tracks `lastMoveId` (default: the cycle start), the list reads it
  from a `withMax` with `whereColumn('to_step', '!=', 'from_step')`. The scenario, rebuilt with today's D2 (the
  Project journey opened by its first reminder), reads `rep2`, band 3, on the page AND the list
  (`SalesFlowChartPathTest::test_a_preview_re_registration_does_not_outrank_a_project_journey_that_moved_later`);
  `test_an_old_active_project_journey_loses_to_a_preview_cycle_started_later` still passes.

### C3 · low · Project landing registrant who pays before the Project webinar: band 2 reads "没有记录 (no record)"
- **Where:** `SalesFlowChartPath.php` ~791 (`seed()`), `bandHasRecord()`.
- **Scenario:** a Project journey with `registered` (source `landing`) → `welcome_sent` → `paid` (before the webinar) → `rep_assigned`.
  - `seed()` puts `project` in as a waiting box (LEAVE_DROP), and `paid` drops it.
  - Band 2 then has no box, so the page shows band 2 as `skipped`, with the hint "没有记录…(例如 import 或 admin 加进来的客户)". That hint is false: the person signed up on the landing page.
  - The list shows band 2 as `done`.
- **Suggested fix:** in `bandHasRecord()` (path branch), return true for `$i === 2 && $band === 3`. Band 3 exists only on a Project journey, and its registration is band 2's record. `project` stays dropped, so it never reads as attended. Regression assertion: page bands `['skipped','done','current']` == `forLead(..., false)`.
- **FIXED 2026-10-13** as suggested, for the page and the list alike
  (`SalesFlowChartPathTest::test_a_project_registrant_who_paid_before_the_project_webinar_has_a_record_of_stage_two`).

### C4 · low · The list hover prints the step-only box title, which is wrong for imports and refused calls
- **Where:** `SalesFlowProgress.vue` ~85 (`summary`), used by `JourneyCell.vue` ~68 (`<SalesFlowProgress compact labelled>`).
- **Scenario:**
  - (1) An imported or admin-added Preview registrant: the journey is opened by a reminder and the step is `registered`. The list hover says "现在：客户在 landing page 报名", while the page says "现在：Preview webinar". The design forbids drawing `start` for non-landing leads.
  - (2) A refused AI call (step `ai_call_missed`): the list hover says "现在：接了吗？", while the page says "AI 打电话".
  - The design accepted the step-only node on the list only because "only the band pills are shown there". The labelled hover now prints the node.
- **Suggested fix:** in compact mode, name the STAGE, not the box. For example:
  `const summary = computed(() => [\`第 ${props.flow.band} 段 / 3\`, props.flow.ended ? where.value : STAGES[props.flow.band - 1]?.title].filter(Boolean).join(' · '));`
- **FIXED 2026-10-13** as suggested (`SalesFlowProgress.vue` `summary`; only the compact form uses it — the page's
  full bar still names the box from the walk). Copy-only: no test (none exists for the component).

### C5 · (duplicate of C1, found by the *ui* lens)
- "The list's pills/chip and the page's bar choose different journeys, so bands and outcome contradict each other (including a Booked deal)". It has the same root cause and the same fix as C1.
- **FIXED 2026-10-13** with C1.

---

## UNVERIFIED on 2026-10-07 (the verifier ran out of quota) — all REPRODUCED and FIXED on 2026-10-13

### U1 · medium · A rejected real "attended" never overturns an inferred no-show
- **Where:** `SalesFlowChartPath.php` ~1141.
- **Scenario (Preview):**
  1. landing → welcome → AI answered (useful) → `ai_handled` (reminders).
  2. 30 minutes after the end, `SettleAttendanceAfterWebinar` writes an INFERRED `webinar_no_show` (`data.inferred`, `event_id` 7, ref registration #55).
  3. The lead pays (`no_show → paid`), and then `rep_assigned`.
  4. The REAL `webinar_attended` for registration #55 / event 7 arrives. It is rejected because the journey is on the paid path (`from = to = rep_assigned`), but `attended_at` is stamped.
  - **Actual:** passed `[…, preview, came, noShow, paidMember]`, and `came-noShow` (没来) is lit.
  - **Expected:** `noShow` removed, and `came-paidMember` (来了) lit.
- **Project version:** inferred no_show → paid → rep_assigned → rejected attended gives `[project, paidFee, follow3]` with `paidFee-follow3` lit, and `paidFee-rep2` not lit.
- **Likely fix:** the "inferred no-show overturned" rule must also fire for a REJECTED attended with the same `event_id`, not only for a moved one.
- **FIXED 2026-10-13** (reproduced): `attended()`'s refused branch calls `overturnNoShow()` before the splice, so
  `noShow` / `follow3` is dropped and `came-paidMember` / `paidFee-rep2` lights
  (`SalesFlowChartPathTest::test_the_real_attended_refused_on_the_paid_path_overturns_an_inferred_no_show`).

### U2 · medium · Project deal closed before the attendance verdict lands → attended webinar drawn grey, band 2 "no record"
- **Where:** `SalesFlowChartPath.php` ~269.
- **Scenario:**
  1. A Project-landing registrant pays during the webinar (`registered → paid`, which drops `project`).
  2. The REP is assigned and the deal is marked Booked (`closed_won` from `rep_assigned`).
  3. Then the reconcile records `webinar_attended` on the closed journey (`from = to = won`, `attended_at` stamped).
  - **Actual:** passed `[paidFee, closed]`, missed `[rep2]`, bands `[skipped, skipped, won]`.
  - **Expected:** `project` passed (it is a fact) and band 2 done. The same applies to `closed_lost`.
- **Likely fix:** treat an attended event logged on a closed journey (from = to = won/lost) the same way as the paid-path splice.
- **FIXED 2026-10-13** (reproduced): a refused attended from `won` / `lost` is a fact like one from the paid path
  (`ATTENDED_IS_A_FACT_STEPS`); `project` is spliced in before the first 第 3 段 box. Result: passed
  `[project, paidFee, closed]`, missed `[rep2]`, bands `[skipped, done, won]` — band 2 is also covered by C3's rule
  (`SalesFlowChartPathTest::test_attendance_recorded_after_the_deal_closed_still_draws_the_project_webinar`).

### U3 · medium · After the From-Preview pick, later work on the Preview journey shows orange ("到过但没做到")
- **Where:** `SalesFlowChartPath.php` ~1042.
- **Scenario:**
  1. Preview: attended → unpaid → `handed_to_human` (task2 open).
  2. The admin picks the lead.
  3. The next morning the colleague logs the call (`human_done` on the Preview journey).
  - **Actual:** missed = `[task2]`, and `task2-pick` is lit. The chart says the call was never done, while the Journey card says "Colleague called".
- **Same on the paid path:** the lead is picked while the REP's Zoom task is open (`rep_assigned`), then `zoom_scheduled` / `zoom_done` happen on the Preview journey. Actual: missed = `[rep1]`.
- **Likely fix:** after `candidate_marked`, a later `human_done` / `zoom_done` on the Preview journey should turn its task box from missed to passed.
- **FIXED 2026-10-13** (reproduced; more likely since A25 keeps call tasks open): the walk remembers the box the
  pick found the lead in; a later moving `human_done` (task1 / task2) or `zoom_scheduled` / `zoom_done` (rep1) on the
  Preview journey turns that box green (`DONE_AFTER_PICK`;
  `SalesFlowChartPathTest::test_a_task_finished_on_the_preview_journey_after_the_pick_is_done_not_missed`).

### U4 · low · With the Project funnel untracked, a lead picked before their Preview webinar shows band 1 on the list and band 2 on the page
- **Where:** `SalesFlowChartPath.php` ~842.
- **Scenario:** the Project funnel's Sales flow is OFF. The lead is picked From Preview before their Preview session has happened, and the Preview journey is at stage 1, step `reminders`.
  - **Page:** `candidate_marked` moves the walk to `project`, so band 2.
  - **List:** `nodeFor(reminders)` gives `preview`, so band 1.
- **Likely fix:** this is a list-only limitation. C1's `withMax` approach could also read "has a candidate_marked event" (`withExists`).
- **FIXED 2026-10-13** (reproduced, with `human_done` stage 1 in place of the now-unreachable `reminders`; and broader
  than "untracked": since D2 a picked lead has no Project journey until its first Project reminder). The list's keys
  include the last `candidate_marked` id; a Preview journey picked in its current cycle reads `project`, band 2, as on
  the page (`SalesFlowChartPathTest::test_the_list_reads_a_pick_made_before_the_preview_webinar_like_the_page`).

### (also raised, low, unverified) Merge reconcile skips ambiguous steps
- **Where:** ~1349.
- **Scenario:** a lead merge moves the loser's events onto the winner's journey but keeps the winner's step, `unpaid`.
  - **Page:** the walk ends at `ai1` (band 1).
  - **List:** `unpaid` (band 2).
- The class docblock says the step "wins whenever it names the box unambiguously". Reconcile at least on the after-webinar verdict steps.
- **FIXED 2026-10-13** (reproduced): `finish()` also lets the step win when it names a box in ANOTHER stage than the
  walk ended in (the design's original band check, kept beside the box check), so the page reads band 2 like the
  list (`SalesFlowChartPathTest::test_a_merged_log_that_ends_in_another_stage_than_the_step_follows_the_step`).

---

## REFUTED (do not fix)

- **"The list chip now follows lead_flow's journey, so an unassigned task on another active journey loses its rose
  warning."** This reproduces, but it is deliberate and documented: see the `chipsForLeads` docblock and the
  funnel-journey readMe §6. The unowned task still shows in My Work → "Tasks nobody holds". If the owner wants the
  warning back, keep the chip on the lead_flow journey but OR the `is_unowned` / `needs_human` flags across all
  active journeys. That is an owner decision, not a bug.
- **"The lead modal shows the bar in the Appointment Engine suite."** Not reproducible in practice. The AE lead
  page hands linked leads to the CRM Show page with `suite=appointment-engine`, which hides the bar. The native AE
  page gets a `crm` prop only under contradictory permissions.
