# 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                                │
│  └──────┘                                                   │
│                                                              │
└─────────────────────────────────────────────────────────────┘
```