212 lines
5.0 KiB
Markdown
212 lines
5.0 KiB
Markdown
|
# 项目异步文件上传功能 - 前端设计文档
|
|||
|
|
|
|||
|
|
## 文档信息
|
|||
|
|
- **创建日期**: 2026-03-05
|
|||
|
|
- **版本**: v1.0
|
|||
|
|
- **作者**: Claude
|
|||
|
|
- **状态**: 已批准
|
|||
|
|
- **关联文档**: [后端设计文档](./2026-03-05-async-file-upload-design.md)
|
|||
|
|
|
|||
|
|
## 1. 设计概述
|
|||
|
|
|
|||
|
|
### 1.1 功能描述
|
|||
|
|
基于现有项目管理模块的上传数据组件（UploadData.vue），扩展实现流水文件的异步批量上传功能，提供直观的用户交互界面和实时状态跟踪能力。
|
|||
|
|
|
|||
|
|
### 1.2 设计原则
|
|||
|
|
- **渐进式增强**：在现有组件基础上扩展，不破坏现有功能
|
|||
|
|
- **实时反馈**：通过 WebSocket 推送状态更新，用户无需手动刷新
|
|||
|
|
- **用户友好**：清晰的状态展示、简洁的操作流程、友好的错误提示
|
|||
|
|
- **响应式设计**：适配不同屏幕尺寸
|
|||
|
|
|
|||
|
|
### 1.3 技术栈
|
|||
|
|
- Vue.js 2.6.12
|
|||
|
|
- Element UI 2.15.14
|
|||
|
|
- WebSocket（实时通信）
|
|||
|
|
- Axios（HTTP 请求）
|
|||
|
|
|
|||
|
|
|
|||
|
|
## 2. 页面布局设计
|
|||
|
|
|
|||
|
|
### 2.1 整体结构
|
|||
|
|
|
|||
|
|
UploadData.vue 组件新增以下模块：
|
|||
|
|
1. **统计卡片区域**：显示上传中、解析中、成功、失败的数量
|
|||
|
|
2. **文件上传记录列表**：展示文件上传历史和状态
|
|||
|
|
3. **批量上传弹窗**：支持批量选择和上传文件
|
|||
|
|
|
|||
|
|
### 2.2 交互流程
|
|||
|
|
|
|||
|
|
1. 用户点击"流水导入"卡片的"上传流水"按钮
|
|||
|
|
2. 打开批量上传弹窗
|
|||
|
|
3. 用户选择/拖拽多个文件（显示已选文件列表，支持删除）
|
|||
|
|
4. 点击"开始上传"，弹窗关闭，显示"上传任务已提交"提示
|
|||
|
|
5. 返回主页面，可以看到统计卡片和列表实时更新（通过WebSocket）
|
|||
|
|
|
|||
|
|
## 3. 技术架构设计
|
|||
|
|
|
|||
|
|
### 3.1 组件数据结构
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
data() {
|
|||
|
|
return {
|
|||
|
|
// 批量上传相关
|
|||
|
|
batchUploadDialogVisible: false,
|
|||
|
|
selectedFiles: [],
|
|||
|
|
uploadLoading: false,
|
|||
|
|
|
|||
|
|
// 统计数据
|
|||
|
|
statistics: {
|
|||
|
|
uploading: 0,
|
|||
|
|
parsing: 0,
|
|||
|
|
parsed_success: 0,
|
|||
|
|
parsed_failed: 0
|
|||
|
|
},
|
|||
|
|
|
|||
|
|
// 文件列表相关
|
|||
|
|
fileList: [],
|
|||
|
|
listLoading: false,
|
|||
|
|
queryParams: {
|
|||
|
|
projectId: null,
|
|||
|
|
fileStatus: null,
|
|||
|
|
pageNum: 1,
|
|||
|
|
pageSize: 20
|
|||
|
|
},
|
|||
|
|
total: 0,
|
|||
|
|
|
|||
|
|
// WebSocket相关
|
|||
|
|
websocket: null,
|
|||
|
|
wsReconnectCount: 0
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.2 API 接口封装
|
|||
|
|
|
|||
|
|
在 src/api/ccdiProjectUpload.js 中新增：
|
|||
|
|
|
|||
|
|
```javascript
|
|||
|
|
// 批量上传文件
|
|||
|
|
export function batchUploadFiles(projectId, files) {
|
|||
|
|
const formData = new FormData()
|
|||
|
|
files.forEach(file => formData.append('files', file))
|
|||
|
|
formData.append('projectId', projectId)
|
|||
|
|
|
|||
|
|
return request({
|
|||
|
|
url: '/ccdi/file-upload/batch',
|
|||
|
|
method: 'post',
|
|||
|
|
data: formData,
|
|||
|
|
timeout: 300000
|
|||
|
|
})
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 查询文件上传记录列表
|
|||
|
|
export function getFileUploadList(params) {
|
|||
|
|
return request({
|
|||
|
|
url: '/ccdi/file-upload/list',
|
|||
|
|
method: 'get',
|
|||
|
|
params
|
|||
|
|
})
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 查询文件上传统计
|
|||
|
|
export function getFileUploadStatistics(projectId) {
|
|||
|
|
return request({
|
|||
|
|
url: `/ccdi/file-upload/statistics/${projectId}`,
|
|||
|
|
method: 'get'
|
|||
|
|
})
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 3.3 WebSocket 集成
|
|||
|
|
|
|||
|
|
#### 连接配置
|
|||
|
|
- 连接地址：ws://localhost:8080/ws/file-upload/{projectId}
|
|||
|
|
- 连接时机：组件 mounted
|
|||
|
|
- 断开时机：组件 beforeDestroy
|
|||
|
|
- 重连机制：最多3次，间隔5秒
|
|||
|
|
|
|||
|
|
#### 消息格式
|
|||
|
|
|
|||
|
|
状态更新：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "status_update",
|
|||
|
|
"record": { "id": 1, "fileStatus": "parsed_success", ... }
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
统计更新：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"type": "statistics_update",
|
|||
|
|
"statistics": { "uploading": 2, "parsing": 3, ... }
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
## 4. 核心功能逻辑
|
|||
|
|
|
|||
|
|
### 4.1 批量上传流程
|
|||
|
|
|
|||
|
|
1. 文件选择校验（数量≤100，格式.xlsx/.xls，大小≤50MB）
|
|||
|
|
2. 调用 batchUploadFiles API
|
|||
|
|
3. 显示"上传任务已提交"提示
|
|||
|
|
4. 刷新列表和统计
|
|||
|
|
|
|||
|
|
### 4.2 文件列表管理
|
|||
|
|
|
|||
|
|
- 支持按状态筛选
|
|||
|
|
- 支持分页（每页20条）
|
|||
|
|
- 支持手动刷新
|
|||
|
|
|
|||
|
|
### 4.3 操作按钮
|
|||
|
|
|
|||
|
|
- **查看流水**：解析成功时显示，跳转到流水明细页面
|
|||
|
|
- **查看错误**：解析失败时显示，弹窗显示错误信息
|
|||
|
|
|
|||
|
|
## 5. 异常处理
|
|||
|
|
|
|||
|
|
### 5.1 文件上传异常
|
|||
|
|
|
|||
|
|
| 异常场景 | 处理方式 | 用户提示 |
|
|||
|
|
|---------|---------|---------|
|
|||
|
|
| 文件数量超限 | 前端校验 | "最多上传100个文件" |
|
|||
|
|
| 文件格式错误 | 前端校验 | "仅支持 .xlsx, .xls 格式文件" |
|
|||
|
|
| 文件大小超限 | 前端校验 | "单个文件不能超过50MB" |
|
|||
|
|
| 网络请求失败 | 捕获异常 | "上传失败：网络错误" |
|
|||
|
|
|
|||
|
|
### 5.2 WebSocket 异常
|
|||
|
|
|
|||
|
|
- 连接失败：记录日志，不影响主要功能
|
|||
|
|
- 连接断开：自动重连（最多3次，间隔5秒）
|
|||
|
|
- 消息解析失败：忽略该消息
|
|||
|
|
|
|||
|
|
## 6. 测试要点
|
|||
|
|
|
|||
|
|
### 6.1 功能测试
|
|||
|
|
|
|||
|
|
- 文件选择和校验（数量、格式、大小）
|
|||
|
|
- 批量上传流程
|
|||
|
|
- 状态筛选和分页
|
|||
|
|
- 操作按钮（查看流水、查看错误）
|
|||
|
|
|
|||
|
|
### 6.2 WebSocket 测试
|
|||
|
|
|
|||
|
|
- 连接建立和断开
|
|||
|
|
- 实时状态更新
|
|||
|
|
- 断线重连机制
|
|||
|
|
|
|||
|
|
## 7. 开发计划
|
|||
|
|
|
|||
|
|
1. **API 接口封装**（0.5天）
|
|||
|
|
2. **批量上传弹窗**（1天）
|
|||
|
|
3. **统计卡片组件**（0.5天）
|
|||
|
|
4. **文件列表组件**（1天）
|
|||
|
|
5. **WebSocket 集成**（1天）
|
|||
|
|
6. **联调测试**（1天）
|
|||
|
|
|
|||
|
|
**总计**：5个工作日
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
**文档结束**
|