> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt. # 8. Contacts Contacts 是门店的客户总账：每个电话在本店一条记录，AI 每天把通话、短信、线索里的信息整理成生命周期、线索阶段、购买意愿、顾虑标签和一段客户简报。代码注释明说这是"查资料的参考页"，不是干活的队列。 ## 1 Contacts 工作台 ### 1.1 顶部工具栏：重置、搜索、排序与分页 Contacts 查看当前门店的客户记录，没有 Leads 的 Received 日期筛选。 | 元素 | 含义与操作 | | --------------------- | ----------------------------------------------- | | Reset | 清除搜索及筛选，恢复 Last Activity 从新到旧排序、每页 100 条，并返回第一页 | | 搜索框 | 按电话、客户名或姓查找 | | Sort: Last Activity | 按最近活动时间排序，默认最新在前 | | Sort: Acquired / Name | 改为按客户记录创建时间或姓名排序 | | 上下箭头 | 切换升序或降序 | | `1–100 of 5697` | 当前页显示范围及符合条件的客户总数，截图数字仅为示例；每页 100 条，用左右箭头翻页 | ### 1.2 表头筛选 筛选入口位于带下拉箭头的列名处，可以组合使用；选项旁的数量表示当前其他条件下该项的人数。 | 列头 | 筛选内容 | | --------------- | ----------------------------------------------------------------------------------------------------------- | | Lifecycle | Lead / Member / Churned / Unknown | | Lead Source | Email lead / Call/SMS lead / Unknown / `—` | | Lead Status | New / Attempted / Connected / Booked / Converted / Bad Timing / Lost Contact / Not Interested / Unreachable | | Purchase Intent | High / Medium / Low / Unknown / `—` | | DNC | Yes / No | | Open Task | Yes / No | Lead Status 旁的信息图标用于解释状态口径。Contact、Phone、Acquired 和 Last Activity 列仅展示数据，没有列头筛选入口。 ### 1.3 联系人列表：一行代表谁 **一条 contact = 一个电话号码在一家门店下的记录。** 同一个号码在不同门店是独立记录；同一客户多次沟通或提交表单，不因此拆成多行。 | 列 | 含义 | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Contact | 头像首字母 + 姓名（超过 40 字或像 "not provided / unknown caller" 这类垃圾值时改显示电话）。点击打开右侧详情 | | Phone | 电话 | | Lifecycle | Lead（潜在客户）/ Member（现会员）/ Churned（流失会员）/ Unknown。由 AI 分析加规则共同写入：会员取消 → Churned；前会员问复会 → Churned 重新活跃；完成复会 → Member。供应商、错号、找经理等不属于健身客户流程的人不硬塞进这三类 | | Lead Source | 常见显示 Email lead / Call/SMS lead，也可能保留 Online Intro 等来源名称。Lead 缺少来源时显示 Unknown；Member / Churned 显示 `—`。Email lead 旁的 ×N 表示重复表单提交次数 | | Lead Status | 线索当前走到哪一步，只有 Lifecycle 为 Lead 的客户才显示，取值与 Leads 篇基本相同（本页筛选项含 Converted、不含 Neglected）。表头旁有 Help：**"New、Attempted、Connected、Booked 是系统记录的；其他状态是从通话对话推断的，可能和 CRM 或线下实际不符"**。代码核查：实际只有新邮件线索首次入库时把状态直接写成 New，Attempted / Connected / Booked 和其余状态一样由 AI 根据通话、短信证据推断写入，同样可能与 CRM 或线下不一致 | | Purchase Intent | High / Medium / Low；是 Lead 但 AI 没给出时显示 Unknown；非 Lead 显示 — | | DNC | Do Not Contact，禁止联系；为真显示红色 DNC 徽章 | | Open Task | 当前门店是否有该客户的未关闭任务；有具体任务链接时 Yes 可点击进入 Tasks，没有任务时显示 No，未确定时显示 Unknown | | Acquired | 客户记录在本店首次创建的时间 | | Last Activity | 最后一次任何互动的时间（按事件发生时间） | ### 1.4 查看客户与进入任务 点击联系人行打开详情；点击 Open Task 的 Yes 则进入 [Tasks](/funding-strategy/02-产品说明书/03-tasks.md) 处理对应任务。 - **Lifecycle** 是客户当前阶段，**Lead Status** 是线索跟进阶段，不是同一个字段。 - Lead 的来源或意向缺失时用 **Unknown**；不适用的字段显示 **`—`**。Lead Status 未提供时也显示 `—`。 - **Acquired** 是客户记录创建时间，**Last Activity** 是最近活动时间，两者可能相隔很久。 - 筛选 Lead + High + Open Task = No，可以找出高意向但当前没有未关闭任务的客户，供进一步核查；这不直接证明员工从未跟进。 Contacts 是跨时间的客户资料，Leads 是指定进线窗口的收件箱，两边总人数不应直接比较。 ## 2 联系人详情 ### 2.1 页签与顶部操作 默认通过 **Overview / History** 切换资料和沟通记录。展开详情后，两部分并排展示，方便边看资料边核对历史。 | 操作 | 作用 | | ------------------ | ------------------------------ | | Open task | 有对应未关闭任务时显示，点击进入 Tasks | | See in RingCentral | 打开 RingCentral 短信窗口；DNC 客户不可使用 | | 展开 / 还原图标 | 展开查看 Overview 与 History，再次点击恢复 | | 关闭图标 | 收起详情，不删除客户记录 | ### 2.2 Overview：客户资料 | 区块 | 内容 | | ------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Name | 点铅笔可分别改 First name / Last name。**员工改的名字信任度最高，之后任何系统来源（表单、电话系统、AI 转录）都不会覆盖**。只要能访问这家门店就能改 | | Phone / Lifecycle / Lead status / Purchase Intent | 同列表 | | Rejection Signals / Purchase Barriers | AI 提取的顾虑标签。Purchase Barriers = 还可能通过解释、优惠或时机克服的顾虑（价格、日程）；Rejection Signals = 很难改变的硬性原因（太远、搬家、已加入竞品） | | DNC | Yes / No；"从未评估过"就等于 No | | Customer Summary | AI 写的 3–5 句客户简报：这人是谁、当前阶段、关键互动结果、主要顾虑或风险、当前最重要的机会 | | Acquisition & Activity | 见下表 | | See in RingCentral | 新开 RingCentral 网页版并预填该电话的短信窗口；**Retaintive 自己不发短信**。DNC 为真时按钮置灰 | | Open task | 跳到 Tasks 打开该客户的未关闭任务 | | Acquisition & Activity | 含义 | | ------------------------ | ------------------------------------------------------------------------------------------------------ | | Acquired | 客户记录创建日期 | | First connected | 本店与该客户第一次真正通上话的时间，显示为 "Observed by \<日期> · partial history"（至少那时已经通上，历史不完整）；没有证据时显示 Not fully measured | | Store-scoped calls | 能百分百证明属于本店本客户的通话条数，显示为 "At least N"（下限，不是全部历史） | | Store-scoped SMS | 短信目前没有"发生当时就绑定到客户"的可靠证据，固定显示 Not fully measured | | Last Activity | 最后活动日期 | | Recorded Task activities | 任务里正式记录的联系动作数。Contacts 页固定显示 —（接口明确返回"未知"而不是 0）；在 Tasks 详情的 Contact Profile & History 页签里才是该任务的真实次数 | **"Not fully measured" 的统一含义：系统不能证明这个数字，宁可说"没量全"也不显示 0。** ### 2.3 History：沟通记录 这个客户在本店的全部通话、短信/MMS、语音留言，按时间排。口径（2026-07-20 决定）：显示所有能安全归到本店 + 本客户的互动（一方是客户电话、另一方是本店电话），这与用于指标和 AI 证据的严格口径是两套刻意分开的规则。 | 元素 | 含义 | | ------------------ | ---------------------------------------------------------------------------------------------------------- | | 头部 N calls · M SMS | 可归属到该客户的通话数和短信数；没加载完显示 Partial history | | 方向 | 外呼靠右、来电靠左、方向不明居中标 Direction unknown——方向是三态，不明时绝不猜 | | 通话条目 | 结果（Connected / No answer / Voicemail / Busy / Missed）、时长、AI 摘要；点播放药丸取录音；View details 用可拖动浮窗看该通电话的分析、录音和逐字稿 | | 语音留言 | 一条留言在系统里是两条记录，页面把 10 分钟内配对的合并成一条并附转录 | | Lead arrived | 标在客户记录创建时刻，一眼看出哪些沟通发生在线索到达前后 | | 默认 5 条 | 打开停在最新消息，往上滚展开并加载更早的 | ## 3 DNC 规则 | 规则 | 说明 | | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 二元 | 只有明确的 true 才阻止联系；未设置视为可联系。新邮件线索入库时 DNC 写为 false（他们主动要求被联系）；重复提交表单永远不改已有客户的 DNC | | 谁能设为真 | 客户回复精确的 STOP 短信时，由服务端唯一的合规写入者持久化，并级联关闭该客户的老式未关闭任务，**永不回滚**。**AI 明确被禁止改 DNC**：发现 STOP / unsubscribe / remove me 之类信号只能提交"待员工复核"的请求，不得改字段、不得写进 Customer Summary | | 效力 | Contacts 和 Tasks 里的 See in RingCentral 置灰；Tasks 的 Call / Text 快捷按钮禁用；Lead Line 自动外呼直接拒绝；线索接入不给 DNC 客户建任务。以 do\_not\_contact 关闭任务要求客户本来就已是 DNC——关闭任务本身不会把客户设成 DNC | ## 4 AI 画像怎么更新 由 Contacts Analyzer 维护：每天 06:00 UTC 全量跑一次，另外在通话分析、任务关闭等事件后按需触发；每次只看最近 30 天、最多 10 通电话 / 10 条消息 / 20 条线索。所以 Customer Summary、Lead status、意向有滞后，久远的互动不进入判断。 ## 5 当前限制 - Complaint 和 Cancellation Risk 两个筛选在接口里存在，页面表头没有对应控件。 - 数据库有客户备注字段，但 Contacts 页和资料卡都没有显示或编辑备注的地方；Tasks 里的 Notes 是任务级备注。 - **没有找到任何界面让员工手动把客户设为 DNC 或取消 DNC**；只能说"客户回复 STOP 由系统写入；AI 发现疑似信号转员工复核"，复核界面的位置未核实。 - Overview 里的 Acquired / Last Activity / First connected 用浏览器本地时区显示，而列表列和 History 用门店时区；异地看的店长可能看到相差一天。 - History 里外呼消息的头像固定写死为 "OTF"，面向其他品牌需注明。 - Lead status 数据里有 12 个值，页面筛选只列 9 个；showed / trialed / neglected 的客户会显示徽章但无法单独筛出。 - 接口还返回有无卡在档、有无未处理投诉、建议动作等字段，页面不显示。 ## 6 实现依据 本篇按本地代码核查，页面实际启用情况以部署版本为准。 [客户列表页](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/web/src/pages/contacts-v3/index.vue) · [列表接口与筛选](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/api/src/routes/v3/contacts.ts) · [资料卡](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/web/src/components/contact-detail/ContactProfilePanel.vue) · [沟通记录](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/web/src/components/contact-detail/CommunicationLog.vue) · [沟通记录口径](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/api/src/utils/contact-communication-log.ts) · [客户表与 DNC 规则](https://github.com/retaintive/callytics-infrastructure/blob/main/packages/common/src/db/schema/contacts.ts) · [AI 画像策略](https://github.com/retaintive/callytics-infrastructure/blob/main/lambda/contacts-analyzer/src/core/prompts/contact/profile-policy.ts) · ["已证明的下限"计数](https://github.com/retaintive/callytics-infrastructure/blob/main/packages/common/src/metrics/contact-interaction-history.ts)