vault backup: 2026-04-06 16:23:54
This commit is contained in:
Yaojia Wang
@@ -1,7 +1,8 @@
|
||||
---
|
||||
created: 2026-03-29
|
||||
updated: 2026-04-06
|
||||
type: project
|
||||
status: 未开始
|
||||
status: COMPLETED (2026-03-31)
|
||||
parent: "[[Smart Support]]"
|
||||
phase: 5
|
||||
timeline: 缓冲周
|
||||
@@ -14,97 +15,78 @@ tags:
|
||||
- documentation
|
||||
- edge-cases
|
||||
- e2e-testing
|
||||
- frontend
|
||||
- rate-limiting
|
||||
---
|
||||
|
||||
# Phase 5：打磨 + 演示准备
|
||||
|
||||
> Status: COMPLETED (2026-03-31)
|
||||
|
||||
## 目标
|
||||
|
||||
将 Smart Support 从「能跑」变成「能演示给客户看」。修复所有边界情况，准备演示数据和脚本，确保一键部署流程顺畅。这个阶段结束时，能录一个 90 秒的产品演示视频。
|
||||
|
||||
## 前置条件
|
||||
|
||||
- [[Smart Support/Phase 4 - 分析 + 回放]] 完成
|
||||
- 所有核心功能端到端可用
|
||||
将 Smart Support 从「能跑」变成「能演示给客户看」。修复所有边界情况，准备演示数据和脚本，确保一键部署流程顺畅。
|
||||
|
||||
## 阶段产出
|
||||
|
||||
- 错误处理覆盖所有已知边界情况
|
||||
- 演示脚本 + 真实感的示例数据
|
||||
- Docker Compose 全栈一键部署
|
||||
- 90 秒产品演示视频
|
||||
### 后端
|
||||
|
||||
---
|
||||
- **对话追踪器** (`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
|
||||
|
||||
## 任务清单
|
||||
### 前端（全部页面实现）
|
||||
|
||||
### 1. 错误处理加固
|
||||
- **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 导入表单 + 任务轮询 + 可编辑分类表
|
||||
|
||||
- [ ] 审查所有 API 端点，确保每个都有明确的错误响应
|
||||
- [ ] LLM API 超时 → 用户收到「AI 正在思考中，请稍候...」→ 15 秒后仍无响应 → 「抱歉，处理超时，请重试」
|
||||
- [ ] WebSocket 异常断开 → 前端自动重连（最多 3 次，间隔 1s/2s/4s）→ 重连失败 → 提示刷新页面
|
||||
- [ ] MCP 工具调用失败 → 「该操作暂时不可用，已通知技术团队」
|
||||
- [ ] 非预期错误 → 统一错误格式，不暴露堆栈信息
|
||||
- [ ] 所有错误记录详细日志（structlog / JSON 格式）
|
||||
### 基础设施
|
||||
|
||||
### 2. 演示数据
|
||||
- `frontend/Dockerfile` -- 多阶段构建（node:20-alpine -> nginx:alpine）
|
||||
- `frontend/nginx.conf` -- SPA 路由 + WebSocket/API 代理
|
||||
- `docker-compose.yml` -- 新增 frontend 服务、健康检查、app_network
|
||||
- `.env.example` -- Docker Compose 环境模板
|
||||
|
||||
- [ ] 创建模拟电商数据集：
|
||||
- 20 个订单（不同状态：待付款、已付款、已发货、已完成、已取消）
|
||||
- 5 个客户（含姓名、邮箱、订单历史）
|
||||
- 3 个优惠活动（满减、折扣码、新人券）
|
||||
- 物流追踪信息（不同快递公司、不同状态）
|
||||
- [ ] Mock 工具返回对应数据（根据 order_id 查表返回）
|
||||
- [ ] 数据感觉真实（合理的金额、日期、商品名称）
|
||||
### 文档
|
||||
|
||||
### 3. 演示脚本
|
||||
- `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` -- 完整项目概述 + 快速启动
|
||||
|
||||
- [ ] 编写演示对话脚本（覆盖核心功能）：
|
||||
## 测试覆盖
|
||||
|
||||
**场景 1：订单查询（30 秒）**
|
||||
> 用户：「我的订单 1042 到哪了？」
|
||||
> Agent：查询 → 返回物流信息 + 预计到达时间
|
||||
- 新增测试：42 个（conversation_tracker 13 + error_handler 19 + edge_cases 10）
|
||||
- 总测试：449（后续工程审查后增至 516）
|
||||
- 覆盖率：92.88%
|
||||
|
||||
**场景 2：取消订单 + 人工确认（30 秒）**
|
||||
> 用户：「帮我取消订单 1043」
|
||||
> Agent：确认提示 → 用户批准 → 取消成功
|
||||
## 与计划的偏差
|
||||
|
||||
**场景 3：OpenAPI 导入（30 秒）**
|
||||
> 粘贴 OpenAPI URL → 进度条 → 审核分类 → 新工具可用 → 用新工具完成操作
|
||||
- MAX_CONTENT_LENGTH 从 8000 改为 10000（匹配计划规格）
|
||||
- _thread_timestamps 模块级别，添加 autouse fixture 清理测试间状态
|
||||
- 异步追踪用 await 而非后台任务（WebSocket 循环已是 async）
|
||||
|
||||
- [ ] 准备一个公开可用的 OpenAPI spec URL 用于演示（或自建 mock API + spec）
|
||||
- [ ] 录制脚本的文字版，标注每个步骤的预期画面
|
||||
## 技术债务
|
||||
|
||||
### 4. Docker Compose 全栈部署
|
||||
|
||||
- [ ] 更新 `docker-compose.yml`：
|
||||
- PostgreSQL 16（带数据持久化 volume）
|
||||
- FastAPI 后端（含 uvicorn）
|
||||
- React 前端（nginx 托管构建产物）
|
||||
- 环境变量通过 `.env` 文件注入
|
||||
- [ ] 创建 `Dockerfile`（后端）和 `Dockerfile`（前端）
|
||||
- [ ] 健康检查：PostgreSQL ready → 后端启动 → 前端可访问
|
||||
- [ ] `docker compose up` 一键启动，无需手动操作
|
||||
- [ ] 编写部署文档（README 中的快速开始部分）
|
||||
|
||||
### 5. 90 秒演示视频
|
||||
|
||||
- [ ] 按演示脚本录制屏幕
|
||||
- [ ] 要点：
|
||||
- 开头 5 秒：一句话说明产品（「粘贴你的 API，获得一个能执行操作的 AI 客服」）
|
||||
- 展示速度：聊天流式输出的流畅感
|
||||
- 展示信任：人工确认流程
|
||||
- 展示魔法：OpenAPI 导入（粘贴 URL → 自动可用）
|
||||
- 展示价值：分析仪表盘（解决率、成本）
|
||||
- [ ] 视频放到可分享的位置（YouTube unlisted 或直接托管）
|
||||
|
||||
### 6. 最终测试
|
||||
|
||||
- [ ] 全量 E2E 测试通过
|
||||
- [ ] `pytest --cov` → 80%+ 覆盖率
|
||||
- [ ] 全新环境 `docker compose up` → 所有功能正常
|
||||
- [ ] 在不同网络环境测试（本地、云服务器）
|
||||
- [ ] 演示脚本完整跑通 3 次无报错
|
||||
- main.py 覆盖率 48%（启动路径需真实 DB）
|
||||
- 速率限制进程全局（多 Worker 需 Redis）
|
||||
- conversations 表 schema 假设已存在
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
Reference in New Issue
Block a user