From 6bb08c2297be1b6415c8bc02e6917eba6ee355e5 Mon Sep 17 00:00:00 2001 From: shimai <shimai@example.com> Date: Fri, 03 Apr 2026 10:42:08 +0800 Subject: [PATCH] Merge remote-tracking branch 'origin/test/tony.cheng/260312' into test/shimai.huang/260309 --- openspec/changes/add-call-record-viewer/design.md | 198 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 198 insertions(+), 0 deletions(-) diff --git a/openspec/changes/add-call-record-viewer/design.md b/openspec/changes/add-call-record-viewer/design.md new file mode 100644 index 0000000..9b39062 --- /dev/null +++ b/openspec/changes/add-call-record-viewer/design.md @@ -0,0 +1,198 @@ +# Design Document: AI调解通话记录查看功能 + +## 上下文 + +### 背景 +云小调系统通过AI调解员自动拨打当事人电话进行初步沟通，调解员需要在实时看板中了解通话详情以便进行后续人工调解。当前系统缺少通话记录的详细展示功能。 + +### 约束条件 +- 前端项目使用React + Ant Design 4.24.12 +- 数据来源为 `OutboundBotAPIService.getConversationLog` API +- 需要兼容多种外呼状态（已接通、未接通等） +- 录音文件为.wav格式 + +### 相关利益相关者 +- 调解员：需要快速查看通话记录了解沟通情况 +- 产品经理：关注用户体验和功能完整性 + +## 目标与非目标 + +### 目标 +- 提供直观的通话记录查看入口 +- 展示清晰的双方对话内容 +- 支持录音文件播放 +- 正确处理各种外呼状态 + +### 非目标 +- 不实现通话记录的编辑功能 +- 不实现通话记录的导出功能 +- 不实现录音文件的下载功能（本期暂不实现） + +## 技术决策 + +### 1. UI组件结构 + +**决策**：使用Ant Design Modal作为弹窗容器，自定义内部组件 + +**理由**： +- Modal组件与系统其他弹窗风格一致 +- 内部需要高度自定义的聊天界面样式 +- 便于后续扩展其他功能 + +**组件层级**： +``` +MediationBoard +└── BoardItem (调解记录卡片) + └── CallRecordButton (通话记录按钮) + └── CallRecordModal (通话记录弹窗) + ├── AudioPlayer (录音播放器) + └── ConversationList (对话记录列表) + └── ConversationItem (单条对话) +``` + +### 2. 数据获取策略 + +**决策**：按需加载，点击按钮时调用API + +**理由**： +- 避免列表加载时请求数量过多 +- 减少不必要的API调用 +- 提升页面初始加载速度 + +**API调用流程**： +``` +用户点击按钮 + → 获取caseId（URL参数 > localStorage） + → 获取person_id和job_id（调解记录数据） + → 调用getConversationLog API + → 处理返回数据（取最后一条） + → 渲染弹窗内容 +``` + +### 3. 外呼状态处理 + +**决策**：根据callStatus字段区分展示内容 + +**状态分类**： +| 状态类型 | callStatus值 | 展示内容 | +|---------|-------------|---------| +| 已接通 | 1, 20-31 | 录音播放器 + 对话记录 | +| 未接通 | 0, 2-19, 32 | 提示"未接通，无通话记录" | + +### 4. 对话记录展示设计 + +**决策**：采用类似微信聊天的左右布局 + +**设计规范**： +- **AI调解员消息**： + - 位置：左侧 + - 头像：机器人图标 + - 背景：浅蓝色(#e3f2fd) + - 名称显示："AI调解员" + +- **当事人消息**： + - 位置：右侧 + - 头像：显示名字首字 + - 背景：浅绿色(#e8f5e9) + - 名称显示：调解记录中的creator字段值 + +**时间戳格式**：`YYYY-MM-DD HH:mm` + +### 5. 录音播放器设计 + +**决策**：使用HTML5原生audio标签 + +**理由**： +- 原生支持.wav格式 +- 无需额外依赖 +- 浏览器兼容性好 + +**样式设计**： +- 位置：弹窗顶部固定 +- 背景：浅灰色(#f5f5f5) +- 高度：50px +- 宽度：100% + +## 替代方案 + +### 方案1：使用第三方聊天UI库 +- **优点**：开箱即用，功能完善 +- **缺点**：引入额外依赖，样式可能不一致 +- **决策**：不采用，保持项目简洁 + +### 方案2：在卡片内直接展示对话 +- **优点**：无需弹窗，操作更直接 +- **缺点**：占用空间大，影响列表展示 +- **决策**：不采用，使用弹窗更合理 + +## 风险与权衡 + +### 风险1：录音文件URL无效 +- **概率**：中 +- **影响**：用户无法播放录音 +- **缓解措施**： + - 提供明确的错误提示 + - 支持用户手动重试 + - 记录错误日志便于排查 + +### 风险2：API响应缓慢 +- **概率**：低 +- **影响**：用户体验下降 +- **缓解措施**： + - 显示加载状态 + - 设置合理的超时时间（30秒） + - 提供取消操作选项 + +### 风险3：对话内容过长 +- **概率**：高 +- **影响**：弹窗内容溢出 +- **缓解措施**： + - 弹窗设置最大高度 + - 内部区域支持滚动 + - 对话列表虚拟化（如内容过多） + +## 迁移计划 + +### 实施步骤 +1. 创建通话记录弹窗组件 +2. 在MediationBoard组件中添加按钮和弹窗触发逻辑 +3. 实现API调用和数据转换 +4. 添加样式和交互效果 +5. 处理各种边界情况 + +### 回滚方案 +- 功能通过feature flag控制，出问题可直接禁用 +- 按钮点击事件独立封装，不影响现有调解记录展示 + +## 开放问题 + +1. **录音文件存储周期**：需要确认录音文件的保存时长，避免播放失败 +2. **并发限制**：是否需要限制同时打开的弹窗数量 +3. **权限控制**：是否所有调解员都能查看通话记录 + +## 参考设计 + +### 对话记录UI设计稿 +``` +┌─────────────────────────────────────────────────────────────┐ +│ AI调解员与申请人（刘树杰）的通话 任务ID: xxx │ +├─────────────────────────────────────────────────────────────┤ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ 🔊 录音播放器 [▶播放] ━━━━━━━●─────── 03:45/10:20 │ │ +│ └─────────────────────────────────────────────────────┘ │ +├─────────────────────────────────────────────────────────────┤ +│ │ +│ ┌──────┐ 你好，刘树杰先生吗？我是白云区... │ +│ │ AI │ 2026-03-12 16:30 │ +│ └──────┘ │ +│ │ +│ 呃，你刚才前面说你是谁？ ┌──────┐ │ +│ 2026-03-12 16:33 │ 刘 │ │ +│ └──────┘ │ +│ │ +│ ┌──────┐ 哦，不好意思，我是白云区人和镇... │ +│ │ AI │ 2026-03-12 16:33 │ +│ └──────┘ │ +│ │ +└─────────────────────────────────────────────────────────────┘ +``` -- Gitblit v1.8.0