237 lines
5.4 KiB
Markdown
237 lines
5.4 KiB
Markdown
# 导入进度实时更新功能说明
|
||
|
||
## 功能概述
|
||
|
||
已成功实现学员数据导入的实时进度更新功能，解决了导入大量数据时页面卡住的问题。
|
||
|
||
## 实现方式
|
||
|
||
使用 **SSE (Server-Sent Events)** 技术实现服务端到客户端的实时进度推送。
|
||
|
||
## 核心改动
|
||
|
||
### 1. 后端改动
|
||
|
||
#### 新增文件
|
||
|
||
- **ImportProgress.java** - 进度信息实体类
|
||
- 位置：`ry-study-common/src/main/java/com/ddnai/common/core/domain/ImportProgress.java`
|
||
- 包含：总数、已处理数、成功数、失败数、百分比、状态、消息等字段
|
||
|
||
- **ImportProgressManager.java** - 进度管理器
|
||
- 位置：`ry-study-common/src/main/java/com/ddnai/common/utils/ImportProgressManager.java`
|
||
- 功能：管理导入任务、SSE连接、进度更新推送
|
||
|
||
#### 修改文件
|
||
|
||
- **StudyClassUserController.java**
|
||
- 修改 `importData` 方法：改为异步处理，返回任务ID
|
||
- 新增 `getImportProgress` 方法：提供SSE端点
|
||
|
||
- **IStudyClassUserService.java**
|
||
- 新增 `importStudentsWithProgress` 方法接口
|
||
|
||
- **StudyClassUserServiceImpl.java**
|
||
- 实现 `importStudentsWithProgress` 方法：每处理10条数据更新一次进度
|
||
|
||
### 2. 前端改动
|
||
|
||
#### 修改文件
|
||
|
||
- **classUser/index.vue**
|
||
- 数据字段：新增 `importTaskId`、`importEventSource`、`importMessage`、`importProcessed`、`importTotal`、`importSuccess`、`importFailed`
|
||
- 方法修改：
|
||
- `handleFileSuccess` - 接收taskId并建立SSE连接
|
||
- 新增 `connectImportProgress` - 连接SSE并监听进度事件
|
||
- 新增 `closeImportProgress` - 关闭SSE连接并清理资源
|
||
- 生命周期：新增 `beforeDestroy` 钩子清理SSE连接
|
||
- UI更新：实时显示处理进度和详细统计
|
||
|
||
## 功能特点
|
||
|
||
### 实时进度显示
|
||
|
||
```
|
||
正在处理: 已完成 3158/3800 (成功 2704, 失败 454)
|
||
进度条：83%
|
||
```
|
||
|
||
### 导入流程
|
||
|
||
1. **文件上传**
|
||
- 显示上传进度：0-100%
|
||
- 状态：`正在上传文件... XX%`
|
||
|
||
2. **数据解析**
|
||
- 后端解析Excel文件
|
||
- 生成唯一任务ID
|
||
- 状态：`文件上传完成，开始处理数据...`
|
||
|
||
3. **异步导入**
|
||
- 每处理10条数据推送一次进度
|
||
- 实时更新：已处理数、成功数、失败数
|
||
- 进度条实时更新
|
||
|
||
4. **完成反馈**
|
||
- 自动关闭进度对话框
|
||
- 刷新数据列表
|
||
- 弹出详细导入结果
|
||
|
||
## 使用方法
|
||
|
||
### 导入学员数据
|
||
|
||
1. 进入"学员管理"页面
|
||
2. 点击"导入"按钮
|
||
3. 选择Excel文件（支持.xls/.xlsx）
|
||
4. 点击"确定"开始导入
|
||
5. **实时查看进度**：
|
||
- 上传进度
|
||
- 处理进度（已完成/总数）
|
||
- 成功/失败统计
|
||
6. 导入完成后查看详细结果
|
||
|
||
### 技术优势
|
||
|
||
✅ **异步处理** - 不阻塞HTTP请求，避免超时
|
||
✅ **实时反馈** - 用户可以看到真实处理进度
|
||
✅ **批量优化** - 每10条更新一次进度，减少网络开销
|
||
✅ **资源管理** - 自动清理SSE连接，防止内存泄漏
|
||
✅ **错误处理** - 完善的异常处理和用户提示
|
||
|
||
## 测试建议
|
||
|
||
### 测试场景
|
||
|
||
1. **小批量数据（< 100条）**
|
||
- 验证功能正常运行
|
||
- 检查进度更新流畅
|
||
|
||
2. **中批量数据（100-1000条）**
|
||
- 验证进度实时性
|
||
- 检查性能表现
|
||
|
||
3. **大批量数据（> 3000条）**
|
||
- 验证页面不卡顿
|
||
- 检查进度准确性
|
||
- 验证完成后结果正确
|
||
|
||
### 测试步骤
|
||
|
||
1. 准备测试数据Excel文件（建议3000条以上）
|
||
2. 启动后端服务
|
||
3. 启动前端服务
|
||
4. 登录系统
|
||
5. 进入"学员管理"页面
|
||
6. 导入测试文件
|
||
7. 观察进度更新：
|
||
- 上传阶段进度
|
||
- 处理阶段进度
|
||
- 成功/失败统计
|
||
- 百分比变化
|
||
8. 等待完成，查看结果
|
||
9. 刷新列表验证数据正确性
|
||
|
||
## 注意事项
|
||
|
||
### 浏览器兼容性
|
||
|
||
- ✅ Chrome/Edge（推荐）
|
||
- ✅ Firefox
|
||
- ✅ Safari
|
||
- ❌ IE（不支持EventSource）
|
||
|
||
### 网络要求
|
||
|
||
- SSE需要保持长连接
|
||
- 确保防火墙不阻止SSE连接
|
||
- 代理服务器需要支持SSE
|
||
|
||
### 性能建议
|
||
|
||
- 单次导入建议不超过10000条
|
||
- 超大数据建议分批导入
|
||
- 服务器内存建议至少2GB
|
||
|
||
## 故障排查
|
||
|
||
### 问题1：进度不更新
|
||
|
||
**可能原因：**
|
||
- SSE连接失败
|
||
- 后端处理异常
|
||
|
||
**解决方法：**
|
||
1. 打开浏览器控制台查看错误
|
||
2. 检查网络连接
|
||
3. 查看后端日志
|
||
|
||
### 问题2：导入失败
|
||
|
||
**可能原因：**
|
||
- Excel格式不正确
|
||
- 数据验证失败
|
||
- 数据库连接问题
|
||
|
||
**解决方法：**
|
||
1. 下载最新模板
|
||
2. 检查数据格式
|
||
3. 查看错误提示
|
||
4. 查看后端日志
|
||
|
||
### 问题3：页面白屏
|
||
|
||
**可能原因：**
|
||
- 前端代码错误
|
||
- 依赖缺失
|
||
|
||
**解决方法：**
|
||
1. 清除浏览器缓存
|
||
2. 重新编译前端代码
|
||
3. 检查控制台错误
|
||
|
||
## 技术细节
|
||
|
||
### SSE事件格式
|
||
|
||
```json
|
||
{
|
||
"taskId": "uuid",
|
||
"total": 3800,
|
||
"processed": 3158,
|
||
"success": 2704,
|
||
"failed": 454,
|
||
"duplicate": 0,
|
||
"percentage": 83,
|
||
"status": "processing",
|
||
"message": "正在处理: 已完成 3158/3800 (成功 2704, 失败 454)",
|
||
"result": null
|
||
}
|
||
```
|
||
|
||
### 状态说明
|
||
|
||
- **processing** - 处理中
|
||
- **completed** - 完成
|
||
- **failed** - 失败
|
||
|
||
## 扩展性
|
||
|
||
该功能框架可以轻松扩展到其他导入场景：
|
||
|
||
- 题库导入
|
||
- 课程导入
|
||
- 用户导入
|
||
- 其他批量数据导入
|
||
|
||
只需：
|
||
1. 复用 `ImportProgressManager`
|
||
2. 在Service层调用进度更新方法
|
||
3. 前端使用相同的SSE连接模式
|
||
|
||
## 开发者
|
||
|
||
- 开发日期：2024
|
||
- 技术栈：Spring Boot + Vue.js + SSE
|
||
- 更新记录：初始版本
|