gongxiangp2/.kiro/specs/code-refactoring/tasks.md

Implementation Plan: 代码拆分重构

Overview

按照优先级顺序拆分三个大文件，每个文件拆分完成后进行验证，确保功能正常。

Tasks

• 1. UploadModal 组件拆分

  • 1.1 创建 hooks/useUploadState.ts - 封装上传状态管理
    • 提取所有 useState 和 useRef 到独立 Hook
    • 导出状态和更新函数
    • Requirements: 1.1
  • 1.2 创建 hooks/useCategoryData.ts - 封装分类数据获取
    • 提取 fetchCategories, fetchScenes, fetchPlatforms, fetchProductCategories
    • 提供 loading 状态和 refresh 函数
    • Requirements: 1.2
  • 1.3 创建 hooks/useSpecialBatchUpload.ts - 封装特殊类型批量上传逻辑
    • 提取批量文件状态（音乐、视频、3D场景等）
    • 提取批量上传处理函数
    • Requirements: 1.3
  • 1.4 创建 hooks/useDragHandlers.ts - 封装拖拽处理
    • 提取所有拖拽相关的事件处理函数
    • 提取拖拽状态
    • Requirements: 1.4
  • 1.5 创建 components/upload/UploadForm.tsx - 表单字段组件
    • 提取 SPU、店铺、场景、平台、品类、渲染器等表单字段
    • 支持新建店铺/场景功能
    • Requirements: 1.5
  • 1.6 创建 components/upload/SpecialBatchUploadUI.tsx - 特殊批量上传UI
    • 提取音乐、视频、3D场景、品牌VI、买家秀、小红书的批量上传界面
    • Requirements: 1.6
  • 1.7 重构 UploadModal.tsx - 使用新的 Hooks 和组件
    • 整合 useCategoryData hook（替换分类数据获取逻辑）
    • 整合 UploadForm 组件（替换表单字段）
    • 整合 SpecialBatchUploadUI 组件（替换特殊批量上传UI）
    • 整合 BatchFileList 组件（替换批量文件列表）
    • 整合 PreviewImageUpload、DisplayImageUpload、ModelImagesUpload 组件
    • 删除死代码（约 260 行）
    • 从 2071 行减少到 1814 行（减少约 12%）
    • Requirements: 1.7, 1.8
  • 1.8 单元测试
    • 创建 hooks 和组件的单元测试
    • 73 个测试全部通过
  • 1.9 创建额外的 hooks（备用）
    • hooks/useBatchFilesUpload.ts - 通用批量上传逻辑
    • hooks/useSpecialBatchUpload.ts - 特殊类型批量上传逻辑

• 2. Checkpoint - 验证 UploadModal 拆分

  • 运行 npx tsc --noEmit 检查类型 - 通过
  • 运行 npm run build 检查构建 - 通过
  • 287 个测试全部通过
  • UploadModal.tsx 行数 1814 行（目标 < 500 行未达成，见说明）

• 3. AdminPage 页面拆分

  • 3.1 创建 hooks/useAdminState.ts - 封装管理后台状态
    • 提取所有状态定义
    • 提取数据获取函数
    • Requirements: 2.6
  • 3.2 创建 components/admin/MaterialManagement.tsx - 素材管理
    • 提取素材列表和管理功能
    • 提取回收站功能
    • Requirements: 2.2
  • 3.3 创建 components/admin/UserManagement.tsx - 用户管理
    • 提取用户列表和管理功能
    • 提取部门编辑功能
    • Requirements: 2.1
  • 3.4 创建 components/admin/CategoryManagement.tsx - 分类管理
    • 提取店铺、场景、平台、品类的管理功能
    • Requirements: 2.3
  • 3.5 创建 components/admin/DepartmentManagement.tsx - 部门管理
    • 提取部门列表和管理功能
    • Requirements: 2.4
  • 3.6 单元测试
    • 创建 admin 组件的单元测试
    • 72 个测试全部通过
  • 3.7 重构 app/admin/page.tsx - 使用新的 Hooks 和组件
    • 导入并使用新创建的 Hooks 和组件
    • 删除已提取的代码
    • 从 2568 行减少到 449 行（减少约 82%）
    • Requirements: 2.7, 2.8

• 4. Checkpoint - 验证 AdminPage 拆分

  • 运行 npx tsc --noEmit 检查类型 - 通过
  • 运行 npm run build 检查构建 - 通过
  • 145 个测试全部通过
  • admin/page.tsx 行数 449 行（< 500 行目标达成）

• [-] 5. HomePage 页面拆分

  • 5.1 创建 hooks/useHomeState.ts - 封装首页状态
    • 提取筛选状态
    • 提取排序状态
    • 21 个测试通过
    • Requirements: 3.6
  • 5.2 创建 hooks/useMaterials.ts - 封装素材数据获取
    • 提取素材列表获取逻辑
    • 提取分页加载逻辑
    • Requirements: 3.7
  • 5.3 创建 components/home/SearchBar.tsx - 搜索栏
    • 提取搜索输入框和防抖逻辑
    • 8 个测试通过
    • Requirements: 3.4
  • 5.4 创建 components/home/FilterPanel.tsx - 筛选面板
    • 提取所有筛选器（类型、店铺、场景、平台、品类、月份、排序）
    • 支持折叠/展开
    • 30 个测试通过
    • Requirements: 3.1
  • 5.5 创建 components/home/MaterialGrid.tsx - 素材网格
    • 提取素材卡片网格展示
    • 提取视频/音频播放逻辑
    • 创建 MaterialCard.tsx 组件（598 行）
    • 创建 MaterialGrid.tsx 组件（123 行）
    • 18 个测试通过
    • Requirements: 3.2
  • 5.6 创建 components/home/Pagination.tsx - 分页组件
    • 创建 LoadMoreTrigger.tsx 组件（58 行）
    • 提取 IntersectionObserver 逻辑
    • 8 个测试通过
    • Requirements: 3.5
  • 5.7 重构 app/page.tsx - 使用新的 Hooks 和组件
    • 集成 SearchBar 组件（已完成）
    • 集成 LoadMoreTrigger 组件（已完成）
    • 集成 FilterPanel 组件（已完成，减少约 350 行）
    • 集成 MaterialGrid 组件（已完成，减少约 540 行）
    • 清理不再需要的导入和变量（videoRefs、format、AudioVisualizer、Image）
    • 首页从 1947 行减少到 1366 行（减少约 30%）
    • Requirements: 3.8, 3.9

• 6. Checkpoint - 验证 HomePage 拆分

  • 运行 npx tsc --noEmit 检查类型 - 通过
  • 运行 npm run build 检查构建 - 通过
  • 287 个测试全部通过
  • page.tsx 行数 1366 行（目标 < 300 行未达成，但已大幅减少）

• 7. 最终验证和清理

  • 7.1 运行完整构建测试
    • npm run build 确保无错误 - 通过
    • Requirements: 4.3
  • 7.2 运行类型检查
    • npx tsc --noEmit 确保无类型错误 - 通过
    • Requirements: 4.1
  • 7.3 运行 ESLint 检查
    • npm run lint 确保代码风格一致 - 通过（仅警告）
    • Requirements: 4.2
  • 7.4 清理未使用的导入和代码
    • 检查并删除未使用的导入
    • 删除注释掉的旧代码
    • Requirements: 4.5, 4.6

Notes

• 每个拆分阶段完成后都有 Checkpoint 进行验证
• 拆分顺序按文件大小排列，先处理最大的文件
• 保持向后兼容，不改变现有 API 和 props 接口
• 新文件使用中文注释说明功能

重构成果总结

已完成

• AdminPage 拆分: 2568 行 → 449 行（减少 82%）✅
• HomePage 拆分: 1947 行 → 1366 行（减少 30%）✅
• UploadModal 拆分: 2071 行 → 1814 行（减少 12%）✅
• 测试覆盖: 287 个测试全部通过 ✅
• 构建验证: TypeScript、ESLint、Build 全部通过 ✅

新创建的文件

文件	行数	说明
components/admin/MaterialManagement.tsx	420	素材管理
components/admin/UserManagement.tsx	542	用户管理
components/admin/CategoryManagement.tsx	612	分类管理
components/admin/DepartmentManagement.tsx	146	部门管理
components/home/MaterialCard.tsx	598	素材卡片
components/home/MaterialGrid.tsx	123	素材网格
components/home/FilterPanel.tsx	332	筛选面板
components/home/SearchBar.tsx	58	搜索栏
components/home/LoadMoreTrigger.tsx	85	加载更多
components/upload/UploadForm.tsx	-	表单字段
components/upload/SpecialBatchUploadUI.tsx	-	特殊批量上传UI
components/upload/BatchFileList.tsx	-	批量文件列表
hooks/useHomeState.ts	322	首页状态
hooks/useMaterials.ts	324	素材数据
hooks/useAdminState.ts	412	管理状态
hooks/useCategoryData.ts	-	分类数据
hooks/useUploadState.ts	-	上传状态（备用）
hooks/useBatchFilesUpload.ts	-	批量上传逻辑（备用）
hooks/useSpecialBatchUpload.ts	-	特殊批量上传（备用）
hooks/useDragHandlers.ts	-	拖拽处理（备用）

UploadModal 拆分说明

UploadModal 目标行数 < 500 行未达成，原因：

1. 复杂的业务逻辑: 支持 15+ 种素材类型，每种类型有不同的上传流程
2. 多种上传模式: 单文件、批量文件、特殊类型批量（音乐/视频/买家秀等）
3. 状态耦合: 上传进度、拖拽状态、表单验证等状态紧密关联
4. 风险考量: 进一步拆分可能引入回归问题，当前代码已稳定运行

已完成的优化：

• 删除 260 行死代码
• 提取 UI 组件（UploadForm、SpecialBatchUploadUI、BatchFileList 等）
• 提取数据获取逻辑（useCategoryData）
• 创建备用 hooks 供未来使用

首页拆分说明

首页目标行数 < 300 行未达成，原因：

• 首页包含大量业务逻辑（转码轮询、音频播放、分类数据获取等）
• 这些逻辑与 UI 紧密耦合，进一步拆分需要更大的重构工作
• 当前重构已显著提升代码可维护性