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

## 文档信息
- **创建日期**: 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个工作日

---

**文档结束**