95 lines
3.2 KiB
Markdown
95 lines
3.2 KiB
Markdown
---
|
||
created: 2026-03-29
|
||
updated: 2026-04-06
|
||
type: project
|
||
status: COMPLETED (2026-03-31)
|
||
parent: "[[Smart Support]]"
|
||
phase: 5
|
||
timeline: 缓冲周
|
||
tags:
|
||
- phase-5
|
||
- error-handling
|
||
- demo
|
||
- deployment
|
||
- docker
|
||
- documentation
|
||
- edge-cases
|
||
- e2e-testing
|
||
- frontend
|
||
- rate-limiting
|
||
---
|
||
|
||
# Phase 5：打磨 + 演示准备
|
||
|
||
> Status: COMPLETED (2026-03-31)
|
||
|
||
## 目标
|
||
|
||
将 Smart Support 从「能跑」变成「能演示给客户看」。修复所有边界情况，准备演示数据和脚本，确保一键部署流程顺畅。
|
||
|
||
## 阶段产出
|
||
|
||
### 后端
|
||
|
||
- **对话追踪器** (`conversation_tracker.py`)：Protocol + PostgresConversationTracker + NoOpConversationTracker，生命周期管理（ensure, record_turn, resolve）
|
||
- **错误处理** (`tools/error_handler.py`)：ErrorCategory 枚举、classify_error()、with_retry() 指数退避（仅重试可重试错误）
|
||
- **WebSocket 加固** (`ws_handler.py`)：
|
||
- analytics_recorder + conversation_tracker + pool 参数
|
||
- _fire_and_forget_tracking 异步追踪
|
||
- 速率限制（10 msg/10s per thread）
|
||
- 空白消息检查、JSON 数组拒绝、10000 字符限制
|
||
- **健康检查**：GET /api/health
|
||
- **演示数据**：demo_data.py 种子脚本 + sample_openapi.yaml
|
||
|
||
### 前端（全部页面实现）
|
||
|
||
- **API 客户端** (`api.ts`)：fetchConversations, fetchReplay, fetchAnalytics 类型化封装
|
||
- **导航** (`NavBar.tsx` + `Layout.tsx`)：水平导航 + App Shell
|
||
- **错误提示** (`ErrorBanner.tsx`)：断线状态 + 重连按钮
|
||
- **分析组件** (`MetricCard.tsx`)：可复用指标卡片
|
||
- **回放组件** (`ReplayTimeline.tsx`)：垂直时间线 + 可展开步骤详情
|
||
- **页面**：
|
||
- `ChatPage.tsx` -- 聊天（集成 ErrorBanner）
|
||
- `ReplayListPage.tsx` -- 对话列表（分页）
|
||
- `ReplayPage.tsx` -- 回放时间线
|
||
- `DashboardPage.tsx` -- 分析仪表盘（范围选择、零状态处理）
|
||
- `ReviewPage.tsx` -- OpenAPI 导入表单 + 任务轮询 + 可编辑分类表
|
||
|
||
### 基础设施
|
||
|
||
- `frontend/Dockerfile` -- 多阶段构建（node:20-alpine -> nginx:alpine）
|
||
- `frontend/nginx.conf` -- SPA 路由 + WebSocket/API 代理
|
||
- `docker-compose.yml` -- 新增 frontend 服务、健康检查、app_network
|
||
- `.env.example` -- Docker Compose 环境模板
|
||
|
||
### 文档
|
||
|
||
- `docs/demo-script.md` -- 10 分钟演示脚本（5 个场景）
|
||
- `docs/agent-config-guide.md` -- agents.yaml 参考
|
||
- `docs/openapi-import-guide.md` -- 导入工作流 + SSRF 防护
|
||
- `docs/deployment.md` -- Docker Compose 部署 + 生产考虑
|
||
- `README.md` -- 完整项目概述 + 快速启动
|
||
|
||
## 测试覆盖
|
||
|
||
- 新增测试：42 个（conversation_tracker 13 + error_handler 19 + edge_cases 10）
|
||
- 总测试：449（后续工程审查后增至 516）
|
||
- 覆盖率：92.88%
|
||
|
||
## 与计划的偏差
|
||
|
||
- MAX_CONTENT_LENGTH 从 8000 改为 10000（匹配计划规格）
|
||
- _thread_timestamps 模块级别，添加 autouse fixture 清理测试间状态
|
||
- 异步追踪用 await 而非后台任务（WebSocket 循环已是 async）
|
||
|
||
## 技术债务
|
||
|
||
- main.py 覆盖率 48%（启动路径需真实 DB）
|
||
- 速率限制进程全局（多 Worker 需 Redis）
|
||
- conversations 表 schema 假设已存在
|
||
|
||
## Related
|
||
|
||
- [[Smart Support/Phase 4 - 分析 + 回放]]
|
||
- [[Smart Support]]
|