# Proposal: 首页任务时间实时展示API对接

## Change ID
`task-time-display`

## 概述
为首页悬浮控制面板增加任务时间实时展示功能，通过API获取任务开始时间并结合本地定时器实现精确的时间计时显示。

## 动机
提升用户体验，让调解员能够实时了解当前任务的进行时长，便于掌握调解进度和时间管理。

## 影响范围
### 新增文件
- `web-app/src/hooks/useTaskTimer.js` - 任务时间计时Hook
- `web-app/src/utils/timeFormatter.js` - 时间格式化工具

### 修改文件
- `web-app/src/contexts/CaseDataContext.jsx` - 集成任务时间数据获取
- `web-app/src/components/dashboard/FloatingControlPanel.jsx` - 展示实时时间
- `web-app/src/services/ProcessAPIService.js` - 补充getTaskTime方法文档

## 用户故事

### 调解员视角
作为调解员，我希望在悬浮控制面板上看到准确的任务进行时间，以便：
- 掌握当前调解环节的耗时
- 决定是否需要人工介入
- 评估调解效率

### 系统管理员视角
作为系统管理员，我希望时间显示具备容错能力，当API不可用时能降级到本地计时，确保功能可用性。

## 关键技术决策

### 1. 时间源策略
- **主时间源**：API返回的startTime（精确）
- **备时间源**：页面加载时刻（降级方案）
- **增量计算**：基于定时器每10秒累加

### 2. 定时器管理
- 轮询间隔：10秒
- 生命周期：页面卸载时自动清理
- 性能优化：使用requestAnimationFrame优化渲染

### 3. 错误处理
- API失败时自动降级到本地计时
- 控制台记录错误日志
- UI保持正常显示（不中断用户体验）

### 4. 数据流设计
```
CaseDataContext加载timeline
        ↓
提取mediation_id和node_id
        ↓
调用ProcessAPIService.getTaskTime
        ↓
获取startTime → useTaskTimer Hook
        ↓
定时器每10秒计算新duration
        ↓
FloatingControlPanel展示实时时间
```

## 验收标准

### 功能性
- [ ] 成功调用getTaskTime API并获取startTime
- [ ] 页面每10秒更新一次时间显示
- [ ] 时间格式正确显示为"XX分钟"
- [ ] 页面刷新后时间计时连续
- [ ] 页面卸载时定时器正确清理

### 可靠性
- [ ] API失败时自动降级到本地计时
- [ ] 网络异常时不阻塞页面其他功能
- [ ] 多次组件重渲染不重复创建定时器

### 性能
- [ ] 定时器内存泄漏为0
- [ ] 页面FPS保持60帧
- [ ] CPU占用率增加不超过5%

### 用户体验
- [ ] 时间显示平滑更新，无闪烁
- [ ] 错误状态下有适当提示
- [ ] 加载状态有视觉反馈

## 风险评估

### 高风险
- **定时器内存泄漏**：可能导致页面性能下降
  - 缓解措施：严格管理定时器生命周期

### 中风险
- **API响应延迟**：影响初始时间准确性
  - 缓解措施：设置合理的超时时间

### 低风险
- **时间计算精度**：JavaScript定时器存在微小偏差
  - 缓解措施：定期与服务器时间同步校准

## 时间估算
- 设计与规划：0.5小时
- 编码实现：2小时
- 测试验证：1小时
- **总计**：3.5小时