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

2026-03-05 10:10:25 +08:00
parent 71d9b5b2d1
commit 332771b009
1 changed files with 211 additions and 0 deletions
--- a/doc/design/2026-03-05-async-file-upload-frontend-design.md
+++ b/doc/design/2026-03-05-async-file-upload-frontend-design.md
@@ -0,0 +1,211 @@
+# 项目异步文件上传功能 - 前端设计文档
+
+## 文档信息
+- **创建日期**: 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个工作日
+
+---
+
+**文档结束**