wehub-resource-sync
204 lines
5.8 KiB
Markdown
204 lines
5.8 KiB
Markdown
# 内嵌式进度条实现方案
|
|
|
|
## 概述
|
|
|
|
本文档描述了为AutoClip项目实现的内嵌式进度条功能，用于替换原有的静态"正在处理中"状态显示，提供实时的任务处理进度反馈。
|
|
|
|
## 设计目标
|
|
|
|
1. **保持原有高度**：不增加"正在处理中"色块的高度
|
|
2. **动态进度显示**：通过背景色变化和进度条显示实时进度
|
|
3. **实时状态同步**：基于WebSocket的实时进度更新
|
|
4. **步骤信息展示**：显示当前处理步骤和详细进度信息
|
|
|
|
## 技术实现
|
|
|
|
### 前端组件
|
|
|
|
#### 1. InlineProgressBar 组件
|
|
|
|
**位置**: `frontend/src/components/InlineProgressBar.tsx`
|
|
|
|
**主要特性**:
|
|
- 内嵌式设计，保持原有色块高度
|
|
- 动态背景渐变效果
|
|
- 实时进度条显示
|
|
- 步骤信息展示
|
|
- WebSocket实时更新
|
|
|
|
**核心功能**:
|
|
```typescript
|
|
interface InlineProgressBarProps {
|
|
projectId: string;
|
|
currentStep?: number;
|
|
totalSteps?: number;
|
|
status?: string;
|
|
onProgressUpdate?: (progress: number, step: string) => void;
|
|
}
|
|
```
|
|
|
|
**视觉效果**:
|
|
- 背景渐变：从蓝色到浅蓝色的进度填充
|
|
- 动画效果：进度条填充动画和闪烁效果
|
|
- 信息层次：主状态 → 步骤信息 → 进度百分比 → 详细进度条
|
|
|
|
#### 2. 流水线步骤配置
|
|
|
|
```typescript
|
|
const PIPELINE_STEPS = [
|
|
{ id: 1, name: '大纲提取', description: '从视频转写文本中提取结构性大纲' },
|
|
{ id: 2, name: '时间定位', description: '基于SRT字幕定位话题时间区间' },
|
|
{ id: 3, name: '内容评分', description: '多维度评估片段质量与传播潜力' },
|
|
{ id: 4, name: '标题生成', description: '为高分片段生成吸引人的标题' },
|
|
{ id: 5, name: '主题聚类', description: '将相关片段聚合为合集推荐' },
|
|
{ id: 6, name: '视频切割', description: '使用FFmpeg生成切片与合集视频' }
|
|
];
|
|
```
|
|
|
|
### 后端集成
|
|
|
|
#### 1. 实时进度推送
|
|
|
|
**位置**: `backend/services/processing_orchestrator.py`
|
|
|
|
**新增方法**:
|
|
```python
|
|
def _send_realtime_progress_update(self, status: TaskStatus, progress: Optional[float] = None,
|
|
error_message: Optional[str] = None):
|
|
"""发送实时进度更新到前端"""
|
|
```
|
|
|
|
**进度映射**:
|
|
- 步骤1 (大纲提取): 0-10%
|
|
- 步骤2 (时间定位): 10-30%
|
|
- 步骤3 (内容评分): 30-50%
|
|
- 步骤4 (标题生成): 50-70%
|
|
- 步骤5 (主题聚类): 70-85%
|
|
- 步骤6 (视频切割): 85-100%
|
|
|
|
#### 2. WebSocket消息格式
|
|
|
|
**位置**: `backend/services/websocket_notification_service.py`
|
|
|
|
**消息结构**:
|
|
```json
|
|
{
|
|
"type": "task_progress_update",
|
|
"task_id": "task_uuid",
|
|
"project_id": "project_uuid",
|
|
"status": "running",
|
|
"progress": 45,
|
|
"current_step": 3,
|
|
"total_steps": 6,
|
|
"step_name": "内容评分",
|
|
"message": "正在执行内容评分...",
|
|
"timestamp": "2024-01-01T12:00:00Z"
|
|
}
|
|
```
|
|
|
|
### 集成点
|
|
|
|
#### 1. ProjectCard 组件更新
|
|
|
|
**位置**: `frontend/src/components/ProjectCard.tsx`
|
|
|
|
**替换内容**:
|
|
```typescript
|
|
// 原有静态显示
|
|
<div style={{...}}>
|
|
<LoadingOutlined />
|
|
正在处理中
|
|
</div>
|
|
|
|
// 新的动态进度条
|
|
<InlineProgressBar
|
|
projectId={project.id}
|
|
currentStep={project.current_step}
|
|
totalSteps={project.total_steps}
|
|
status={normalizedStatus}
|
|
onProgressUpdate={(progress, stepName) => {
|
|
console.log(`项目 ${project.id} 进度更新: ${progress}% - ${stepName}`);
|
|
}}
|
|
/>
|
|
```
|
|
|
|
## 用户体验改进
|
|
|
|
### 1. 视觉反馈
|
|
- **动态背景**：进度条背景随进度变化
|
|
- **动画效果**：平滑的进度填充动画
|
|
- **状态指示**：清晰的步骤名称和进度百分比
|
|
|
|
### 2. 信息层次
|
|
- **主状态**：当前步骤名称（如"大纲提取"）
|
|
- **进度信息**：步骤计数和百分比
|
|
- **详细进度条**：精确的进度可视化
|
|
- **步骤详情**：可选的详细描述信息
|
|
|
|
### 3. 实时性
|
|
- **WebSocket连接**：实时接收后端进度更新
|
|
- **即时响应**：进度变化立即反映在UI上
|
|
- **状态同步**：多用户环境下的状态一致性
|
|
|
|
## 技术优势
|
|
|
|
### 1. 性能优化
|
|
- **轻量级组件**：最小化重渲染
|
|
- **WebSocket连接复用**：避免频繁HTTP请求
|
|
- **状态管理优化**：局部状态更新
|
|
|
|
### 2. 可扩展性
|
|
- **模块化设计**：组件可独立使用
|
|
- **配置化步骤**：易于添加新的处理步骤
|
|
- **主题支持**：可自定义颜色和样式
|
|
|
|
### 3. 错误处理
|
|
- **连接失败处理**：WebSocket断开时的降级方案
|
|
- **数据验证**：进度数据的有效性检查
|
|
- **异常恢复**：自动重连和状态恢复
|
|
|
|
## 部署说明
|
|
|
|
### 1. 前端部署
|
|
- 确保WebSocket连接配置正确
|
|
- 验证组件导入路径
|
|
- 测试不同浏览器的兼容性
|
|
|
|
### 2. 后端部署
|
|
- 确保WebSocket服务正常运行
|
|
- 验证进度推送逻辑
|
|
- 监控WebSocket连接状态
|
|
|
|
### 3. 测试验证
|
|
- 功能测试：验证进度条显示正确
|
|
- 性能测试：验证实时更新性能
|
|
- 兼容性测试：验证多浏览器支持
|
|
|
|
## 未来扩展
|
|
|
|
### 1. 功能增强
|
|
- **暂停/恢复**：支持任务暂停和恢复
|
|
- **取消操作**：支持任务取消功能
|
|
- **历史记录**：显示处理历史
|
|
|
|
### 2. 用户体验
|
|
- **个性化设置**：用户可自定义进度条样式
|
|
- **通知系统**：处理完成时的通知提醒
|
|
- **移动端优化**：响应式设计优化
|
|
|
|
### 3. 技术优化
|
|
- **缓存机制**：进度数据的本地缓存
|
|
- **离线支持**：网络断开时的离线模式
|
|
- **性能监控**：实时性能指标监控
|
|
|
|
## 总结
|
|
|
|
内嵌式进度条功能成功实现了以下目标：
|
|
|
|
1. ✅ **保持原有高度**：进度条完全内嵌在原有色块中
|
|
2. ✅ **动态进度显示**：实时显示处理进度和当前步骤
|
|
3. ✅ **实时状态同步**：基于WebSocket的实时更新机制
|
|
4. ✅ **用户体验提升**：提供丰富的视觉反馈和信息展示
|
|
|
|
该实现为AutoClip项目提供了现代化的任务处理状态显示，显著提升了用户体验和系统的实时性。
|