> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # 近期后端能力产品化 Roadmap > **Historical roadmap / Non-normative（2026-07-15）**：本文保留 2026-06/07 能力盘点，但 Task 对象、progress、closeResult、UI 与 AI 结论不得覆盖 [Task System Design](/product-design/v3/tasks-feature/task-domain-lifecycle.md)。实施前必须重新核查 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](/system-design/multi-tenant/v1-gaps.md)）。 一句话结论： > 后端已经不只是“生成任务”，而是开始具备“解释为什么有任务、记录员工怎么跟进、追踪任务最后结果、把 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 为什么这么判断”的解释面板 | | Lead | `leads` 已带 `store_id`，lead-tracking 已改成通过统一任务系统创建 lead follow-up | Lead Tracker 可以直接连接任务状态 | | Contact | `contacts` 的主键已经是 `(phone, store_id)` | 同一个手机号在不同门店下可以是不同客户，不再混账 | | Store/Phone | `rc_store_phones` 有 `source=user_manual/rc_sync` 和 `assigned_at` | 用户手动归属电话号码后，系统应优先相信用户配置 | | Call | `calls` 有 `store_id`、通话方向、结果、AI 分类和通话结论字段 | Dashboard / Lead / Task 可以继续从通话事实做聚合 | 当前需要特别注意：旧文档 [Tasks Schema](../../v2/tasks-feature/tasks-schema.md) 已落后于 final-state task schema。做 Task 相关设计时，应以 common live schema、近期 PR 和 [Task Pipeline Deliverable](../../v2/tasks-feature/design/task-pipeline-deliverable-codex.md) 的方向为准。 还需要注意 multi-tenant 边界：根据 [why-tenant.md](/system-design/multi-tenant/why-tenant.md) 和 [v1-gaps.md](/system-design/multi-tenant/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-tenant | **V1 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](/system-design/multi-tenant/v1-gaps.md)。 | | Shadow engine | **研发验证路径，不是客户功能**。 | 暂时只适合 internal diff viewer，不建议客户前端。 | ## 本轮已做的 low hanging fruit ### 1. Task progress 写接口 已在 Studio API 增加： ```text 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 answer | `no_answer` | | Left voicemail | `left_voicemail` | | Text sent | `text_sent` | | Still considering | `customer_considering` | | Schedule callback | `callback_requested` | | Schedule follow-up | `follow_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。 产品上应该形成一条线： ```text 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\_started | Lead 进来了，但还没有有效跟进 | | 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](/system-design/multi-tenant/v1-gaps.md) 缺口 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 自动接管所有动作 ## 最重要的产品主线 下一轮所有改进都应该围绕这条线： ```text Lead 进来 → 系统判断该不该跟 → 创建任务 → 员工在任务页执行跟进 → 系统记录每次尝试和证据 → 任务关闭并写入业务结果 → Manager 在 Dashboard 看结果 ``` 如果一个功能不能增强这条线，就不应该排在前面。 ## 相关文档 - [下一轮产品迭代执行逻辑](/product-design/future-plans/next-iteration-execution-logic.md) — 本文「剩下要做的」5 件事的执行层(怎么做/什么顺序/验收) - [系统世界观](/product-design/system-worldview.md) - [Multi-Tenant V1 缺口清单](/system-design/multi-tenant/v1-gaps.md) - [Multi-Tenant 上 Prod Checklist](/system-design/multi-tenant/prod-rollout-checklist.md) - [Store-Level 数据隔离](/system-design/store-level-isolation.md) - [Lead Tracker — 计算配置](../../v2/lead-tracker-feature/lead-tracker-calculations.md) - [Task Pipeline Deliverable](../../v2/tasks-feature/design/task-pipeline-deliverable-codex.md) - [任务与营收归因](/product-design/future-plans/revenue-attribution.md) - [Task 改进建议](/product-design/future-plans/task-improvement-proposals.md)