feat: 实现智能外呼自动触发与状态监控功能

tony.cheng

2026-02-09 d31819515e4aac228f26e7cbb92c89e0f520e8ac

feat: 实现智能外呼自动触发与状态监控功能

- 新增智能外呼自动触发逻辑（CaseDataContext）
  - 页面加载后自动发起外呼
  - 幂等性检查避免重复触发
  - 成功/失败分类处理和提示
  - 添加caseId字段用于轮询

- 重构外呼状态轮询机制（OutboundCallWidget）
  - 修正API参数：同时传入caseRef和jobId
  - 10秒轮询间隔 + 2小时最大轮询时长
  - 失败重试10次机制
  - 终态自动清理（Succeeded/Failed/Cancelled）
  - 状态中文映射显示
  - 组件卸载时清理定时器

- 创建OpenSpec提案文档
  - proposal.md: 功能概述与影响范围
  - tasks.md: 67项实现任务清单
  - design.md: 技术决策与风险分析
  - spec.md: 7个核心需求 + 20+场景

参考: integrate-auto-outbound-call

 API文档.md

@@ -23,8 +23,6 @@

Base URLs:

* <a href="http://localhost:9015">开发环境: http://localhost:9015</a>

# Authentication

# AI云小调/典型案例查询
@@ -3956,5 +3954,298 @@
|»» agreeId|string|true|none|协议ID|none|
|»» agreeContent|string|true|none|协议内容|none|

# AI云小调/外呼通话

## POST 智能外呼拨打电话

POST /api/v1/outbound-bot/call-v2

> Body 请求参数

```json
{
  "caseId": "string",
  "mediationId": "string",
  "callAuto": 0,
  "callPersonId": "string"
}
```

### 请求参数

|名称|位置|类型|必选|中文名|说明|
|---|---|---|---|---|---|
|body|body|object| 否 ||none|
|» caseId|body|string| 是 | 案件ID|none|
|» mediationId|body|string| 是 | AI调解反馈ID|none|
|» callAuto|body|integer| 是 | 是否自动拨打(0:自动,1:手动)|none|
|» callPersonId|body|string| 是 | 被呼叫人ID|none|

> 返回示例

> 201 Response

```json
{
  "code": 201,
  "message": "外呼请求处理完成",
  "data": [
    {
      "errorCode": 0,
      "message": "外呼发起成功",
      "id": 26,
      "mediationId": 20,
      "nodeId": 5,
      "taskName": "履约回访",
      "result": null,
      "personType": 0,
      "mediationType": 1,
      "personId": "2303191513081131",
      "jobId": "1770463000471-447e-96ea-97523c61189b",
      "instanceId": "4087bb39-7688-4c5b-a4c5-01f7bb98e466",
      "jobGroupId": "dfd0c60b-6434-4482-afc7-ac5f83f9ffe6",
      "scriptId": "3c0aabe5-eb82-4f25-a8c2-8a66ddd5fa0f",
      "callStatus": "Scheduling",
      "remark": null,
      "deleteStatus": 1,
      "creator": "system",
      "createTime": "2026-02-07",
      "modifier": null,
      "modifyTime": null,
      "startTime": null,
      "callInterval": null
    },
    {
      "errorCode": 0,
      "message": "外呼发起成功",
      "id": 27,
      "mediationId": 20,
      "nodeId": 5,
      "taskName": "履约回访",
      "result": null,
      "personType": 0,
      "mediationType": 1,
      "personId": "2303191513081130",
      "jobId": "1770463016662-4d90-ab26-a10656d79a73",
      "instanceId": "4d5f2f2b-c7c2-4c41-b19c-02a72341323b",
      "jobGroupId": "280e5420-e0e2-43a9-be51-c54270f6abdd",
      "scriptId": "fc73783d-1ea6-4282-a116-7b2ab6186470",
      "callStatus": "Scheduling",
      "remark": null,
      "deleteStatus": 1,
      "creator": "system",
      "createTime": "2026-02-07",
      "modifier": null,
      "modifyTime": null,
      "startTime": null,
      "callInterval": null
    }
  ]
}
```

### 返回结果

|状态码|状态码含义|说明|数据模型|
|---|---|---|---|
|201|[Created](https://tools.ietf.org/html/rfc7231#section-6.3.2)|none|Inline|

### 返回数据结构

状态码 **201**

|名称|类型|必选|约束|中文名|说明|
|---|---|---|---|---|---|
|» code|integer|true|none||none|
|» message|string|true|none||none|
|» data|[object]|true|none||none|
|»» errorCode|integer|true|none|错误码(0:成功,1001:须等待,1002:呼叫已达上限)|none|
|»» message|string|true|none||none|
|»» id|integer|true|none|调解记录ID|none|
|»» mediationId|integer|true|none|调解ID|none|
|»» nodeId|integer|true|none|节点ID|none|
|»» taskName|string|true|none|任务名称|none|
|»» result|null|true|none|记录结果|none|
|»» personType|integer|true|none|用户类型|none|
|»» mediationType|integer|true|none|调解方式|none|
|»» personId|string|true|none|用户ID|none|
|»» jobId|string|true|none|工作ID|none|
|»» instanceId|string|true|none|实例ID|none|
|»» jobGroupId|string|true|none|工作组ID|none|
|»» scriptId|string|true|none|场景ID|none|
|»» callStatus|string|true|none|呼叫状态|none|
|»» remark|null|true|none||none|
|»» deleteStatus|integer|true|none||none|
|»» creator|string|true|none||none|
|»» createTime|string|true|none||none|
|»» modifier|null|true|none||none|
|»» modifyTime|null|true|none||none|
|»» startTime|null|true|none|下一轮呼叫开始时间|none|
|»» callInterval|null|true|none|下一轮呼叫间隔|none|

## GET 获取通话录音接口

GET /api/v1/outbound-bot/conversation-log

### 请求参数

|名称|位置|类型|必选|中文名|说明|
|---|---|---|---|---|---|
|caseId|query|string| 否 ||案件id|
|personId|query|string| 否 ||当事人id|
|jobId|query|string| 否 ||工作ID|

> 返回示例

> 200 Response

```json
{
  "code": 200,
  "message": "查询成功",
  "data": [
    {
      "callType": "follow_up",
      "jobId": "1770604607798-4f25-a8be-32a23b347047",
      "conversations": "[{\"timestamp\": 1770604618000, \"speaker\": \"Contact\", \"script\": \"\", \"action\": \"BeginDialogue\"}, {\"timestamp\": 1770604619000, \"speaker\": \"Robot\", \"script\": \"您好，刘树杰先生，请问您有关于调解协议执行情况的问题吗？我是负责跟进您与胡龙光先生之间调解协议执行情况的调解员。\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770604629000, \"speaker\": \"Contact\", \"script\": null, \"action\": \"EndDialogue\"}]",
      "callStatus": "Succeeded",
      "recordUrl": "http://voicenavigator-cn-shanghai.oss-cn-shanghai.aliyuncs.com/exported_files/e938a68795634c88b8160f30c6da7b67.wav?Expires=1770691031&OSSAccessKeyId=LTAIHgPej9maicqw&Signature=oFCXtkSWyuEjOQQl97nBRnCIxUA%3D"
    },
    {
      "callType": "follow_up",
      "jobId": "1770602740446-4bb6-bbbd-ffe36aea0c10",
      "conversations": "[{\"timestamp\": 1770602756000, \"speaker\": \"Contact\", \"script\": \"\", \"action\": \"BeginDialogue\"}, {\"timestamp\": 1770602762000, \"speaker\": \"Robot\", \"script\": \"您好！我是您的调解员。请问有关调解协议的执行情况，您需要了解哪方面的信息？例如支付进度或是遇到的任何问题。\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770602765000, \"speaker\": \"Contact\", \"script\": null, \"action\": \"EndDialogue\"}]",
      "callStatus": "Succeeded",
      "recordUrl": "http://voicenavigator-cn-shanghai.oss-cn-shanghai.aliyuncs.com/exported_files/c88d0baef0274b7fac77dc295305e18c.wav?Expires=1770689167&OSSAccessKeyId=LTAIHgPej9maicqw&Signature=kU56Yb6AoJGcolEwAfvDNQ80X48%3D"
    },
    {
      "callType": "follow_up",
      "jobId": "1770463373513-4403-bf04-c3874e76dc45",
      "conversations": "[{\"timestamp\": 1770463384000, \"speaker\": \"Contact\", \"script\": \"\", \"action\": \"BeginDialogue\"}, {\"timestamp\": 1770463385000, \"speaker\": \"Robot\", \"script\": \"您好！我是您的调解员。请问关于调解协议的执行情况，您需要了解哪方面的信息？例如支付进度或是遇到的问题等。\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770463392000, \"speaker\": \"Contact\", \"script\": null, \"action\": \"EndDialogue\"}]",
      "callStatus": "Succeeded",
      "recordUrl": "http://voicenavigator-cn-shanghai.oss-cn-shanghai.aliyuncs.com/exported_files/4839545695964058a1034c574023076a.wav?Expires=1770549793&OSSAccessKeyId=LTAIHgPej9maicqw&Signature=jQhpnhu7OU7YZYTmkGwApTlDyiA%3D"
    },
    {
      "callType": "follow_up",
      "jobId": "1770463328247-4d9e-9280-9f529c2ddc2e",
      "conversations": "[{\"timestamp\": 1770463341000, \"speaker\": \"Contact\", \"script\": \"\", \"action\": \"BeginDialogue\"}, {\"timestamp\": 1770463343000, \"speaker\": \"Robot\", \"script\": \"您好，我是您的调解员。请问您是刘树杰先生吗？关于您与胡龙光先生之间的调解协议，我需要了解一些执行情况。您可以告诉我目前的进展吗？\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770463344000, \"speaker\": \"Contact\", \"script\": null, \"action\": \"EndDialogue\"}]",
      "callStatus": "Succeeded",
      "recordUrl": "http://voicenavigator-cn-shanghai.oss-cn-shanghai.aliyuncs.com/exported_files/c70a9ead18884893ab75f7fa23a3b2fe.wav?Expires=1770549745&OSSAccessKeyId=LTAIHgPej9maicqw&Signature=oTTdOvz0TxAsybkF762Nd2Tc1b4%3D"
    },
    {
      "callType": "follow_up",
      "jobId": "1770463016662-4d90-ab26-a10656d79a73",
      "conversations": "[{\"timestamp\": 1770463027000, \"speaker\": \"Contact\", \"script\": \"\", \"action\": \"BeginDialogue\"}, {\"timestamp\": 1770463029000, \"speaker\": \"Robot\", \"script\": \"您好，刘树杰先生，请问您有关于调解协议执行情况的问题吗？需要我帮忙确认什么信息？\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770463029000, \"speaker\": \"Contact\", \"script\": null, \"action\": \"EndDialogue\"}]",
      "callStatus": "Succeeded",
      "recordUrl": "http://voicenavigator-cn-shanghai.oss-cn-shanghai.aliyuncs.com/exported_files/4630b437e9604e308a538a6fd7ae7b07.wav?Expires=1770549430&OSSAccessKeyId=LTAIHgPej9maicqw&Signature=Hom7YsvUoYUtl5lNpJZ1WBuOTbc%3D"
    },
    {
      "callType": "agreement",
      "jobId": "1770443034230-469e-a0f0-ea0aa3ab6bea",
      "conversations": "[{\"timestamp\": 1770443048000, \"speaker\": \"Contact\", \"script\": \"\", \"action\": \"BeginDialogue\"}, {\"timestamp\": 1770443050000, \"speaker\": \"Robot\", \"script\": \"您好，刘树杰女士。经过前期沟通，您与胡龙光先生已就3742元工资支付达成初步共识。以下是调解协议草案的主要内容：\\n\\n1. **分期支付**：6月26日前支付1500元，7月26日前支付1500元，8月26日前支付742元。\\n2. **支付方式**：通过微信转账至您的微信号liusujie7879。\\n3. **协议效力**：本协议将申请司法确认，具有法律强制力。\\n\\n请您仔细审阅以上内容，确认是否同意此方案？如有任何修改意见，请及时提出。谢谢。\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770443064000, \"speaker\": \"Contact\", \"script\": null, \"action\": \"EndDialogue\"}]",
      "callStatus": "Succeeded",
      "recordUrl": "http://voicenavigator-cn-shanghai.oss-cn-shanghai.aliyuncs.com/exported_files/45f8967ff20d4c8aa4f514bdb3e80945.wav?Expires=1770529466&OSSAccessKeyId=LTAIHgPej9maicqw&Signature=phWs9VrnkMf9lM1xKJzu9G6thsI%3D"
    },
    {
      "callType": "follow_up",
      "jobId": "1770434323240-43e9-9322-c3ee9a5432e6",
      "conversations": "[{\"timestamp\": 1770434333000, \"speaker\": \"Contact\", \"script\": \"\", \"action\": \"BeginDialogue\"}, {\"timestamp\": 1770434335000, \"speaker\": \"Robot\", \"script\": \"您好！我是您的调解员。请问您是刘树杰先生吗？关于您与胡龙光先生之间的调解协议履行情况，我需要进行回访。根据协议，胡龙光先生应在2025年10月31日前一次性支付给您3742元工资。请问您是否已经收到了这笔款项？如果还没有收到，我们将帮助您跟进此事。如果有任何问题或需要进一步的帮助，请随时告诉我。\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770434341000, \"speaker\": \"Contact\", \"script\": \"我是我是。\", \"action\": \"Dialogue\"}, {\"timestamp\": 1770434342000, \"speaker\": \"Robot\", \"script\": \"刘树杰先生，感谢您的确认。根据我们之前的调解协议，胡龙光先生应在2025年10月31日前一次性支付给您3742元工资。请问您是否已经收到了这笔款项？如果已收到，请确认金额是否准确；如果没有收到，我们将协助您跟进此事。请您告知具体情况，以便我们能够提供相应的帮助。\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770434348000, \"speaker\": \"Contact\", \"script\": null, \"action\": \"EndDialogue\"}]",
      "callStatus": "Succeeded",
      "recordUrl": "http://voicenavigator-cn-shanghai.oss-cn-shanghai.aliyuncs.com/exported_files/69599600af11482fb693e9e040394d2c.wav?Expires=1770520749&OSSAccessKeyId=LTAIHgPej9maicqw&Signature=00KtVr%2BIszHq1wW5gRwWJQlyGhc%3D"
    },
    {
      "callType": "follow_up",
      "jobId": "1770430061262-4918-88b2-5f24100726d7",
      "conversations": "[{\"timestamp\": 1770430070000, \"speaker\": \"Contact\", \"script\": \"\", \"action\": \"BeginDialogue\"}, {\"timestamp\": 1770430071000, \"speaker\": \"Robot\", \"script\": \"您好！我是您的调解员。请问关于您的调解协议有需要确认或跟进的事项吗？特别是关于胡龙光先生应支付的款项，您是否已经收到了相应的金额？如果有任何问题或需要帮助的地方，请随时告诉我。\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770430081000, \"speaker\": \"Contact\", \"script\": \"都搞定了都搞定了。都搞定了。问题。\", \"action\": \"Dialogue\"}, {\"timestamp\": 1770430085000, \"speaker\": \"Robot\", \"script\": \"好的，看起来可能有些重复了。如果问题是关于调解协议的后续事宜或者其他相关问题，请直接说明，我会尽力帮助您。是否有具体的事项需要确认或处理？\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770430091000, \"speaker\": \"Contact\", \"script\": \"都搞定了都搞定了。\", \"action\": \"Dialogue\"}, {\"timestamp\": 1770430092000, \"speaker\": \"Robot\", \"script\": \"非常好，既然一切都已解决，如果您未来有任何其他问题或需要帮助，无论是关于这次调解还是其他事宜，都欢迎随时联系我。祝您生活顺利！如果有新的问题或需要进一步的帮助，请告诉我。\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770430095000, \"speaker\": \"Contact\", \"script\": null, \"action\": \"EndDialogue\"}]",
      "callStatus": "Succeeded",
      "recordUrl": "http://voicenavigator-cn-shanghai.oss-cn-shanghai.aliyuncs.com/exported_files/15f0eb41b36c41fdaeaceedc322c568c.wav?Expires=1770516497&OSSAccessKeyId=LTAIHgPej9maicqw&Signature=ipoBRl%2FtUQCQUSsM6cUogXBVMas%3D"
    },
    {
      "callType": "follow_up",
      "jobId": "1770428492869-4a7c-bd6b-9cb47940c1d4",
      "conversations": "[{\"timestamp\": 1770428515000, \"speaker\": \"Contact\", \"script\": \"\", \"action\": \"BeginDialogue\"}, {\"timestamp\": 1770428520000, \"speaker\": \"Robot\", \"script\": \"您好！我是您的调解员。请问关于您的调解协议有需要确认或跟进的事项吗？特别是关于胡龙光先生应支付的款项，您是否已经收到了相应的金额？如果有任何问题或需要帮助的地方，请随时告诉我。\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770428536000, \"speaker\": \"Contact\", \"script\": \"嗯，调解协议内容有什么呢？\", \"action\": \"Dialogue\"}, {\"timestamp\": 1770428537000, \"speaker\": \"Robot\", \"script\": \"根据我们之前达成的调解协议，主要内容如下：\\n\\n1. **纠纷背景**：您在胡龙光经营的心怡服装厂工作，由于服装厂经营不善，胡龙光拖欠您2025年4月份工资共计人民币3742元。\\n\\n2. **调解结果**：\\n   - 胡龙光同意一次性支付您2025年4月份工资共计人民币3742元。\\n   - 支付方式为转账至您指定的银行账户。\\n   - 履行期限为2025年10月31日前完成支付。\", \"action\": \"Broadcast\"}, {\"timestamp\": 1770428549000, \"speaker\": \"Contact\", \"script\": null, \"action\": \"EndDialogue\"}]",
      "callStatus": "Succeeded",
      "recordUrl": "http://voicenavigator-cn-shanghai.oss-cn-shanghai.aliyuncs.com/exported_files/0e94b3c359fd4366a0b7d380b0477a64.wav?Expires=1770514950&OSSAccessKeyId=LTAIHgPej9maicqw&Signature=oZn8wXu7wit9gs%2F3%2FvE4rJXLF5k%3D"
    }
  ]
}
```

### 返回结果

|状态码|状态码含义|说明|数据模型|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|none|Inline|

### 返回数据结构

状态码 **200**

|名称|类型|必选|约束|中文名|说明|
|---|---|---|---|---|---|
|» code|integer|true|none||none|
|» message|string|true|none||none|
|» data|[object]|true|none||none|
|»» callType|string|true|none|阶段类型|none|
|»» jobId|string|true|none|工作ID|none|
|»» conversations|string|true|none|通话列表|none|
|»» callStatus|string|true|none|通话状态|none|
|»» recordUrl|string|true|none|音频地址|none|

## GET 通话状态查询

GET /api/v1/outbound-bot/status

### 请求参数

|名称|位置|类型|必选|中文名|说明|
|---|---|---|---|---|---|
|caseRef|query|string| 否 ||案件id|
|phoneNumber|query|string| 否 ||电话号码|
|jobId|query|string| 否 ||工作ID|

> 返回示例

> 200 Response

```json
{
  "code": 200,
  "message": "查询成功",
  "data": {
    "caseRef": "202601281644031088",
    "phoneNumber": "13922111489",
    "jobId": "1770616775983-4d49-942b-14fb194e6527",
    "callStatus": "Succeeded",
    "fetchTime": "2026-02-09 14:10:11",
    "jobGroupId": "0a541bee-0d6d-461f-ac84-4de2cd765ea1",
    "instanceId": "4087bb39-7688-4c5b-a4c5-01f7bb98e466"
  }
}
```

### 返回结果

|状态码|状态码含义|说明|数据模型|
|---|---|---|---|
|200|[OK](https://tools.ietf.org/html/rfc7231#section-6.3.1)|none|Inline|

### 返回数据结构

状态码 **200**

|名称|类型|必选|约束|中文名|说明|
|---|---|---|---|---|---|
|» code|integer|true|none||none|
|» message|string|true|none||none|
|» data|object|true|none||none|
|»» caseRef|string|true|none|案件ID|none|
|»» phoneNumber|string|true|none|手机号|none|
|»» jobId|string|true|none|工作ID|none|
|»» callStatus|string|true|none|呼叫状态|none|
|»» fetchTime|string|true|none|更新时间|none|
|»» jobGroupId|string|true|none|工作组ID|none|
|»» instanceId|string|true|none|场景ID|none|

# 数据模型


 openspec/changes/integrate-auto-outbound-call/design.md

New file
@@ -0,0 +1,243 @@
# Design: 智能外呼自动触发与状态监控

## Context

当前"云小调"系统已实现首页案件数据加载和右下角智能外呼气泡组件，但外呼流程需要手动触发，缺少自动化能力。根据产品需求，调解流程应在案件数据加载完成后自动启动 AI 智能外呼，提升调解效率。

**核心挑战**：
1. 何时触发外呼？如何避免重复触发？
2. 如何处理多人外呼场景（申请人、被申请人）？
3. 如何管理 jobId 状态和生命周期？
4. 如何设计轮询策略平衡实时性与服务器压力？
5. 如何处理页面刷新、组件卸载等边界场景？

**技术栈约束**：
- React + Ant Design 4.24.12
- Context API 管理全局状态
- localStorage 持久化存储
- 前端 Mock 数据（当前阶段）

## Goals / Non-Goals

### Goals
1. **自动触发**：案件数据加载完成后自动发起外呼，无需手动操作
2. **状态监控**：实时展示外呼状态（拨号中、通话中、已完成等）
3. **多任务支持**：同时展示多人通话状态
4. **幂等性保证**：页面刷新时不重复发起外呼，继续监听现有任务
5. **自动清理**：通话结束后自动移除气泡和存储数据
6. **错误容错**：API 失败时提供友好提示，不阻塞主流程

### Non-Goals
- 不涉及后端外呼接口实现
- 不涉及通话录音播放功能
- 不涉及外呼任务的手动取消或重试操作
- 不涉及复杂的权限控制（当前仅前端功能）

## Decisions

### Decision 1: 触发时机选择 - 在 `loadCaseData` 后触发

**方案对比**：

| 方案 | 优点 | 缺点 | 决策 |
|------|------|------|------|
| A. 在 `CaseDataContext` 中触发 | 集中管理数据流，逻辑清晰 | 增加 Context 耦合度 | ✅ 采用 |
| B. 在 `OutboundCallWidget` 组件内触发 | 解耦数据和外呼逻辑 | 依赖组件挂载时机，可能触发延迟 | ❌ 不采用 |
| C. 在 App.js 路由层触发 | 全局控制 | 难以获取案件数据，需要额外传递 | ❌ 不采用 |

**选择 A 的理由**：
- `loadCaseData` 是唯一的数据入口，在此处触发可确保数据就绪
- 避免组件挂载时机不确定导致的触发延迟
- 便于实现幂等性检查（基于 localStorage 判断是否已有活跃任务）

### Decision 2: jobId 状态管理 - localStorage + 活跃状态过滤

**数据结构设计**：
```javascript
// localStorage key: 'outbound_call_jobs'
[
  {
    jobId: "1770602736933-4794-83bb-e2cec968ebfc",
    callStatus: "Scheduling", // 或 Executing, Paused, Drafted, Succeeded, Failed, Cancelled
    personId: "2303191513081131",
    mediationId: 20,
    startTime: 1738228800000, // 触发时间戳
    retryCount: 0, // 重试次数
    pollStartTime: 1738228800000 // 轮询开始时间（用于2小时超时检测）
  }
]
```

**状态分类**：
- **活跃状态**（需轮询）：`Scheduling`, `Executing`, `Paused`, `Drafted`
- **终态**（需清除）：`Succeeded`, `Failed`, `Cancelled`

**方案对比**：

| 方案 | 优点 | 缺点 | 决策 |
|------|------|------|------|
| A. localStorage 持久化 | 页面刷新后状态不丢失，支持断点续传 | 需要手动清理终态数据 | ✅ 采用 |
| B. Context 内存存储 | 简单，自动清理 | 页面刷新后丢失，无法继续监听 | ❌ 不采用 |
| C. IndexedDB 存储 | 支持复杂查询 | 过度设计，增加复杂度 | ❌ 不采用 |

**选择 A 的理由**：
- 用户刷新页面后可继续监听外呼状态，提升体验
- 终态清理逻辑简单，可在轮询中实现

### Decision 3: 轮询策略 - 10秒间隔 + 2小时超时 + 10次重试

**参数配置**：
```javascript
const POLL_INTERVAL = 10000; // 10秒
const MAX_POLL_DURATION = 7200000; // 2小时（毫秒）
const MAX_RETRY_COUNT = 10; // 最大重试次数
```

**方案对比**：

| 方案 | 轮询间隔 | 服务器压力 | 实时性 | 决策 |
|------|----------|-----------|--------|------|
| A. 5秒间隔 | 5s | 较高 | 高 | ❌ 压力过大 |
| B. 10秒间隔 | 10s | 中等 | 较高 | ✅ 采用 |
| C. 30秒间隔 | 30s | 低 | 低 | ❌ 延迟过高 |

**选择 B 的理由**：
- 10秒间隔在实时性和服务器压力之间取得平衡
- 对于电话外呼场景，10秒延迟可接受（通话时长通常数分钟）

**超时设计**：
- 2小时后自动停止轮询，避免无限轮询
- 超时后从 localStorage 移除 jobId，防止脏数据累积

**重试机制**：
- 单次查询失败累加 `retryCount`，不立即清除 jobId
- 连续失败 10 次后展示错误提示并清除该 jobId
- 避免因偶发网络抖动导致任务丢失

### Decision 4: 多任务展示 - 纵向堆叠气泡

**UI 设计**：
```
┌─────────────────────────┐
│ 智能体工作中             │
│ 正在与申请人(张三)通话... │
│ 已持续: 02:35           │
└─────────────────────────┘
┌─────────────────────────┐
│ 智能体工作中             │
│ 正在与被申请人(李四)通话...│
│ 已持续: 01:20           │
└─────────────────────────┘
```

**方案对比**：

| 方案 | 优点 | 缺点 | 决策 |
|------|------|------|------|
| A. 纵向堆叠多个气泡 | 清晰展示每个任务，易扩展 | 占用屏幕空间 | ✅ 采用 |
| B. 单个气泡轮播展示 | 节省空间 | 用户难以同时了解所有任务 | ❌ 不采用 |
| C. 折叠列表 | 灵活 | 增加交互复杂度 | ❌ 不采用 |

**选择 A 的理由**：
- 外呼任务数量有限（通常 1-2 个），堆叠不会占用过多空间
- 直观展示每个任务状态，符合用户心智模型

### Decision 5: 幂等性设计 - 基于活跃 jobId 判断

**触发条件**：
```javascript
// 伪代码
const activeJobs = getActiveJobsFromStorage(); // 从 localStorage 获取活跃任务
if (activeJobs.length > 0) {
  console.log('已有活跃外呼任务，跳过发起新外呼');
  return;
}
// 否则，发起新外呼
await OutboundBotAPIService.makeCallV2(...);
```

**边界场景处理**：
1. **首次进入页面**：无活跃 jobId，发起新外呼
2. **刷新页面**：检测到活跃 jobId，继续监听，不发起新外呼
3. **通话结束后再次刷新**：jobId 已清除，可发起新外呼
4. **多标签页同时打开**：共享 localStorage，避免重复触发

## Risks / Trade-offs

### Risk 1: 轮询频率与服务器压力

**风险描述**：多个用户同时轮询可能增加服务器负载。

**缓解措施**：
- 采用 10 秒轮询间隔（非 5 秒或更短）
- 设置 2 小时最大轮询时长，避免无限轮询
- 终态任务立即停止轮询，减少无效请求

**Trade-off**：牺牲部分实时性（10秒延迟）换取服务器稳定性。

### Risk 2: localStorage 容量限制

**风险描述**：jobId 数据累积可能超出 localStorage 容量（5MB）。

**缓解措施**：
- 终态任务立即清除
- 定期清理超过 24 小时的历史数据（后续扩展）
- 单个 jobId 对象约 200 字节，可存储数千条记录

**Trade-off**：当前风险较低，暂不引入复杂的存储淘汰策略。

### Risk 3: 页面刷新时的竞态条件

**风险描述**：用户快速刷新页面可能触发多次 `makeCallV2` 调用。

**缓解措施**：
- 在 `CaseDataContext` 中使用 `hasLoaded` 标志防止重复加载
- `makeCallV2` 调用前检查活跃 jobId，确保幂等性
- 后端接口应支持幂等性设计（基于 caseId + mediationId 去重）

**Trade-off**：前后端协同保障，前端尽最大努力避免重复调用。

### Risk 4: 组件卸载时的内存泄漏

**风险描述**：定时器未清理可能导致内存泄漏或组件卸载后仍执行回调。

**缓解措施**：
- 在 `useEffect` 返回清理函数：`return () => clearInterval(intervalId)`
- 使用 `useRef` 保存 `isMounted` 状态，回调中检查组件是否已卸载
- 考虑使用 `AbortController` 取消未完成的 API 请求

**Trade-off**：增加代码复杂度，但避免生产环境内存泄漏和控制台报错。

## Migration Plan

### Phase 1: 实现基础功能（当前提案）
1. 在 `CaseDataContext` 中添加外呼触发逻辑
2. 改造 `OutboundCallWidget` 轮询逻辑
3. 实现 localStorage 状态管理
4. 完成错误处理和重试机制

### Phase 2: 优化与扩展（后续迭代）
1. 支持手动取消外呼任务
2. 外呼结果通知（成功/失败弹窗）
3. 外呼历史记录查询
4. 集成通话录音播放功能

### Rollback Plan
如发现严重问题，可通过以下步骤回滚：
1. 注释 `CaseDataContext` 中外呼触发代码
2. 恢复 `OutboundCallWidget` 原有轮询逻辑
3. 清除 localStorage 中 `outbound_call_jobs` 数据

## Open Questions

1. **多标签页同步问题**：如何在多个标签页之间同步 jobId 状态？
   - **初步方案**：使用 `window.addEventListener('storage', ...)` 监听 localStorage 变化
   
2. **外呼失败后是否自动重试**：当前设计为不自动重试，是否需要调整？
   - **决策点**：需产品确认，当前保持简单设计
   
3. **通话时长计算逻辑**：API 返回的 `startTime` 字段格式是否统一？
   - **待确认**：API 文档中未明确说明，需要与后端对齐

4. **外呼任务优先级**：如果同时有多个案件，如何决定外呼顺序？
   - **当前方案**：按 API 响应顺序依次展示，不涉及优先级排序

 openspec/changes/integrate-auto-outbound-call/proposal.md

New file
@@ -0,0 +1,43 @@
# Change: 智能外呼自动触发与状态监控

## Why

当前首页加载案件数据后，无法自动触发AI智能外呼功能，调解员需要手动操作才能启动外呼流程。为提升调解效率和自动化水平，需要实现：
1. 案件数据加载完成后自动发起智能外呼
2. 实时监控并展示外呼状态和进度
3. 支持多人同时外呼的场景

## What Changes

- **CaseDataContext.jsx**: 在 `loadCaseData` 方法返回 `timelineData` 后，调用 `OutboundBotAPIService.makeCallV2` 发起外呼
- **OutboundCallWidget.jsx**: 改造现有轮询逻辑，基于 jobId 查询通话状态，支持多任务展示和生命周期管理
- **localStorage 管理**: 新增 jobId 状态持久化存储，区分活跃任务（Scheduling/Executing/Paused/Drafted）与终态任务（Succeeded/Failed/Cancelled）
- **轮询策略**: 采用 10 秒轮询间隔，最大轮询时长 2 小时，失败重试 10 次
- **错误处理**: `makeCallV2` 失败时展示错误提示并记录日志，`getCallStatus` 失败时支持重试机制

## Impact

- **Affected specs**: outbound-call-auto-trigger（新建）
- **Affected code**: 
  - `web-app/src/contexts/CaseDataContext.jsx` (141行后新增外呼触发逻辑)
  - `web-app/src/components/common/OutboundCallWidget.jsx` (重构轮询逻辑)
  - `web-app/src/services/OutboundBotAPIService.js` (已有API方法，无需修改)
- **Dependencies**: 依赖 API 文档中定义的外呼机器人接口
- **Breaking Changes**: 无

## User Experience

1. **用户进入首页** → 页面自动加载案件数据
2. **数据加载完成** → 系统自动发起外呼（无需手动操作）
3. **右下角气泡弹出** → 展示"正在与XX电话沟通中..."
4. **实时更新状态** → 每10秒刷新通话状态和时长
5. **通话结束** → 气泡自动消失，jobId 从存储中清除

## Technical Notes

- **jobId 来源**: 从 `timelineData` 中提取 `id`（mediationId）和 `case_id`（caseId）作为外呼请求参数，响应返回 jobId 数组
- **状态映射**: 
  - 活跃状态: `Scheduling`, `Executing`, `Paused`, `Drafted`
  - 终态状态: `Succeeded`, `Failed`, `Cancelled`
- **多任务支持**: 单次外呼可能生成多个 jobId（申请人、被申请人），需循环展示
- **轮询限制**: 最大轮询时长 2 小时（7200秒），超时后自动停止并清理

 openspec/changes/integrate-auto-outbound-call/specs/outbound-call-auto-trigger/spec.md

New file
@@ -0,0 +1,203 @@
## ADDED Requirements

### Requirement: 智能外呼自动触发

系统在首页加载案件数据完成后，SHALL 自动发起 AI 智能外呼，无需用户手动操作。外呼请求应基于案件数据（mediationId、caseId）构建，并确保幂等性（页面刷新时不重复触发）。

#### Scenario: 首次进入首页自动触发外呼

- **GIVEN** 用户首次进入首页，localStorage 中无活跃外呼任务
- **WHEN** `CaseDataContext.loadCaseData()` 完成并返回 `timelineData`
- **THEN** 系统自动调用 `OutboundBotAPIService.makeCallV2({ mediationId, caseId, callAuto: 0, callPersonId: null })`
- **AND** 成功响应后，从 `response.data` 中提取所有 `errorCode === 0` 的记录
- **AND** 将每条记录的 `jobId`、`callStatus`、`personId`、`mediationId` 存储到 localStorage（键名：`outbound_call_jobs`）
- **AND** 右下角智能外呼气泡组件自动弹出，展示"正在与XX电话沟通中..."

#### Scenario: 页面刷新时检测活跃任务

- **GIVEN** localStorage 中存在活跃状态的外呼任务（`callStatus` 为 `Scheduling`、`Executing`、`Paused` 或 `Drafted`）
- **WHEN** 用户刷新页面，`CaseDataContext.loadCaseData()` 执行
- **THEN** 系统检测到活跃任务，跳过发起新外呼
- **AND** 继续轮询查询现有任务的通话状态
- **AND** 右下角气泡组件根据 localStorage 中的 jobId 恢复显示

#### Scenario: 外呼发起失败处理

- **GIVEN** 用户进入首页，数据加载完成
- **WHEN** 调用 `makeCallV2` 失败（如网络错误、API 返回 500）
- **THEN** 系统展示 Ant Design 错误提示：`message.error('发起外呼失败，请稍后重试')`
- **AND** 在浏览器控制台输出详细错误日志：`console.error('makeCallV2 failed:', err)`
- **AND** 不阻塞页面其他功能，用户可正常使用首页

#### Scenario: API 返回部分成功记录

- **GIVEN** `makeCallV2` 响应包含多条记录，其中部分 `errorCode === 0`（成功），部分 `errorCode !== 0`（失败）
- **WHEN** 系统解析响应数据
- **THEN** 仅提取并存储 `errorCode === 0` 的记录到 localStorage
- **AND** 对于失败记录（如"外呼次数已达上限"），在控制台输出警告日志
- **AND** 右下角气泡仅展示成功发起的外呼任务

---

### Requirement: 外呼状态实时监控

系统 SHALL 对活跃外呼任务进行定时轮询，查询通话状态并实时更新右下角气泡组件显示。轮询策略应平衡实时性与服务器压力，采用 10 秒间隔、最大 2 小时轮询时长、失败重试 10 次的机制。

#### Scenario: 定时轮询查询通话状态

- **GIVEN** localStorage 中存在活跃状态的 jobId（`callStatus` 为 `Scheduling`、`Executing`、`Paused` 或 `Drafted`）
- **WHEN** `OutboundCallWidget` 组件挂载后启动轮询定时器（间隔 10 秒）
- **THEN** 遍历所有活跃 jobId，调用 `OutboundBotAPIService.getCallStatus({ jobId })`
- **AND** 解析每个响应的 `callStatus`，更新组件内部 `calls` 状态数组
- **AND** 气泡组件实时显示通话人姓名、通话状态（中文）、通话时长（格式：MM:SS）

#### Scenario: 检测终态状态并停止轮询

- **GIVEN** 轮询过程中某个 jobId 的 `callStatus` 变为 `Succeeded`（成功）
- **WHEN** 系统检测到终态状态
- **THEN** 立即从 localStorage 的 `outbound_call_jobs` 中移除该 jobId
- **AND** 更新 `calls` 状态数组，移除对应记录
- **AND** 如果所有 jobId 均为终态，右下角气泡自动隐藏（`isVisible=false`）
- **AND** 停止该 jobId 的后续轮询

#### Scenario: 轮询超时自动停止

- **GIVEN** 某个 jobId 的轮询已持续 2 小时（从 `pollStartTime` 开始计时）
- **WHEN** 系统检测到轮询时长超过 7200 秒
- **THEN** 自动停止该 jobId 的轮询，从 localStorage 中移除
- **AND** 在控制台输出警告日志：`console.warn('轮询超时，jobId: xxx')`
- **AND** 不展示错误提示，避免打扰用户

#### Scenario: 单次查询失败重试机制

- **GIVEN** 调用 `getCallStatus` 失败（如网络抖动、API 返回 500）
- **WHEN** 系统检测到单次查询失败
- **THEN** 累加该 jobId 的 `retryCount` 计数器
- **AND** 保留该 jobId 在 localStorage 中，下次轮询继续重试
- **AND** 在控制台输出日志：`console.warn('查询失败，重试次数: X/10, jobId: xxx')`

#### Scenario: 连续失败 10 次后移除任务

- **GIVEN** 某个 jobId 的 `retryCount` 已达到 10
- **WHEN** 第 10 次查询失败
- **THEN** 展示 Ant Design 错误提示：`message.error('获取通话状态失败，请检查网络连接')`
- **AND** 从 localStorage 中移除该 jobId
- **AND** 在控制台输出错误日志：`console.error('重试次数超限，jobId: xxx')`
- **AND** 更新气泡组件，移除该任务显示

---

### Requirement: 多任务并行支持

系统 SHALL 支持同时展示多个外呼任务的状态（如申请人、被申请人同时外呼），气泡组件采用纵向堆叠布局，每个任务独立显示通话人和状态信息。

#### Scenario: 同时展示多个外呼任务

- **GIVEN** `makeCallV2` 响应返回 2 条成功记录（2 个 jobId）
- **WHEN** 系统存储到 localStorage 并启动轮询
- **THEN** 右下角气泡组件纵向堆叠展示 2 个气泡
- **AND** 每个气泡独立显示：通话人姓名、通话状态、通话时长
- **AND** 第一个气泡位于下方，第二个气泡位于上方（堆叠顺序）

#### Scenario: 单个任务结束后部分气泡消失

- **GIVEN** 存在 2 个活跃外呼任务
- **WHEN** 其中 1 个任务状态变为 `Succeeded`（成功）
- **THEN** 对应气泡立即消失
- **AND** 另一个任务的气泡继续显示并轮询
- **AND** localStorage 中仅保留 1 个活跃 jobId

#### Scenario: 所有任务结束后气泡完全隐藏

- **GIVEN** 所有外呼任务均已结束（`callStatus` 为 `Succeeded`、`Failed` 或 `Cancelled`）
- **WHEN** 系统检测到 localStorage 中无活跃 jobId
- **THEN** 右下角气泡完全隐藏（包括最小化的 AI 客服图标）
- **AND** 停止轮询定时器

---

### Requirement: 组件生命周期管理

系统 SHALL 在组件卸载或用户离开页面时正确清理定时器和资源，避免内存泄漏和控制台报错。

#### Scenario: 组件卸载时清理定时器

- **GIVEN** `OutboundCallWidget` 组件已挂载并启动轮询定时器
- **WHEN** 用户导航到其他页面，组件卸载
- **THEN** 在 `useEffect` 的清理函数中调用 `clearInterval(intervalId)`
- **AND** 停止所有正在进行的轮询
- **AND** 不抛出任何错误或警告到控制台

#### Scenario: 路由切换时保留 localStorage 状态

- **GIVEN** 用户在首页查看外呼气泡，然后切换到其他页面
- **WHEN** `OutboundCallWidget` 组件卸载
- **THEN** localStorage 中的 `outbound_call_jobs` 数据保持不变
- **AND** 用户返回首页时，组件重新挂载并从 localStorage 恢复状态
- **AND** 继续轮询之前的活跃任务

#### Scenario: 避免组件卸载后的异步回调执行

- **GIVEN** 组件发起了 `getCallStatus` 异步请求
- **WHEN** 请求尚未返回时，组件被卸载
- **THEN** 使用 `useRef` 记录 `isMounted` 状态
- **AND** 异步回调中检查 `isMounted`，如果组件已卸载则不执行状态更新
- **AND** 不抛出"Can't perform a React state update on an unmounted component"警告

---

### Requirement: 通话状态中文映射

系统 SHALL 将 API 返回的英文通话状态映射为中文，便于用户理解当前外呼进度。

#### Scenario: 状态中文映射规则

- **GIVEN** API 返回的 `callStatus` 为英文值
- **WHEN** 气泡组件渲染通话状态
- **THEN** 按照以下规则显示中文：
  - `Scheduling` → "拨号中"
  - `Executing` → "通话中"
  - `Paused` → "已暂停"
  - `Drafted` → "草稿"
  - `Succeeded` → "已完成"
  - `Failed` → "失败"
  - `Cancelled` → "已取消"
- **AND** 未知状态显示原始值

#### Scenario: 通话时长计算

- **GIVEN** API 响应包含 `startTime` 字段（时间戳或 ISO 格式字符串）
- **WHEN** 气泡组件显示通话时长
- **THEN** 计算当前时间与 `startTime` 的差值（秒）
- **AND** 格式化为"MM:SS"格式（如"02:35"表示 2 分 35 秒）
- **AND** 每次轮询更新时重新计算并刷新显示

---

### Requirement: 错误提示与日志记录

系统 SHALL 在关键操作失败时提供友好的错误提示，并在浏览器控制台输出详细日志，便于开发调试。

#### Scenario: makeCallV2 失败提示

- **GIVEN** 调用 `makeCallV2` 失败（如网络错误、API 返回 500）
- **WHEN** 捕获到异常
- **THEN** 展示 Ant Design 错误提示：`message.error('发起外呼失败，请稍后重试')`
- **AND** 在控制台输出错误日志：`console.error('makeCallV2 failed:', err)`

#### Scenario: getCallStatus 重试超限提示

- **GIVEN** 某个 jobId 的查询连续失败 10 次
- **WHEN** 第 10 次失败后
- **THEN** 展示 Ant Design 错误提示：`message.error('获取通话状态失败，请检查网络连接')`
- **AND** 在控制台输出错误日志：`console.error('重试次数超限，jobId: xxx')`

#### Scenario: 关键步骤日志记录

- **GIVEN** 系统执行外呼触发、轮询、状态更新等关键步骤
- **WHEN** 每个步骤完成
- **THEN** 在控制台输出相应日志：
  - `console.log('发起外呼，mediationId: X, caseId: Y')`
  - `console.log('存储 jobId: X, callStatus: Y')`
  - `console.log('轮询查询 jobId: X')`
  - `console.log('检测到终态，移除 jobId: X')`

 openspec/changes/integrate-auto-outbound-call/tasks.md

New file
@@ -0,0 +1,66 @@
# Implementation Tasks

## 1. 数据存储与状态管理
- [ ] 1.1 创建 localStorage 键 `outbound_call_jobs` 用于存储 jobId 数组和状态
- [ ] 1.2 实现 jobId 数据结构设计：`{ jobId, callStatus, startTime, personId, mediationId }`
- [ ] 1.3 实现状态过滤逻辑：活跃状态保留，终态清除

## 2. CaseDataContext 外呼触发逻辑
- [ ] 2.1 在 `loadCaseData` 方法的第 141 行 `saveToStorage(timelineData)` 之后添加外呼触发调用
- [ ] 2.2 检查 localStorage 中是否有活跃的 jobId，如有则跳过发起新外呼
- [ ] 2.3 提取 `mediationId`（timelineData.id）和 `caseId`（timelineData.case_id）构建请求参数
- [ ] 2.4 调用 `OutboundBotAPIService.makeCallV2({ mediationId, caseId, callAuto: 0, callPersonId: null })`
- [ ] 2.5 处理 `makeCallV2` 响应：
  - [ ] 2.5.1 解析 `response.data` 数组，提取所有 `errorCode === 0` 的记录
  - [ ] 2.5.2 存储 jobId、callStatus、personId 等信息到 localStorage
  - [ ] 2.5.3 失败时（errorCode !== 0）展示 `message.error()` 并记录控制台日志
- [ ] 2.6 错误捕获：`makeCallV2` 调用失败时展示友好提示，不阻塞页面加载

## 3. OutboundCallWidget 轮询改造
- [ ] 3.1 移除现有 `getCallStatus` 基于 `caseRef` 的轮询逻辑
- [ ] 3.2 从 localStorage 读取 `outbound_call_jobs`，过滤活跃状态的 jobId
- [ ] 3.3 实现新的轮询逻辑：
  - [ ] 3.3.1 遍历所有活跃 jobId，调用 `OutboundBotAPIService.getCallStatus({ jobId })`
  - [ ] 3.3.2 更新 `calls` 状态数组，展示通话人和状态信息
  - [ ] 3.3.3 检测终态状态（Succeeded/Failed/Cancelled），从 localStorage 移除对应 jobId
- [ ] 3.4 设置轮询间隔为 10 秒（`setInterval(fetchCallStatus, 10000)`）
- [ ] 3.5 实现最大轮询时长限制（2小时）：
  - [ ] 3.5.1 记录轮询开始时间
  - [ ] 3.5.2 每次轮询检查是否超时，超时则停止轮询并清理 jobId
- [ ] 3.6 实现失败重试机制：
  - [ ] 3.6.1 为每个 jobId 维护重试计数器
  - [ ] 3.6.2 单次查询失败时累加计数，最多重试 10 次
  - [ ] 3.6.3 超过 10 次失败后展示 `message.error()` 并移除该 jobId

## 4. 气泡组件显示优化
- [ ] 4.1 支持多任务显示：当 `calls.length > 1` 时，纵向堆叠展示多个气泡
- [ ] 4.2 显示字段映射：
  - [ ] 4.2.1 通话人姓名：从 API 响应的 `personId` 或 Mock 数据获取
  - [ ] 4.2.2 通话状态：中文映射（Scheduling→拨号中，Executing→通话中等）
  - [ ] 4.2.3 通话时长：根据 `startTime` 和当前时间计算（格式：MM:SS）
- [ ] 4.3 终态处理：当所有 jobId 均为终态时，自动隐藏气泡（设置 `isVisible=false`）

## 5. 组件卸载与清理
- [ ] 5.1 在 `OutboundCallWidget` 的 `useEffect` 清理函数中停止轮询定时器
- [ ] 5.2 用户离开页面时（如路由切换），确保定时器被清除
- [ ] 5.3 避免内存泄漏：组件卸载时取消所有待处理的 API 请求（如使用 AbortController）

## 6. 错误提示与日志
- [ ] 6.1 `makeCallV2` 失败时：`message.error('发起外呼失败，请稍后重试')` + `console.error(err)`
- [ ] 6.2 `getCallStatus` 重试超限时：`message.error('获取通话状态失败，请检查网络连接')` + `console.error()`
- [ ] 6.3 所有关键步骤记录 `console.log`，便于前端调试

## 7. 测试与验证
- [ ] 7.1 测试场景1：首次进入首页，自动发起外呼，气泡正常弹出
- [ ] 7.2 测试场景2：刷新页面，检测到活跃 jobId，继续监听不发起新外呼
- [ ] 7.3 测试场景3：多人外呼（2个jobId），气泡同时展示两条记录
- [ ] 7.4 测试场景4：通话成功（Succeeded），气泡消失，jobId 清除
- [ ] 7.5 测试场景5：通话失败（Failed），展示错误提示，jobId 清除
- [ ] 7.6 测试场景6：API 连续失败 10 次，展示重试超限提示
- [ ] 7.7 测试场景7：轮询超过 2 小时，自动停止并清理
- [ ] 7.8 测试场景8：组件卸载时定时器正常清除，无报错

## 9. 文档与注释
- [ ] 9.1 为新增代码添加 JSDoc 注释
- [ ] 9.2 更新 `OutboundCallWidget.jsx` 头部组件说明
- [ ] 9.3 在关键逻辑处添加行内注释（jobId 状态判断、轮询逻辑等）

 web-app/src/App.js

@@ -14,6 +14,7 @@

// 弹窗组件
import ToolModal from './components/common/ToolModal';
import OutboundCallWidget from './components/common/OutboundCallWidget';

// 工具内容组件
import WageCalculatorContent from './components/tools/WageCalculatorContent';
@@ -112,6 +113,9 @@
            {renderModalContent()}
          </ToolModal>
        )}

        {/* 智能外呼通话显示组件 - 全局显示 */}
        <OutboundCallWidget />
      </div>
    </Spin>
  );

 web-app/src/components/common/OutboundCallWidget.jsx

New file
@@ -0,0 +1,474 @@
import React, { useState, useEffect, useCallback, useRef } from 'react';
import { message } from 'antd';
import OutboundBotAPIService from '../../services/OutboundBotAPIService';

// 常量配置
const OUTBOUND_JOBS_KEY = 'outbound_call_jobs';
const POLL_INTERVAL = 10000; // 10秒轮询间隔
const MAX_POLL_DURATION = 7200000; // 2小时最大轮询时长（毫秒）
const MAX_RETRY_COUNT = 10; // 最大重试次数

// 活跃状态和终态定义
const ACTIVE_STATUSES = ['Scheduling', 'Executing', 'Paused', 'Drafted'];
const TERMINAL_STATUSES = ['Succeeded', 'Failed', 'Cancelled'];

// 状态中文映射
const STATUS_MAP = {
  'Scheduling': '拨号中',
  'Executing': '通话中',
  'Succeeded': '通话成功',
  'Paused': '暂停',
  'Failed': '通话失败',
  'Cancelled': '通话已取消',
  'Drafted': '草稿'
};

/**
 * 智能外呼通话显示组件
 * 基于 localStorage 中的 jobId 轮询查询通话状态
 * 支持多任务并行显示、自动清理终态任务
 */
const OutboundCallWidget = () => {
  const [isVisible, setIsVisible] = useState(true);
  const [isMinimized, setIsMinimized] = useState(false);
  const [calls, setCalls] = useState([]);
  const isMountedRef = useRef(true);

  /**
   * 格式化通话时长
   * @param {number} startTime - 开始时间戳（毫秒）
   * @returns {string} 格式化的时长（MM:SS）
   */
  const formatDuration = (startTime) => {
    if (!startTime) return '00:00';
    const seconds = Math.floor((Date.now() - startTime) / 1000);
    const mins = Math.floor(seconds / 60);
    const secs = seconds % 60;
    return `${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
  };

  /**
   * 从 localStorage 读取外呼任务
   * @returns {Array} 任务数组
   */
  const loadJobsFromStorage = () => {
    try {
      const stored = localStorage.getItem(OUTBOUND_JOBS_KEY);
      if (!stored) return [];
      return JSON.parse(stored);
    } catch (err) {
      console.error('读取外呼任务失败:', err);
      return [];
    }
  };

  /**
   * 保存任务到 localStorage
   * @param {Array} jobs - 任务数组
   */
  const saveJobsToStorage = (jobs) => {
    try {
      if (jobs.length === 0) {
        localStorage.removeItem(OUTBOUND_JOBS_KEY);
      } else {
        localStorage.setItem(OUTBOUND_JOBS_KEY, JSON.stringify(jobs));
      }
    } catch (err) {
      console.error('保存外呼任务失败:', err);
    }
  };

  /**
   * 移除终态或超时的任务
   * @param {Array} jobs - 当前任务数组
   * @returns {Array} 清理后的任务数组
   */
  const cleanupJobs = (jobs) => {
    const now = Date.now();
    return jobs.filter(job => {
      // 检查是否超时（2小时）
      if (now - job.pollStartTime > MAX_POLL_DURATION) {
        console.warn('外呼轮询超时（2小时），自动停止，jobId:', job.jobId);
        return false;
      }
      // 保留活跃状态
      return ACTIVE_STATUSES.includes(job.callStatus);
    });
  };

  /**
   * 查询通话状态（轮询核心逻辑）
   */
  const fetchCallStatus = useCallback(async () => {
    let jobs = loadJobsFromStorage();
    
    // 过滤出活跃任务
    const activeJobs = jobs.filter(job => ACTIVE_STATUSES.includes(job.callStatus));
    
    if (activeJobs.length === 0) {
      setCalls([]);
      return;
    }

    console.log('轮询查询通话状态，任务数量:', activeJobs.length);

    // 遍历所有活跃任务，逐个查询状态（caseRef 和 jobId 都是必传参数）
    const updatedJobs = await Promise.all(
      activeJobs.map(async (job) => {
        try {
          // 同时传入 caseRef 和 jobId
          const response = await OutboundBotAPIService.getCallStatus({ 
            caseRef: job.caseId,
            jobId: job.jobId 
          });
          
          if (response?.data) {
            const newStatus = response.data.callStatus;
            
            // 更新任务状态
            const updatedJob = {
              ...job,
              callStatus: newStatus,
              retryCount: 0 // 成功后重置重试计数
            };

            // 检测终态
            if (TERMINAL_STATUSES.includes(newStatus)) {
              console.log('检测到终态，jobId:', job.jobId, ', status:', newStatus);
              return null; // 标记为删除
            }

            return updatedJob;
          }
          
          return job;
        } catch (err) {
          console.warn('查询失败，重试次数:', job.retryCount + 1, '/', MAX_RETRY_COUNT, ', jobId:', job.jobId, ', 错误:', err.message);
          
          // 累加重试计数
          const retryCount = job.retryCount + 1;
          
          if (retryCount >= MAX_RETRY_COUNT) {
            console.error('重试次数超限，jobId:', job.jobId);
            message.error('外呼状态查询失败次数过多，已停止监控');
            return null; // 标记为删除
          }
          
          return { ...job, retryCount };
        }
      })
    );

    // 过滤掉标记为删除的任务（null）
    const filteredJobs = updatedJobs.filter(job => job !== null);
    
    // 清理超时任务
    const cleanedJobs = cleanupJobs(filteredJobs);

    // 保存到 localStorage
    saveJobsToStorage(cleanedJobs);

    // 更新组件状态
    if (isMountedRef.current) {
      setCalls(cleanedJobs);
    }
  }, []);

  // 定时轮询通话状态
  useEffect(() => {
    // 初始加载
    fetchCallStatus();
    
    // 设置轮询定时器（10秒间隔）
    const interval = setInterval(fetchCallStatus, POLL_INTERVAL);
    
    // 清理函数
    return () => {
      clearInterval(interval);
      isMountedRef.current = false;
    };
  }, [fetchCallStatus]);

  // 组件挂载时标记
  useEffect(() => {
    isMountedRef.current = true;
    return () => {
      isMountedRef.current = false;
    };
  }, []);

  // 关闭气泡
  const handleClose = (e) => {
    e.stopPropagation();
    setIsVisible(false);
    setIsMinimized(true);
  };

  // 展开气泡
  const handleExpand = () => {
    setIsMinimized(false);
    setIsVisible(true);
  };

  // 如果最小化，显示AI客服图标
  if (isMinimized) {


    return (
      <div
        onClick={handleExpand}
        style={{
          position: 'fixed',
          right: 20,
          bottom: 80,
          width: 56,
          height: 56,
          borderRadius: '50%',
          background: 'linear-gradient(135deg, #1A6FB8 0%, #0d4a8a 100%)',
          display: 'flex',
          alignItems: 'center',
          justifyContent: 'center',
          cursor: 'pointer',
          boxShadow: '0 4px 12px rgba(26, 111, 184, 0.4)',
          zIndex: 1000,
          transition: 'all 0.3s ease',
        }}
        onMouseEnter={(e) => {
          e.currentTarget.style.transform = 'scale(1.1)';
        }}
        onMouseLeave={(e) => {
          e.currentTarget.style.transform = 'scale(1)';
        }}
      >
        <i
          className="fas fa-headset"
          style={{
            fontSize: 24,
            color: 'white',
          }}
        />
        {/* 红点提示有通话 */}
        {calls.length > 0 && (
          <div
            style={{
              position: 'absolute',
              top: -2,
              right: -2,
              width: 16,
              height: 16,
              borderRadius: '50%',
              background: '#ff4d4f',
              display: 'flex',
              alignItems: 'center',
              justifyContent: 'center',
              fontSize: 10,
              color: 'white',
              fontWeight: 'bold',
            }}
          >
            {calls.length}
          </div>
        )}
      </div>
    );
  }

  // 展开状态 - 显示通话气泡
  return (
    <div
      style={{
        position: 'fixed',
        right: 20,
        bottom: 80,
        zIndex: 1000,
        display: 'flex',
        flexDirection: 'column',
        gap: 10,
        maxWidth: 320,
      }}
    >
      {calls.map((call, index) => (
        <div
          key={call.jobId || call.phoneNumber || index}
          style={{
            background: 'linear-gradient(135deg, #1A6FB8 0%, #0d4a8a 100%)',
            borderRadius: 12,
            padding: '16px 20px',
            color: 'white',
            boxShadow: '0 4px 16px rgba(26, 111, 184, 0.3)',
            position: 'relative',
            minWidth: 280,
          }}
        >
          {/* 关闭按钮 */}
          <button
            onClick={handleClose}
            style={{
              position: 'absolute',
              top: 8,
              right: 8,
              width: 24,
              height: 24,
              borderRadius: '50%',
              border: 'none',
              background: 'rgba(255,255,255,0.2)',
              color: 'white',
              cursor: 'pointer',
              display: 'flex',
              alignItems: 'center',
              justifyContent: 'center',
              fontSize: 14,
              transition: 'all 0.2s ease',
            }}
            onMouseEnter={(e) => {
              e.currentTarget.style.background = 'rgba(255,255,255,0.3)';
            }}
            onMouseLeave={(e) => {
              e.currentTarget.style.background = 'rgba(255,255,255,0.2)';
            }}
          >
            <i className="fas fa-times" />
          </button>

          {/* 头部 - 智能体工作中 */}
          <div
            style={{
              display: 'flex',
              alignItems: 'center',
              gap: 10,
              marginBottom: 12,
            }}
          >
            <div
              style={{
                width: 36,
                height: 36,
                borderRadius: '50%',
                background: 'rgba(255,255,255,0.2)',
                display: 'flex',
                alignItems: 'center',
                justifyContent: 'center',
              }}
            >
              <i className="fas fa-robot" style={{ fontSize: 18 }} />
            </div>
            <div style={{ flex: 1 }}>
              <div
                style={{
                  fontSize: 16,
                  fontWeight: 600,
                  display: 'flex',
                  alignItems: 'center',
                  gap: 8,
                }}
              >
                智能体工作中
                <span
                  style={{
                    width: 8,
                    height: 8,
                    borderRadius: '50%',
                    background: '#52c41a',
                    animation: 'pulse 2s infinite',
                  }}
                />
              </div>
            </div>
          </div>

          {/* 通话信息 */}
          <div style={{ marginBottom: 10 }}>
            <div style={{ fontSize: 14, opacity: 0.9, lineHeight: 1.5 }}>
              正在与 {call.personId || '未知联系人'} 电话沟通中...
            </div>
            <div style={{ fontSize: 12, opacity: 0.75, marginTop: 4 }}>
              状态：{STATUS_MAP[call.callStatus] || call.callStatus}
            </div>
          </div>

          {/* 通话时长 */}
          <div
            style={{
              display: 'flex',
              alignItems: 'center',
              gap: 6,
              fontSize: 13,
              opacity: 0.85,
            }}
          >
            <i className="far fa-clock" />
            <span>已持续: {formatDuration(call.startTime)}</span>
          </div>
        </div>
      ))}

      {/* 无通话时的占位提示 */}
      {calls.length === 0 && isVisible && (
        <div
          style={{
            background: 'linear-gradient(135deg, #1A6FB8 0%, #0d4a8a 100%)',
            borderRadius: 12,
            padding: '16px 20px',
            color: 'white',
            boxShadow: '0 4px 16px rgba(26, 111, 184, 0.3)',
            position: 'relative',
            minWidth: 280,
          }}
        >
          {/* 关闭按钮 */}
          <button
            onClick={handleClose}
            style={{
              position: 'absolute',
              top: 8,
              right: 8,
              width: 24,
              height: 24,
              borderRadius: '50%',
              border: 'none',
              background: 'rgba(255,255,255,0.2)',
              color: 'white',
              cursor: 'pointer',
              display: 'flex',
              alignItems: 'center',
              justifyContent: 'center',
              fontSize: 14,
            }}
          >
            <i className="fas fa-times" />
          </button>

          <div style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
            <div
              style={{
                width: 36,
                height: 36,
                borderRadius: '50%',
                background: 'rgba(255,255,255,0.2)',
                display: 'flex',
                alignItems: 'center',
                justifyContent: 'center',
              }}
            >
              <i className="fas fa-robot" style={{ fontSize: 18 }} />
            </div>
            <div>
              <div style={{ fontSize: 16, fontWeight: 600 }}>智能外呼系统</div>
              <div style={{ fontSize: 13, opacity: 0.85 }}>暂无进行中的通话</div>
            </div>
          </div>
        </div>
      )}

      {/* CSS 动画 */}
      <style>{`
        @keyframes pulse {
          0%, 100% { opacity: 1; }
          50% { opacity: 0.5; }
        }
      `}</style>
    </div>
  );
};

export default OutboundCallWidget;

 web-app/src/contexts/CaseDataContext.jsx

@@ -6,6 +6,7 @@
import React, { createContext, useContext, useState, useEffect, useRef } from 'react';
import { message } from 'antd';
import ProcessAPIService from '../services/ProcessAPIService';
import OutboundBotAPIService from '../services/OutboundBotAPIService';
import { getMergedParams } from '../utils/urlParams';
import { mockTimelineData } from '../mocks/timeline';
import { getFallbackStartTime, parseTimeString } from '../utils/timeFormatter';
@@ -15,6 +16,7 @@

// localStorage键名
const STORAGE_KEY = 'case_data_timeline';
const OUTBOUND_JOBS_KEY = 'outbound_call_jobs';

/**
 * CaseDataProvider组件
@@ -30,21 +32,6 @@
  const [hasLoaded, setHasLoaded] = useState(false);  // 防止重复加载

  /**
   * 从localStorage读取数据
   */
  const loadFromStorage = () => {
    try {
      const stored = localStorage.getItem(STORAGE_KEY);
      if (stored) {
        return JSON.parse(stored);
      }
    } catch (err) {
      console.error('Failed to load data from localStorage:', err);
    }
    return null;
  };

  /**
   * 保存数据到localStorage
   */
  const saveToStorage = (data) => {
@@ -52,6 +39,104 @@
      localStorage.setItem(STORAGE_KEY, JSON.stringify(data));
    } catch (err) {
      console.error('Failed to save data to localStorage:', err);
    }
  };

  /**
   * 检查是否有活跃的外呼任务
   * @returns {boolean} 是否有活跃任务
   */
  const hasActiveOutboundJobs = () => {
    try {
      const stored = localStorage.getItem(OUTBOUND_JOBS_KEY);
      if (!stored) return false;
      
      const jobs = JSON.parse(stored);
      const activeStatuses = ['Scheduling', 'Executing', 'Paused', 'Drafted'];
      
      // 过滤出活跃状态的任务
      const activeJobs = jobs.filter(job => activeStatuses.includes(job.callStatus));
      return activeJobs.length > 0;
    } catch (err) {
      console.error('检查活跃外呼任务失败:', err);
      return false;
    }
  };

  /**
   * 触发智能外呼
   * @param {Object} timeline - 案件时间线数据
   */
  const triggerOutboundCall = async (timeline) => {
    try {
      // 检查是否已有活跃任务，如有则跳过
      if (hasActiveOutboundJobs()) {
        console.log('检测到活跃外呼任务，跳过发起新外呼');
        return;
      }

      const mediationId = timeline.id;
      const caseId = timeline.case_id;

      if (!mediationId || !caseId) {
        console.warn('缺少必要参数，跳过外呼触发:', { mediationId, caseId });
        return;
      }

      console.log('发起智能外呼，mediationId:', mediationId, ', caseId:', caseId);

      // 调用外呼API
      const response = await OutboundBotAPIService.makeCallV2({
        mediationId: String(mediationId),
        caseId: String(caseId),
        callAuto: 0,
        callPersonId: ''
      });

      // 处理响应
      if (response?.data && Array.isArray(response.data)) {
        const successJobs = [];
        const failedJobs = [];

        // 分类成功和失败的记录
        response.data.forEach(item => {
          if (item.errorCode === 0 && item.jobId) {
            successJobs.push({
              jobId: item.jobId,
              callStatus: item.callStatus || 'Scheduling',
              personId: item.personId,
              mediationId: item.mediationId,
              caseId: String(caseId), // 添加 caseId 字段用于轮询
              startTime: Date.now(),
              pollStartTime: Date.now(),
              retryCount: 0
            });
          } else {
            failedJobs.push({
              personId: item.personId,
              message: item.message || '未知错误'
            });
          }
        });

        // 存储成功的任务到 localStorage
        if (successJobs.length > 0) {
          localStorage.setItem(OUTBOUND_JOBS_KEY, JSON.stringify(successJobs));
          console.log('存储外呼任务成功，数量:', successJobs.length);
        }

        // 提示失败的任务
        if (failedJobs.length > 0) {
          const failedMsg = failedJobs
            .map(job => `${job.personId}（${job.message}）`)
            .join('、');
          message.warning(`部分联系人外呼失败：${failedMsg}`);
          console.warn('部分外呼失败:', failedJobs);
        }
      }
    } catch (err) {
      console.error('智能外呼发起失败:', err);
      message.error('智能外呼发起失败，请检查网络后重试');
    }
  };

@@ -140,6 +225,10 @@
      // 保存到localStorage
      saveToStorage(timelineData);

      // 触发智能外呼
      await triggerOutboundCall(timelineData);
      

      // 加载任务时间数据
      await loadTaskTime(timelineData);


 web-app/src/services/EvidenceAPIService.js

@@ -64,7 +64,7 @@
   * @returns {Promise} 审核结果
   */
  static auditEvidence(data = {}) {
    return request.put('/api/v1/evidence/audit', data);
    return request.post('/api/v1/evidence/audit', data);
  }

  /**

 web-app/src/services/LawAPIService.js

@@ -122,6 +122,16 @@
      sortOrder: 'desc'
    });
  }

  /**
   * 根据法条ID查询法条详情
   * GET /api/web/lawProvision/listById
   * @param {string} provision_id - 法条ID
   * @returns {Promise} 法条详情
   */
  static getLawProvisionById(provision_id) {
    return request.get('/api/web/lawProvision/listById', { id: provision_id });
  }
}

export default LawAPIService;

 web-app/src/services/OutboundBotAPIService.js

@@ -8,186 +8,56 @@

class OutboundBotAPIService {
  /**
   * 创建外呼任务
   * 电话拨打获取记录
   * POST /api/v1/outbound-bot/call
   * @param {Object} data - 外呼任务数据
   * @param {string} data.caseRef - 案件编号
   * @param {string} data.personId - 申请方或被申请方id
   * @param {string} data.mediationStage - 外呼话术阶段(10~14)
   * @param {string} data.phoneNumber - 当事人电话号码
   * @param {string} data.type - 外呼类型(intent_survey/fact_finding/material_verify/agreement/follow_up)
   * @param {string} data.partyType - 当事人类型(applicant/respondent)
   * @param {boolean} data.forceUseInput - 是否强制使用输入号码
   * @returns {Promise} 外呼任务创建结果
   * @param {Object} data - 请求数据
   * @param {string} data.caseRef - 案件引用ID
   * @param {string} data.phoneNumber - 电话号码
   * @param {string} data.scriptId - 脚本ID
   * @returns {Promise} 外呼结果
   */
  static createCallTask(data = {}) {
  static makeCall(data = {}) {
    return request.post('/api/v1/outbound-bot/call', data);
  }

  /**
   * 获取外呼任务详情
   * GET /api/v1/outbound-bot/task/{taskId}
   * @param {string} taskId - 任务ID
   * @returns {Promise} 任务详情
   * 智能外呼拨打电话
   * POST /api/v1/outbound-bot/call-v2
   * @param {Object} data - 请求数据
   * @param {string} data.caseRef - 案件引用ID
   * @param {string} data.phoneNumber - 电话号码
   * @param {string} data.scriptId - 脚本ID
   * @param {Object} data.variables - 变量参数
   * @returns {Promise} 外呼结果
   */
  static getCallTaskDetail(taskId) {
    return request.get(`/api/v1/outbound-bot/task/${taskId}`);
  static makeCallV2(data = {}) {
    return request.post('/api/v1/outbound-bot/call-v2', data);
  }

  /**
   * 获取外呼任务列表
   * GET /api/v1/outbound-bot/tasks
   * 获取通话录音接口
   * GET /api/v1/outbound-bot/conversation-log
   * @param {Object} params - 查询参数
   * @param {string} params.caseRef - 案件编号
   * @param {string} params.status - 任务状态
   * @param {string} params.type - 外呼类型
   * @param {number} params.page - 页码
   * @param {number} params.size - 每页数量
   * @returns {Promise} 任务列表
   * @param {string} params.caseRef - 案件引用ID
   * @param {string} params.phoneNumber - 电话号码
   * @param {string} params.jobId - 工作ID
   * @returns {Promise} 通话记录
   */
  static getCallTasks(params = {}) {
    return request.get('/api/v1/outbound-bot/tasks', params);
  static getConversationLog(params = {}) {
    return request.get('/api/v1/outbound-bot/conversation-log', params);
  }

  /**
   * 取消外呼任务
   * POST /api/v1/outbound-bot/task/{taskId}/cancel
   * @param {string} taskId - 任务ID
   * @param {string} reason - 取消原因
   * @returns {Promise} 取消结果
   */
  static cancelCallTask(taskId, reason) {
    return request.post(`/api/v1/outbound-bot/task/${taskId}/cancel`, { reason });
  }

  /**
   * 重试外呼任务
   * POST /api/v1/outbound-bot/task/{taskId}/retry
   * @param {string} taskId - 任务ID
   * @returns {Promise} 重试结果
   */
  static retryCallTask(taskId) {
    return request.post(`/api/v1/outbound-bot/task/${taskId}/retry`);
  }

  /**
   * 获取外呼统计信息
   * GET /api/v1/outbound-bot/statistics
   * @param {Object} params - 统计参数
   * @param {string} params.caseRef - 案件编号
   * @param {string} params.startTime - 开始时间
   * @param {string} params.endTime - 结束时间
   * @returns {Promise} 统计信息
   */
  static getCallStatistics(params = {}) {
    return request.get('/api/v1/outbound-bot/statistics', params);
  }

  /**
   * 获取外呼话术模板
   * GET /api/v1/outbound-bot/scripts
   * @param {string} type - 外呼类型
   * @param {string} stage - 调解阶段
   * @returns {Promise} 话术模板列表
   */
  static getCallScripts(type, stage) {
    return request.get('/api/v1/outbound-bot/scripts', { type, stage });
  }

  /**
   * 获取外呼任务执行日志
   * GET /api/v1/outbound-bot/task/{taskId}/logs
   * @param {string} taskId - 任务ID
   * @param {number} page - 页码
   * @param {number} size - 每页数量
   * @returns {Promise} 执行日志
   */
  static getCallTaskLogs(taskId, page = 1, size = 20) {
    return request.get(`/api/v1/outbound-bot/task/${taskId}/logs`, { page, size });
  }

  /**
   * 批量创建外呼任务
   * POST /api/v1/outbound-bot/batch-call
   * @param {Array} tasks - 任务数组
   * @returns {Promise} 批量创建结果
   */
  static createBatchCallTasks(tasks = []) {
    return request.post('/api/v1/outbound-bot/batch-call', { tasks });
  }

  /**
   * 根据案件信息智能创建外呼任务
   * @param {Object} caseInfo - 案件信息
   * @param {string} caseInfo.caseRef - 案件编号
   * @param {string} caseInfo.mediationStage - 调解阶段
   * @param {Array} caseInfo.parties - 当事人信息数组
   * @param {Object} options - 创建选项
   * @returns {Promise} 创建结果
   */
  static async createSmartCallTasks(caseInfo, options = {}) {
    const {
      callType = 'material_verify', // 默认外呼类型
      forceUseInput = false // 是否强制使用输入号码
    } = options;

    const tasks = [];

    // 为每个当事人创建外呼任务
    caseInfo.parties.forEach(party => {
      // 验证必要字段
      if (!party.personId || !party.phoneNumber) {
        console.warn(`当事人信息不完整:`, party);
        return;
      }

      tasks.push({
        caseRef: caseInfo.caseRef,
        personId: party.personId,
        mediationStage: caseInfo.mediationStage,
        phoneNumber: party.phoneNumber,
        type: callType,
        partyType: party.type || 'applicant', // 默认为申请人
        forceUseInput: forceUseInput
      });
    });

    if (tasks.length === 0) {
      return Promise.reject(new Error('没有有效的当事人信息用于创建外呼任务'));
    }

    return this.createBatchCallTasks(tasks);
  }

  /**
   * 获取当事人外呼历史
   * GET /api/v1/outbound-bot/person/{personId}/history
   * @param {string} personId - 当事人ID
   * 通话状态查询
   * GET /api/v1/outbound-bot/status
   * @param {Object} params - 查询参数
   * @returns {Promise} 外呼历史记录
   * @param {string} params.caseRef - 案件ID
   * @param {string} params.phoneNumber - 电话号码
   * @param {string} params.jobId - 工作ID
   * @returns {Promise} 通话状态
   */
  static getPersonCallHistory(personId, params = {}) {
    return request.get(`/api/v1/outbound-bot/person/${personId}/history`, params);
  }

  /**
   * 更新外呼任务
   * PUT /api/v1/outbound-bot/task/{taskId}
   * @param {string} taskId - 任务ID
   * @param {Object} data - 更新数据
   * @returns {Promise} 更新结果
   */
  static updateCallTask(taskId, data = {}) {
    return request.put(`/api/v1/outbound-bot/task/${taskId}`, data);
  }

  /**
   * 获取外呼配置
   * GET /api/v1/outbound-bot/config
   * @returns {Promise} 外呼配置信息
   */
  static getCallConfig() {
    return request.get('/api/v1/outbound-bot/config');
  static getCallStatus(params = {}) {
    return request.get('/api/v1/outbound-bot/status', params);
  }
}