# 云客数据镜像 · 数据分析与增值功能全景方案

- **日期**：2026-08-24（v1.1 修订：2026-08-25）
- **状态**：方案存档（讨论稿，未实施；每批落地前另出独立 spec + plan）
- **依据**：基于 2026-08-24 对生产 MySQL（`yunke` 库）的实测数据审计，所有数据能力论断均有查询背书（见附录 A）。价值论证基准只有一个：**我们自己的数据能否支撑 × 三受众需要 ÷ 实现成本**，与任何外部系统无关。
- **受众**：老板/销售管理者、销售员工、合规/存档。

**修订记录**：
- v1.1（2026-08-25）：评审修订——新增 §1 价值图谱、§4 横切设计约束（权限模型/性能承载）；新增 E0 数据健康（提首批第一项）、B5 RFM 分层；修复 10 处口径/设计漏洞（A1 新增客户口径、A3 流失三分法、E1 迟到数据回写、B2 尾部判定、C1 误报处置、C2 导出内存、A2/A4 一人多号聚合、图表库选型等，详见各节 **[v1.1]** 标记）；A6 渠道对比降级为筛选维度。

---

## 1. 分析能力与价值图谱——这份数据到底能帮我们什么

### 1.1 八大分析能力域

| # | 能力域 | 能算什么 | 数据支撑 | 回答什么问题 | 帮我们什么 |
|---|---|---|---|---|---|
| ① | 沟通行为 | 消息收发量、首响时长、回复率、跟进客户数、时段热力图 | 方向+精确时间戳 ~100% | 谁在干活、干得多快、什么时间干 | 绩效从印象变事实；发现响应瓶颈；负载/排班有依据 |
| ② | 客户健康度 | 活跃/沉默/沉睡分层、沟通频度衰减、该回未回清单 | last_chat_time（4h 刷新）+ 对话尾部 | 谁正在流失、谁的最后一条没人回 | **流失前干预（最直接业绩保护）**；销售每天有行动清单 |
| ③ | 客户结构 | 跨渠道客户全景、撞单检测、RFM 分层、地区分布 | customer.phone 96% 可归一 | 客户资产长什么样、谁该优先跟 | 消解撞单内耗；销售精力按价值排序 |
| ④ | 群运营 | 群活跃排行、沉默群、群消息趋势、活跃成员 TOP | 948 有消息群 + 12,866 成员 | 群是资产还是僵尸 | 死群清理决策；从活跃成员挖线索 |
| ⑤ | 话务 | 接通率、通话时长、呼入呼出比、时段分布 | 3,042 通话（响铃/接通/方向） | 电话打得值不值 | 话术效果间接判断；拨打时段优化 |
| ⑥ | 内容 | 关键词全文检索、敏感词扫描、话题分布（+LLM 后摘要/打标） | 65.5 万文本 + ngram 毫秒级 | 沟通里到底说了什么 | 风控证据链；话术库/培训素材挖掘 |
| ⑦ | 趋势 | 任意指标日/周/月趋势、环比、渠道对比 | 10 个月完整时序 | 业务在涨还是跌、为什么 | 管理决策从感觉到数据；异常当天可见 |
| ⑧ | 存档取证 | 任意员工/客户/时间窗全量调取、录音图片本地播放、HTML 导出 | 2.5GB 媒体字节在手 | 任何一笔沟通发生过什么 | 纠纷取证、离职交接、数据资产保全 |

### 1.2 综合价值三层

| 层 | 从 → 到 | 具体价值 |
|---|---|---|
| 看得懂 | 记录堆积 → 规律呈现 | 73.9 万条消息变成每天 5 分钟能看完的数字和清单 |
| 管得住 | 事后追责 → 事前预警 | 流失预警/该回未回/敏感词在**变成损失之前**推到面前 |
| 说得清 | 主观评价 → 数据事实 | 考核、复盘、纠纷、交接全部有可回溯证据链 |

**一句话**：这份数据是公司客户沟通的完整黑匣子，本方案把黑匣子变成**仪表盘 + 预警器 + 取证库**。

### 1.3 价值边界（诚实前提）

只覆盖沟通面，无业绩/订单数据——能回答"跟得勤不勤、聊得好不好"，回答不了"最后成没成单"。若未来接入业绩数据源，①③⑦ 的价值翻倍。

---

## 2. 数据资产审计（实测，2026-08-24）

### 2.1 核心表规模

| 表 | 行数 | 分析意义 |
|---|---|---|
| message | 738,865 | 行为+内容分析核心 |
| media | 50,941（2.5GB 已本地化） | 媒体资产 |
| customer | 12,391 | 客户档案 |
| group_member | 12,866 | 群成员网络 |
| phone_call | 3,042（voice_call 2406 / wa_voice_call 636） | 话务行为 |
| chat_group | 1,470 | 群档案 |
| voice_clip | 1,441 | 长语音（音频字节在手） |
| sms | 0 | 阻塞（pcLogin 未通） |

### 2.2 关键结构指标（实测）

- **时间跨度**：2025-10-24 → 2026-08-24（整 10 个月，含今日）
- **1:1 对话数**：10,281（distinct owner×talker）；**有消息的群**：948；**活跃员工账号**：92（→ 41 员工，**一人多号 ≈2.2 账号/人**，见 §4.2 聚合规则）
- **消息类型分布**：text 654,891（88.6%）/ unknown 101,029 / image 62,321 / image_legacy 8,977
- **消息级语音**：无独立 voice 类型（ASR 对象以 voice_clip + 通话录音为准）

### 2.3 字段肥力矩阵（决定各功能可行性等级）

| 字段 | 覆盖 | 结论 |
|---|---|---|
| message.is_send + timestamp + owner/talker | ~100% | ✅ 行为分析三要素，所有 A/B/C 系列地基 |
| message.text（MEDIUMTEXT） | 88.6% 文本 | ✅ 内容分析可行 |
| customer.phone | 96%（11,942/12,391） | ✅ 跨渠道身份归一可行（B1/B3/B5 钥匙） |
| customer.region | 42% | ⚠️ 地域分布仅部分可用 |
| customer.add_time | 26%（3,282） | ⚠️ **不能当"新增客户"主口径**（见 A1 修订） |
| ngram 全文索引 | 已建（毫秒级） | ✅ C1 零基建成本 |
| message.refer_msg | 结构性非空（密度待抽样） | ⚠️ 回复链分析待验证 |
| phone_call.ring_time / call_status / incoming_call / call_duration | 有值 | ✅ 话务分析可行 |
| message.pay_msg_id、chat_group.loss_members/add_members | **0** | ❌ 转账标记/群进退人数无数据，相关分析不做 |
| phone_call.ai_asr、message.transcription_text | **0** | ❌ 转写需自建（D4） |

### 2.4 固有边界（所有功能共同前提）

1. **镜像滞后 ≤4h**：实时性按"小时级"承诺；所有看板必须带「数据截至」角标（取 sync_run 最新成功时间）。
2. **只覆盖沟通面**：见 §1.3。
3. **unknown 消息 13.7%**：计入消息量，不计入内容分析。

---

## 3. 功能全景（A–E 五系列 23 项）

图例：难度 ★☆☆（纯 SQL/复用现有设施，1-2 天）/ ★★☆（3-5 天）/ ★★★（外部依赖或较大工程）；价值 🔥🔥🔥 / 🔥🔥 / 🔥。

### A 系列 · 管理者看板

| # | 功能 | 做什么 | 数据依据 | 难度 | 价值 |
|---|---|---|---|---|---|
| A1 | 经营总览 Dashboard | 今日/本周/本月卡片（消息量、活跃客户、活跃员工、通话量、**首次沟通客户数**）+ 趋势折线 + 环比 + 「数据截至」角标 | stat_daily + message | ★☆☆ | 🔥🔥🔥 |
| A2 | 员工绩效深度分析 | 排行榜（消息量/首响时长/回复率/跟进客户数/通话时长）+ 单员工趋势 + 横向对比；**员工级一律按 user_id 聚合**（§4.2） | message + phone_call | ★★☆ | 🔥🔥🔥 |
| A3 | 客户流失预警 | **三分法**：真流失（曾活跃→沉默）/ 从未激活（last_chat_time=NULL）/ 待交接（归属员工离职）；30/60/90 天分层；按员工分组 CSV | customer.last_chat_time + message | ★☆☆ | 🔥🔥🔥 |
| A4 | 工作强度/时段分析 | 员工×小时热力图（按 user_id 聚合）、非工作时段沟通占比、通话密度 | timestamp 按Asia/Shanghai 抽小时 | ★☆☆ | 🔥🔥 |
| A5 | 群运营分析 | 群活跃度排行、沉默群清单、群消息趋势、TOP 活跃成员、员工群运营对比 | message(room_id)、group_member | ★★☆ | 🔥🔥 |
| A6 | ~~渠道对比~~ | **[v1.1] 降级**：channel 对比作为筛选维度并入各视图（A1/A2 的 tab），不独立成页 | — | ★☆☆ | 🔥 |

### B 系列 · 员工工具

| # | 功能 | 做什么 | 数据依据 | 难度 | 价值 |
|---|---|---|---|---|---|
| B1 | 客户 360 视图 | 单客户跨员工跨渠道全部沟通聚合（全局镜像库的结构能力：customer.phone 96% 归一）+ 活跃度曲线 + 偏好渠道。**归一规则**：phone/wechat_phone 去 `+86`/空格/横线后比对，命中即合并视图（customer 仍按 owner 多行存） | customer + message | ★★☆ | 🔥🔥🔥 |
| B2 | 该回未回清单 | 对话尾部为**有效类型**客户消息且员工 N 小时未回（尾部时间 = max(最后消息, 最后通话)，排除 delete_flag/is_block）；默认 2h 可调 | message 尾部 + phone_call | ★☆☆ | 🔥🔥🔥 |
| B3 | 撞单检测 | 同一归一手机号被多员工维护的冲突清单 | customer.phone + owner | ★☆☆ | 🔥🔥 |
| B4 | 高级客户检索 | 手机号/昵称/备注/地区组合查询，跨渠道 | 已有 search 底座 + region 42% | ★☆☆ | 🔥🔥 |
| B5 | **[v1.1 新增] RFM 客户分层** | R=最近沟通距今天数、F=统计窗沟通天数/条数、M=沟通深度（消息量+媒体交互+通话时长）→ 高价值/潜力/一般/沉睡四层 + 优先跟进清单 | E1 stat_daily_customer | ★☆☆ | 🔥🔥 |

### C 系列 · 合规风控

| # | 功能 | 做什么 | 数据依据 | 难度 | 价值 |
|---|---|---|---|---|---|
| C1 | 敏感词扫描 | 可配置词库（私单/飞单/加私人微信/红包转账/辱骂/离职倾向），定时扫描 + 命中表 + 跳转对话上下文 + 报告导出；**误报治理**（见 §5.5） | ngram 索引 + 65 万文本 | ★★☆ | 🔥🔥🔥 |
| C2 | 离职审计包 | 一键导出员工全部客户+消息+录音+图片；**[v1.1] zip 流式分卷**（每客户一 HTML + media/ 按 hash 去重目录），杜绝内存拼接 | export 机制扩展 | ★★☆ | 🔥🔥🔥 |
| C3 | 异常行为监测 | 深夜高频沟通、单客户消息量突增、删除好友(delete_flag)/被拉黑(is_block) 清单 | timestamp + flags | ★☆☆ | 🔥🔥 |
| C4 | 数据主权保障 | 定期全量备份 + 数据资产报告 | 镜像本质 + 导出 job | ★☆☆ | 🔥🔥 |

### D 系列 · LLM 智能化（需外部依赖）

| # | 功能 | 说明 | 难度 |
|---|---|---|---|
| D1 | 客户对话摘要 | LLM 摘要客户历史（接管/复盘速览） | ★★☆ + API 成本 |
| D2 | Chat with data | 自然语言问答 → 受控 SQL/API | ★★★ |
| D3 | 语义搜索 | embedding 搜模糊意图 | ★★☆ |
| D4 | 语音转写 ASR | **[v1.1] 分层转写**：先转「已手动匹配客户的长语音 + >60s 通话录音」，再扩全量（2.5GB）；转写文本回填 transcription_text/ai_asr 字段并接入 C1/搜索 | ★★★ + 算力 |
| D5 | 自动客户画像 | 从消息内容提取意向度/话题标签 | ★★☆ |

### E 系列 · 工程基建（支撑层）

| # | 功能 | 说明 |
|---|---|---|
| **E0** | **[v1.1 新增] 数据健康视图** | sync_run 成功率/失败清单、各实体最后成功同步时间、消息量日环比突变告警（某员工突然 0 消息=掉同步或离职）、cookie 失效检测。**所有看板数字的信任地基**，A1 的「数据截至」角标数据源 |
| E1 | 日汇总层 | `stat_daily_*` 物化表，scheduler 增量跑 + 回填脚本；所有看板毫秒级的地基（迟到数据回写见 §5.1） |
| E2 | 报表订阅 | 日报/周报自动生成 HTML/PDF 推送（邮件/企微 webhook） |
| E3 | BI 直连 | MySQL 只读账号给 Metabase/Grafana 自助探索 |

---

## 4. 横切设计约束 **[v1.1 新增]**

### 4.1 权限模型（现状：API_TOKEN 为空 = 鉴权关闭）

- **第一版假设：单管理者使用**（全局可见，部署在内网/可信边界）。B2 等员工向工具在多角色落地前**仅管理者使用**。
- **多角色路线（第二批随员工向功能一并做）**：加用户体系（admin / staff 两角色）；staff 行级权限 = 只看自己 `owner_account_id`（经 user_id→账号映射展开）；C1 词库管理与命中查看独立权限位（词库本身是高敏数据）。
- 上线任何监控类功能（A4/C1/C3）前，公司内部明示告知（劳动合规）。

### 4.2 性能与承载

- **员工级聚合规则**：92 活跃账号 vs 41 员工（≈2.2 账号/人）——员工级统计（A2/A4/E1 视图）一律按 `user_id` 聚合，账号级仅作下钻维度；离职员工（is_on_job=0）默认排除、可切换包含。
- **看板一律走 E1 汇总表**，禁止裸扫 message；C1 扫描分批限速。
- **建表**：新表走 `Base.metadata.create_all` 幂等（现有机制，alembic 为残留物）。
- **调度挂载**：E1/C1 复用 scheduler 现有 `asyncio.Lock` 排队，避开 02:00 全量窗口。
- **图表库选型（首批阻塞项）**：前端现无任何图表依赖。选型：**推荐 ECharts**（一次引入，A1/A2/A4/A5 全线复用）；备选首版纯 CSS 条形图（零依赖出活快，无趋势折线）。落地时在批次 spec 里定案。

---

## 5. 首批设计：「全家桶」= E0 + E1 + A1 + A3 + B2 + C1

（用户已确认推荐方向，实施另约；全部纯 SQL/复用现有设施、零外部依赖，~1.5 周）

### 5.0 E0 数据健康（先行——没有它，后面所有数字不可信）

- 数据源：sync_run（1,431 行闲置资产）+ sync_state + 调度日志。
- 视图：各实体最后成功同步时间、近 7 天成功率、失败 run 清单（error 摘要）；**日环比突变告警**（昨日消息量 vs 前 7 日均值偏离 >50% 标黄，定位到员工级判断"掉同步 or 离职 or 真跌"）；cookie 失效 = 近期 run 连续 code 告警。
- A1「数据截至」角标读这里。

### 5.1 E1 日汇总层

- 表：`stat_daily_staff(date, channel, owner_account_id, user_id, msg_sent, msg_recv, active_talkers, call_cnt, call_seconds)`、`stat_daily_customer(date, channel, friend_id, msg_in, msg_out, last_msg_ts)`、`stat_daily_group(date, channel, room_id, msg_cnt, active_members)`。
- **[v1.1] 迟到数据回写**：增量以"日期分区"为单位幂等重算——每次跑当日 + 本窗口内 `updated_at` 触及的历史日期分区（watermark 补扫会产生迟到历史消息，只跑当日会让历史行错）。
- 回填：一次性脚本扫 message 全表（73.9 万行，分钟级）。
- 口径：日期/小时一律 Asia/Shanghai；首响时长 = 客户消息串后员工首条回复间隔（同对话 24h 窗内有效，跨窗丢弃；"消息串"=客户连续消息不被员工消息打断）。

### 5.2 A1 经营总览

- **[v1.1] 新增客户口径修正**：主指标 = **首次沟通客户数**（该 talker 在 message 全库首条消息落当日，100% 覆盖）；add_time（26%）仅作辅助参考列。
- 卡片：今日/本周/本月消息量、活跃客户、活跃员工、通话量、首次沟通客户数；近 30 天折线；channel tab；**「数据截至」角标**（E0）。

### 5.3 A3 流失预警（三分法）

- **真流失**：历史有 ≥N 条消息（默认 5）且 last_chat_time 距今 30/60/90 天分层；
- **从未激活**：last_chat_time IS NULL 的新好友（该激活，不是挽回）；
- **待交接**：归属员工 is_on_job=0 的客户（该交接，不是流失）；
- 全部剔除 delete_flag=1；列：客户/渠道/归属员工/最后沟通/历史消息量/历史活跃天数；按员工分组导出 CSV。

### 5.4 B2 该回未回

- 判定：1:1 对话尾部消息 is_send=false 且 type ∈ 有效类型（text/image/voice/video/file/link，排除 unknown/divider）且尾部时间距今 > N 小时（默认 2h，可调 1/2/4/24h）。
- **[v1.1]** 尾部时间 = max(该对话最后消息 ts, 该客户最后通话 ts)——通话也算"已回应"；剔除 delete_flag/is_block；工作时间感知放 v2。
- 列：客户/员工/最后消息时间/等待时长/预览；点击跳 ChatTimeline。

### 5.5 C1 敏感词扫描

- 词库表 `sensitive_word(word, category, enabled, min_len, exclude_words)`，内置起步词库，后台可维护（权限位见 §4.1）。
- 扫描：scheduler 任务走 ngram MATCH / 分批 LIKE，写 `sensitive_hit(hit_id, word_id, msg_id, ts, channel, owner, talker, snippet, **disposition**)`。
- **[v1.1] 误报治理**：disposition ∈ pending/confirmed/false_positive/ignored，后台处置界面（列表默认只显示 pending+confirmed）；词级 exclude_words 与 min_len 抑制短词误命中。
- 范围：v1 仅 text；**预留** refer_msg 引文与 D4 转写文本接入位。
- UI：命中列表 → 跳 ChatTimeline 上下文；按员工/时间段导出报告。

---

## 6. 分批路线图 **[v1.1 更新]**

| 批次 | 内容 | 前置 | 预估 |
|---|---|---|---|
| 第一批 | **E0 + E1 + A1 + A3 + B2 + C1** | 无（图表库选型定案） | ~1.5 周 |
| 第二批 | B1 客户 360、B5 RFM、A2 绩效深化、**多角色权限体系**（员工向功能上线前必须）、C2 离职审计包、A5 群分析、E2 报表订阅、B3/B4/A4 | 第一批 E1 | 1-2 周 |
| 第三批 | D 系列（D1 摘要试水 → D3 语义搜索 → D4 分层 ASR → D2 问答 → D5 画像） | LLM API / 算力决策 | 按需 |

## 7. 风险与合规

1. **员工监控边界**：A4/C1/C3 上线前内部明示告知（§4.1）。
2. **口径透明**：所有对外数字标注口径（首次沟通客户数口径、含 unknown、滞后 ≤4h + 数据截至角标）。
3. **性能**：§4.2 全条。
4. **每批实施前**出独立 spec + implementation plan，本方案只定方向与口径。

---

## 附录 A · 实测验证记录（2026-08-24，MySQL `yunke` 库）

| 验证项 | 结果 |
|---|---|
| message 总量 / 时间跨度 | 738,865；2025-10-24 08:25 → 2026-08-24 10:02 |
| 消息类型分布 | text 654,891 / unknown 101,029 / image 62,321 / image_legacy 8,977 |
| 1:1 对话 / 有消息群 / 活跃员工账号（员工数） | 10,281 / 948 / 92（41） |
| phone_call 渠道分布 | voice_call 2,406 + wa_voice_call 636 |
| customer.phone / region / add_time 覆盖 | 11,942 (96%) / 5,241 (42%) / 3,282 (26%) |
| message.pay_msg_id 非空 | 0（转账分析不可行） |
| message.refer_msg 非空 JSON | 698,100（有效引用密度待抽样验证） |
| message.transcription_text / phone_call.ai_asr 非空 | 0 / 0（转写需自建） |
| chat_group.loss_members>0 / add_members>0 | 0 / 0（群进退分析不可行） |
| media 本地化体积 | 2.5GB（bind mount `./yunke-server/media`） |
| 系统事实（2026-08-25 复核） | API_TOKEN 空=鉴权关闭；前端无图表库；建表走 create_all 幂等；scheduler asyncio.Lock 互斥已有 |