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小时