> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Lead Funnel 与 Task

> **Status boundary**：Funnel 与 Task lifecycle 分离已经进入 Task V3 selected Target；这不表示 projection 已在目标环境部署或通过验收。
>
> 当前 contract 见 [Task V3 Product / Domain Contract](/product-design/v3/tasks-feature/task-domain-lifecycle.md)，实施与环境状态见 [Task V3 Rollout 状态快照](/product-design/v3/tasks-feature/task-v3-rollout-status.md)。[Task V2+ 工程审计与设计建议](/product-design/v2/tasks-feature/task-v2-plus-engineering-audit.md) 只保留为 historical context。

## 1. 三个维度不要再混

| Concept               | 回答的问题                                      | Example                                                    |
| --------------------- | ------------------------------------------ | ---------------------------------------------------------- |
| `contacts.leadStatus` | AI/系统当前如何概括这个 Lead？                        | `new / attempted / booked`                                 |
| Task system           | 门店要解决什么、当前属于哪类工作、下一步做什么、实际做了什么、最终 Outcome？ | `lead_conversion` + `displayType` + Next Action + Activity |
| Funnel Projection     | 某个 cohort 在指定窗口内走到了哪里？                     | Received → Attempted → Connected → Booked                  |

关键规则：

- `leadStatus` 不是 Task status。
- Task `open/closed` 不是客户的完整历史。
- Funnel stage 不能拿来表示员工是否开始处理。
- MVP 不新建 Journey/Milestone/provider system；它从当前真实 evidence 做 projection。

***

## 2. Current `contacts.leadStatus`

Source：`callytics-infrastructure/packages/common/src/db/schema/contacts.ts`。

当前它是 AI 可写的 mutable text snapshot，schema 注释列出：

```text
new
attempted
connected
booked
showed
trialed
converted
unreachable
lost_contact
neglected
bad_timing
not_interested
```

它适合 Contact/Lead UI 的当前 label 和 compatibility filter，不适合单独承担 Funnel counting 或权威 customer history。

| Value                         | 正确解释                                                                               |
| ----------------------------- | ---------------------------------------------------------------------------------- |
| `new`                         | 当前未观察到 qualifying outreach                                                         |
| `attempted`                   | 有 outreach Activity；更接近 work projection                                            |
| `connected`                   | 有 connected communication evidence                                                 |
| `booked`                      | 当前 evidence 支持 booked；必须同时展示 verification                                          |
| `showed / trialed`            | 当前没有 attendance provider truth；只有 explicit communication 或 staff confirmation 才可表达 |
| `converted`                   | 当前没有 membership system truth；必须标 communication/staff-confirmed 或 AI-inferred       |
| `unreachable / lost_contact`  | 需 versioned observation/exhaustion policy                                          |
| `neglected`                   | 门店执行 coverage，不是客户意向；应从 Activity/SLA 派生                                            |
| `bad_timing / not_interested` | 客户意向结果，需 explicit evidence 或员工确认                                                   |

***

## 3. Current Funnel 的真实输入

Current `/v3/leads/funnel` 已经综合：

- `leads`：Email Lead intake。
- `tasks`：Task V2 type/Outcome。
- `calls` 与 `messages`：RingCentral communication。
- `contact_timeline`：Task Activity 和事件。

Current implementation source：

- `callytics-infrastructure/apps/api/src/routes/v3/lead-funnel.ts`
- `callytics-infrastructure/apps/api/src/utils/lead-intake-events.ts`
- `callytics-infrastructure/apps/api/src/utils/lead-funnel-stage-counts.ts`

它不是 authoritative CRM report。Contact snapshot、Task close result 和 communication evidence 的 strength 不同，不能只返回一个 stage 而隐藏来源。

***

## 4. Target projection contract

建议的最小 projection（不是强制线性 workflow）：

```text
Received → Outreach Attempted → Connected → Booked → Converted

Received / Attempted / Connected 也可以直接 → Converted
```

| Funnel stage       | Evidence rule                                                                                                            | Caveat                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------- |
| Received           | Email Lead intake / accepted Lead source                                                                                 | `system_observed` 只证明 Lead 到达                      |
| Outreach Attempted | qualifying outbound Task Activity                                                                                        | 不要求 Task close                                     |
| Connected          | connected Call 或 inbound reply                                                                                           | 与“拨出电话”分开                                          |
| Booked             | current valid completed-booking evidence；Target 为 `businessProgress=intro_booked`，legacy form fallback 标 `form_asserted` | 非终态；Task 保持 open；form fallback 不自动改变 `displayType` |
| Converted          | `lead_conversion.resultCode=converted` terminal Outcome                                                                  | 可以不经过 Intro；当前不是 membership-system verified        |

如果未来需要 Showed/Trialed：

- 必须先定义当前可用 evidence。
- 没有 external attendance truth 时只能标 staff/communication/inferred。
- 不因预约时间已经过去就自动推断 attendance。

每个 projection row/aggregate 至少携带：

```text
stage
occurredAt / attributedAt
evidenceType
evidenceRefs
policyVersion
projectionDefinitionVersion
```

后续更正 Task Outcome 时，current Funnel projection 更新，但旧判断和 correction 留在 audit trail。

***

## 5. Lead Task 如何工作

Target 不再使用 `lead_outreach Task → lead_follow_up Task → convert_after_intro Task` relay。Backend 只有一个 stable `taskKind=lead_conversion`；员工仍看到三个可筛选的 current `displayType`：

```text
lead_outreach
lead_follow_up
booked_not_converted
```

`booked_not_converted` 是兼容性的 UI category；精确进展必须看 `businessProgress=intro_booked / intro_attended`。Current taxonomy 里的同名 legacy value 实际偏向“已 attended/completed Intro”，migration 不能按名字直接当 booking evidence。

示例：

```text
Email Lead received
  → create Task(lead_conversion)
  → displayType: lead_outreach
  → Next Action: Call now
  → first-response SLA: 5 minutes

Phone Activity: no_answer
  → Task remains open
  → displayType: lead_follow_up
  → Next Action: Send SMS, call tomorrow

SMS explicitly confirms booking
  → Business Progress: intro_booked
  → displayType: booked_not_converted
  → Task remains open
  → Next Action: confirm attendance plan / discuss the right membership path
  → Funnel projection: Booked (communication-confirmed)

Later, membership conversion is explicitly confirmed
  → Outcome: converted
  → Task closes
  → Funnel projection: Converted
```

如果客户在线下预约而系统没有 communication evidence，员工用 `staff_confirmed` 记录 `intro_booked` progress；这不需要 Close Task。人工入口是 data boundary 的组成部分，不是失败模式。

Lead follow-up 不一定是推销 Intro：客户可能需要答疑，也可能直接购买 Membership。因此 `converted` 可以从三种 `displayType` 中任何一种直接发生；系统不知道 attendance 时也不能凭时间自动猜。Booking 被取消或纠正后，Task 仍 open，并回到 `lead_follow_up`。

***

## 6. Reporting integrity

- `Attempted` 来自 Activity，不来自 Task lifecycle。
- `Booked / Converted` 必须显示 evidence strength；前者是 non-terminal progress，后者是 terminal Outcome。
- Task Outcome 可影响 Funnel，但不能反向把 Funnel label 当 closure evidence。
- Revenue 只能写 assisted/attributed/staff-confirmed；没有 authoritative source 时不能写 verified revenue。
- Definition 改变时发布新的 `projectionDefinitionVersion`，不静默重算历史 dashboard。
- 所有查询强制 `store_id`；同一手机号在不同 store 的 evidence 不得混用。

***

## 7. Related documents

- [Task V3 Product / Domain Contract](/product-design/v3/tasks-feature/task-domain-lifecycle.md)
- [Task V3 Rollout 状态快照](/product-design/v3/tasks-feature/task-v3-rollout-status.md)
- [Historical Task V2+ audit](/product-design/v2/tasks-feature/task-v2-plus-engineering-audit.md)
- [Lead Tracker 页面展示](/product-design/v2/lead-tracker-feature/lead-tracker-display.md)
- [Lead Tracker Schema](/product-design/v2/lead-tracker-feature/lead-tracker-schema.md)