wkc/ccdi

Fork 0

Files

wkc 332771b009 docs: 添加异步文件上传功能前端设计文档

2026-03-05 10:10:25 +08:00

5.0 KiB

Raw Blame History

项目异步文件上传功能 - 前端设计文档

文档信息

创建日期: 2026-03-05
版本: v1.0
作者: Claude
状态: 已批准
关联文档: 后端设计文档

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 组件新增以下模块：

统计卡片区域：显示上传中、解析中、成功、失败的数量
文件上传记录列表：展示文件上传历史和状态
批量上传弹窗：支持批量选择和上传文件

2.2 交互流程

用户点击"流水导入"卡片的"上传流水"按钮
打开批量上传弹窗
用户选择/拖拽多个文件（显示已选文件列表，支持删除）
点击"开始上传"，弹窗关闭，显示"上传任务已提交"提示
返回主页面，可以看到统计卡片和列表实时更新（通过WebSocket）

3. 技术架构设计

3.1 组件数据结构

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 中新增：

// 批量上传文件
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秒

消息格式

状态更新：

{
  "type": "status_update",
  "record": { "id": 1, "fileStatus": "parsed_success", ... }
}

统计更新：

{
  "type": "statistics_update",
  "statistics": { "uploading": 2, "parsing": 3, ... }
}

4. 核心功能逻辑

4.1 批量上传流程

文件选择校验（数量≤100，格式.xlsx/.xls，大小≤50MB）
调用 batchUploadFiles API
显示"上传任务已提交"提示
刷新列表和统计

4.2 文件列表管理

支持按状态筛选
支持分页（每页20条）
支持手动刷新

4.3 操作按钮

查看流水：解析成功时显示，跳转到流水明细页面
查看错误：解析失败时显示，弹窗显示错误信息

5. 异常处理

5.1 文件上传异常

异常场景	处理方式	用户提示
文件数量超限	前端校验	"最多上传100个文件"
文件格式错误	前端校验	"仅支持 .xlsx, .xls 格式文件"
文件大小超限	前端校验	"单个文件不能超过50MB"
网络请求失败	捕获异常	"上传失败：网络错误"

5.2 WebSocket 异常

连接失败：记录日志，不影响主要功能
连接断开：自动重连（最多3次，间隔5秒）
消息解析失败：忽略该消息

6. 测试要点

6.1 功能测试

文件选择和校验（数量、格式、大小）
批量上传流程
状态筛选和分页
操作按钮（查看流水、查看错误）

6.2 WebSocket 测试

连接建立和断开
实时状态更新
断线重连机制

7. 开发计划

API 接口封装（0.5天）
批量上传弹窗（1天）
统计卡片组件（0.5天）
文件列表组件（1天）
WebSocket 集成（1天）
联调测试（1天）

总计：5个工作日

文档结束

5.0 KiB Raw Blame History Unescape Escape