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

# 产品北极星

> **这是 retaintive 的产品本质 / 长期方向定义**。所有 repo / 设计 doc / phase 计划都围绕这一段展开。
>
> **如果你只读 1 份 doc,读这份。** 其他 system-design doc 是这一份的展开。
>
> Updated: 2026-07-16（Lead 统一为 stable `lead_conversion` Task + current `displayType`）

***

## 一句话

retaintive 是给**所有用电话 + 短信做客户运营的连锁服务业**(健身房、连锁按摩店、连锁警务、任何依赖语音通话+短信跟客户打交道的连锁机构)的 **AI 客户运营系统**。

把当前真实可获得的电话、短信、Email Lead 和员工线下 context 汇到同一个 store-scoped Contact 上。AI 发现机会、建立或建议 Task、给出下一步并跟踪 Outcome；代码负责权限和一致性；员工始终能补充系统看不到的信息并纠正结果。

目标不是取消员工判断，而是让员工**少挖数据、少漏机会、把时间用在客户沟通和关键确认上**。

***

## 这套系统存在的目的 — 两件事,一体两面

### 1. 抓住客户身上每一个赚钱机会

每个进系统的客户身上,都有可能转钱的点。靠人工记忆 / 翻通话记录 / 翻短信 拼出来这些点 = 大量漏掉。

AI 替老板替员工把这些点全部抓住,不漏:

- 该跟进的 hot lead(刚问完价格还没决定)
- 该接住的预约转化(订了试课但没到的)
- 该提醒的续费(合约快到期的)
- 该挽留的流失风险(投诉过 / 不来上课 / 提取消的)
- 该接住的转介绍机会(满意会员说朋友也想来)
- 该召回的流失会员(之前停了想回来的)
- 该升级的现有会员(在问更高级套餐的)

### 2. 把员工的时间、精力、老板的钱用在该用的地方

员工 1 小时是有成本的。让员工花时间挖数据、翻记录、判断"这个客户该做啥" = **浪费**。这些事 AI 能做。

让员工花时间在**只有人能做的事**上:打那个电话、聊那次试课、维系那段关系、解决那个投诉。

老板的钱用在 "客户 conversion + retention" 上,不用在养"专门做数据整理判断的人"上。

***

## 怎么做到的 — AI 辅助的闭环

RingCentral Call/SMS 和 Email Lead 尽量自动进入；员工用最少操作补充线下 Activity、Next Action 与 Outcome。AI 在 meaningful event 到来时运行受控分析，不永远后台运行：

```
客户打电话 ─────► 录音存 S3 ────► AI 转录(Deepgram)─────┐
客户发短信 ─────► RC webhook ────────────────────────────┤
客户填 lead 表 ──► Email ingestion ────────────────────────┤
                                                          ▼
                                              ┌─────────────────────┐
                                              │   AI 分析层(多个    │
                                              │   analyzer 围着客户 │
                                              │   转)              │
                                              ├─────────────────────┤
                                              │ • 单通电话分析       │
                                              │   (33 个 AI 字段)   │
                                              │ • 客户级综合分析     │
                                              │   (store-scoped      │
                                              │    compact context) │
                                              │ • Task / Next Action│
                                              │   / Outcome proposal│
                                              │   + evidence        │
                                              └──────────┬──────────┘
                                                         │
                                                         ▼
                                            ┌──────────────────────┐
                                            │ Task + Next Action   │
                                            │ + Activity + Outcome │
                                            │  → 员工高效处理       │
                                            └──────────────────────┘
```

**核心引擎是多个 AI analyzer**,不是单一 Lambda。围着每个客户转:

| Analyzer                | 职责                                                               |
| ----------------------- | ---------------------------------------------------------------- |
| `transcribe-processor`  | 录音 → 文字                                                          |
| `ai-analysis-processor` | 单通电话 → 33 个 AI 字段(分类 / 情绪 / 意图 / 跟进类型...)                        |
| `contacts-analyzer`     | 一个客户的 store-scoped compact context → typed Task proposal；代码校验后执行 |
| `message-processor`     | 短信进来 → 关联到客户 + 触发分析                                              |
| `lead-tracking` poller  | lead 邮件 → 解析 → 关联客户 + 触发分析                                       |

AI 负责理解 transcript、短信和模糊意图；代码负责 store isolation、DNC、state transition、idempotency、evidence requirement 和 transaction。它不是纯规则引擎，也不是让模型直接控制 world state。

***

## Task 怎么把机会落地

Task 表示一件需要解决到底的客户机会或问题；Next Action 是当前已经采用的下一步，Activity 是实际发生的处理，Outcome 是最后结果与证据。

| Managed Task kind      | 完整目标                               | 典型 Next Action（不是固定流程）            |
| ---------------------- | ---------------------------------- | --------------------------------- |
| `lead_conversion`      | 推进 Lead 到明确销售结果；Intro 是可选路径，不是强制目标 | 首次联系；答疑；预约 Intro；或直接讨论 Membership |
| `cancellation_request` | 处理取消请求并争取 retention                | 经理今天回电                            |
| `payment_recovery`     | 恢复中断付款                             | 联系客户安排安全更新                        |
| `renewal`              | 完成本轮续费                             | 确认续约决定和处理路径                       |
| `upgrade`              | 完成方案升级                             | 回应需求并确认 option                    |
| `referral`             | 获得可执行的有效推荐                         | 确认 consent 和 referral details     |
| `win_back`             | 让流失客户重新回来                          | 联系客户确认 return goal                |

当前代码仍使用 9 个 legacy `typeCategory`。Target 把 `lead_outreach / lead_follow_up / booked_not_converted` 合并成同一个 stable `taskKind=lead_conversion`，同时保留为三个用户可见、可筛选的 current `displayType`。`intro_booked / intro_attended` 是非终态 business progress：它们更新 `displayType` 与 Funnel，但不关闭 Task；明确 `converted / not_converted / outcome_unknown / not_applicable` 才是 terminal Outcome。Current `booked_not_converted` 的文字定义实际偏向 attended/completed Intro，正说明 migration 必须通过 evidence 做 split/merge，不能按名字直接 rename；`retention` 同样混合多个完整事项。

一个 Contact/store 可以同时有多个独立 Task，例如 Upgrade 与 Referral；同一通电话 Activity 可以为两个 Tasks 提供 evidence，但 interaction 和 staff credit 只记录一次。完整定义见 [Task System Design](/product-design/v3/tasks-feature/task-domain-lifecycle.md)。

***

## 当前落地

**当前主要业务场景**：OrangeTheory 等依赖电话、短信和 Lead 的连锁门店客户运营。

**架构是通用的** — 系统 schema / Lambda / API 不绑定健身房。换成连锁按摩店 / 连锁警务,只要客户运营靠"电话+短信+lead 邮件",同一套系统能复用。当前产品的术语(member / class / franchise)是按 OrangeTheory 业务习惯填的,不是架构限制。

***

## 未来扩展(笼统提一下,具体方向后续填)

**还会引入更多 AI 方式深化"抓机会 + 省力气"这两件事**。可能的方向:

- 更精准的 lead scoring(每个 lead 的"赚钱可能性"打分,不只是规则)
- 更主动的 outbound 建议(AI 写出该说什么,不只是"该打谁")
- 跨客户群体分析(哪些 cohort 流失风险高 / 哪些行为预示流失)
- 更多通道接入(WhatsApp / 微信 / web chat / 视频通话 / 上门数据)
- 客户行为预测(转化概率 / 流失时间窗 / LTV 预测)

具体哪些做、按啥顺序做、为啥做 — 以后填这一段。

***

## 相关 doc(从顶到底)

- 这份 — **产品本质 / 北极星**(为啥做)
- [`architecture/2-backend.md`](/architecture/2-backend.md) — **5 条数据线路怎么流**(技术怎么做到)
- [`identity-fields.md`](/system-design/identity-fields.md) — **identity 字段速查 + crosswalk**(userId / store\_id / account\_id / franchise\_id / ...)
- [`store-level-isolation.md`](/system-design/store-level-isolation.md) — **店级数据隔离设计**
- ~~`store-id-migration-rollout.md`~~ — **隔离改造 4 步走** 已 archive(2026-04-26 phase 全 ship 完),如需追溯看 `docs/archive/store-id-migration-rollout.md`
- [`write-matrix/index.md`](/system-design/write-matrix/index.md) — **谁写哪张表哪个字段**(实现契约)
- [`feature-map.md`](feature-map.md) — **前端用户能看到什么**(交付的功能)
- 测试设计文已搬到 callytics-infrastructure repo(测试跟代码同 repo)

***

## Updates — append-only

(后续产品本质 / AI 实现方式 / 落地客户 有变化时加新段)