retaintive 文档中心¶
欢迎来到 retaintive 内部文档。本站涵盖健身房电话管理 SaaS 的行业知识、产品设计、系统架构和改进计划。
Last verified: 2026-04-26 (主 session grep verification) — Store-Level 隔离 4 phase 全部 ship;Pipeline 5 条全通;
site_id字段已 rename 为account_id(infra #642 / #647 / lead-tracking #88)。
行业知识¶
健身房电话类型的业务定义与优化策略。
| 文档 | 简介 |
|---|---|
| 健身房电话管理概述 | 营收公式 Revenue = New + Retained − Lost；定义六种电话类型（Lead、Service、Referral、Win-back、Reminder、Retention）及跟进机制 |
| Lead Call（潜在客户电话） | 对潜在客户的首次联系尝试，销售漏斗的第一入口；5 分钟响应机制、触达率、预约率等关键指标 |
| Service Call（售后服务电话） | 会员入会后的主动关怀电话，核心目标是提升 NPS 和续费率；含效果判断标准和常见失误 |
| Referral Call（转介绍电话） | 向满意会员请求推荐新客户的低成本获客渠道；含转介绍成功率指标和激励策略 |
| Win-back Call（召回电话） | 针对已过期会员的召回电话，使用限时优惠和情感连接，获客成本低于新客获取 |
| Appointment Reminder Call（预约提醒电话） | 预约前的提醒电话，目标降低 No-show 率、提升到店率；含最佳提醒时机和话术 |
| Retention Call（留存关怀电话） | 针对不活跃/低频到店会员的主动电话，了解流失原因并提供针对性解决方案 |
| 跟进机制（Follow-up） | 所有电话类型共用的通用跟进模式；6 种电话各自的跟进规则、节奏和管理指标 |
| CI 对话智能知识体系 | Conversation Intelligence 技术栈与分析框架；5 层分析维度（转录→理解→评估→洞察→行动）；CI 与 BI 协同关系；2025-2026 行业趋势 |
| BI 商业智能知识体系 | BI 核心架构（数据源→ETL→数据仓库→分析引擎→可视化→决策）；四层分析框架（描述→诊断→预测→规范）；以 Retaintive 为例的 Lead 全链路指标体系；2025-2026 行业趋势（AI+BI 融合、云原生、嵌入式 BI） |
产品设计¶
潜在客户追踪漏斗、客户分级、生命周期管理等产品层设计。
| 文档 | 简介 |
|---|---|
| 产品定位 | 一句话定位：垂直行业的智能销售运营平台；五大核心能力架构（CI 感知→BI 度量→AI 决策→Automation 执行→Coaching 赋能）；与传统 CI/CRM 的差异化定位 |
| 前端数据来源与指标计算 | 前端每个页面的数据来源表、SQL 逻辑、指标计算方式；Lead Funnel 三表计算（leads + contacts + timeline）、Tasks 指标 SQL、Revenue 归因、Contacts 指标 |
| 全流程数据分析框架 | 从 lead 获取到 call outcome 的完整数据流和分析模型（Draw.io 架构图） |
| Lead Outreach（潜在客户触达） | 首次触达的 7 阶段漏斗（获取→分配→拨打→接通→沟通→预约→到店）；定义有效率、放弃率、未触达率、触达率、预约率 5 个指标及计算公式 |
| Lead Follow-up（潜在客户跟进） | 试课后、犹豫期、爽约、续费四种场景的跟进节奏和重试规则；含管理指标和常见失误 |
| 用户生命周期管理 | 以手机号为主键的全生命周期（获取→触达→转化→活跃→预警→流失→回归）；用户画像四维度、意向信号链、客户温度评级（Hot/Warm/Cold） |
| 模块化服务策略 | 五层架构（核心基础→业务场景→AI 分析→培训赋能→增值服务）；"基础订阅 + 模块加购"定价，按健身房类型推荐套餐 |
| 角色化仪表盘设计 | 三种角色视角（Owner/Manager/Staff）的仪表盘设计；各角色核心指标、数据粒度、刷新频率；跨角色下钻关系 |
| 下钻分析设计 | 从汇总指标逐层拆解的下钻交互设计；可下钻指标、维度层级关系、智能提示；3 个典型排查场景 |
| Lead Funnel 与 Status 汇总 | 9 个状态定义 + 5 阶段漏斗映射 + Lifecycle State 分类；覆盖到已预约的链路；乘法漏斗效应 |
| Lead Temperature | V1 只实现降温 + Cold 后自动判定终态；Hot/Warm/Cold 时间窗口定义；三个终态（Unreachable / Lost Contact / Neglected）；升温机制推后 |
| Lead Contact Cadence | V1 只计算 SLA（首次响应时限）；Lead Contact Cadence 完整版的精简实现；复杂节奏机制推后 |
| Contacts 数据来源与字段设计 | Contacts（原 PhoneBook）V1 的 34 个字段定义；砍掉无数据源的预留字段（身份扩展、健身画像、消费决策、联系偏好），只保留有数据写入的字段 |
| Rules Feature Design | 店铺管理者自定义业务规则阈值：温度时间窗口、SLA 时限、任务截止时间、静默时间、MRR 假设值；按 Site 级别生效 |
| Coaching Highlights Specification | prescriptive spec：AI 对每通合格销售电话的 5 个 SA 维度（Booking Ask/Objection Handling/Retention/Rapport/Info Accuracy）逐通话 0–10 打分 + rationale；逐维度阈值推导 flag/highlight，flag rate 按通话去重；Coaching Highlights 全列表 + 类别/staff 筛选；Rules 可配 minCallDuration/rollingWindow/flag/highlight 阈值 |
| Prompt 改进 — 总览 | 通话分析 AI 4 个生产 prompt 的改进追踪入口；按 Pipeline 1（单通话 triage/classify/coaching）/ Pipeline 2（contacts 跨通话）分目录；关联两报错文档与 epic #891 |
| Pipeline 1 — Prompt 源码快照 | prompts.ts 全文逐字拷贝（TRIAGE/CLASSIFY/COACHING 3 个 system prompt）+ 出处块；callytics-infrastructure main@0d35d02 点时间快照，以 live 代码为准 |
| Pipeline 1 — Prompt 讲解（PM 审阅版） | 同事在 Lark 写给 PM 的 3 段 prompt 中英文讲解（Triage/Classify/Coaching）；从 docx 经 pandoc 转 md，逐字保留；出处含 Lark wiki 链接，原文为 SoT |
| Pipeline 1 — Prompt 中英对照 | prompts.ts 中 3 段 system prompt 的逐段中英对照（按 ═══ 分节）；英文逐字摘自源码（权威），中文翻译辅助阅读（非权威）；首批放 TRIAGE，CLASSIFY/COACHING 待格式确认 |
| Pipeline 2 — Prompt 源码快照 | prompt-builder.ts 全文逐字拷贝（SYSTEM_PROMPT ~660 行 + buildUserMessage）+ 出处块；source of truth 在 prompt-eval，快照非权威 |
| Pipeline 2 — Prompt 中英对照 | prompt-builder.ts 中 SYSTEM_PROMPT 模板的逐段中英对照（按 SECTION 与子标题分节）；英文逐字摘自源码（权威），中文翻译辅助阅读（非权威）；第一批：引言 + SECTION 1（角色与输出规范）+ SECTION 2（分类与枚举），其余待续 |
| Pipeline 2 — Oliver 改进方案 | Oliver 对 contacts-analyzer prompt-builder.ts 的全文标注+提议改动（独立 HTML 文档,自带样式）；薄 iframe shim 内嵌进 Material 站点框架；源 HTML 在同目录 Oliver改进方案.html |
| Tasks Overview | 员工每日工作台（Daily Action Queue）定位；执行驱动的任务列表——打开就知道先做哪个、怎么做、截止时间 |
| Tasks 字段设计 | Task 表字段结构定义；写入者说明；供开发者实现时参考；业务规则详见 Tasks Overview |
| Task 生成、更新与关闭机制 | Contact Analysis（Pipeline 2）按业务目标识别客户场景；Task 生成、更新（Adjust dueAt + 状态重算）与关闭机制 |
| 任务与营收归因 — V1 简化版 | Tasks 作为"员工行动"与"营收结果"的归因桥梁；6 个业务目标 → 营收类型映射；追踪任务全过程量化跟进对营收的贡献 |
| 学 Zenoti 怎么学 — Next Goal | Zenoti 8 个 AI Agent 4 象限评估（OS-native / DB 支持 / low-hanging fruit）+ UI 学习清单 + Customer-Specific Gold Standards 长期 roadmap；Codex adversarial review 修正版 |
| Zenoti + Keepme 资源 Inventory | Zenoti 与 Keepme 全部公开资源链接（Keepme 11 个 product video + Zenoti marketing/help docs + 第三方 listing + Dribbble/Behance/Mobbin + Vue/Figma 开源模板 + Wayback） |
| Zenoti + Keepme Feature 对比 + 抄什么 | 三方 feature 对比表（30+ capabilities）+ 抄什么清单（Z1-Z6 / K1-K6 / 开源模板 4 个）+ 15 项 ranked priority（立刻 / 1 月内 / 2-3 月内 / 后置 / 不做）+ schema 一段话总结 |
| Zenoti + Keepme 抄什么 — 详细版 | 16 个抄的项目展开版（Z1-Z6 / K1-K6 / OSS1-OSS4），每个 200-400 字描述：他们页面长什么样 + 我们抄过来该显示什么（含 ASCII mockup）+ 关键 UI 元素 + 字段映射到 schema + 不要踩的坑；附录 Zenoti 真技术栈解码（HyperConnect=Twilio softphone / Amazon Transcribe STT / Bedrock LLM） |
| 现有 Per-Call AI 字段分析 | call-analysis 表 44,151 条记录的 AI 输出字段梳理；为 Follow-up Task 生成逻辑（Cross-Call AI）提供数据基础 |
| Contacts 字段设计（完整版） | PhoneBook 表字段完整分析：逐字段对照 UI 设计和数据指标需求；字段放置原则——客户级聚合判定存 PhoneBook，原始数据查各来源表 |
| 任务与营收归因（完整版） | 完整版营收归因设计；6 个业务目标 → 营收类型映射；跟进全过程追踪与量化 |
| Lead Temperature（完整版） | 客户温度评级 Hot/Warm/Cold 完整设计；时间窗口自动衰减 + 事件驱动升温 + 重复提交升温规则 |
| Lead Contact Cadence（完整版） | 四层联系节奏体系：决策层（节奏）→ 基准层（SLA 计算）→ 调度层（提醒机制）→ 监控层（预警策略）；店铺可自定义参数 |
| Lead 归因设计 | 多员工跟进场景的绩效归因模型；Setter/Closer 两段分工（约访专员 vs 成交顾问）；提成触发点定义；行业现状（Mindbody/Zenoti 均为单人归因，多员工分成是行业空白） |
系统设计¶
后端管道、前端架构、数据库 schema 等技术实现。架构总览和跨 repo 数据流见下方两行。
| 文档 | 简介 |
|---|---|
| 系统架构总览 | 10 个 repo 的职责边界与协作关系；ASCII 架构图（RC → Lambda → DDB/Neon → Dashboard）；共享 SQS 队列和 DynamoDB 表的跨 repo 合约；三个部署环境（test/pre/prod）URL 对照 |
| 通话分析 Pipeline（跨 Repo） | RC Webhook → Deepgram 转录 → Kimi K2 AI 分析 → DDB/Neon 存储 → Dashboard 的完整 Mermaid 时序图；每步涉及的 Lambda、文件路径、输入输出格式；改动影响速查表（改什么 → 动哪个 repo → 风险） |
| 后端数据管道 | 四条并行管道（通话分析、修复管道、线索采集、SMS）；三个仓库（callytics、lead-tracking、studio-website）的职责分工；技术栈含 Lambda、DynamoDB、SQS、Deepgram、AWS Bedrock |
| 前端架构 | Vue 3 五层架构（入口→路由→组件→逻辑→API）；TanStack Query + Pinia 状态管理；Axios API 层含 Cognito 认证流程和缓存策略 |
| 功能地图 | 13 个核心页面（登录、仪表盘、门店活动、通话列表、消息中心、线索跟踪等）的前端组件 ↔ 后端 API ↔ 数据库表映射 |
| Lambda 写入矩阵 | 5 个 Lambda 对 Neon 4 张表的字段级写入职责（contacts/tasks/timeline）；P1 基础字段 vs P2 AI 字段所有权分离；AI Prompt 输入数据与输出 Schema；P2 触发源/冷却机制/SQS 消息设计；13 个已知代码隐患（含跨租户数据泄露 P0） |
| Identity 字段速查 | 8 identity 字段身份证（userId/storeid/accountid/franchiseid/clientid/connection_id/phone/extension）+ crosswalk 表 + 读写流程图 + 自检清单。新同事 onboarding 必读 |
| DynamoDB 表关系图 | 26 张 prod 表 + 19 张 test 表的状态审计（ACTIVE/LEGACY/DEAD）；实体关系图；GSI 详解；archive 候选清单；Deletion Protection 审计 |
| Store-Level 数据隔离 | store_id (UUID) 终态隔离设计；层级关系（Brand→Account→Store→Phone）；7 张 Neon 表终态 schema；Onboarding 流程；23 edge case 验证；P0/P1/P2 实施计划（#599 #610） |
| Contacts API Read Patterns | (新增 2026-04-26) /v2/contacts/profile（accountid 跨店共享）+ /v2/contacts/communications（storephone hybrid + 游标分页）+ ContactDetailSheet 共享组件；Tasks/未来 Contacts 页复用；Peter PR #254/#255/#256 |
| Phone Normalization Strategy | (新增 2026-04-30) 全系统 phone 写入/查询用 E.164 canonical；callytics-common/utils/phone.ts libphonenumber-js helper 取代 3 个 fragmented normalizer；7 phase dual-write+dual-read zero-downtime 迁移；Codex+Gemini cross-validate 完成；执行 plan 在 .claude/specs/ (#688) |
改进计划¶
V1 阶段（数据管道打通、AI 分析插入、Contacts 中心化、Task 系统、混合 DB 架构等）已合并并归档。后续改进规划散落在以下入口：
| 文档 | 简介 |
|---|---|
| 产品本质 / North Star | 这个系统在干什么 — 产品长期方向 + 9 类 AI 任务 + 全自动 pipeline 架构 |
| Campaign Engine — AI 对话式营销顾问 | AI Chat 对话式营销；老板自然语言描述活动 → AI 匹配 PhoneBook → 外部情报 → 生成 SMS → 人工审核 → 批量发送 |
| Task Staff Attribution | Staff Attribution 设计；calls.staffName AI 自动 + tasks.closedByStaffName 员工操作；轻量员工身份路线图 |
| 全链路 AI 赋能规划 | 行业知识 + AI 在客户全生命周期各环节的应用规划 |
AI Agent 设计¶
AI 工具体系与产品集成路线图：如何在 retaintive 产品中接入 AI 能力。
| 文档 | 简介 |
|---|---|
| AI 工具体系指南 | AI 编程助手（Claude Code/Cursor/Copilot）的六层扩展体系：配置层（CLAUDE.md）、指令层（Skills）、工具层（Built-in/MCP/CLI）、代理层（Custom Agents）、事件层（Hooks）、打包层（Plugins）；含 MCP 协议详解、进程级物理解释、实战场景分析和选择决策树 |
| AI 集成路线图 — MCP / Skills / Agents | MCP / Skills / Agents 融入产品的 ROI 排序路线图；Claude API tool-calling 架构（不需要 Bedrock Agents / Agent SDK / MCP）；TOP 10 集成机会详细 Workflow（AI 诊断对话、Dashboard 洞察、Campaign Engine、Staff Coaching、内部 Skills、Churn 预测）；5 级自动化金字塔（L1-L5）可行性评估；Phase 1→5 执行顺序 + 成本估算；竞品 AI 能力对标（Keepme / AmplifAI / Convin） |
Agentic Software Factory¶
如何用 AI agent 构建软件：整个 repository 的开发方法论，agent 执行任务的操作规范。
| 文档 | 简介 |
|---|---|
| 文档组织策略 — For Agents | 发布型 vs 上下文型文档的区别与判断标准；docs repo 战略层 + 代码 repo 战术层 + CLAUDE.md 指针层的三层分层方案；Meegle + MCP Orchestrator 未来集成路径 |
| Agentic Software Factory — 完整参考 | 17 个已知问题（成本/质量/安全/协调/可观测性）的行业案例和解法；Stripe Minions / StrongDM / Devin 真实案例对比；三层验证体系（Unit/Integration/Digital Twin）；优先行动清单 |
| Agentic Software Factory — 操作手册 | 2-step 操作手册：Step 1 设计（你 + AI 协作 30 分钟，产出 Task Spec）→ Step 2 执行（agent 自动实现+测试+开 PR）；Task Spec 完整模板；Park & Notify 机制；完整 Overnight 流程示例 |
| Diátaxis 文档框架 | 我们的文档信息架构标准；4 种类型（Tutorial / How-to / Reference / Explanation）定义、2×2 矩阵、与我们目录结构的完整映射；快速分类清单 |
| 外部工具生态 — 知识库 | Gas Town + Beads 深度解析：西部小镇角色体系（Mayor/Polecats/Rigs/Convoys 含「为什么这么叫」）+ 依赖栈类比（Dolt/Go/tmux 非技术解释）+ Mayor vs Meegle 适配问题（⚠️ 无原生集成，需写 bridge）+ Beads vs Meegle 层级区别（机器用 vs 人用）+ k8s 类比分析 + Gas Town 替换 vs 叠加分析 + 引入时机触发条件 + 「隔夜自动跑」前提条件 |
| Factory 演进路线图 | retaintive 三阶段演进：Phase 现在（Claude Code native，已有配置清单 + 当前瓶颈）→ Phase 中期（Beads 单独引入，触发条件 + 安装 + Meegle 分工）→ Phase 成熟期（Gas Town 全套，Mayor 自动调度 + Meegle→Beads bridge 设计草图 + 约束规则）；不演进也合理的判断框架 |