---
created: 2026-03-29
type: project
status: 未开始
parent: "[[Smart Support]]"
phase: 5
timeline: 缓冲周
tags:
  - phase-5
  - error-handling
  - demo
  - deployment
  - docker
  - documentation
  - edge-cases
  - e2e-testing
---

# Phase 5：打磨 + 演示准备

## 目标

将 Smart Support 从「能跑」变成「能演示给客户看」。修复所有边界情况，准备演示数据和脚本，确保一键部署流程顺畅。这个阶段结束时，能录一个 90 秒的产品演示视频。

## 前置条件

- [[Smart Support/Phase 4 - 分析 + 回放]] 完成
- 所有核心功能端到端可用

## 阶段产出

- 错误处理覆盖所有已知边界情况
- 演示脚本 + 真实感的示例数据
- Docker Compose 全栈一键部署
- 90 秒产品演示视频

---

## 任务清单

### 1. 错误处理加固

- [ ] 审查所有 API 端点，确保每个都有明确的错误响应
- [ ] LLM API 超时 → 用户收到「AI 正在思考中，请稍候...」→ 15 秒后仍无响应 → 「抱歉，处理超时，请重试」
- [ ] WebSocket 异常断开 → 前端自动重连（最多 3 次，间隔 1s/2s/4s）→ 重连失败 → 提示刷新页面
- [ ] MCP 工具调用失败 → 「该操作暂时不可用，已通知技术团队」
- [ ] 非预期错误 → 统一错误格式，不暴露堆栈信息
- [ ] 所有错误记录详细日志（structlog / JSON 格式）

### 2. 演示数据

- [ ] 创建模拟电商数据集：
  - 20 个订单（不同状态：待付款、已付款、已发货、已完成、已取消）
  - 5 个客户（含姓名、邮箱、订单历史）
  - 3 个优惠活动（满减、折扣码、新人券）
  - 物流追踪信息（不同快递公司、不同状态）
- [ ] Mock 工具返回对应数据（根据 order_id 查表返回）
- [ ] 数据感觉真实（合理的金额、日期、商品名称）

### 3. 演示脚本

- [ ] 编写演示对话脚本（覆盖核心功能）：

**场景 1：订单查询（30 秒）**
> 用户：「我的订单 1042 到哪了？」
> Agent：查询 → 返回物流信息 + 预计到达时间

**场景 2：取消订单 + 人工确认（30 秒）**
> 用户：「帮我取消订单 1043」
> Agent：确认提示 → 用户批准 → 取消成功

**场景 3：OpenAPI 导入（30 秒）**
> 粘贴 OpenAPI URL → 进度条 → 审核分类 → 新工具可用 → 用新工具完成操作

- [ ] 准备一个公开可用的 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 次无报错

## Related

- [[Smart Support/Phase 4 - 分析 + 回放]]
- [[Smart Support]]