ccdi/doc/design/2026-03-05-async-file-upload-frontend-design.md

# 项目异步文件上传功能 - 前端设计文档（轮询版本）

## 文档信息
- **创建日期**: 2026-03-05
- **版本**: v1.1
- **作者**: Claude
- **状态**: 已批准
- **关联文档**: [后端设计文档](./2026-03-05-async-file-upload-design.md)
- **变更说明**: 移除WebSocket，改为页面轮询机制

## 1. 设计概述

### 1.1 功能描述
基于现有项目管理模块的上传数据组件（UploadData.vue），扩展实现流水文件的异步批量上传功能。

### 1.2 技术栈
- Vue.js 2.6.12
- Element UI 2.15.14
- Axios（HTTP 请求）
- 页面轮询（定时刷新）

## 2. 核心变更

### 2.1 移除WebSocket
- 不再使用WebSocket实时推送
- 改用HTTP轮询机制定时刷新

### 2.2 轮询机制

**启动条件**：
- 上传文件后立即启动
- 检测到有uploading或parsing状态文件时自动启动

**停止条件**：
- 所有文件处理完成（无uploading和parsing状态）
- 组件销毁时
- 用户手动停止

**轮询间隔**：
- 默认5秒
- 可根据活跃任务数量动态调整

## 3. 轮询实现

### 3.1 数据结构

```javascript
data() {
  return {
    // 轮询相关
    pollingTimer: null,
    pollingEnabled: false,
    pollingInterval: 5000  // 5秒
  }
}
```

### 3.2 核心方法

```javascript
methods: {
  // 启动轮询
  startPolling() {
    if (this.pollingEnabled) return
    
    this.pollingEnabled = true
    
    const poll = () => {
      if (!this.pollingEnabled) return
      
      Promise.all([
        this.loadStatistics(),
        this.loadFileList()
      ]).then(() => {
        // 检查是否需要继续轮询
        if (this.statistics.uploading === 0 && 
            this.statistics.parsing === 0) {
          this.stopPolling()
          return
        }
        
        this.pollingTimer = setTimeout(poll, this.pollingInterval)
      })
    }
    
    poll()
  },
  
  // 停止轮询
  stopPolling() {
    this.pollingEnabled = false
    if (this.pollingTimer) {
      clearTimeout(this.pollingTimer)
      this.pollingTimer = null
    }
  },
  
  // 上传成功后启动轮询
  async handleBatchUpload() {
    // ... 上传逻辑 ...
    
    // 刷新数据并启动轮询
    await Promise.all([
      this.loadStatistics(),
      this.loadFileList()
    ])
    
    this.startPolling()
  }
}
```

### 3.3 生命周期管理

```javascript
mounted() {
  this.loadStatistics()
  this.loadFileList()
  
  // 检查是否需要启动轮询
  if (this.statistics.uploading > 0 || this.statistics.parsing > 0) {
    this.startPolling()
  }
},

beforeDestroy() {
  this.stopPolling()
}
```

## 4. 其他功能

批量上传弹窗、统计卡片、文件列表等功能保持不变，详见原设计文档。

## 5. 开发计划

1. **API 接口封装**（0.5天）
2. **批量上传弹窗**（1天）
3. **统计卡片组件**（0.5天）
4. **文件列表组件**（1天）
5. **轮询机制**（0.5天）
6. **联调测试**（1天）

**总计**：4.5个工作日

---

**文档结束**
```