# Proposal: 集成Dashboard实时API数据展示

## Change ID
`integrate-dashboard-api-data`

## 概述
为首页Dashboard集成ProcessAPI的实时数据，替换现有静态Mock数据，实现从URL参数获取案件信息，调用`ProcessAPIService.getCaseProcessInfo`获取timeline数据，并通过React Context + localStorage方式全局共享，动态更新页面各组件的数据展示。

## 动机
当前首页Dashboard使用的是硬编码的静态数据，无法反映真实案件的调解进度和状态。需要集成后端API实现：
1. **动态数据加载**：根据URL参数动态获取不同案件的调解数据
2. **全局数据共享**：通过Context和localStorage确保数据在组件间共享和持久化
3. **实时状态同步**：页面各区域（顶部信息、进度条、选项卡等）同步显示最新的调解状态
4. **用户体验提升**：增加Loading状态和错误提示，提升用户体验

## 影响范围

### 新增文件
- `web-app/src/contexts/CaseDataContext.jsx` - 案件数据全局Context
- `web-app/src/utils/urlParams.js` - URL参数解析工具
- `web-app/src/utils/stateTranslator.js` - 状态翻译工具（mediation.state → 中文）

### 修改文件
- `web-app/src/App.js` - 集成Context Provider，添加数据加载逻辑
- `web-app/src/components/dashboard/TopSection.jsx` - 从Context获取动态数据
- `web-app/src/components/dashboard/MediationProgress.jsx` - 从Context获取当前节点动态计算进度
- `web-app/src/components/dashboard/TabContainer.jsx` - MediationDataBoard组件从Context获取数据
- `web-app/src/components/dashboard/FloatingControlPanel.jsx` - 从Context获取状态和节点名称

## 用户故事

### 作为调解员
- **我想要**：打开页面时自动加载指定案件的调解数据
- **以便于**：实时查看该案件的调解进度和分析结果

### 作为系统管理员
- **我想要**：通过URL参数切换不同案件
- **以便于**：灵活查看和管理多个案件

### 作为开发人员
- **我想要**：在开发环境使用默认参数，在生产环境使用URL参数
- **以便于**：快速调试和部署

## 关键技术决策

### 1. 数据存储方案：React Context + localStorage
**选择原因**：
- Context：实现组件树内的全局状态共享，避免props逐层传递
- localStorage：页面刷新后数据不丢失，提升用户体验
- 组合使用：Context作为运行时状态管理，localStorage作为持久化备份

### 2. URL参数处理
**默认参数（开发环境）**：
```javascript
{
  caseId: "202601281644031088",
  caseTypeFirst: "24_01-2",
  platform_code: "AI_0001",
  authorization: "" // 可选
}
```

**URL格式**：
```
http://localhost:3000?caseId=xxx&caseTypeFirst=xxx&platform_code=xxx&authorization=xxx
```

### 3. 状态翻译映射
```javascript
mediation.state → 中文状态
0 → "待调解"
1 → "调解中"
2 → "调解成功"
3 → "调解失败"
```

### 4. 错误处理策略
- **API调用失败**：显示Ant Design Message错误提示
- **控制台日志**：打印详细错误信息供开发调试
- **降级方案**：API失败时仍可查看localStorage缓存的历史数据

## 数据流设计

```
URL参数 
  ↓
解析 & 默认值填充
  ↓
调用 ProcessAPIService.getCaseProcessInfo(caseId, params)
  ↓
获取 timeline 数据
  ↓
存储到 Context + localStorage
  ↓
各组件从 Context 读取并展示
```

## 非目标
- 本次不实现数据的自动刷新和轮询机制
- 本次不实现案件列表切换功能
- 本次不涉及其他Tab（AI调解实时看板、证据材料汇总、调解协议）的API对接

## 依赖关系
- ✅ ProcessAPIService已完成（包含getCaseProcessInfo方法）
- ✅ Ant Design 4.24.12已集成
- ✅ API文档已更新（timeline字段完整）

## 验收标准
1. ✅ 页面首次加载时正确解析URL参数（无参数时使用默认值）
2. ✅ 成功调用ProcessAPIService.getCaseProcessInfo并获取timeline数据
3. ✅ timeline数据正确存储到Context和localStorage
4. ✅ TopSection组件展示的事项编号、纠纷类型、开始时间、结束时间与API数据一致
5. ✅ AI状态标签正确翻译mediation.state（0/1/2/3 → 中文）
6. ✅ MediationProgress进度条根据current_node动态计算当前步骤
7. ✅ FloatingControlPanel显示"调解进行中-阶段X：{节点名称}"格式正确
8. ✅ MediationDataBoard中的主要分歧点、更新时间、成功率、轮次与API数据一致
9. ✅ API调用过程中显示Loading状态
10. ✅ API调用失败时显示错误提示并在控制台打印错误

## 风险评估
- **低风险**：改动主要是数据绑定，不涉及业务逻辑变更
- **测试重点**：不同案件ID的数据展示、网络异常处理、localStorage容量限制

## 时间估算
- 开发时间：4-6小时
- 测试时间：2小时
- 总计：6-8小时