Retaintive

    近期后端能力产品化 Roadmap

    Historical roadmap / Non-normative（2026-07-15）：本文保留 2026-06/07 能力盘点，但 Task 对象、progress、closeResult、UI 与 AI 结论不得覆盖 Task System Design。实施前必须重新核查 live code。

    本文把 2026-06 下旬后端完成的一批能力，翻译成下一轮产品可以上的前端和后端改进。

    2026-07-01 更新：重新核查 studio-website-monorepo、callytics-common、callytics-infrastructure、lead-tracking 代码，并用 AWS / Neon 实测复核 multi-tenant 运行时后，发现不少能力已经做了或做了一半。本文已改成“现状矩阵 + 剩余 low hanging fruit”，并把本轮能直接补的小缺口补上（progress 接口和 6 种进度记录 UI 已在 studio#639/#641 merge；multi-tenant 实测结论回写进了 v1-gaps）。

    一句话结论：

    后端已经不只是“生成任务”，而是开始具备“解释为什么有任务、记录员工怎么跟进、追踪任务最后结果、把 Lead / Store / Dashboard 串起来”的能力。下一轮重点不是再堆复杂逻辑，而是把这些能力做成前端可用、业务看得懂的工作流。

    先说清楚：我们到底有没有 Neon DB？

    有。当前系统已经以 PostgreSQL / Neon 作为主要关系型数据层之一，@retaintive/common 里的 Drizzle schema 覆盖了 contacts、calls、leads、tasks、contact_timeline、task_suggestions、rc_store_phones 等核心表。

    但本文的结论基于三类证据：

    • @retaintive/common 的 schema 和 domain 代码
    • 近期 merged PR 的描述和代码改动
    • Studio API / Web 当前读写路径

    本文没有直接连接线上 Neon 实例逐列验证生产库状态。若要确认某个字段是否已经在生产环境实际可用，需要再看 migration deploy 状态和 Neon schema。这里说的“后端底座已具备”，指代码和迁移设计已经到位，具体发布环境以部署状态为准。

    已复核的代码和 schema

    这次复核重点看了和产品化最相关的代码路径，不是把每个 repo 的每个文件逐行审计了一遍。

    已确认的关键事实：

    领域已有后端事实对产品的意义
    Task 当前状态tasks 存 open / closed、任务类型、关闭结果、到期时间、任务原因、来源信息前端可以稳定展示“现在该做什么”和“最后结果是什么”
    Task 历史contact_timeline 存 task.progress_recorded 等历史事件前端可以展示员工跟进历史，而不是只显示一个静态任务
    Task 建议task_suggestions 存 AI / 人生成的建议，且是 append-only前端可以显示“建议怎么跟”，也可以以后做建议采纳率
    AI 判断审计ai_task_decision_assessments 存 AI 对每个 visible task / new objective 的判断可以做“AI 为什么这么判断”的解释面板
    Leadleads 已带 store_id，lead-tracking 已改成通过统一任务系统创建 lead follow-upLead Tracker 可以直接连接任务状态
    Contactcontacts 的主键已经是 (phone, store_id)同一个手机号在不同门店下可以是不同客户，不再混账
    Store/Phonerc_store_phones 有 source=user_manual/rc_sync 和 assigned_at用户手动归属电话号码后，系统应优先相信用户配置
    Callcalls 有 store_id、通话方向、结果、AI 分类和通话结论字段Dashboard / Lead / Task 可以继续从通话事实做聚合

    当前需要特别注意：旧文档 Tasks Schema 已落后于 final-state task schema。做 Task 相关设计时，应以 common live schema、近期 PR 和 Task Pipeline Deliverable 的方向为准。

    还需要注意 multi-tenant 边界：根据 why-tenant.md 和 v1-gaps.md，V1 tenant 现在是 identity / accounting 层，不是业务数据安全防线；业务读写隔离仍靠 store_id。因此本文所有前端/后端建议都不能把 tenant_id 当成已经可用的安全隔离键。

    代码核查后的现状矩阵

    产品能力代码现状还缺什么
    Task Detail 工作台已做大半。已有 Task list、detail panel、timeline、evidence sources、action summary、action plan、AI feedback、close（15 值 close result 分正/负/中性三组）、note、postpone。2026-07-01 本轮已补 POST /v3/tasks/progress 和前端 Record progress 6 种进度记录（studio#639/#641 已 merge；callback_requested / follow_up_scheduled 带 nextDueAt 和可选 note；domain 层 appendTaskProgress 已随 common 4.3.1 发布）。还缺从具体 call / message 直接挂证据、instant progress note、和更完整的 staff attribution。
    Task evidence / timeline已做。/v3/tasks/timeline 从 tasks + contact_timeline 组装 staff-facing story，并展示 evidence sources。继续补 evidence drill-down 到具体 call/message/lead 详情。
    Lead → Task 合流后端已接上，产品层半做。lead-tracking 已通过统一 task writer 创建 lead_outreach；Tasks 页面也有 lead workstream filter。Lead Tracker 还缺一个简单的 lead follow-up state，不应该让前端自己拼 leads + tasks + timeline。
    AI 判断解释后端底座已做，Studio 未产品化。ai_task_decision_assessments schema 已有，contacts-analyzer 已写 assessment audit。Studio API 缺解释接口；前端缺 internal / manager 面板。
    Setup / Phone 归属已做很多。已有 /v3/setup、manual store、assign/move/unlink phone、suggestions、unassigned phones UI；user_manual 优先。缺健康检查摘要：zero-call store、store without phone、orphan/unmapped/mapping drift、RingCentral suggestion 待处理状态。
    Dashboard / Task Trends已做一部分。已有 dashboard analytics、multi-store、task trends、comparison mode、任务 workstream/filter。缺一个稳定的结果型 Task Outcomes 聚合，统一按 workstream + close result + AI/human 口径返回。
    Attempted vs connected已做。/v3/leads/funnel 与 multi-store 已按 was_outreached（发起过外呼/短信）vs was_contacted（call_state = HUMAN_CONVERSATION 真接通）分层；前端 funnel 五阶段也把 Outreached 和 Contacted 分开，lead 状态分组文案是 “Tried, not reached” vs “Connected, not booked”。Tasks list 另有 attempt_count / first_attempted_at / first_connected_at。仅 legacy dashboard/lead-tracker 端点还把 outbound 当 contacted（旧页面已隐藏，随清理一起处理）；meaningful_conversation 第三层未建。
    Tenant / multi-tenantV1 identity-only 已有，但不能当防线。control plane、tenant mappings、tenant stamping 代码存在；studio-api 建店已自动写 mapping（#516，sync 和手动两条路径）。lead tenant_id 0% 的根因已定位：lead-tracking 部署积压 6 周（merge≠deploy），重跑 deploy workflow 即修；orphan mapping 和脏 tenant 已于 2026-07-01 清理。仍缺机制：NULL 率告警（可扩现成的 storeid-coverage-monitor）、sweeper 回填、mapping 对账 job、fallback 退役，见 v1-gaps。
    Shadow engine研发验证路径，不是客户功能。暂时只适合 internal diff viewer，不建议客户前端。

    本轮已做的 low hanging fruit

    1. Task progress 写接口

    已在 Studio API 增加：

    POST /v3/tasks/progress?taskId=...

    它做三件事：

    • 往 contact_timeline 写 task.progress_recorded
    • 根据 progress 类型更新下一次 due_at
    • 不改变 task 的 open / closed 状态

    安全和边界：

    • 仍用 store_id + store authorization 做实际访问控制
    • 新接口不沿用旧的 store_phone OR store_id 写入 fallback；任务写路径只接受目标 store_id
    • VIEWER 不能写
    • closed task 不能写 progress
    • DNC contact 不能写 contact progress
    • tenant_id 只从 task snapshot 带入 timeline 做记账，不作为安全判断

    2. Task Detail 最小前端入口

    已在 open task 的详情页加 Record progress 动作：

    动作写入 progress
    No answerno_answer
    Left voicemailleft_voicemail
    Text senttext_sent
    Still consideringcustomer_considering
    Schedule callbackcallback_requested
    Schedule follow-upfollow_up_scheduled

    前四个是 instant action,不要求员工选择时间。callback_requested / follow_up_scheduled 已补时间选择器,并可带可选 note。

    3. common 依赖声明收敛

    Studio root 已经用 @retaintive/common@^4.3.1，但 apps/api / apps/web 还写着 ^3.0.0。本轮已把两个 workspace package 的依赖声明同步到 ^4.3.1，避免干净安装或独立部署时拿到旧 common。

    后端这批能力的人话版

    1. 任务从“待办卡片”升级成“工作对象”

    以前任务更像一张待办卡：有一个标题、一个状态、一个结果。

    现在任务背后可以回答更多问题：

    • 为什么有这个任务？
    • 是哪个 Lead、电话、短信或 AI 分析触发的？
    • AI 建议员工怎么跟？
    • 员工后来有没有打电话、发短信、留言、约回访？
    • 最后是约成了、成交了、救回取消了，还是打不通？

    这意味着前端不应该只做任务列表，而应该把任务做成“员工工作的地方”。

    2. AI 的动作开始能解释

    AI 不只是输出“创建任务 / 关闭任务”。后端现在可以保存 AI 当时对每个任务的判断：

    • 这个任务为什么继续保持 open？
    • 这个任务为什么可以 close？
    • 为什么要创建一个新任务？
    • 为什么这次没有新任务？
    • 判断依据来自哪通电话、哪条短信、哪个 Lead？

    这对 manager、support、prompt QA 都很重要。它能把“AI 黑箱”变成“可查账”。

    3. Lead 和 Task 开始合流

    Lead 进入系统后，不应该只停留在 Lead Tracker 里。现在后端已经可以把 Lead 转成统一的 follow-up task。

    产品上应该形成一条线：

    Lead 进入 → 生成跟进任务 → 员工执行跟进 → 任务记录结果 → Lead Funnel 更新

    4. 门店电话归属变成用户可控

    以前 RingCentral 同步出来的结构更容易主导门店电话归属。现在方向变成：系统可以给建议，但用户手动配置优先。

    这件事非常关键，因为号码归属错了，后面的 Call、Lead、Task、Dashboard 都会错。

    5. Dashboard / Task / Lead 读路径更适合做 drill-down

    Studio API 已经对多个热点读接口做了聚合优化。前端可以更大胆地做筛选、下钻、趋势对比，而不必把所有页面都做成静态概览。

    剩余前端推荐改进

    P0：把 Task Detail 做成“跟进工作台”

    这是最值得先做的前端能力，也是本轮已经开始补的地方。

    员工点进一个任务后，不应该只看到“任务状态”。应该看到：

    • 为什么这个任务存在
    • AI 建议下一步怎么跟
    • 证据来自哪通电话 / 短信 / Lead
    • 已经跟进过几次
    • 每次跟进发生了什么
    • 下一次什么时候该跟
    • 最终结果是什么

    员工动作的状态：

    员工动作产品含义
    打不通已补最小入口
    留了 voicemail已补最小入口
    发了短信已补最小入口
    客户还在考虑已补最小入口
    客户要求回电已补时间选择器 + 可选 note
    已安排后续跟进已补时间选择器 + 可选 note
    关闭任务已有 close flow

    这件事很重要，因为没有它，任务页还是“看任务”。本轮补上的 6 种进度记录已经让任务页开始变成“员工真的在这里工作”的地方；下一步应该补 evidence drill-down、从具体 call / message 直接记录 progress、以及更完整的 staff attribution。

    P0：Lead Tracker 直接显示跟进状态

    Lead Tracker 不应该只回答“来了多少 Lead”。它应该能回答：

    • 哪些 Lead 还没跟？
    • 哪些已经打过但没接？
    • 哪些已经约成 intro？
    • 哪些明确没兴趣？
    • 哪些其实已经是 member？
    • 哪些超过 SLA 还没人处理？

    推荐在 Lead 列表和 Funnel drill-down 中展示关联任务状态。Lead Tracker 的每个关键数字都应该能点进去看到具体人和具体跟进情况。后端已经能从 Lead 创建任务，但还缺一个专门给 Lead Tracker 用的“这个 Lead 当前跟进到哪一步”的状态桥。

    文案上要注意：当前很多 “contacted” 更准确是“attempted outreach”，不一定是真人接通。前端应避免把“打过电话”说成“已经联系上”。

    P1：AI 判断解释面板

    先做 internal / manager 版本即可，不一定直接暴露给普通员工。

    它应该回答：

    • AI 为什么创建这个任务？
    • AI 为什么关闭这个任务？
    • AI 为什么保留这个任务？
    • AI 为什么没有创建新任务？
    • AI 参考了哪些证据？

    这个功能的价值不是炫 AI，而是建立信任和方便排错。当客户问“为什么系统这样判断”，support 不应该只能猜。

    P1：Setup 升级成“门店电话归属健康检查”

    Setup 页面不应该只是配置页。它应该主动告诉用户：

    • 哪些电话号码还没分配门店？
    • 哪些门店没有电话？
    • 某个号码现在属于哪家店？
    • 这个号码是否需要移动到另一家店？
    • 为什么这家店 dashboard 没有 calls / leads / tasks？

    这会直接减少“数据看起来不对”的问题。

    P1：Manager Dashboard 从任务数量升级到任务结果

    Manager 不只想看“开了多少任务”。更重要的是：

    • Lead follow-up 带来了多少 intro booking？
    • Cancellation risk 救回了多少？
    • Upgrade / win-back / referral 成功了多少？
    • 哪些门店打不通最多？
    • 哪些任务逾期最多？
    • 哪些任务是 AI 关闭，哪些是人工关闭？

    后端现在的 task 类型和 close result 已经更适合做这种结果型 dashboard。

    P2：Dashboard comparison 和趋势图继续深化

    既然 API 已经开始支持 period comparison，前端可以继续增强：

    • 本期 vs 上期
    • 本期 vs 去年同期
    • Store vs Store
    • Workstream vs Workstream
    • Task outcome trend

    但这类图表应该排在“任务工作台”和“Lead 到 Task 打通”之后。

    剩余后端推荐改进

    P0：继续完善“记录跟进”能力

    common 里已经有任务跟进历史模型，Studio API 本轮已补最小入口。现在剩余的是把它从快捷按钮扩展成完整跟进记录能力。

    已支持的快捷记录：

    • 打不通
    • 留 voicemail
    • 发短信
    • 客户还在考虑

    还需要支持：

    • 客户要求回电
    • 已安排后续跟进
    • 每次跟进的备注
    • 从具体 call / message 直接挂证据

    后端要负责：

    • 写入任务历史（已补）
    • 更新下一次跟进时间（已补固定规则，待补手选时间）
    • 做门店隔离校验
    • 避免重复写入
    • 不把“打不通几次”自动等同于“任务完成”

    最后一点很重要：尝试联系是过程，关闭任务是结果。两者不能混在一起。

    P0：补 Lead 到 Task 的状态桥

    前端需要一个简单结构来显示每个 Lead 当前卡在哪里。

    推荐后端直接给 Lead Tracker 返回类似业务状态：

    状态含义
    not_startedLead 进来了，但还没有有效跟进
    attempted已尝试联系，但未必接通
    connected真的联系上了
    booked已约 intro / appointment
    converted已成交
    not_interested明确没兴趣
    already_member其实已经是会员
    unable_to_reach多次尝试仍无法联系
    overdue应该跟但没有及时跟

    这比让前端自己拼 leads、tasks、contact_timeline、calls 更安全。

    动手前先做一个设计决策：contacts.lead_status 已经是 AI 维护的 12 值枚举（new / attempted / connected / booked / showed / trialed / converted / unreachable / lost_contact / neglected / bad_timing / not_interested），和上表的状态桥枚举高度重合，且 GET /v3/leads 已经在返回它。方案 A = 复用它 + 补 task 维度（overdue = 关联 open task 的 due_at 过期；already_member 从 customer_type 映射），只需要一个聚合端点；方案 B = 完全从 tasks 派生一套新状态。倾向方案 A（便宜、口径与 contacts 页一致），但要先确认 AI 写入 lead_status 的及时性够不够撑 funnel 口径。

    P1：补 AI 判断解释接口

    ai_task_decision_assessments 是后端新资产，但前端不应该直接消费原始表结构。

    后端应提供面向产品的解释接口，把底层记录翻译成：

    • AI 看到了什么
    • AI 判断了什么
    • AI 为什么这么判断
    • 最后哪些动作被系统接受
    • 哪些动作被系统拒绝，为什么

    这个接口可以先只给 internal / admin / manager 使用。

    P1：补 Store / Phone 数据健康检查接口

    后端应主动返回门店配置健康状态：

    • unassigned phone numbers
    • store without phone
    • phone moved recently
    • phone conflict resolved by user manual assignment
    • store has zero calls because no phone is assigned
    • RingCentral suggestions waiting for confirmation

    这样 Setup 页面才能从“让用户填表”变成“帮用户修数据”。

    P1：补结果型 Dashboard 聚合接口

    前端不应该自己在页面里定义业务归因规则。后端应该直接给 manager dashboard 返回结果聚合：

    • 按任务类型统计 open / closed / overdue
    • 按 close result 统计 booked / converted / cancel saved / upgraded / won back
    • 按门店统计任务完成率和逾期率
    • 按 AI vs human closed 统计结果
    • 按 Lead / Member Care / Revenue Growth 三类 workstream 汇总

    这会让前端展示稳定，也能保证所有页面口径一致。

    P2：把“尝试联系”和“真的联系上”分清楚 — 已基本做完

    2026-07-01 实测：/v3/leads/funnel 和 multi-store 已经按 was_outreached（发起过外呼/短信）vs was_contacted（HUMAN_CONVERSATION 真接通）分层，前端 funnel 和 lead 状态文案也分开了。三层里前两层已落地：

    层级人话含义状态
    attempted打过电话 / 发过短信已做（was_outreached）
    connected真的接通或收到回复已做（was_contacted，以 HUMAN_CONVERSATION 判定）
    meaningful conversation有实质沟通，能推进状态未建，需要时再加

    剩余收尾：legacy dashboard/lead-tracker 端点还把 outbound 当 contacted（服务已隐藏的旧页面），随旧页面清理一起处理。

    P2：做内部 AI 质量看板

    底座已部署（2026-07-01 实测）：shadow engine 在跑（EventBridge → engine-run Lambda → 只写 engine_shadow_runs 表，不碰 live 数据），contacts-analyzer 有 golden-eval 脚本，ai_task_decision_assessments 带 prompt/model provenance。缺的只是 read 端点和内部页面。可以做一个内部看板：

    • 最近 AI 判断覆盖率
    • 哪些场景最容易错
    • 哪些任务被错误关闭
    • 哪些 Lead 没有生成任务
    • 不同 prompt version 的表现变化
    • assessment 缺失或 coverage 失败的数量

    这不是客户第一优先级，但对持续提高 AI 质量很有价值。

    推荐执行顺序

    第一阶段：把任务变成工作台

    目标：员工可以在任务页完成真实工作。

    已完成：

    • 前端 Task Detail 工作台骨架
    • 后端记录跟进最小接口
    • 6 种 progress 记录(4 个 instant action + 2 个 scheduled action)
    • scheduled follow-up 时间选择器 + 可选 note
    • 任务 timeline 和 evidence 展示优化
    • 关闭任务时明确业务结果

    剩余：

    • instant progress note
    • 从 call / message 详情页直接记录 progress 并挂证据
    • staff name / staff id attribution 更完整

    第二阶段：把 Lead Tracker 接到任务执行

    目标：Lead 页面不只是报表，而是能看到每个 Lead 的处理状态。

    交付：

    • Lead 列表展示关联任务状态
    • Funnel drill-down 到具体 Lead / Task
    • Lead SLA / overdue 标识
    • 后端 Lead 到 Task 状态桥
    • lead tenant_id runtime gap 修复前，不要把 tenant 维度用于 Lead Tracker 隔离或计费口径（根因已定位：lead-tracking 部署积压，重跑 deploy 即修，见 v1-gaps 缺口 3）

    第三阶段：把 AI 判断变透明

    目标：manager / support 能解释系统为什么这么做。

    交付：

    • AI 判断解释接口
    • Internal / manager 解释面板
    • 每个任务展示“为什么有这个任务”
    • 支持按 task / contact / run 查判断历史

    第四阶段：把 Setup 变成数据健康中心

    目标：减少门店电话归属错误导致的数据问题。

    交付：

    • unassigned phone list
    • move / unlink / confirm 流程优化
    • zero-data diagnostic
    • RingCentral suggestion review
    • tenant mapping reconciliation 只作为健康提示/内部诊断，不作为 V1 业务数据安全边界

    第五阶段：做结果型 Manager Dashboard

    目标：从“任务量”走向“业务结果”。

    交付：

    • Task outcome dashboard
    • Store-level outcome comparison
    • Lead / Member Care / Revenue Growth workstream view
    • AI vs human outcome breakdown

    暂时不建议上客户前端的东西

    Shadow engine

    Shadow engine 更适合先做内部 diff viewer，用来比较新旧 AI 决策差异。暂时不建议直接做客户可见前端。

    原因很简单：它现在更像研发验证工具，不是客户要日常使用的运营功能。

    过早做全自动 AI outreach

    当前更稳的路线是“AI 赋能人工”，不是马上让 AI 直接替代员工对外沟通。

    原因：

    • 电话 / SMS 触达涉及合规和品牌风险
    • 健身行业的成交和挽留仍然很依赖人
    • 现在最缺的是把员工跟进过程记录清楚，而不是让 AI 自动接管所有动作

    最重要的产品主线

    下一轮所有改进都应该围绕这条线：

    Lead 进来
  → 系统判断该不该跟
  → 创建任务
  → 员工在任务页执行跟进
  → 系统记录每次尝试和证据
  → 任务关闭并写入业务结果
  → Manager 在 Dashboard 看结果

    如果一个功能不能增强这条线，就不应该排在前面。

    相关文档