---
created: 2026-03-29
updated: 2026-04-06
type: project
status: COMPLETED (2026-03-31)
parent: "[[Smart Support]]"
phase: 4
timeline: 第 6-7 周
tags:
  - phase-4
  - analytics
  - replay
  - dashboard
  - postgresql
  - pagination
  - data-visualization
  - resolution-rate
  - cost-tracking
---

# Phase 4：分析 + 回放

> Status: COMPLETED (2026-03-31)

## 目标

让客户看到 AI 客服的 ROI。对话回放让客户信任系统，分析仪表盘用数据证明价值。

## 阶段产出

- 回放数据模型：StepType 枚举、ReplayStep、ReplayPage（冻结数据类）
- 检查点转换器：PostgresSaver JSONB -> 结构化 ReplayStep 时间线
- 回放 API：GET /api/conversations（分页列表）、GET /api/replay/{thread_id}（分页时间线）
- 分析数据模型：AgentUsage、InterruptStats、AnalyticsResult
- 分析事件记录器：Protocol 接口 + PostgresAnalyticsRecorder + NoOpAnalyticsRecorder
- 分析查询：resolution_rate、agent_usage、escalation_rate、cost_per_conversation、interrupt_stats
- 分析 API：GET /api/analytics?range=Xd
- DB 迁移：analytics_events 表 + conversations 列扩展

## 新增文件

| 文件 | 用途 |
|------|------|
| `app/replay/models.py` | StepType, ReplayStep, ReplayPage |
| `app/replay/transformer.py` | Checkpoint JSONB -> ReplayStep[] |
| `app/replay/api.py` | 回放 + 对话列表 API |
| `app/analytics/models.py` | AgentUsage, InterruptStats, AnalyticsResult |
| `app/analytics/event_recorder.py` | 记录器 Protocol + 实现 |
| `app/analytics/queries.py` | SQL 查询 + get_analytics 聚合 |
| `app/analytics/api.py` | 分析 API 路由 |

## 分析指标

| 指标 | 计算方式 |
|------|---------|
| 解决率 | 成功工具调用 + 未升级 / 总对话数 |
| Agent 使用率 | 每 Agent 路由次数占比 |
| 升级率 | 触发 Webhook 对话占比 |
| 每对话成本 | Token 用量 x 价格 |
| 中断统计 | approved/rejected/expired 分布 |

## 测试覆盖

- 新增测试：74 个
- 总测试：399
- 覆盖率：92.87%
- 所有新模块覆盖率 81-100%

## 与计划的偏差

- 前端页面推迟到 Phase 5
- ws_handler 事件记录推迟（注册 NoOpAnalyticsRecorder）
- conversations.agents_used 列未填充

## Related

- [[Smart Support/Phase 3 - OpenAPI 自动发现]]
- [[Smart Support/Phase 5 - 打磨 + 演示]]
- [[Smart Support]]