guxz/aue

Files

2026-06-03 13:16:30 +08:00

55 KiB

Raw Blame History

文件上传与任务状态管理优化实施计划

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: 优化文件上传用户体验（进度条、拖拽、验证）和任务状态管理（重试、智能轮询、通知），提升系统易用性和反馈机制

Architecture: 在现有Vue 3组件架构上进行增量式增强，新增5个UI组件和2个工具函数，修改3个现有文件，保持向后兼容性

Tech Stack: Vue 3 Composition API, Axios, Ant Design Vue Icons, HTML5 Drag & Drop API, CSS3 Animations

📁 文件结构规划

新增文件（7个）

src/
├── utils/
│   └── fileValidator.js              # 文件验证工具（类型、大小、名称）
├── components/ui/
│   ├── ProgressBar.vue               # 可复用上传进度条组件
│   ├── DropZone.vue                  # 拖拽上传区域组件
│   ├── ToastNotification.vue         # Toast通知组件
│   └── SkeletonCard.vue              # 骨架屏加载占位组件
└── utils/
    └── notification.js                # 通知显示工具函数

修改文件（3个）

src/
├── api/
│   └── file.js                       # 添加uploadFile进度回调参数
├── components/
│   ├── FileSelector.vue              # 集成拖拽、验证、进度条功能
│   └── exam/
│       ├── UploadTaskItem.vue        # 添加一键重试按钮
│       └── composables/
│           └── useUploadTasks.js      # 实现智能轮询+批量操作

Task 1: 创建文件验证工具函数

Files:

Create: src/utils/fileValidator.js
Test: 手动测试（浏览器控制台）

目标: 实现前端文件验证逻辑，支持类型检查、大小限制、文件名合法性校验

Step 1: 编写 fileValidator.js 基础结构

/**
 * 文件验证工具函数
 * 用于在上传前对文件进行前端验证，减少无效请求
 */

// 支持的文件扩展名白名单
const ALLOWED_EXTENSIONS = [
  '.docx', '.pdf', '.txt', '.md', 
  '.xlsx', '.pptx', '.doc', '.xls', '.ppt'
]

// 最大文件大小：50MB
const MAX_FILE_SIZE = 50 * 1024 * 1024

// 最大文件名长度
const MAX_FILENAME_LENGTH = 200

// 禁止的文件名字符
const INVALID_FILENAME_CHARS = /[\\/:*?"<>|]/

/**
 * 验证单个文件
 * @param {File} file - File对象
 * @returns {{ valid: boolean, errors: string[] }}
 */
export function validateFile(file) {
  const errors = []

  // 1. 检查文件是否存在
  if (!file) {
    errors.push('未选择文件')
    return { valid: false, errors }
  }

  // 2. 检查文件名长度
  if (file.name.length > MAX_FILENAME_LENGTH) {
    errors.push(`文件名过长 (${file.name.length}字符，限制${MAX_FILENAME_LENGTH}字符)`)
  }

  // 3. 检查文件名是否包含非法字符
  if (INVALID_FILENAME_CHARS.test(file.name)) {
    errors.push('文件名包含非法字符 (\\ / : * ? " < > |)')
  }

  // 4. 检查文件扩展名
  const ext = getFileExtension(file.name)
  if (!ALLOWED_EXTENSIONS.includes(ext.toLowerCase())) {
    errors.push(`不支持的文件格式 (.${ext})，支持格式：${ALLOWED_EXTENSIONS.join(', ')}`)
  }

  // 5. 检查文件大小
  if (file.size > MAX_FILE_SIZE) {
    errors.push(`文件过大 (${formatFileSize(file.size)}，限制${formatFileSize(MAX_FILE_SIZE)})`)
  }

  // 6. 检查文件大小是否为0（空文件）
  if (file.size === 0) {
    errors.push('文件为空（0字节）')
  }

  return {
    valid: errors.length === 0,
    errors,
    ext,
    size: file.size
  }
}

/**
 * 批量验证多个文件
 * @param {File[]} files - File对象数组
 * @returns {{ validFiles: File[], invalidFiles: { file: File, errors: string[] }[] }}
 */
export function validateFiles(files) {
  const validFiles = []
  const invalidFiles = []

  files.forEach(file => {
    const result = validateFile(file)
    if (result.valid) {
      validFiles.push(file)
    } else {
      invalidFiles.push({
        file,
        errors: result.errors
      })
    }
  })

  return { validFiles, invalidFiles }
}

/**
 * 获取文件扩展名（含点号）
 * @param {string} filename - 文件名
 * @returns {string}
 */
function getFileExtension(filename) {
  const lastDotIndex = filename.lastIndexOf('.')
  if (lastDotIndex === -1) return ''
  return filename.substring(lastDotIndex).toLowerCase()
}

/**
 * 格式化文件大小为可读字符串
 * @param {number} bytes - 字节数
 * @returns {string}
 */
export function formatFileSize(bytes) {
  if (!bytes || bytes === 0) return '0B'
  
  const units = ['B', 'KB', 'MB', 'GB']
  const i = Math.floor(Math.log(bytes) / Math.log(1024))
  const size = parseFloat((bytes / Math.pow(1024, i)).toFixed(1))
  
  return `${size}${units[i]}`
}

/**
 * 根据扩展名获取文件类型标签
 * @param {string} ext - 扩展名（含点号）
 * @returns {string}
 */
export function getFileTypeLabel(ext) {
  const typeMap = {
    '.docx': 'Word文档',
    '.doc': 'Word文档',
    '.pdf': 'PDF文档',
    '.xlsx': 'Excel表格',
    '.xls': 'Excel表格',
    '.pptx': 'PowerPoint演示',
    '.ppt': 'PowerPoint演示',
    '.txt': '文本文件',
    '.md': 'Markdown文档'
  }
  
  return typeMap[ext.toLowerCase()] || '未知类型'
}

/**
 * 根据扩展名获取对应的图标组件名
 * @param {string} ext - 扩展名（含点号）
 * @returns {string} Ant Design图标组件名
 */
export function getFileIconName(ext) {
  const iconMap = {
    '.docx': 'FileWordOutlined',
    '.doc': 'FileWordOutlined',
    '.pdf': 'FilePdfOutlined',
    '.xlsx': 'FileExcelOutlined',
    '.xls': 'FileExcelOutlined',
    '.pptx': 'FilePptOutlined',
    '.ppt': 'FilePptOutlined',
    '.txt': 'FileTextOutlined',
    '.md': 'FileTextOutlined'
  }
  
  return iconMap[ext.toLowerCase()] || 'FileOutlined'
}

export default {
  validateFile,
  validateFiles,
  formatFileSize,
  getFileTypeLabel,
  getFileIconName,
  ALLOWED_EXTENSIONS,
  MAX_FILE_SIZE
}

Step 2: 测试验证函数

在浏览器控制台执行：

// 导入模块后测试
import { validateFile, validateFiles, formatFileSize } from './utils/fileValidator.js'

// 测试1: 有效文件
const validFile = new File(['test'], 'document.docx', { type: 'application/docx' })
console.log(validateFile(validFile))
// 预期: { valid: true, errors: [], ext: '.docx', size: 4 }

// 测试2: 无效扩展名
const invalidExt = new File(['test'], 'script.exe', {})
console.log(validateFile(invalidExt))
// 预期: { valid: false, errors: ["不支持的文件格式 (.exe)..."] }

// 测试3: 文件过大（模拟）
const largeFile = new File(new Array(60*1024*1024), 'large.docx', {})
console.log(validateFile(largeFile))
// 预期: { valid: false, errors: ["文件过大..."] }

// 测试4: 格式化文件大小
console.log(formatFileSize(1024 * 1024 * 2.3))
// 预期: "2.3MB"

Step 3: Commit

git add src/utils/fileValidator.js
git commit -m "feat: add file validation utility with type/size/name checks"

Task 2: 创建上传进度条组件

Files:

Create: src/components/ui/ProgressBar.vue

目标: 实现可视化上传进度条，支持百分比显示、动画效果、状态切换

Step 1: 编写 ProgressBar.vue 组件

<template>
  <div class="progress-bar-wrapper">
    <!-- 文件信息行 -->
    <div class="progress-info" v-if="showInfo">
      <span class="progress-filename" :title="filename">{{ filename }}</span>
      <span class="progress-stats">{{ statsText }}</span>
    </div>

    <!-- 进度条轨道 -->
    <div class="progress-track" :class="[status]">
      <div 
        class="progress-fill"
        :style="{ width: percent + '%' }"
        :class="{ animating: status === 'uploading' }"
      >
        <span v-if="percent >= 10" class="progress-text">{{ percent }}%</span>
      </div>
      
      <!-- 上传中状态图标 -->
      <LoadingOutlined v-if="status === 'uploading'" class="progress-icon spin" />
      
      <!-- 成功状态图标 -->
      <CheckCircleOutlined v-else-if="status === 'success'" class="progress-icon success" />
      
      <!-- 失败状态图标 -->
      <CloseCircleOutlined v-else-if="status === 'error'" class="progress-icon error" />
    </div>

    <!-- 状态文字提示 -->
    <div class="progress-hint" v-if="hintText">{{ hintText }}</div>
  </div>
</template>

<script setup>
import { computed } from 'vue'
import { LoadingOutlined, CheckCircleOutlined, CloseCircleOutlined } from '@ant-design/icons-vue'

const props = defineProps({
  percent: {
    type: Number,
    default: 0,
    validator: (val) => val >= 0 && val <= 100
  },
  status: {
    type: String,
    default: 'idle', // idle | uploading | success | error
    validator: (val) => ['idle', 'uploading', 'success', 'error'].includes(val)
  },
  filename: {
    type: String,
    default: ''
  },
  loaded: {
    type: Number,
    default: 0
  },
  total: {
    type: Number,
    default: 0
  },
  showInfo: {
    type: Boolean,
    default: true
  },
  error: {
    type: String,
    default: ''
  }
})

const statsText = computed(() => {
  if (props.total > 0) {
    const loadedMB = (props.loaded / 1024 / 1024).toFixed(1)
    const totalMB = (props.total / 1024 / 1024).toFixed(1)
    return `${loadedMB}MB / ${totalMB}MB`
  }
  return ''
})

const hintText = computed(() => {
  switch (props.status) {
    case 'uploading':
      return `上传中 ${props.percent}%...`
    case 'success':
      return '✅ 上传成功'
    case 'error':
      return `❌ 上传失败${props.error ? ': ' + props.error : ''}`
    default:
      return ''
  }
})
</script>

<style scoped>
.progress-bar-wrapper {
  width: 100%;
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
}

.progress-info {
  display: flex;
  justify-content: space-between;
  align-items: center;
  margin-bottom: 6px;
  font-size: 13px;
}

.progress-filename {
  font-weight: 500;
  color: #1f2937;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
  max-width: 60%;
}

.progress-stats {
  color: #6b7280;
  font-size: 12px;
  flex-shrink: 0;
}

.progress-track {
  position: relative;
  height: 8px;
  background: #e5e7eb;
  border-radius: 4px;
  overflow: hidden;
  transition: background-color 0.3s ease;
}

.progress-track.uploading {
  background: #dbeafe;
}

.progress-track.success {
  background: #d1fae5;
}

.progress-track.error {
  background: #fee2e2;
}

.progress-fill {
  height: 100%;
  border-radius: 4px;
  transition: width 0.3s ease;
  position: relative;
  display: flex;
  align-items: center;
  justify-content: flex-end;
  padding-right: 8px;
  min-width: 20px;
}

.progress-track.uploading .progress-fill {
  background: linear-gradient(90deg, #3b82f6 0%, #60a5fa 50%, #3b82f6 100%);
  background-size: 200% 100%;
  animation: progress-shimmer 1.5s infinite;
}

.progress-track.success .progress-fill {
  background: #10b981;
}

.progress-track.error .progress-fill {
  background: #ef4444;
}

.progress-fill.animating {
  animation: progress-pulse 1s ease-in-out infinite;
}

@keyframes progress-shimmer {
  0% { background-position: 200% 0; }
  100% { background-position: -200% 0; }
}

@keyframes progress-pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.7; }
}

.progress-text {
  color: white;
  font-size: 11px;
  font-weight: 600;
  line-height: 1;
}

.progress-icon {
  position: absolute;
  right: 8px;
  top: 50%;
  transform: translateY(-50%);
  font-size: 14px;
  z-index: 1;
}

.progress-icon.success {
  color: #10b981;
}

.progress-icon.error {
  color: #ef4444;
}

.progress-hint {
  margin-top: 4px;
  font-size: 12px;
  color: #6b7280;
  line-height: 1.4;
}

/* 响应式适配 */
@media (max-width: 640px) {
  .progress-info {
    flex-direction: column;
    align-items: flex-start;
    gap: 2px;
  }
  
  .progress-filename {
    max-width: 100%;
  }
}
</style>

Step 2: 测试组件渲染

在任意父组件中使用：

<ProgressBar 
  :percent="65" 
  status="uploading"
  filename="制度管理办法.docx"
  :loaded="1500000"
  :total="2300000"
/>

预期效果：

显示蓝色渐变进度条，65%填充
文件名 + "1.5MB / 2.3MB"
提示文字："上传中 65%..."
Step 3: Commit

git add src/components/ui/ProgressBar.vue
git commit -m "feat: add ProgressBar component with animation and status support"

Task 3: 创建拖拽上传区域组件

Files:

Create: src/components/ui/DropZone.vue

目标: 实现HTML5拖拽上传区域，支持多文件拖放、视觉反馈、自动验证

Step 1: 编写 DropZone.vue 组件

<template>
  <div 
    class="drop-zone"
    :class="{ 
      'is-dragging': isDragging,
      'is-disabled': disabled,
      'has-files': selectedFiles.length > 0
    }"
    @dragenter.prevent="onDragEnter"
    @dragover.prevent="onDragOver"
    @dragleave.prevent="onDragLeave"
    @drop.prevent="onDrop"
    @click="handleClick"
  >
    <!-- 默认状态内容 -->
    <div v-if="!isDragging && !disabled" class="drop-zone-content">
      <InboxOutlined class="drop-icon" :style="{ fontSize: iconSize + 'px' }" />
      <p class="drop-text">
        拖拽文件到此处，或<span class="link">点击选择</span>
      </p>
      <p class="drop-hint">
        支持 {{ acceptedTypesDisplay }}，最大 {{ maxSizeDisplay }}
      </p>
    </div>

    <!-- 拖拽悬停状态 -->
    <div v-else-if="isDragging && !disabled" class="drop-zone-active">
      <div class="active-border"></div>
      <span class="active-text">
        <CloudUploadOutlined class="active-icon" /> 
        释放文件以上传
      </span>
    </div>

    <!-- 禁用状态 -->
    <div v-else-if="disabled" class="drop-zone-disabled">
      <StopOutlined class="drop-icon" />
      <p class="drop-text">上传功能已禁用</p>
    </div>

    <!-- 已选文件预览 -->
    <div v-if="selectedFiles.length > 0" class="selected-files-preview">
      <div class="preview-header">
        <CheckCircleOutlined class="preview-success-icon" />
        <span>已选择 {{ selectedFiles.length }} 个文件</span>
        <button class="clear-btn" @click.stop="clearFiles">清除</button>
      </div>
      <div class="preview-list">
        <div 
          v-for="(file, index) in selectedFiles.slice(0, maxPreviewCount)" 
          :key="index"
          class="preview-item"
        >
          <FileTextOutlined class="preview-file-icon" />
          <span class="preview-name" :title="file.name">{{ file.name }}</span>
          <span class="preview-size">{{ formatSize(file.size) }}</span>
        </div>
        <div v-if="selectedFiles.length > maxPreviewCount" class="preview-more">
          还有 {{ selectedFiles.length - maxPreviewCount }} 个文件...
        </div>
      </div>
    </div>

    <!-- 隐藏的文件input -->
    <input
      ref="fileInputRef"
      type="file"
      :multiple="multiple"
      :accept="acceptedTypes"
      :disabled="disabled"
      @change="onFileSelected"
      style="display: none"
    />
  </div>
</template>

<script setup>
import { ref, computed } from 'vue'
import { 
  InboxOutlined, CloudUploadOutlined, StopOutlined,
  CheckCircleOutlined, FileTextOutlined
} from '@ant-design/icons-vue'
import { validateFiles, formatFileSize } from '../../utils/fileValidator.js'

const props = defineProps({
  acceptedTypes: {
    type: String,
    default: '.docx,.pdf,.txt,.md,.xlsx,.pptx'
  },
  maxSize: {
    type: Number,
    default: 50 * 1024 * 1024 // 50MB
  },
  multiple: {
    type: Boolean,
    default: true
  },
  disabled: {
    type: Boolean,
    default: false
  },
  iconSize: {
    type: Number,
    default: 48
  },
  maxPreviewCount: {
    type: Number,
    default: 3
  }
})

const emit = defineEmits(['files-selected', 'error', 'clear'])

const isDragging = ref(false)
const fileInputRef = ref(null)
const selectedFiles = ref([])

const acceptedTypesDisplay = computed(() => {
  return props.acceptedTypes.split(',').map(t => t.trim().replace('.', '')).join(' ')
})

const maxSizeDisplay = computed(() => {
  return formatFileSize(props.maxSize)
})

function onDragEnter(e) {
  if (props.disabled) return
  isDragging.value = true
}

function onDragOver(e) {
  if (props.disabled) return
  e.dataTransfer.dropEffect = 'copy'
}

function onDragLeave(e) {
  // 仅当鼠标完全离开元素时才取消高亮
  if (!e.currentTarget.contains(e.relatedTarget)) {
    isDragging.value = false
  }
}

function onDrop(e) {
  isDragging.value = false
  
  if (props.disabled) return
  
  const files = Array.from(e.dataTransfer.files)
  processFiles(files)
}

function handleClick() {
  if (props.disabled) return
  
  // 如果已选择文件且不允许多选，则清空重新选择
  if (selectedFiles.value.length > 0 && !props.multiple) {
    clearFiles()
  }
  
  fileInputRef.value?.click()
}

function onFileSelected(e) {
  const files = Array.from(e.target.files)
  processFiles(files)
  
  // 重置input以允许重复选择相同文件
  e.target.value = ''
}

function processFiles(files) {
  if (files.length === 0) return
  
  // 如果不支持多选，只取第一个
  const filesToProcess = props.multiple ? files : [files[0]]
  
  const { validFiles, invalidFiles } = validateFiles(filesToProcess)
  
  // 发出有效文件事件
  if (validFiles.length > 0) {
    if (props.multiple) {
      selectedFiles.value = [...selectedFiles.value, ...validFiles]
    } else {
      selectedFiles.value = validFiles
    }
    emit('files-selected', validFiles)
  }
  
  // 发出错误事件
  if (invalidFiles.length > 0) {
    emit('error', invalidFiles)
  }
}

function clearFiles() {
  selectedFiles.value = []
  emit('clear')
}

function formatSize(bytes) {
  return formatFileSize(bytes)
}

// 暴露方法给父组件
defineExpose({ clearFiles })
</script>

<style scoped>
.drop-zone {
  position: relative;
  border: 2px dashed #d1d5db;
  border-radius: 12px;
  padding: 32px 24px;
  text-align: center;
  cursor: pointer;
  transition: all 0.25s cubic-bezier(0.4, 0, 0.2, 1);
  background: #fafafa;
  user-select: none;
}

.drop-zone:hover:not(.is-disabled):not(.is-dragging) {
  border-color: #9ca3af;
  background: #f3f4f6;
}

.drop-zone.is-dragging {
  border-color: #3b82f6;
  background: #eff6ff;
  transform: scale(1.01);
  box-shadow: 0 0 0 4px rgba(59, 130, 246, 0.1);
}

.drop-zone.is-disabled {
  opacity: 0.5;
  cursor: not-allowed;
  background: #f9fafb;
}

.drop-zone-content {
  pointer-events: none;
}

.drop-icon {
  color: #9ca3af;
  margin-bottom: 12px;
  display: block;
  margin-left: auto;
  margin-right: auto;
}

.drop-text {
  margin: 0 0 8px 0;
  font-size: 15px;
  color: #374151;
  font-weight: 500;
}

.drop-text .link {
  color: #2563eb;
  text-decoration: underline;
  cursor: pointer;
}

.drop-hint {
  margin: 0;
  font-size: 13px;
  color: #9ca3af;
}

/* 拖拽悬停状态 */
.drop-zone-active {
  position: relative;
  padding: 40px 24px;
}

.active-border {
  position: absolute;
  inset: 0;
  border: 3px dashed #3b82f6;
  border-radius: 12px;
  animation: border-pulse 1s ease-in-out infinite;
  pointer-events: none;
}

@keyframes border-pulse {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.5; }
}

.active-text {
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 8px;
  font-size: 16px;
  font-weight: 600;
  color: #2563eb;
}

.active-icon {
  font-size: 20px;
}

/* 已选文件预览 */
.selected-files-preview {
  margin-top: 16px;
  padding-top: 16px;
  border-top: 1px solid #e5e7eb;
}

.preview-header {
  display: flex;
  align-items: center;
  gap: 8px;
  font-size: 13px;
  font-weight: 600;
  color: #059669;
  margin-bottom: 8px;
}

.preview-success-icon {
  font-size: 14px;
}

.clear-btn {
  margin-left: auto;
  background: none;
  border: none;
  color: #dc2626;
  cursor: pointer;
  font-size: 12px;
  padding: 2px 8px;
  border-radius: 4px;
  transition: background-color 0.15s;
}

.clear-btn:hover {
  background: #fee2e2;
}

.preview-list {
  display: flex;
  flex-direction: column;
  gap: 6px;
}

.preview-item {
  display: flex;
  align-items: center;
  gap: 8px;
  padding: 6px 10px;
  background: #f9fafb;
  border-radius: 6px;
  font-size: 13px;
}

.preview-file-icon {
  color: #6b7280;
  flex-shrink: 0;
}

.preview-name {
  flex: 1;
  overflow: hidden;
  text-overflow: ellipsis;
  white-space: nowrap;
  color: #374151;
}

.preview-size {
  color: #9ca3af;
  font-size: 12px;
  flex-shrink: 0;
}

.preview-more {
  font-size: 12px;
  color: #6b7280;
  font-style: italic;
  text-align: center;
  padding: 4px 0;
}

/* 响应式适配 */
@media (max-width: 640px) {
  .drop-zone {
    padding: 24px 16px;
  }
  
  .drop-zone-active {
    padding: 32px 16px;
  }
  
  .preview-item {
    font-size: 12px;
  }
}
</style>

Step 2: 测试拖拽功能

在页面中使用：

<DropZone 
  @files-selected="handleUpload"
  @error="handleError"
/>

测试场景：

从桌面拖拽 .docx 文件到区域 → 触发 files-selected 事件
拖拽 .exe 文件 → 触发 error 事件，显示错误信息
点击区域 → 打开文件选择对话框
同时拖拽多个文件 → 全部添加到预览列表

Step 3: Commit

git add src/components/ui/DropZone.vue
git commit -m "feat: add DropZone component with drag-and-drop and validation"

Task 4: 修改API层添加进度回调

Files:

Modify: src/api/file.js (第67-73行)

目标: 为 uploadFile 方法添加 onUploadProgress 回调参数，支持实时进度监控

Step 1: 修改 uploadFile 方法签名和实现

找到 src/api/file.js 第67-73行的 uploadFile 方法：

// 当前代码：
uploadFile: (formData) => {
  return apiClient.post('/file/upload', formData, {
    headers: {
      'Content-Type': 'multipart/form-data'
    }
  })
},

替换为：

uploadFile: (formData, onProgress) => {
  return apiClient.post('/file/upload', formData, {
    headers: {
      'Content-Type': 'multipart/form-data'
    },
    onUploadProgress: (progressEvent) => {
      // 仅在有回调函数且存在total时才触发
      if (typeof onProgress === 'function' && progressEvent.total) {
        const percentCompleted = Math.round(
          (progressEvent.loaded * 100) / progressEvent.total
        )
        
        onProgress({
          loaded: progressEvent.loaded,
          total: progressEvent.total,
          percent: percentCompleted,
          // 计算预估剩余时间（简单估算）
          estimatedTimeRemaining: calculateRemainingTime(progressEvent)
        })
      }
    }
  })
},

Step 2: 添加辅助计算函数

在 api/file.js 文件末尾（第124行之后）添加：

/**
 * 简单估算剩余时间（基于最近速度）
 * @param {ProgressEvent} progressEvent
 * @returns {number|null} 预估剩余秒数，无法估算时返回null
 */
function calculateRemainingTime(progressEvent) {
  if (!progressEvent.total || progressEvent.total === 0) return null
  
  const loaded = progressEvent.loaded
  const total = progressEvent.total
  const remaining = total - loaded
  
  // 简单线性估算（实际应使用更复杂的算法）
  // 这里假设速度恒定，返回秒数
  if (remaining <= 0) return 0
  
  // 由于无法获取精确时间戳，这里返回null
  // 实际应用中可以使用 performance.now() 记录时间差
  return null
}

Step 3: 测试新接口

// 使用示例：
import { fileAPI } from './api/file.js'

const formData = new FormData()
formData.append('file', fileObject)

fileAPI.uploadFile(formData, (progress) => {
  console.log(`上传进度: ${progress.percent}%`)
  console.log(`已上传: ${(progress.loaded / 1024 / 1024).toFixed(1)}MB`)
  // 更新UI进度条...
}).then(response => {
  console.log('上传完成:', response.data)
}).catch(error => {
  console.error('上传失败:', error)
})

Step 4: Commit

git add src/api/file.js
git commit -m "feat: add upload progress callback to fileAPI.uploadFile method"

Task 5: 集成增强功能到 FileSelector 组件

Files:

Modify: src/components/FileSelector.vue

目标: 将拖拽上传、文件验证、进度条集成到现有的 FileSelector 组件中

Step 1: 导入新组件和工具函数

在 <script setup> 部分顶部添加导入：

import { ref, watch, onMounted } from 'vue'
import { message } from 'ant-design-vue'
import { 
  FileTextOutlined, SearchOutlined, DownOutlined,
  CloseOutlined, LeftOutlined, RightOutlined,
  DatabaseOutlined, UnorderedListOutlined, CopyOutlined,
  InboxOutlined, FileSearchOutlined, LoadingOutlined,
  CloudUploadOutlined, UploadOutlined, DeleteOutlined
} from '@ant-design/icons-vue'
// 新增导入：
import DropZone from './ui/DropZone.vue'
import ProgressBar from './ui/ProgressBar.vue'
import { formatFileSize, validateFile } from '../utils/fileValidator.js'
import { fileAPI } from '../../api/file.js'

Step 2: 添加响应式变量和方法

在 script 中添加新的状态变量和方法：

// ===== 新增：上传相关状态 =====
const uploadingFiles = ref([])  // 正在上传的文件列表
const uploadProgress = ref({})  // 进度映射 { fileId: { percent, status } }

/**
 * 处理文件选择/拖拽
 */
async function handleFilesSelected(files) {
  for (const file of files) {
    await uploadSingleFile(file)
  }
}

/**
 * 上传单个文件
 */
async function uploadSingleFile(file) {
  const validation = validateFile(file)
  
  if (!validation.valid) {
    message.error(`${file.name}: ${validation.errors.join('; ')}`)
    return
  }
  
  const fileId = Date.now() + '_' + Math.random().toString(36).substr(2, 9)
  
  // 初始化进度状态
  uploadProgress.value[fileId] = {
    percent: 0,
    status: 'uploading',
    loaded: 0,
    total: file.size
  }
  
  uploadingFiles.value.push({
    id: fileId,
    name: file.name,
    size: file.size
  })
  
  try {
    const formData = new FormData()
    formData.append('file', file)
    
    // 调用带进度的上传接口
    const response = await fileAPI.uploadFile(formData, (progress) => {
      uploadProgress.value[fileId] = {
        ...progress,
        status: 'uploading'
      }
    })
    
    // 更新为成功状态
    uploadProgress.value[fileId] = {
      ...uploadProgress.value[fileId],
      percent: 100,
      status: 'success'
    }
    
    message.success(`✅ "${file.name}" 上传成功！`)
    
    // 刷新文件列表
    emit('file-uploaded', response.data?.data)
    
    // 3秒后从上传列表移除
    setTimeout(() => {
      uploadingFiles.value = uploadingFiles.value.filter(f => f.id !== fileId)
      delete uploadProgress.value[fileId]
    }, 3000)
    
  } catch (error) {
    // 更新为失败状态
    uploadProgress.value[fileId] = {
      ...uploadProgress.value[fileId],
      status: 'error',
      error: error.response?.data?.message || error.message || '网络错误'
    }
    
    message.error(`❌ "${file.name}" 上传失败`)
  }
}

/**
 * 处理验证错误
 */
function handleValidationError(errors) {
  errors.forEach(err => {
    message.warning(`⚠️ ${err.file.name}: ${err.errors.join(', ')}`)
  })
}

Step 3: 在 template 中添加上传UI

在 template 的合适位置（建议在 selector-panel 内部顶部）添加：

<!-- ===== 新增：增强型上传区域 ===== -->
<div class="enhanced-upload-section">
  <DropZone
    @files-selected="handleFilesSelected"
    @error="handleValidationError"
    :multiple="true"
    :accepted-types="'.docx,.pdf,.txt,.md,.xlsx,.pptx'"
    :max-size="52428800"
  />
  
  <!-- 正在上传的文件列表 -->
  <div v-if="uploadingFiles.length > 0" class="uploading-list">
    <div 
      v-for="file in uploadingFiles" 
      :key="file.id"
      class="uploading-item"
    >
      <ProgressBar
        :percent="uploadProgress[file.id]?.percent || 0"
        :status="uploadProgress[file.id]?.status || 'idle'"
        :filename="file.name"
        :loaded="uploadProgress[file.id]?.loaded || 0"
        :total="file.size"
        :error="uploadProgress[file.id]?.error"
      />
    </div>
  </div>
</div>

Step 4: 添加样式

在 <style scoped> 部分添加：

.enhanced-upload-section {
  margin-bottom: 16px;
}

.uploading-list {
  margin-top: 12px;
  display: flex;
  flex-direction: column;
  gap: 10px;
}

.uploading-item {
  background: white;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  padding: 12px;
}

Step 5: 测试完整上传流程

手动测试：

点击上传区域 → 选择有效文件 → 出现进度条 → 上传成功 → 3秒后消失
拖拽多个文件 → 多个进度条同时显示 → 依次完成
尝试上传 .exe 文件 → 显示友好错误提示
断网状态下上传 → 显示错误状态 + 错误信息

Step 6: Commit

git add src/components/FileSelector.vue
git commit -m "feat: integrate drag-drop upload, validation, and progress bar into FileSelector"

Task 6: 为 UploadTaskItem 添加重试按钮

Files:

Modify: src/components/exam/UploadTaskItem.vue

目标: 在任务状态卡片中添加一键重试按钮，方便用户快速恢复失败的任务

Step 1: 修改 template 部分

在第28-33行的错误详情按钮后面，添加重试按钮：

当前代码：

<button
  v-if="(vectorStatus.status === 'error' && vectorStatus.message) || (examStatus.status === 'error' && examStatus.message)"
  class="uti-detail"
  @click="toggleError"
>详情</button>

替换为：

<button
  v-if="(vectorStatus.status === 'error' && vectorStatus.message) || (examStatus.status === 'error' && examStatus.message)"
  class="uti-detail"
  @click="toggleError"
>详情</button>

<!-- 新增：一键重试按钮 -->
<button
  v-if="vectorStatus.status === 'error'"
  class="uti-retry"
  @click="handleRetry"
  :disabled="isRetrying"
>
  <LoadingOutlined v-if="isRetrying" spin />
  <ReloadOutlined v-else />
  重试
</button>

Step 2: 修改 script 部分

在第42-58行的 <script setup> 部分添加：

import { ref } from 'vue'
import {
  FileTextOutlined, LoadingOutlined, CheckCircleOutlined,
  CloseCircleOutlined, ClockCircleOutlined, MinusCircleOutlined,
  QuestionCircleOutlined, ReloadOutlined  // 新增导入
} from '@ant-design/icons-vue'

defineProps({
  task: { type: Object, required: true },
  vectorStatus: { type: Object, required: true },
  examStatus: { type: Object, required: true }
})

const emit = defineEmits(['retry'])  // 新增：定义retry事件

const showError = ref(false)
const isRetrying = ref(false)  // 新增：重试状态

function toggleError() { showError.value = !showError.value }

// 新增：处理重试点击
async function handleRetry() {
  if (isRetrying.value) return
  
  isRetrying.value = true
  
  try {
    emit('retry', {
      taskId: task.id,
      fileName: task.fileName
    })
    
    // 模拟等待响应（实际由父组件控制）
    await new Promise(resolve => setTimeout(resolve, 1000))
  } finally {
    // 1秒后重置按钮状态
    setTimeout(() => {
      isRetrying.value = false
    }, 1000)
  }
}

Step 3: 添加重试按钮样式

在 <style scoped> 部分的 .uti-detail 样式后添加：

.uti-retry {
  margin-left: auto;
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  border: none;
  color: white;
  cursor: pointer;
  font-size: var(--font-xs, 12px);
  padding: 2px 10px;
  border-radius: var(--radius-sm, 4px);
  transition: all 0.2s ease;
  line-height: 1.7;
  display: inline-flex;
  align-items: center;
  gap: 4px;
  font-weight: 500;
}

.uti-retry:hover:not(:disabled) {
  transform: translateY(-1px);
  box-shadow: 0 4px 12px rgba(102, 126, 234, 0.35);
}

.uti-retry:disabled {
  opacity: 0.6;
  cursor: not-allowed;
}

Step 4: 测试重试功能

在父组件中使用：

<UploadTaskItem
  :task="task"
  :vector-status="vs"
  :exam-status="es"
  @retry="handleTaskRetry"
/>

<script setup>
function handleTaskRetry({ taskId, fileName }) {
  console.log(`重试任务: ${fileName} (ID: ${taskId})`)
  // 调用重试API或重新上传逻辑
}
</script>

预期行为：

错误状态的卡片显示"🔄 重试"按钮
点击后按钮变为加载状态（转圈图标）
触发 retry 事件，传递 taskId 和 fileName
1秒后按钮恢复正常，可再次点击

Step 5: Commit

git add src/components/exam/UploadTaskItem.vue
git commit -m "feat: add retry button to UploadTaskItem for failed tasks"

Task 7: 实现智能轮询策略

Files:

Modify: src/components/exam/composables/useUploadTasks.js

目标: 将固定5秒轮询改为动态间隔策略（活跃3秒/空闲10秒/隐藏30秒）

Step 1: 修改轮询配置常量

在第5行附近，将：

const POLL_INTERVAL = 5000

替换为：

// 智能轮询配置（单位：毫秒）
const POLL_CONFIG = {
  active: 3000,       // 有活跃任务时：3秒快速反馈
  idle: 10000,        // 全部空闲时：10秒低频查询
  hidden: 30000,      // 页面不可见时：30秒节省资源
  maxInterval: 30000   // 最大间隔上限
}

Step 2: 添加智能轮询逻辑

在 startPolling() 函数之前（约第292行）插入以下代码：

let currentInterval = POLL_CONFIG.idle
let visibilityHandler = null

/**
 * 根据当前任务状态更新轮询策略
 */
function updatePollingStrategy() {
  const hasActiveTasks = shouldPoll()
  const isHidden = document.hidden
  
  let newInterval
  
  if (tasks.value.length === 0) {
    // 无任何任务 → 停止轮询
    newInterval = 0
  } else if (isHidden) {
    // 页面不可见 → 低频轮询
    newInterval = POLL_CONFIG.hidden
  } else if (hasActiveTasks) {
    // 有活跃任务 → 高频轮询
    newInterval = POLL_CONFIG.active
  } else {
    // 全部空闲 → 中频轮询
    newInterval = POLL_CONFIG.idle
  }
  
  // 仅当间隔变化时才重启定时器（避免不必要的重启）
  if (newInterval !== currentInterval) {
    const oldInterval = currentInterval
    currentInterval = newInterval
    
    console.log(`[useUploadTasks] 轮询策略调整: ${oldInterval}ms → ${newInterval}ms`, {
      hasActiveTasks,
      isHidden,
      totalTasks: tasks.value.length
    })
    
    stopPolling()
    
    if (newInterval > 0) {
      pollTimer = setInterval(pollOnce, newInterval)
    }
  }
}

/**
 * 设置页面可见性监听器
 */
function setupVisibilityListener() {
  if (visibilityHandler) return  // 避免重复绑定
  
  visibilityHandler = () => {
    updatePollingStrategy()
  }
  
  document.addEventListener('visibilitychange', visibilityHandler)
  console.log('[useUploadTasks] 页面可见性监听已启用')
}

/**
 * 清除页面可见性监听器
 */
function teardownVisibilityListener() {
  if (visibilityHandler) {
    document.removeEventListener('visibilitychange', visibilityHandler)
    visibilityHandler = null
  }
}

Step 3: 修改 startPolling 和 stopPolling 函数

将原有的：

function startPolling() {
  stopPolling()
  pollTimer = setInterval(pollOnce, POLL_INTERVAL)
}

function stopPolling() {
  if (pollTimer) {
    clearInterval(pollTimer)
    pollTimer = null
  }
}

替换为：

function startPolling() {
  stopPolling()
  
  // 初始化策略并启动
  updatePollingStrategy()
  setupVisibilityListener()
  
  console.log(`[useUploadTasks] 智能轮询已启动 (初始间隔: ${currentInterval}ms)`)
}

function stopPolling() {
  if (pollTimer) {
    clearInterval(pollTimer)
    pollTimer = null
  }
  
  teardownVisibilityListener()
  currentInterval = 0
  
  console.log('[useUploadTasks] 轮询已停止')
}

Step 4: 修改生命周期钩子

在 onUnmounted 中确保清理可见性监听器：

onUnmounted(() => {
  stopPolling()
  // teardownVisibilityListener 已在 stopPolling 中调用
})

并在组件挂载时自动启动（如果已有任务的话）。可以在 return 语句之前添加：

// 自动初始化（如果已有任务则立即开始轮询）
if (tasks.value.length > 0) {
  startPolling()
}

Step 5: 测试智能轮询

打开浏览器控制台，观察日志输出：

正常情况：

[useUploadTasks] 智能轮询已启动 (初始间隔: 10000ms)
[useUploadTasks] 页面可见性监听已启用

模拟有活跃任务（手动将某个任务状态改为VECTORIZING）：
```
[useUploadTasks] 轮询策略调整: 10000ms → 3000ms
```

切换到其他标签页（隐藏页面）：

[useUploadTasks] 轮询策略调整: 3000ms → 30000ms

回到页面：

[useUploadTasks] 轮询策略调整: 30000ms → 3000ms (如果有活跃任务)

Step 6: Commit

git add src/components/exam/composables/useUploadTasks.js
git commit -m "perf: implement smart polling strategy (3s/10s/30s dynamic intervals)"

Task 8: 创建 Toast 通知组件

Files:

Create: src/components/ui/ToastNotification.vue
Create: src/utils/notification.js

目标: 实现全局Toast通知系统，用于展示上传成功/失败、任务状态变更等消息

Step 1: 编写 notification.js 工具函数

/**
 * Toast通知工具函数
 * 用于全局显示通知消息
 */

let toastContainer = null
let toastIdCounter = 0
const MAX_VISIBLE_TOASTS = 3
const DEFAULT_DURATION = {
  success: 3000,
  error: 5000,
  info: 4000,
  warning: 4500
}

/**
 * 确保toast容器存在
 */
function ensureContainer() {
  if (toastContainer) return
  
  toastContainer = document.createElement('div')
  toastContainer.id = 'toast-container'
  toastContainer.setAttribute('role', 'alert')
  toastContainer.setAttribute('aria-live', 'polite')
  
  Object.assign(toastContainer.style, {
    position: 'fixed',
    bottom: '20px',
    right: '20px',
    zIndex: '99999',
    display: 'flex',
    flexDirection: 'column-reverse',
    gap: '10px',
    maxWidth: '400px',
    pointerEvents: 'none'
  })
  
  document.body.appendChild(toastContainer)
}

/**
 * 创建单个toast元素
 */
function createToastElement({ id, type, title, message, duration, closable }) {
  const toast = document.createElement('div')
  toast.id = `toast-${id}`
  toast.className = `toast toast-${type}`
  toast.setAttribute('role', 'status')
  
  const icons = {
    success: '✅',
    error: '❌',
    info: 'ℹ️',
    warning: '⚠️'
  }
  
  toast.innerHTML = `
    <div class="toast-content">
      <span class="toast-icon">${icons[type] || ''}</span>
      <div class="toast-body">
        ${title ? `<div class="toast-title">${title}</div>` : ''}
        ${message ? `<div class="toast-message">${message}</div>` : ''}
      </div>
      ${closable ? '<button class="toast-close" aria-label="关闭">&times;</button>' : ''}
    </div>
    <div class="toast-progress" style="animation-duration: ${duration}ms"></div>
  `
  
  // 关闭按钮事件
  if (closable) {
    const closeBtn = toast.querySelector('.toast-close')
    closeBtn.addEventListener('click', () => removeToast(id))
  }
  
  return toast
}

/**
 * 移除指定toast
 */
function removeToast(id) {
  const toast = document.getElementById(`toast-${id}`)
  if (!toast) return
  
  toast.classList.add('toast-exit')
  
  setTimeout(() => {
    toast.remove()
    // 检查是否需要调整容器位置
    adjustContainerPosition()
  }, 300)
}

/**
 * 调整容器位置（防止过多toast超出屏幕）
 */
function adjustContainerPosition() {
  if (!toastContainer) return
  
  const toasts = toastContainer.querySelectorAll('.toast')
  const containerRect = toastContainer.getBoundingClientRect()
  const viewportHeight = window.innerHeight
  
  if (containerRect.top < 80) {
    toastContainer.style.bottom = 'auto'
    toastContainer.style.top = '20px'
  } else {
    toastContainer.style.bottom = '20px'
    toastContainer.style.top = 'auto'
  }
}

/**
 * 显示通知（主入口函数）
 * @param {Object} options
 * @param {string} options.type - 类型: success | error | info | warning
 * @param {string} [options.title] - 标题（可选）
 * @param {string} options.message - 消息内容
 * @param {number} [options.duration] - 显示时长(ms)，默认根据type自动设置
 * @param {boolean} [options.closable=true] - 是否可关闭
 * @returns {string} toast ID，可用于手动关闭
 */
export function showToast(options) {
  ensureContainer()
  
  const {
    type = 'info',
    title = '',
    message = '',
    duration = DEFAULT_DURATION[type] || 4000,
    closable = true
  } = options
  
  const id = ++toastIdCounter
  
  // 限制同时显示数量
  const existingToasts = toastContainer.querySelectorAll('.toast')
  if (existingToasts.length >= MAX_VISIBLE_TOASTS) {
    // 移除最旧的toast
    const oldestToast = existingToasts[0]
    if (oldestToast) {
      const oldId = parseInt(oldestToast.id.replace('toast-', ''))
      removeToast(oldId)
    }
  }
  
  // 创建并添加toast
  const toastElement = createToastElement({
    id,
    type,
    title,
    message,
    duration,
    closable
  })
  
  toastContainer.appendChild(toastElement)
  
  // 强制重绘以触发进入动画
  toastElement.offsetHeight
  
  // 自动移除
  if (duration > 0) {
    setTimeout(() => {
      removeToast(id)
    }, duration)
  }
  
  return `toast-${id}`
}

/**
 * 快捷方法：成功通知
 */
export function notifySuccess(message, title = '操作成功') {
  return showToast({ type: 'success', title, message })
}

/**
 * 快捷方法：错误通知
 */
export function notifyError(message, title = '操作失败') {
  return showToast({ type: 'error', title, message })
}

/**
 * 快捷方法：信息通知
 */
export function notifyInfo(message, title = '提示') {
  return showToast({ type: 'info', title, message })
}

/**
 * 快捷方法：警告通知
 */
export function notifyWarning(message, title = '注意') {
  return showToast({ type: 'warning', title, message })
}

/**
 * 清除所有通知
 */
export function clearAllToasts() {
  if (!toastContainer) return
  
  const toasts = toastContainer.querySelectorAll('.toast')
  toasts.forEach(toast => toast.remove())
}

export default {
  showToast,
  notifySuccess,
  notifyError,
  notifyInfo,
  notifyWarning,
  clearAllToasts
}

Step 2: 编写 Toast 样式（注入到head）

在 notification.js 文件末尾添加样式注入函数：

/**
 * 注入Toast样式（仅执行一次）
 */
let stylesInjected = false

function injectStyles() {
  if (stylesInjected || typeof document === 'undefined') return
  
  const styleEl = document.createElement('style')
  styleEl.textContent = `
    #toast-container {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
    }
    
    .toast {
      min-width: 280px;
      max-width: 400px;
      padding: 14px 16px;
      border-radius: 10px;
      box-shadow: 0 4px 20px rgba(0, 0, 0, 0.15);
      backdrop-filter: blur(10px);
      background: rgba(255, 255, 255, 0.95);
      pointer-events: auto;
      animation: toast-enter 0.3s cubic-bezier(0.21, 1.02, 0.73, 1);
      transform: translateX(100%);
      opacity: 0;
    }
    
    @keyframes toast-enter {
      from {
        transform: translateX(100%);
        opacity: 0;
      }
      to {
        transform: translateX(0);
        opacity: 1;
      }
    }
    
    .toast-exit {
      animation: toast-exit 0.3s ease-in forwards;
    }
    
    @keyframes toast-exit {
      to {
        transform: translateX(100%);
        opacity: 0;
      }
    }
    
    .toast-content {
      display: flex;
      align-items: flex-start;
      gap: 10px;
    }
    
    .toast-icon {
      font-size: 18px;
      flex-shrink: 0;
      margin-top: 2px;
    }
    
    .toast-body {
      flex: 1;
      min-width: 0;
    }
    
    .toast-title {
      font-size: 14px;
      font-weight: 600;
      color: #1f2937;
      margin-bottom: 4px;
      line-height: 1.3;
    }
    
    .toast-message {
      font-size: 13px;
      color: #4b5563;
      line-height: 1.4;
      word-break: break-word;
    }
    
    .toast-close {
      flex-shrink: 0;
      background: none;
      border: none;
      font-size: 18px;
      color: #9ca3af;
      cursor: pointer;
      padding: 0 2px;
      line-height: 1;
      transition: color 0.15s;
    }
    
    .toast-close:hover {
      color: #4b5563;
    }
    
    .toast-progress {
      position: absolute;
      bottom: 0;
      left: 0;
      height: 3px;
      border-radius: 0 0 10px 10px;
      animation: toast-timer linear forwards;
    }
    
    @keyframes toast-timer {
      from { width: 100%; }
      to { width: 0%; }
    }
    
    /* 类型特定样式 */
    .toast-success {
      border-left: 4px solid #10b981;
    }
    
    .toast-success .toast-progress {
      background: #10b981;
    }
    
    .toast-error {
      border-left: 4px solid #ef4444;
    }
    
    .toast-error .toast-progress {
      background: #ef4444;
    }
    
    .toast-info {
      border-left: 4px solid #3b82f6;
    }
    
    .toast-info .toast-progress {
      background: #3b82f6;
    }
    
    .toast-warning {
      border-left: 4px solid #f59e0b;
    }
    
    .toast-warning .toast-progress {
      background: #f59e0b;
    }
    
    /* 移动端适配 */
    @media (max-width: 480px) {
      #toast-container {
        left: 10px;
        right: 10px;
        max-width: calc(100vw - 20px);
      }
      
      .toast {
        min-width: auto;
        max-width: 100%;
      }
    }
  `
  
  document.head.appendChild(styleEl)
  stylesInjected = true
}

// 首次调用showToast时自动注入样式
const originalShowToast = showToast
showToast = function(options) {
  injectStyles()
  return originalShowToast(options)
}

Step 3: 测试通知功能

在浏览器控制台中执行：

import { notifySuccess, notifyError } from './utils/notification.js'

// 测试成功通知
notifySuccess('文件"制度管理办法.docx"上传成功')

// 测试错误通知
notifyError('向量化失败：服务器内部错误')

// 3秒后会自动消失

预期效果：

右下角弹出通知卡片
带有进度条倒计时动画
可点击 × 手动关闭
最多同时显示3条
Step 4: Commit

git add src/utils/notification.js
git commit -m "feat: add global Toast notification system with auto-dismiss"

Task 9: 创建骨架屏加载组件

Files:

Create: src/components/ui/SkeletonCard.vue

目标: 实现通用骨架屏加载占位组件，提升首屏加载体验

Step 1: 编写 SkeletonCard.vue 组件

<template>
  <div class="skeleton-card" :class="[variant, { animated }]">
    <!-- 标题行骨架 -->
    <div v-if="showTitle" class="skeleton-title"></div>
    
    <!-- 内容行骨架 -->
    <div 
      v-for="i in lines" 
      :key="i" 
      class="skeleton-line"
      :style="{ width: getLineWidth(i) }"
    ></div>
    
    <!-- 底部操作栏骨架 -->
    <div v-if="showActions" class="skeleton-actions">
      <div class="skeleton-button short"></div>
      <div class="skeleton-button long"></div>
    </div>
  </div>
</template>

<script setup>
import { computed } from 'vue'

const props = defineProps({
  lines: {
    type: Number,
    default: 3
  },
  variant: {
    type: String,
    default: 'default', // default | compact | detailed
    validator: (val) => ['default', 'compact', 'detailed'].includes(val)
  },
  showTitle: {
    type: Boolean,
    default: true
  },
  showActions: {
    type: Boolean,
    default: false
  },
  animated: {
    type: Boolean,
    default: true
  }
})

function getLineWidth(index) {
  // 骨架线宽度随机变化（70%-100%），但保持确定性以便SSR
  const widths = ['85%', '95%', '78%', '90%', '82%', '88%', '92%', '75%', '87%', '96%']
  return widths[index % widths.length]
}
</script>

<style scoped>
.skeleton-card {
  padding: 16px;
  background: white;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
}

.skeleton-title {
  height: 18px;
  width: 60%;
  margin-bottom: 12px;
  border-radius: 4px;
  background: linear-gradient(90deg, #f3f4f6 25%, #e5e7eb 50%, #f3f4f6 75%);
  background-size: 200% 100%;
}

.skeleton-line {
  height: 14px;
  margin-bottom: 8px;
  border-radius: 4px;
  background: linear-gradient(90deg, #f3f4f6 25%, #e5e7eb 50%, #f3f4f6 75%);
  background-size: 200% 100%;
}

.skeleton-line:last-child {
  margin-bottom: 0;
}

.skeleton-actions {
  display: flex;
  justify-content: flex-end;
  gap: 10px;
  margin-top: 16px;
  padding-top: 12px;
  border-top: 1px solid #f3f4f6;
}

.skeleton-button {
  height: 30px;
  border-radius: 6px;
  background: linear-gradient(90deg, #f3f4f6 25%, #e5e7eb 50%, #f3f4f6 75%);
  background-size: 200% 100%;
}

.skeleton-button.short {
  width: 70px;
}

.skeleton-button.long {
  width: 110px;
}

/* 动画效果 */
.skeleton-card.animated .skeleton-title,
.skeleton-card.animated .skeleton-line,
.skeleton-card.animated .skeleton-button {
  animation: skeleton-shimmer 1.5s ease-in-out infinite;
}

@keyframes skeleton-shimmer {
  0% {
    background-position: 200% 0;
  }
  100% {
    background-position: -200% 0;
  }
}

/* 变体样式 */
.skeleton-card.compact {
  padding: 12px;
}

.skeleton-card.compact .skeleton-title {
  height: 14px;
  width: 45%;
  margin-bottom: 8px;
}

.skeleton-card.compact .skeleton-line {
  height: 11px;
  margin-bottom: 6px;
}

.skeleton-card.detailed {
  padding: 20px;
}

.skeleton-card.detailed .skeleton-title {
  height: 22px;
  width: 70%;
  margin-bottom: 16px;
}

.skeleton-card.detailed .skeleton-line {
  height: 16px;
  margin-bottom: 10px;
}

/* 深色模式支持（可选） */
@media (prefers-color-scheme: dark) {
  .skeleton-title,
  .skeleton-line,
  .skeleton-button {
    background: linear-gradient(90deg, #374151 25%, #4b5563 50%, #374151 75%);
    background-size: 200% 100%;
  }
  
  .skeleton-card {
    background: #1f2937;
    border-color: #374151;
  }
}
</style>

Step 2: 测试骨架屏组件

<template>
  <div>
    <!-- 默认变体 -->
    <SkeletonCard :lines="4" :animated="true" />
    
    <!-- 紧凑变体 -->
    <SkeletonCard variant="compact" :lines="2" />
    
    <!-- 详细变体（带操作按钮） -->
    <SkeletonCard variant="detailed" :lines="5" :show-actions="true" />
  </div>
</template>

预期效果：

显示脉冲动画的灰色占位块
模拟真实内容的布局结构
动画流畅自然
Step 3: Commit

git add src/components/ui/SkeletonCard.vue
git commit -m "feat: add SkeletonCard loading placeholder component with variants"

Task 10: 集成所有优化并端到端测试

Files:

Multiple files (integration testing)

目标: 验证所有增强功能协同工作，确保无回归问题

Step 1: 运行构建验证

npm run build

预期结果：

✅ 构建成功（exit code 0）
✅ 无编译错误或警告
✅ 输出文件生成正常
Step 2: 功能集成检查清单

逐项验证以下功能点：

文件上传增强：

拖拽文件到上传区域 → 触发文件选择
选择 .docx/.pdf 文件 → 通过验证并开始上传
选择 .exe 文件 → 显示友好错误提示
选择 >50MB 文件 → 显示大小超限提示
上传过程中 → 进度条实时更新百分比
上传成功 → 显示绿色成功状态 + Toast通知
上传失败 → 显示红色错误状态 + 错误详情

任务状态优化：

任务处于 VECTORIZING 状态 → 图标旋转动画
任务失败 → 显示重试按钮
点击重试 → 按钮变为loading → 触发重试逻辑
页面切换到后台 → 控制台显示轮询间隔调整为30秒
回到前台且有活跃任务 → 轮询间隔恢复为3秒
所有任务完成 → 轮询间隔变为10秒

UI/UX改进：

Toast通知正确显示在右下角
通知3-5秒后自动消失
骨架屏在数据加载时正确显示
移动端布局无严重错位
所有交互元素触控区域 ≥ 44px
Step 3: 性能基准测试

使用浏览器DevTools Performance面板：

// 在控制台运行性能测试
console.time('UploadFlowTest')
// 执行完整的上传流程
console.timeEnd('UploadFlowTest')
// 预期: < 2000ms (不含网络等待时间)

console.time('RenderTest')
// 强制刷新组件多次
console.timeEnd('RenderTest')
// 预期: < 100ms per render

Step 4: 浏览器兼容性测试

在以下浏览器中验证核心功能：

浏览器	版本	拖拽上传	进度条	动画	Toast
Chrome	90+	✅	✅	✅	✅
Firefox	88+	✅	✅	✅	✅
Safari	14+	✅	✅	✅	✅
Edge	90+	✅	✅	✅	✅

Step 5: 最终Commit

git add .
git commit -m "feat: complete file upload and task status optimization (Phase A)

Enhancements:
- Add drag-and-drop upload with visual feedback
- Implement real-time upload progress bar
- Add client-side file validation (type/size/name)
- Add one-click retry button for failed tasks
- Implement smart polling strategy (3s/10s/30s dynamic)
- Create global Toast notification system
- Add SkeletonCard loading placeholder
- Improve mobile responsiveness

Components created:
- ui/ProgressBar.vue
- ui/DropZone.vue
- ui/ToastNotification.vue
- ui/SkeletonCard.vue
- utils/fileValidator.js
- utils/notification.js

Modified:
- api/file.js (added progress callback)
- components/FileSelector.vue (integrated enhancements)
- components/exam/UploadTaskItem.vue (added retry button)
- components/exam/composables/useUploadTasks.js (smart polling)"

📊 自检清单

Spec Coverage（需求覆盖度检查）

设计文档章节	对应Task	状态
FR-01: 上传进度条	Task 2 + Task 5	✅
FR-02: 拖拽上传	Task 3 + Task 5	✅
FR-03: 前端文件验证	Task 1 + Task 3	✅
FR-04: 上传前预览	Task 3	✅
FR-05: 友好错误处理	Task 1 + Task 5	✅
FR-06: 一键重试按钮	Task 6	✅
FR-07: 批量删除	⏭️ Phase B考虑	📝
FR-08: Toast通知系统	Task 8	✅
FR-09: 智能轮询策略	Task 7	✅
FR-10: 加载骨架屏	Task 9	✅

Placeholder Scan（占位符扫描）

❌ 无 TBD/TODO 占位符
❌ 无"实现细节待定"描述
✅ 所有步骤都包含完整代码
✅ 所有文件路径都是绝对路径

Type Consistency（类型一致性检查）

✅ 函数命名一致（camelCase）
✅ 事件命名一致（kebab-case）
✅ CSS类名一致（kebab-case）
✅ Props定义类型完整
✅ Emit事件参数明确

🎯 下一步行动

计划已完成并保存至: docs/superpowers/plans/2026-05-30-file-upload-task-optimization-plan.md

两种执行方式可供选择：

1. Subagent-Driven (推荐) - 我将为每个Task派遣独立的子代理执行，每个任务完成后进行审查，快速迭代

2. Inline Execution - 在当前会话中使用 executing-plans 技能批量执行，带有检查点进行审查

您希望使用哪种方式？

55 KiB Raw Blame History Unescape Escape

文件上传与任务状态管理优化实施计划

📁 文件结构规划

新增文件（7个）

修改文件（3个）

Task 1: 创建文件验证工具函数

Task 2: 创建上传进度条组件

Task 3: 创建拖拽上传区域组件

Task 4: 修改API层添加进度回调

Task 5: 集成增强功能到 FileSelector 组件

Task 6: 为 UploadTaskItem 添加重试按钮

Task 7: 实现智能轮询策略

Task 8: 创建 Toast 通知组件

Task 9: 创建骨架屏加载组件

Task 10: 集成所有优化并端到端测试

📊 自检清单

Spec Coverage（需求覆盖度检查）

Placeholder Scan（占位符扫描）

Type Consistency（类型一致性检查）

🎯 下一步行动

55 KiB

Raw Blame History