gongxiangp2/docs/upload-state-cleanup-fix.md
chenpei ea9076df45 feat: 实现统一的下载错误处理系统并修复产品全案数据库Schema
- 创建统一的下载错误处理模块 (lib/download-errors.ts)
- 实现13种错误类型分类和中文错误消息
- 后端统一使用 createDownloadError 创建标准化错误响应
- 前端统一使用 parseDownloadError 解析错误并显示
- 修复正式系统数据库Schema,添加产品全案相关字段和表
- 执行数据库迁移:添加 task_no, task_status, task_fetched_at 字段
- 创建 material_assets, api_keys, api_call_logs 表
2026-01-05 17:52:42 +08:00

3.3 KiB
Raw Blame History

上传状态清理修复说明

📋 修复概述

修复了上传过程中错误情况下 IndexedDB 状态未清理的问题,避免状态残留导致前端显示"一直在上传"。

🔧 修复内容

1. 导出 generateFileId 函数

文件:lib/chunk-upload.ts

修改:

// 修改前
function generateFileId(file: File): string { ... }

// 修改后
export function generateFileId(file: File): string { ... }

原因:需要在错误处理中使用此函数生成文件ID,以便清理对应的状态。

2. 在错误处理中添加状态清理逻辑

文件:components/UploadModal.tsx

位置:handleSubmit 方法的 catch 块(第1351-1373行)

修改:

} catch (error) {
  console.error('Upload error:', error)
  
  // 如果使用了分片上传,清理可能残留的 IndexedDB 状态
  if (zipFile && zipFile.size >= CHUNK_THRESHOLD) {
    try {
      const { deleteUploadState, generateFileId } = await import('@/lib/chunk-upload')
      const fileId = generateFileId(zipFile)
      await deleteUploadState(fileId)
      console.log('[UploadModal] 已清理上传状态:', fileId)
    } catch (cleanupError) {
      console.warn('[UploadModal] 清理上传状态失败(忽略):', cleanupError)
    }
  }
  
  setError((error as Error)?.message || '上传失败,请稍后再试')
  setUploading(false)
}

解决的问题:

  • 当 uploadSingleFile 成功完成分片上传但 submitFormData 失败时,会自动清理 IndexedDB 中的状态
  • 避免状态残留导致前端显示异常

3. 在重试失败时清理状态

文件:lib/chunk-upload.ts

位置:chunkUpload 方法的 completeUpload 重试逻辑(第451-456行)

修改:

retries++
if (retries < maxRetries) {
  await new Promise(resolve => setTimeout(resolve, retryDelay * retries))
} else {
  // 达到最大重试次数,清理状态以避免残留
  await deleteUploadState(fileId).catch(() => {
    console.warn('[ChunkUpload] 清理上传状态失败(忽略)')
  })
  throw new Error('完成上传失败,已重试多次')
}

解决的问题:

  • 当 completeUpload 达到最大重试次数时,会清理 IndexedDB 状态
  • 虽然默认 maxRetries = Infinity,但添加此逻辑可以处理边界情况

✅ 修复效果

修复前

  • ❌ 错误情况下状态不清理
  • ❌ IndexedDB 中残留状态
  • ❌ 前端可能显示"一直在上传"

修复后

  • ✅ 错误情况下自动清理状态
  • ✅ 避免状态残留
  • ✅ 提升用户体验

🧪 测试建议

  1. 测试正常上传:确保正常上传流程不受影响
  2. 测试错误情况:模拟网络错误或服务器错误,验证状态会被清理
  3. 测试大文件:上传大文件(≥5MB),触发分片上传,验证错误处理

📝 注意事项

  1. 状态清理是异步操作:使用 await import 动态导入,避免影响主流程
  2. 清理失败不阻塞:即使清理失败,也不会影响错误提示的显示
  3. 仅清理分片上传状态:只有文件大小 ≥ CHUNK_THRESHOLD 时才清理(小文件不走分片上传)

🔗 相关文档

  • docs/code-review-upload-state-issues.md - 详细问题分析
  • docs/code-review-summary.md - 问题总结
  • docs/upload-status-issue-analysis.md - 原始问题分析