docs(analytics): 数据分析与增值功能全景方案(22项/5系列,基于2026-08-24实测数据审计,首批E1+A1+A3+B2+C1)

Co-Authored-By: Claude <noreply@anthropic.com>

docs/superpowers/specs/2026-08-24-yunke-analytics-portfolio-design.md

@@ -0,0 +1,176 @@
+# 云客数据镜像 · 数据分析与增值功能全景方案
+
+- **日期**：2026-08-24
+- **状态**：方案存档（讨论稿，未实施；每批落地前另出独立 spec + plan）
+- **依据**：本方案基于 2026-08-24 对生产 MySQL（`yunke` 库）的实测数据审计，所有数据能力论断均有查询背书（见附录 A）。
+- **背景**：镜像系统主体（6 列表 + 全操作对齐云客 + 五容器部署）已闭环。本方案回答：**基于现有数据，还能做哪些分析、实现哪些额外价值**，服务三类受众：老板/销售管理者、销售员工、合规/存档。
+
+---
+
+## 1. 数据资产审计（实测，2026-08-24）
+
+### 1.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 未通） |
+
+### 1.2 关键结构指标（实测）
+
+- **时间跨度**：2025-10-24 → 2026-08-24（整 10 个月，含今日）
+- **1:1 对话数**：10,281（distinct owner×talker）
+- **有消息的群**：948；**活跃员工账号**：92
+- **消息类型分布**：text 654,891（88.6%）/ unknown 101,029 / image 62,321 / image_legacy 8,977
+- **消息级语音**：无独立 voice 类型（转写对象以 voice_clip + 通话录音为准）
+
+### 1.3 字段肥力矩阵（决定各功能的可行性等级）
+
+| 字段 | 覆盖 | 结论 |
+|---|---|---|
+| message.is_send + timestamp + owner/talker | ~100% | ✅ 行为分析三要素齐，所有 A/B/C 系列的地基 |
+| message.text（MEDIUMTEXT） | 88.6% 为文本 | ✅ 内容分析（敏感词/话题/LLM）可行 |
+| customer.phone | 96%（11,942/12,391） | ✅ **跨渠道身份归一可行（B1/B3 的钥匙）** |
+| customer.region | 42% | ⚠️ 地域分布仅部分可用 |
+| customer.add_time | 26%（3,282） | ⚠️ 生命周期/新增客户口径受限，需标注 |
+| 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** | ❌ 上游转写为空，ASR 需自建（D4） |
+
+### 1.4 固有边界（所有功能共同的前提）
+
+1. **镜像滞后 ≤4h**：调度增量周期 4h，实时性口径按"小时级"承诺。
+2. **只覆盖沟通面**：未抓业绩/订单/商机，绩效分析只能评"沟通质量"，不能评"成单率"。若未来接入业绩数据源，A2 价值再上一档。
+3. **unknown 消息 13.7%**：类型未知的行为计入消息量，不计入内容分析。
+
+---
+
+## 2. 功能全景（A–E 五系列 22 项）
+
+图例：难度 ★☆☆（纯 SQL/复用现有设施，1-2 天）/ ★★☆（3-5 天）/ ★★★（需外部依赖或较大工程）；价值 🔥🔥🔥（核心）/ 🔥🔥（高）/ 🔥（中）。
+
+### A 系列 · 管理者看板（老板/销售管理视角）
+
+| # | 功能 | 做什么 | 数据依据 | 难度 | 价值 |
+|---|---|---|---|---|---|
+| A1 | 经营总览 Dashboard | 今日/本周/本月卡片（消息量、活跃客户、活跃员工、通话量、新增客户）+ 趋势折线 + 环比；微信/WA 分渠道 | message 按日聚合、customer.add_time（26% 口径标注）、phone_call | ★☆☆ | 🔥🔥🔥 |
+| A2 | 员工绩效深度分析 | 排行榜（消息量/首响时长/回复率/跟进客户数/通话时长）+ 单员工趋势 + 横向对比；从现有 5 数字 modal 升级为独立分析页 | message(is_send,timestamp)、phone_call(call_duration) | ★★☆ | 🔥🔥🔥 |
+| A3 | 客户流失预警 | 30/60/90 天未沟通分层清单、活跃→沉默转化、按归属员工分组、CSV 分发 | customer.last_chat_time（4h 实时刷新） | ★☆☆ | 🔥🔥🔥 |
+| A4 | 工作强度/时段分析 | 员工×小时热力图、非工作时段沟通占比、通话密度分布 | timestamp 小时抽取 | ★☆☆ | 🔥🔥 |
+| A5 | 群运营分析 | 群活跃度排行、沉默群清单、群消息趋势、TOP 活跃成员、员工群运营对比 | message(room_id)、group_member | ★★☆ | 🔥🔥 |
+| A6 | 微信 vs WA 渠道对比 | 两渠道客户量/消息量/响应效率/通话量并排视图 | channel 维度切分 | ★☆☆ | 🔥 |
+
+### B 系列 · 员工工具（销售视角）
+
+| # | 功能 | 做什么 | 数据依据 | 难度 | 价值 |
+|---|---|---|---|---|---|
+| B1 | 客户 360 视图 | 单客户**跨员工跨渠道**全部沟通聚合（云客按员工隔离看不到，我们全局库天然优势）+ 活跃度曲线 + 偏好渠道 | customer.phone 96% 归一 + message | ★★☆ | 🔥🔥🔥 |
+| B2 | 该回未回清单 | 对话尾部为客户消息且员工 N 小时未回的待办清单（默认 2h，可调） | 每对话尾部 message.is_send=false + timestamp | ★☆☆ | 🔥🔥🔥 |
+| B3 | 撞单检测 | 同一手机号被多员工维护的冲突清单 | customer.phone + owner_account_id | ★☆☆ | 🔥🔥 |
+| B4 | 高级客户检索 | 手机号/昵称/备注/地区组合查询，跨渠道 | 已有 search 底座 + region 42% | ★☆☆ | 🔥🔥 |
+
+### C 系列 · 合规风控（镜像系统独有）
+
+| # | 功能 | 做什么 | 数据依据 | 难度 | 价值 |
+|---|---|---|---|---|---|
+| C1 | 敏感词扫描 | 可配置词库（私单/飞单/加私人微信/红包转账/辱骂/离职倾向），定时全量+增量扫描，命中表 + 跳转对话上下文 + 按员工/时间出报告 | ngram 全文索引（毫秒级）+ 65 万文本 | ★★☆ | 🔥🔥🔥 |
+| C2 | 离职审计包 | 一键导出员工全部客户+消息+录音+图片（HTML 媒体内嵌）存档 | export HTML 单客户版已有，扩展员工级 | ★★☆ | 🔥🔥🔥 |
+| C3 | 异常行为监测 | 深夜高频沟通、单客户消息量突增、删除好友(delete_flag)/被拉黑(is_block) 清单 | timestamp + delete_flag + is_block | ★☆☆ | 🔥🔥 |
+| C4 | 数据主权保障 | 定期全量备份 + 数据资产报告；云客停订后完整留存 | 镜像本质 + 导出 job | ★☆☆ | 🔥🔥 |
+
+### D 系列 · LLM 智能化（增值方向，需外部依赖）
+
+| # | 功能 | 说明 | 难度 |
+|---|---|---|---|
+| D1 | 客户对话摘要 | LLM 摘要客户历史（接管/复盘速览上下文） | ★★☆ + API 成本 |
+| D2 | Chat with data | 自然语言问答 → 受控 SQL/API（"上个月谁跟张三聊最多"） | ★★★ |
+| D3 | 语义搜索 | embedding 搜模糊意图（"客户在抱怨价格"） | ★★☆ |
+| D4 | 语音转写 ASR | 1,441 长语音 + 3,042 通话录音（字节在手）；上游转写字段全空，需自跑 Whisper 类模型；转写后进搜索/摘要价值放大 | ★★★ + 算力 |
+| D5 | 自动客户画像 | 从消息内容提取意向度/话题标签 | ★★☆ |
+
+### E 系列 · 工程基建（支撑层）
+
+| # | 功能 | 说明 |
+|---|---|---|
+| E1 | 日汇总层 | `stat_daily_*` 物化表（员工日/客户日/群日指标），scheduler 增量跑 + 回填脚本；所有看板毫秒级的地基 |
+| E2 | 报表订阅 | 日报/周报自动生成 HTML/PDF，邮件或企微机器人推送（scheduler 加 job） |
+| E3 | BI 直连 | MySQL 只读账号给 Metabase/Grafana 自助探索 |
+
+---
+
+## 3. 首批推荐：「全家桶」（用户已确认推荐方向，实施另约）
+
+**E1 → A1 → A3 → B2 → C1**，全部纯 SQL / 复用现有设施、零外部依赖，合计约 1 周。指标口径草案：
+
+### E1 日汇总层（地基，先行）
+
+- `stat_daily_staff(date, channel, owner_account_id, user_id, msg_sent, msg_recv, active_talkers, call_cnt, call_seconds, first_response_sum...)`
+- `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)`
+- 生成方式：scheduler 在每 4h messages 增量后跑当日增量；一次性回填脚本扫 message 全表（73.9 万行，分钟级）。
+- 口径：日期按 Asia/Shanghai；首响时长 = 客户消息后员工首条回复的间隔（同对话 24h 窗内有效，跨窗丢弃）。
+
+### A1 经营总览
+
+- 新增 Dashboard 路由 + 菜单组「数据分析」。
+- 指标：活跃客户 = 当日有消息收发的 distinct talker；新增客户 = add_time 当日（**口径标注：仅 26% 客户有 add_time**）；消息量/通话量来自 stat_daily。
+- 图表：卡片 + 近 30 天折线 + 渠道拆分 tab。
+
+### A3 流失预警
+
+- 分层：>30 / >60 / >90 天（按 customer.last_chat_time 对比当前，4h 实时刷新）。
+- 列：客户、渠道、归属员工、最后沟通时间、历史消息量、历史活跃天数。
+- 操作：按员工分组导出 CSV（复用 csvExport.ts）。
+
+### B2 该回未回
+
+- 判定：对话尾部消息 is_send=false（客户发的）且距今 > N 小时（默认 2h，前端可调 1/2/4/24h）。
+- 列：客户、员工、客户最后消息时间、等待时长、消息预览；点击跳 ChatTimeline。
+- 范围：仅 1:1 对话（群不做）。
+
+### C1 敏感词扫描
+
+- 词库：DB 表 `sensitive_word(word, category, enabled)` 起步词库内置（私单/飞单/加私人微信/红包/转账/辱骂/离职倾向类），后台可维护。
+- 扫描：scheduler 定时任务跑 ngram MATCH 或分批 LIKE，命中写 `sensitive_hit(hit_id, word_id, msg_id, ts, channel, owner, talker, snippet)`。
+- UI：命中列表（词/时间/员工/客户/上下文片段）→ 点击跳 ChatTimeline 定位；按员工/时间段导出报告。
+- 边界：只扫描 text 类型（88.6%），图片 OCR 不在首批。
+
+## 4. 分批路线图
+
+| 批次 | 内容 | 前置 | 预估 |
+|---|---|---|---|
+| 第一批 | E1 + A1 + A3 + B2 + C1 | 无 | ~1 周 |
+| 第二批 | A2 绩效深化、B1 客户 360、C2 离职审计包、A5 群分析、E2 报表订阅、B3/B4/A4/A6 | 第一批 E1 | 1-2 周 |
+| 第三批 | D 系列（建议 D1 摘要试水 → D3 语义搜索 → D4 ASR 看算力 → D2 问答） | LLM API / 算力决策 | 按需 |
+
+## 5. 风险与合规注意
+
+1. **员工监控边界**：A4/C1/C3 属监控性质，上线前建议公司内部明示告知（劳动合规视角）。
+2. **口径透明**：所有对外数字标注口径（尤其新增客户 26% 覆盖、消息量含 unknown、滞后 ≤4h）。
+3. **性能**：看板一律走 E1 汇总表，禁止裸扫 message；C1 扫描分批限速避免与增量同步抢锁。
+4. **每批实施前**出独立 spec + implementation plan（走既有 superpowers 流程），本方案只定方向与口径。
+
+---
+
+## 附录 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 |
+| 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`） |