wehub-resource-sync
178 lines
4.9 KiB
Markdown
178 lines
4.9 KiB
Markdown
# 进度系统修复总结
|
|
|
|
## 问题描述
|
|
|
|
1. **前端进度显示问题**: 前端始终显示0%进度，然后直接变成已完成，没有中间进度
|
|
2. **WebSocket系统复杂**: 旧的WebSocket进度系统过于复杂，难以维护
|
|
3. **UI状态不统一**: 下载中、处理中的状态色块UI不统一，高度不一致
|
|
4. **下载进度不同步**: 下载进度没有正常同步显示
|
|
|
|
## 解决方案
|
|
|
|
### 1. 实现简化的后端进度系统
|
|
|
|
**文件**: `backend/services/simple_progress.py`
|
|
- 6个固定阶段，每个阶段有固定权重
|
|
- 简单的百分比计算逻辑
|
|
- Redis存储和事件发布
|
|
- 支持子进度（可选）
|
|
|
|
**文件**: `backend/api/v1/simple_progress.py`
|
|
- 进度快照查询API接口
|
|
- 批量获取多个项目进度
|
|
- 阶段配置查询
|
|
|
|
**文件**: `backend/services/simple_pipeline_adapter.py`
|
|
- 在现有流水线中集成进度上报
|
|
- 每个阶段切换时自动发送事件
|
|
- 最多只发送6次事件
|
|
|
|
### 2. 前端状态管理重构
|
|
|
|
**文件**: `frontend/src/stores/useSimpleProgressStore.ts`
|
|
- Zustand状态管理
|
|
- 轮询控制机制
|
|
- 进度数据缓存
|
|
- 支持批量轮询
|
|
|
|
### 3. 统一UI组件设计
|
|
|
|
**文件**: `frontend/src/components/UnifiedStatusBar.tsx`
|
|
- 统一的状态栏组件
|
|
- 支持下载中、处理中、完成、失败等状态
|
|
- 固定高度32px，不会超出卡片
|
|
- 渐变背景，视觉效果统一
|
|
- 自动轮询下载进度和处理进度
|
|
|
|
**文件**: `frontend/src/components/SimpleProgressDisplay.tsx`
|
|
- 详细的进度条显示
|
|
- 仅在处理中时显示
|
|
- 支持阶段信息和消息显示
|
|
|
|
### 4. 主组件集成
|
|
|
|
**文件**: `frontend/src/components/ProjectCard.tsx`
|
|
- 移除旧的复杂进度系统
|
|
- 集成新的统一状态栏
|
|
- 支持下载进度轮询
|
|
- 简化状态显示逻辑
|
|
|
|
## 核心特性
|
|
|
|
### 固定阶段定义
|
|
```python
|
|
STAGES = [
|
|
("INGEST", 10), # 下载/就绪
|
|
("SUBTITLE", 15), # 字幕/对齐
|
|
("ANALYZE", 20), # 语义分析/大纲
|
|
("HIGHLIGHT", 25), # 片段定位/打分
|
|
("EXPORT", 20), # 导出/封装
|
|
("DONE", 10), # 校验/归档
|
|
]
|
|
```
|
|
|
|
### 进度计算逻辑
|
|
```python
|
|
def compute_percent(stage: str, subpercent: Optional[float] = None) -> int:
|
|
# 累加之前阶段权重
|
|
done = 0
|
|
for s in ORDER:
|
|
if s == stage:
|
|
break
|
|
done += WEIGHTS[s]
|
|
|
|
# 当前阶段
|
|
cur = WEIGHTS.get(stage, 0)
|
|
|
|
if subpercent is None:
|
|
return min(100, done + cur) if stage == "DONE" else min(99, done)
|
|
else:
|
|
return min(99, done + int(cur * subpercent / 100))
|
|
```
|
|
|
|
### 事件格式
|
|
```json
|
|
{
|
|
"project_id": "46ab50a6-....",
|
|
"stage": "HIGHLIGHT",
|
|
"percent": 70,
|
|
"message": "已完成片段定位，共 12 段候选",
|
|
"ts": 1640995200
|
|
}
|
|
```
|
|
|
|
## UI设计改进
|
|
|
|
### 统一状态栏样式
|
|
- **高度**: 固定32px，不会超出卡片
|
|
- **背景**: 渐变背景，根据状态使用不同颜色
|
|
- **布局**: 左侧图标+文字，右侧百分比
|
|
- **颜色方案**:
|
|
- 下载中: 蓝色渐变 (#1890ff → #40a9ff)
|
|
- 处理中: 根据阶段动态颜色
|
|
- 完成: 绿色渐变 (#52c41a → #73d13d)
|
|
- 失败: 红色渐变 (#ff4d4f → #ff7875)
|
|
- 等待: 灰色渐变 (#d9d9d9 → #f0f0f0)
|
|
|
|
### 响应式设计
|
|
- 支持不同屏幕尺寸
|
|
- 文字大小和间距适配
|
|
- 图标和文字对齐
|
|
|
|
## 轮询机制
|
|
|
|
### 下载进度轮询
|
|
- 每2秒轮询项目API获取下载进度
|
|
- 自动更新进度显示
|
|
- 下载完成后自动切换到处理状态
|
|
|
|
### 处理进度轮询
|
|
- 每2秒轮询简化进度API
|
|
- 获取最新阶段和进度信息
|
|
- 支持批量轮询多个项目
|
|
|
|
## 测试和验证
|
|
|
|
**文件**: `frontend/src/pages/ProgressTestPage.tsx`
|
|
- 提供完整的测试界面
|
|
- 可以模拟各种状态和进度
|
|
- 验证轮询机制和UI显示
|
|
|
|
## 迁移指南
|
|
|
|
### 后端迁移
|
|
1. 使用`SimplePipelineAdapter`替换旧的流水线适配器
|
|
2. 在流水线关键点调用`emit_progress()`
|
|
3. 移除复杂的WebSocket进度发布
|
|
|
|
### 前端迁移
|
|
1. 使用`UnifiedStatusBar`替换旧的进度组件
|
|
2. 使用`useSimpleProgressStore`管理状态
|
|
3. 配置轮询替代WebSocket订阅
|
|
|
|
## 性能优化
|
|
|
|
1. **批量轮询**: 一次请求获取多个项目进度
|
|
2. **智能缓存**: 避免重复请求相同数据
|
|
3. **条件轮询**: 只在需要时启动轮询
|
|
4. **自动清理**: 定期清理过期进度数据
|
|
|
|
## 故障处理
|
|
|
|
1. **Redis连接失败**: 记录警告日志，跳过进度发送
|
|
2. **网络中断**: 前端轮询自动重试，数据缓存在本地
|
|
3. **阶段异常**: 支持失败状态检测，提供重试机制
|
|
|
|
## 总结
|
|
|
|
通过这次修复，我们实现了：
|
|
|
|
✅ **可靠性**: 基于HTTP轮询，不依赖WebSocket
|
|
✅ **简单性**: 固定阶段，易于理解和维护
|
|
✅ **统一性**: UI样式统一，高度一致
|
|
✅ **实时性**: 下载和处理进度都能实时同步
|
|
✅ **扩展性**: 易于添加新阶段和功能
|
|
✅ **调试性**: 完整的日志和状态追踪
|
|
|
|
相比之前的复杂系统，这个方案更加稳定可靠，易于维护和扩展。
|