Retaintive

    Lead Funnel 与 Task

    Status boundary：Funnel 与 Task lifecycle 分离已经进入 Task V3 selected Target；这不表示 projection 已在目标环境部署或通过验收。

    当前 contract 见 Task V3 Product / Domain Contract，实施与环境状态见 Task V3 Rollout 状态快照。Task V2+ 工程审计与设计建议 只保留为 historical context。

    1. 三个维度不要再混

    Concept回答的问题Example
    contacts.leadStatusAI/系统当前如何概括这个 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 注释列出：

    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）：

    Received → Outreach Attempted → Connected → Booked → Converted

Received / Attempted / Connected 也可以直接 → Converted
    Funnel stageEvidence ruleCaveat
    ReceivedEmail Lead intake / accepted Lead sourcesystem_observed 只证明 Lead 到达
    Outreach Attemptedqualifying outbound Task Activity不要求 Task close
    Connectedconnected Call 或 inbound reply与“拨出电话”分开
    Bookedcurrent valid completed-booking evidence；Target 为 businessProgress=intro_booked，legacy form fallback 标 form_asserted非终态；Task 保持 open；form fallback 不自动改变 displayType
    Convertedlead_conversion.resultCode=converted terminal Outcome可以不经过 Intro；当前不是 membership-system verified

    如果未来需要 Showed/Trialed：

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

    每个 projection row/aggregate 至少携带：

    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：

    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。

    示例：

    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 不得混用。