718 lines
21 KiB
Markdown
718 lines
21 KiB
Markdown
# 文件上传与任务状态管理优化设计文档
|
||
|
||
**方案选择**：A - 渐进式增强（用户体验优先）
|
||
**版本**：V1.0
|
||
**日期**：2026-05-30
|
||
**状态**：待审核
|
||
|
||
---
|
||
|
||
## 1. 设计概述
|
||
|
||
### 1.1 项目背景
|
||
|
||
基于《文件管理接口文档》（V2.12.0）规范，对现有文件上传功能和文件列表下的任务向量化/出题状态组件进行系统性用户体验优化。
|
||
|
||
### 1.2 优化目标
|
||
|
||
- **主要目标**：提升用户交互体验，增强功能易用性和反馈机制
|
||
- **次要目标**：改善性能表现，优化错误处理流程
|
||
- **非目标**：不进行架构重构，不改变核心数据流，不引入新技术栈
|
||
|
||
### 1.3 设计原则
|
||
|
||
1. **KISS原则**：保持简单，避免过度工程化
|
||
2. **增量改进**：每个优化点独立可回滚
|
||
3. **向后兼容**：不破坏现有API和组件接口
|
||
4. **用户驱动**：所有改进围绕实际使用场景
|
||
5. **渐进增强**：在现有代码基础上添加功能，不重写
|
||
|
||
---
|
||
|
||
## 2. 当前实现分析
|
||
|
||
### 2.1 现有架构
|
||
|
||
```
|
||
前端组件结构：
|
||
├── FileSelector.vue # 文件选择器（用于AI对话中选择文件）
|
||
├── exam/
|
||
│ ├── UploadTaskItem.vue # 任务状态展示卡片
|
||
│ ├── composables/
|
||
│ │ ├── useUploadTasks.js # 任务状态管理逻辑
|
||
│ │ └── useTaskManager.js # 任务管理器
|
||
│ ├── GeneratePanel.vue # 向量化/出题面板
|
||
│ └── ExamModuleContainer.vue
|
||
├── api/
|
||
│ └── file.js # 文件API接口定义
|
||
└── views/
|
||
└── ReaderPage.vue # 文档阅读页面
|
||
```
|
||
|
||
### 2.2 已识别问题清单
|
||
|
||
#### **P0 - 必须修复（影响核心功能）**
|
||
|
||
| 问题ID | 问题描述 | 影响范围 | 严重程度 |
|
||
|--------|---------|----------|----------|
|
||
| P0-01 | 无上传进度条显示 | 文件上传体验 | 🔴 高 |
|
||
| P0-02 | 错误状态无重试机制 | 任务失败处理 | 🔴 高 |
|
||
| P0-03 | 轮询策略固定（5秒间隔） | 性能浪费 | 🟡 中 |
|
||
|
||
#### **P1 - 应该改进（显著提升体验）**
|
||
|
||
| 问题ID | 问题描述 | 影响范围 | 严重程度 |
|
||
|--------|---------|----------|----------|
|
||
| P1-01 | 不支持拖拽上传 | 上传便捷性 | 🟡 中 |
|
||
| P1-02 | 无前端文件验证 | 错误预防 | 🟡 中 |
|
||
| P1-03 | 错误提示不够友好 | 用户理解 | 🟡 中 |
|
||
| P1-04 | 不支持批量操作 | 效率提升 | 🟢 低 |
|
||
| P1-05 | 移动端适配不完善 | 多设备支持 | 🟢 低 |
|
||
|
||
#### **P2 - 可以优化（锦上添花）**
|
||
|
||
| 问题ID | 问题描述 | 影响范围 | 严重程度 |
|
||
|--------|---------|----------|----------|
|
||
| P2-01 | 无状态变更通知提醒 | 用户感知 | 🟢 低 |
|
||
| P2-02 | 缺少加载骨架屏 | 视觉体验 | 🟢 低 |
|
||
| P2-03 | 任务列表无虚拟滚动 | 大列表性能 | 🟢 低 |
|
||
|
||
---
|
||
|
||
## 3. 详细设计方案
|
||
|
||
### 3.1 模块一：文件上传增强（优先级：🔴 最高）
|
||
|
||
#### **3.1.1 功能需求**
|
||
|
||
##### **FR-01: 上传进度条**
|
||
- **描述**：显示实时上传百分比和预计剩余时间
|
||
- **触发条件**：文件大小 > 1MB 或上传时间 > 2秒时自动显示
|
||
- **UI设计**：
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ 📄 制度管理办法.docx (2.3MB) │
|
||
│ ████████████░░░░░░ 65% 剩余 3秒 │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
##### **FR-02: 拖拽上传支持**
|
||
- **描述**：支持将文件从桌面/资源管理器拖拽到上传区域
|
||
- **技术方案**：HTML5 Drag and Drop API
|
||
- **交互细节**：
|
||
- 拖拽悬停时：边框高亮 + 提示文字"释放以上传"
|
||
- 拖拽离开时：恢复原状
|
||
- 支持多文件同时拖拽
|
||
|
||
##### **FR-03: 前端文件验证**
|
||
- **验证规则**：
|
||
- ✅ 支持的文件类型：`.docx, .pdf, .txt, .md, .xlsx, .pptx`
|
||
- ✅ 最大文件大小：50MB（可配置）
|
||
- ✅ 文件名长度：≤200字符
|
||
- ✅ 特殊字符检查（禁止 `\ / : * ? " < > |`）
|
||
- **错误提示**：
|
||
- 类型不支持："❌ 不支持的文件格式，请上传 .docx/.pdf/.txt 等文档"
|
||
- 文件过大："❌ 文件超过50MB限制，请压缩后重试"
|
||
- 其他错误："⚠️ 文件验证失败：{具体原因}"
|
||
|
||
##### **FR-04: 上传前预览**
|
||
- **预览信息**：
|
||
- 文件图标（根据扩展名显示不同图标）
|
||
- 文件名（高亮显示）
|
||
- 文件大小（格式化为KB/MB）
|
||
- 文件类型标签（如"Word文档"、"PDF文件"）
|
||
|
||
##### **FR-05: 友好的错误处理**
|
||
- **错误分类**：
|
||
- 🌐 **网络错误**：连接超时、服务器无响应
|
||
- 📁 **文件错误**：格式不支持、文件损坏
|
||
- 🔐 **权限错误**：未登录、无上传权限
|
||
- ⚙️ **服务器错误**：500内部错误、存储空间不足
|
||
- **错误展示**：
|
||
- 图标 + 标题 + 详细说明 + 操作建议
|
||
- 示例：
|
||
```
|
||
⚠️ 上传失败
|
||
|
||
原因：服务器响应超时（>60秒）
|
||
|
||
建议：
|
||
• 检查网络连接是否正常
|
||
• 尝试压缩文件后重新上传
|
||
• 如持续失败，请联系管理员
|
||
|
||
[重新上传] [取消]
|
||
```
|
||
|
||
#### **3.1.2 技术实现方案**
|
||
|
||
##### **修改文件清单**：
|
||
|
||
| 文件路径 | 改动类型 | 改动量 | 说明 |
|
||
|---------|---------|--------|------|
|
||
| `src/components/FileSelector.vue` | 修改 | ~150行 | 添加拖拽、验证、进度条 |
|
||
| `src/api/file.js` | 修改 | ~20行 | 添加onUploadProgress回调 |
|
||
| `src/utils/fileValidator.js` | 新增 | ~80行 | 文件验证工具函数 |
|
||
| `src/components/ui/ProgressBar.vue` | 新增 | ~60行 | 可复用进度条组件 |
|
||
| `src/components/ui/DropZone.vue` | 新增 | ~90行 | 拖拽上传区域组件 |
|
||
|
||
##### **核心代码示例**：
|
||
|
||
**Axios进度监听** (`src/api/file.js`)：
|
||
```javascript
|
||
uploadFile: (formData, onProgress) => {
|
||
return apiClient.post('/file/upload', formData, {
|
||
headers: { 'Content-Type': 'multipart/form-data' },
|
||
onUploadProgress: (progressEvent) => {
|
||
if (onProgress && progressEvent.total) {
|
||
const percentCompleted = Math.round(
|
||
(progressEvent.loaded * 100) / progressEvent.total
|
||
)
|
||
onProgress({
|
||
loaded: progressEvent.loaded,
|
||
total: progressEvent.total,
|
||
percent: percentCompleted
|
||
})
|
||
}
|
||
}
|
||
})
|
||
}
|
||
```
|
||
|
||
**拖拽上传组件** (`src/components/ui/DropZone.vue`)：
|
||
```vue
|
||
<template>
|
||
<div
|
||
class="drop-zone"
|
||
:class="{ 'is-dragging': isDragging }"
|
||
@dragenter.prevent="onDragEnter"
|
||
@dragover.prevent="onDragOver"
|
||
@dragleave.prevent="onDragLeave"
|
||
@drop.prevent="onDrop"
|
||
@click="$refs.fileInput.click()"
|
||
>
|
||
<div v-if="!isDragging" class="drop-zone-content">
|
||
<InboxOutlined class="drop-icon" />
|
||
<p class="drop-text">拖拽文件到此处，或<span class="link">点击选择</span></p>
|
||
<p class="drop-hint">支持 .docx .pdf .txt .xlsx .pptx，最大 50MB</p>
|
||
</div>
|
||
<div v-else class="drop-zone-active">
|
||
<span class="active-text">📥 释放文件以上传</span>
|
||
</div>
|
||
<input
|
||
ref="fileInput"
|
||
type="file"
|
||
multiple
|
||
:accept="acceptedTypes"
|
||
@change="onFileSelected"
|
||
style="display: none"
|
||
/>
|
||
</div>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref } from 'vue'
|
||
import { InboxOutlined } from '@ant-design/icons-vue'
|
||
|
||
const props = defineProps({
|
||
acceptedTypes: {
|
||
type: String,
|
||
default: '.docx,.pdf,.txt,.md,.xlsx,.pptx'
|
||
},
|
||
maxSize: {
|
||
type: Number,
|
||
default: 50 * 1024 * 1024 // 50MB
|
||
}
|
||
})
|
||
|
||
const emit = defineEmits(['files-selected', 'error'])
|
||
|
||
const isDragging = ref(false)
|
||
const fileInput = ref(null)
|
||
|
||
function onDragEnter(e) {
|
||
isDragging.value = true
|
||
}
|
||
|
||
function onDragOver(e) {
|
||
e.dataTransfer.dropEffect = 'copy'
|
||
}
|
||
|
||
function onDragLeave(e) {
|
||
if (!e.currentTarget.contains(e.relatedTarget)) {
|
||
isDragging.value = false
|
||
}
|
||
}
|
||
|
||
function onDrop(e) {
|
||
isDragging.value = false
|
||
const files = Array.from(e.dataTransfer.files)
|
||
validateAndEmit(files)
|
||
}
|
||
|
||
function onFileSelected(e) {
|
||
const files = Array.from(e.target.files)
|
||
validateAndEmit(files)
|
||
// 重置input以允许重复选择相同文件
|
||
e.target.value = ''
|
||
}
|
||
|
||
function validateAndEmit(files) {
|
||
const validFiles = []
|
||
const errors = []
|
||
|
||
files.forEach(file => {
|
||
// 验证文件类型
|
||
const ext = '.' + file.name.split('.').pop().toLowerCase()
|
||
if (!props.acceptedTypes.includes(ext)) {
|
||
errors.push({ file: file.name, reason: '不支持的文件格式' })
|
||
return
|
||
}
|
||
|
||
// 验证文件大小
|
||
if (file.size > props.maxSize) {
|
||
errors.push({ file: file.name, reason: `文件过大 (${formatSize(file.size)}，限制${formatSize(props.maxSize)})` })
|
||
return
|
||
}
|
||
|
||
validFiles.push(file)
|
||
})
|
||
|
||
if (validFiles.length > 0) {
|
||
emit('files-selected', validFiles)
|
||
}
|
||
|
||
if (errors.length > 0) {
|
||
emit('error', errors)
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
### 3.2 模块二：任务状态优化（优先级：🟡 高）
|
||
|
||
#### **3.2.1 功能需求**
|
||
|
||
##### **FR-06: 一键重试按钮**
|
||
- **触发条件**：任务状态为 error 时显示
|
||
- **位置**：UploadTaskItem 组件的错误标签旁
|
||
- **行为**：
|
||
1. 点击后立即调用重新处理API
|
||
2. 按钮变为加载状态（转圈图标）
|
||
3. 成功后自动刷新任务列表
|
||
4. 失败后显示错误详情
|
||
- **UI设计**：
|
||
```
|
||
❌ 向量化失败 [🔄 重试] [📋 详情]
|
||
```
|
||
|
||
##### **FR-07: 批量删除功能**
|
||
- **使用场景**：清理大量失败/已完成的历史任务
|
||
- **交互流程**：
|
||
1. 进入批量模式（勾选框出现）
|
||
2. 选择多个任务（支持全选）
|
||
3. 点击"删除选中项(N)"按钮
|
||
4. 弹出确认对话框（显示即将删除的任务数）
|
||
5. 执行删除并显示进度
|
||
- **权限控制**：仅管理员可见此功能
|
||
|
||
##### **FR-08: Toast通知系统**
|
||
- **触发事件**：
|
||
- ✅ 上传成功："✅ 文件「{filename}」上传成功，正在处理中..."
|
||
- ✅ 向量化完成："🎉 「{filename}」向量化完成，准备生成题目..."
|
||
- ✅ 出题完成："📝 「{filename}」已生成{count}道题目"
|
||
- ❌ 处理失败："❌ 「{filename}」处理失败：{原因}"
|
||
- **配置选项**：
|
||
- 显示时长：成功=3秒，失败=5秒
|
||
- 位置：右下角
|
||
- 可关闭：是
|
||
- 堆叠方式：垂直堆叠（最多3条同时显示）
|
||
|
||
##### **FR-09: 智能轮询策略**
|
||
- **当前问题**：固定5秒轮询，无论是否有活跃任务
|
||
- **优化方案**：
|
||
|
||
| 任务状态 | 轮询间隔 | 说明 |
|
||
|---------|---------|------|
|
||
| 有处理中任务 | 3秒 | 快速反馈 |
|
||
| 全部完成/失败 | 10秒 | 降低频率 |
|
||
| 页面不可见 | 30秒 | 节省资源 |
|
||
| 无任何任务 | 停止轮询 | 完全停止 |
|
||
|
||
- **实现方式**：使用 `document.visibilitychange` 事件检测页面可见性
|
||
|
||
##### **FR-10: 加载骨架屏**
|
||
- **应用场景**：
|
||
1. 首次加载任务列表时
|
||
2. 刷新任务状态时（>500ms）
|
||
- **UI效果**：灰色脉冲动画块模拟真实内容布局
|
||
- **组件复用**：创建通用 SkeletonCard 组件
|
||
|
||
#### **3.2.2 技术实现方案**
|
||
|
||
##### **修改文件清单**：
|
||
|
||
| 文件路径 | 改动类型 | 改动量 | 说明 |
|
||
|---------|---------|--------|------|
|
||
| `src/components/exam/UploadTaskItem.vue` | 修改 | ~40行 | 添加重试按钮 |
|
||
| `src/components/exam/composables/useUploadTasks.js` | 修改 | ~80行 | 智能轮询+批量操作 |
|
||
| `src/components/ui/SkeletonCard.vue` | 新增 | ~50行 | 骨架屏组件 |
|
||
| `src/components/ui/ToastNotification.vue` | 新增 | ~90行 | 通知组件 |
|
||
| `src/utils/notification.js` | 新增 | ~60行 | 通知工具函数 |
|
||
|
||
##### **核心代码示例**：
|
||
|
||
**智能轮询** (`useUploadTasks.js` 修改部分)：
|
||
```javascript
|
||
// 新增智能轮询配置
|
||
const POLL_CONFIG = {
|
||
active: 3000, // 有活跃任务时：3秒
|
||
idle: 10000, // 全部空闲时：10秒
|
||
hidden: 30000, // 页面隐藏时：30秒
|
||
maxInterval: 30000 // 最大间隔上限
|
||
}
|
||
|
||
let currentInterval = POLL_CONFIG.idle
|
||
let visibilityHandler = null
|
||
|
||
function updatePollingStrategy() {
|
||
const hasActiveTasks = shouldPoll()
|
||
const isHidden = document.hidden
|
||
|
||
let newInterval
|
||
if (isHidden) {
|
||
newInterval = POLL_CONFIG.hidden
|
||
} else if (hasActiveTasks) {
|
||
newInterval = POLL_CONFIG.active
|
||
} else {
|
||
newInterval = POLL_CONFIG.idle
|
||
}
|
||
|
||
// 仅当间隔变化时才重启定时器
|
||
if (newInterval !== currentInterval) {
|
||
currentInterval = newInterval
|
||
stopPolling()
|
||
if (tasks.value.length > 0) {
|
||
startPolling()
|
||
}
|
||
console.log(`[useUploadTasks] 轮询间隔调整为 ${currentInterval}ms`)
|
||
}
|
||
}
|
||
|
||
// 监听页面可见性
|
||
function setupVisibilityListener() {
|
||
if (visibilityHandler) return
|
||
|
||
visibilityHandler = () => {
|
||
updatePollingStrategy()
|
||
}
|
||
document.addEventListener('visibilitychange', visibilityHandler)
|
||
}
|
||
|
||
onMounted(() => {
|
||
setupVisibilityListener()
|
||
})
|
||
|
||
onUnmounted(() => {
|
||
if (visibilityHandler) {
|
||
document.removeEventListener('visibilitychange', visibilityHandler)
|
||
}
|
||
})
|
||
```
|
||
|
||
**一键重试** (`UploadTaskItem.vue` 修改部分)：
|
||
```vue
|
||
<template>
|
||
<!-- 在错误标签旁添加重试按钮 -->
|
||
<span v-if="vectorStatus.status === 'error'" class="uti-tag error">
|
||
{{ vectorStatus.label }}
|
||
<button class="retry-btn" @click="handleRetry" :disabled="retrying">
|
||
<LoadingOutlined v-if="retrying" spin />
|
||
<ReloadOutlined v-else />
|
||
重试
|
||
</button>
|
||
</span>
|
||
</template>
|
||
|
||
<script setup>
|
||
import { ref } from 'vue'
|
||
import { ReloadOutlined, LoadingOutlined } from '@ant-design/icons-vue'
|
||
|
||
const props = defineProps({
|
||
task: Object,
|
||
vectorStatus: Object,
|
||
examStatus: Object
|
||
})
|
||
|
||
const emit = defineEmits(['retry'])
|
||
const retrying = ref(false)
|
||
|
||
async function handleRetry() {
|
||
retrying.value = true
|
||
try {
|
||
await emit('retry', props.task.id)
|
||
} finally {
|
||
setTimeout(() => { retrying.value = false }, 1000)
|
||
}
|
||
}
|
||
</script>
|
||
```
|
||
|
||
---
|
||
|
||
### 3.3 模块三：移动端适配（优先级：🟢 中）
|
||
|
||
#### **3.3.1 适配策略**
|
||
|
||
##### **断点定义**：
|
||
|
||
| 断点名称 | 宽度范围 | 目标设备 |
|
||
|---------|---------|---------|
|
||
| `sm` | ≥640px | 大屏手机横屏/小平板 |
|
||
| `md` | ≥768px | 平板竖屏 |
|
||
| `lg` | ≥1024px | 桌面端 |
|
||
|
||
##### **关键改动**：
|
||
|
||
1. **UploadTaskItem 组件**：
|
||
- 字体缩小（12px → 11px）
|
||
- 状态标签换行显示
|
||
- 错误信息默认展开（无需点击"详情"）
|
||
|
||
2. **文件列表**：
|
||
- 卡片布局改为单列
|
||
- 操作按钮改为底部固定栏
|
||
- 添加下拉刷新手势支持
|
||
|
||
3. **上传区域**：
|
||
- 拖拽区域全屏宽度
|
||
- 点击区域增大（最小44px触控目标）
|
||
|
||
---
|
||
|
||
## 4. 数据流与接口变更
|
||
|
||
### 4.1 API接口调整
|
||
|
||
#### **新增接口**（可选，如后端已支持则使用）：
|
||
|
||
| 接口 | 方法 | 用途 |
|
||
|------|------|------|
|
||
| `/api/file/{id}/retry` | POST | 重试失败任务 |
|
||
| `/api/file/batch-delete` | POST | 批量删除任务 |
|
||
|
||
#### **兼容性处理**：
|
||
|
||
如果后端暂不支持上述接口，前端降级方案：
|
||
- **重试功能**：调用原有上传接口重新上传同一文件
|
||
- **批量删除**：循环调用单个删除接口（带loading状态）
|
||
|
||
### 4.2 数据流图
|
||
|
||
```
|
||
用户操作
|
||
↓
|
||
FileSelector.vue（拖拽/选择文件）
|
||
↓
|
||
fileValidator.js（前端验证）
|
||
├─ 通过 → 显示预览 → 开始上传
|
||
└─ 失败 → 显示友好错误提示
|
||
↓
|
||
api/file.js uploadFile（带进度回调）
|
||
↓
|
||
ProgressBar.vue（实时更新进度）
|
||
↓
|
||
上传完成
|
||
↓
|
||
useUploadTasks.js（添加任务到列表）
|
||
↓
|
||
智能轮询（3-30秒动态调整）
|
||
↓
|
||
UploadTaskItem.vue（展示状态）
|
||
├─ 处理中 → 动画图标
|
||
├─ 完成 → 成功图标 + Toast通知
|
||
└─ 失败 → 错误图标 + 重试按钮
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 性能与兼容性考虑
|
||
|
||
### 5.1 性能优化措施
|
||
|
||
1. **按需加载**：新组件使用动态导入
|
||
```javascript
|
||
const DropZone = defineAsyncComponent(() => import('./components/ui/DropZone.vue'))
|
||
```
|
||
|
||
2. **防抖/节流**：
|
||
- 搜索输入：debounce 300ms
|
||
- 窗口resize：throttle 150ms
|
||
- 滚动事件：passive listener
|
||
|
||
3. **内存管理**：
|
||
- 轮询定时器在组件卸载时清除
|
||
- 大文件上传完成后释放引用
|
||
- 图片/文件预览使用URL.revokeObjectURL()
|
||
|
||
### 5.2 浏览器兼容性
|
||
|
||
| 功能 | 最低版本 | 降级方案 |
|
||
|------|---------|---------|
|
||
| Drag & Drop API | IE10+, 所有现代浏览器 | 回退到点击上传 |
|
||
| Progress Event | IE10+, 所有现代浏览器 | 不显示进度条 |
|
||
| Visibility API | IE10+, Chrome 13+ | 固定10秒轮询 |
|
||
| CSS Grid/Flexbox | IE11+ (partial), 现代浏览器全支持 | 使用float fallback |
|
||
|
||
---
|
||
|
||
## 6. 测试计划
|
||
|
||
### 6.1 单元测试
|
||
|
||
| 测试场景 | 输入 | 预期输出 | 优先级 |
|
||
|---------|------|---------|--------|
|
||
| 文件类型验证 | `test.exe` | 返回错误"不支持的格式" | P0 |
|
||
| 文件大小验证 | 60MB文件 | 返回错误"超过50MB限制" | P0 |
|
||
| 进度计算 | loaded=50, total=100 | percent=50 | P0 |
|
||
| 拖拽事件处理 | 有效文件 | 触发files-selected事件 | P1 |
|
||
| 轮询间隔调整 | 页面hidden | 间隔变为30秒 | P1 |
|
||
| 重试按钮点击 | error状态任务 | 调用retry事件 | P0 |
|
||
|
||
### 6.2 集成测试
|
||
|
||
1. **上传流程测试**：
|
||
- 选择文件 → 验证 → 上传 → 进度显示 → 完成
|
||
- 拖拽文件 → 验证 → 上传 → 进度显示 → 完成
|
||
- 选择无效文件 → 显示错误 → 修正后重试
|
||
|
||
2. **任务状态测试**：
|
||
- 上传后观察状态流转（UPLOADED→VECTORIZING→VECTORIZED→EXAM_GENERATING→COMPLETED）
|
||
- 模拟失败场景 → 点击重试 → 验证重试逻辑
|
||
- 批量选择 → 删除 → 确认删除成功
|
||
|
||
3. **边界情况测试**：
|
||
- 同时上传10个文件
|
||
- 网络中断后恢复
|
||
- 页面刷新后状态保持
|
||
- 移动端触摸操作
|
||
|
||
### 6.3 兼容性测试
|
||
|
||
- ✅ Chrome 90+
|
||
- ✅ Firefox 88+
|
||
- ✅ Safari 14+
|
||
- ✅ Edge 90+
|
||
- ⚠️ iOS Safari 14+（移动端）
|
||
- ⚠️ Android Chrome 90+
|
||
|
||
---
|
||
|
||
## 7. 实施路线图
|
||
|
||
### Phase 1：核心功能（第1天）- 6小时
|
||
|
||
**上午（3小时）**：
|
||
- [ ] 创建 `src/utils/fileValidator.js` 文件验证工具
|
||
- [ ] 创建 `src/components/ui/ProgressBar.vue` 进度条组件
|
||
- [ ] 修改 `src/api/file.js` 添加进度回调支持
|
||
|
||
**下午（3小时）**：
|
||
- [ ] 创建 `src/components/ui/DropZone.vue` 拖拽组件
|
||
- [ ] 修改 `src/components/FileSelector.vue` 集成新功能
|
||
- [ ] 测试上传流程（正常/异常场景）
|
||
|
||
### Phase 2：任务状态优化（第2天）- 6小时
|
||
|
||
**上午（3小时）**：
|
||
- [ ] 修改 `UploadTaskItem.vue` 添加重试按钮
|
||
- [ ] 修改 `useUploadTasks.js` 实现智能轮询
|
||
- [ ] 创建 `src/components/ui/ToastNotification.vue`
|
||
|
||
**下午（3小时）**：
|
||
- [ ] 实现批量删除功能
|
||
- [ ] 创建骨架屏组件
|
||
- [ ] 测试任务状态流转
|
||
|
||
### Phase 3：打磨与测试（第3天）- 6小时
|
||
|
||
**上午（3小时）**：
|
||
- [ ] 移动端响应式适配
|
||
- [ ] 跨浏览器测试
|
||
- [ ] 性能 profiling
|
||
|
||
**下午（3小时）**：
|
||
- [ ] 用户体验走查
|
||
- [ ] Bug修复
|
||
- [ ] 文档编写
|
||
|
||
---
|
||
|
||
## 8. 风险评估与缓解
|
||
|
||
### 8.1 技术风险
|
||
|
||
| 风险 | 可能性 | 影响 | 缓解措施 |
|
||
|------|-------|------|---------|
|
||
| 后端不支持重试API | 中 | 中 | 前端降级为重新上传 |
|
||
| 大文件上传内存溢出 | 低 | 高 | 使用分片上传（Phase 2考虑） |
|
||
| 拖拽API兼容性问题 | 低 | 低 | Feature detection + 降级方案 |
|
||
| 轮询性能开销 | 低 | 中 | 智能间隔 + 页面不可见时暂停 |
|
||
|
||
### 8.2 业务风险
|
||
|
||
| 风险 | 可能性 | 影响 | 缓解措施 |
|
||
|------|-------|------|---------|
|
||
| 用户不接受新交互 | 低 | 低 | A/B测试 + 快速回滚能力 |
|
||
| 移动端体验不佳 | 中 | 中 | 充分的设备测试 |
|
||
| 与现有工作流冲突 | 低 | 中 | 保持向后兼容 + 渐进启用 |
|
||
|
||
---
|
||
|
||
## 9. 成功指标（KPIs）
|
||
|
||
### 9.1 定量指标
|
||
|
||
| 指标 | 当前值 | 目标值 | 测量方法 |
|
||
|------|-------|--------|---------|
|
||
| 上传操作成功率 | 未知 | ≥98% | 错误日志统计 |
|
||
| 平均上传等待感知时间 | 未知 | 减少30% | 用户调研 |
|
||
| 任务状态查询次数/会话 | 固定12次/分钟 | 动态3-30次 | 性能监控 |
|
||
| 错误重试成功率 | 0% | ≥80% | 重试按钮点击率 |
|
||
|
||
### 9.2 定性指标
|
||
|
||
- ✅ 用户能够清晰了解上传进度
|
||
- ✅ 任务失败时有明确的解决路径（重试按钮）
|
||
- ✅ 移动端操作流畅无明显卡顿
|
||
- ✅ 错误信息易于理解和行动
|
||
|
||
---
|
||
|
||
## 10. 附录
|
||
|
||
### 10.1 参考文档
|
||
|
||
- [文件管理接口文档 V2.12.0](./文件管理接口文档.md)
|
||
- Vue 3 官方文档：https://vuejs.org/
|
||
- Ant Design Vue 组件库：https://antdv.com/
|
||
- MDN Drag & Drop API：https://developer.mozilla.org/en-US/docs/Web/API/Drag_and_Drop
|
||
|
||
### 10.2 术语表
|
||
|
||
| 术语 | 定义 |
|
||
|------|------|
|
||
| **向量化(Vectorize)** | 将文档内容转换为向量表示，用于语义搜索 |
|
||
| **出题(Exam Generation)** | 基于文档内容自动生成考试题目 |
|
||
| **轮询(Polling)** | 客户端定期向服务器请求最新状态的机制 |
|
||
| **骨架屏(Skeleton)** | 内容加载时的占位动画效果 |
|
||
| **Toast通知** | 短暂出现的消息提示，通常位于屏幕角落 |
|
||
|
||
---
|
||
|
||
**文档结束**
|
||
|
||
*请审核本设计文档，确认后我们将进入实施阶段。*
|