# Proposal: integrate-call-status-update

## 概述

当查询通话状态返回的状态发生变化时，调用通话状态更新API更新后端状态，并刷新页面数据、切换到AI调解实时看板页签。

## 背景

当前 `OutboundCallWidget` 组件会轮询查询通话状态，但状态变化时只更新本地 localStorage，未同步到后端。需要：
1. 调用 `OutboundBotAPIService.updateCallStatus` 更新后端状态
2. 刷新AI调解进度数据
3. 切换到"AI调解实时看板"Tab页签

## 目标

- 当通话状态变化（排除 Scheduling）时，调用 API 更新后端状态
- 更新成功后刷新案件数据并切换到实时看板
- 支持多任务并行更新

## 技术方案

### 1. 状态变化检测逻辑

```
状态变化判断：newStatus !== job.callStatus
排除条件：job.callStatus === 'Scheduling'（调度中状态变化不触发更新）
触发条件：状态变化且原状态不为 Scheduling
```

### 2. 架构设计

**方案 B：事件回调方式**

```
App.js
  ├── TabContainer (接收 switchTab 方法)
  │     └── 内部 activeTab 状态管理
  └── OutboundCallWidget (接收 onSwitchTab, onRefreshData 回调)
        └── 状态变化时调用回调
```

### 3. 交互流程

```mermaid
graph TD
    A[轮询查询通话状态] --> B{状态变化?}
    B -->|否| Z[继续轮询]
    B -->|是| C{原状态是Scheduling?}
    C -->|是| D[仅更新localStorage]
    D --> Z
    C -->|否| E[调用updateCallStatus API]
    E --> F{API调用成功?}
    F -->|是| G[调用refreshData刷新数据]
    G --> H[调用onSwitchTab切换Tab]
    H --> I[更新localStorage]
    F -->|否| J[记录错误日志]
    J --> I
```

### 4. 多任务并行处理

当多个任务状态同时变化时：
- 使用 `Promise.all` 并行调用所有任务的 `updateCallStatus`
- 等待所有调用完成后再执行刷新和Tab切换
- 任一调用失败只记录日志，不影响其他任务

### 5. Props 设计

**OutboundCallWidget 新增 props：**

| Prop | 类型 | 必填 | 描述 |
|------|------|------|------|
| `onSwitchTab` | `(tabKey: string) => void` | 否 | Tab切换回调 |
| `onRefreshData` | `() => void` | 否 | 数据刷新回调 |

## 影响范围

### 修改文件
- `web-app/src/components/common/OutboundCallWidget.jsx` - 核心逻辑实现
- `web-app/src/components/dashboard/TabContainer.jsx` - 暴露 switchTab 方法
- `web-app/src/App.js` - 传递回调 props

### 依赖组件
- `web-app/src/services/OutboundBotAPIService.js` - API服务（已存在）
- `web-app/src/contexts/CaseDataContext.jsx` - refreshData 方法（已存在）

## 风险评估

### 低风险
- ✅ API 已经实现（`OutboundBotAPIService.updateCallStatus`）
- ✅ Context 已有 `refreshData` 方法
- ✅ 改动范围小，不影响现有功能

### 需要注意
- ⚠️ 多任务并行调用时的错误处理
- ⚠️ Tab 切换的时序（确保数据刷新后再切换）

## 验收标准

- [ ] 当通话状态从非 Scheduling 变化时，调用 `updateCallStatus` API
- [ ] 当状态从 Scheduling 变化时，不调用 `updateCallStatus` API
- [ ] API 调用成功后，调用 `refreshData()` 刷新案件数据
- [ ] API 调用成功后，切换到"AI调解实时看板"Tab
- [ ] 多任务并行时，所有任务都正确调用 API
- [ ] API 调用失败时，记录错误日志但不影响用户体验

## 待办任务

见 [tasks.md](./tasks.md)