# Design Document: 代码拆分重构 ## Overview 本设计文档描述如何将三个大型代码文件拆分为更小、更可维护的模块。采用 React 自定义 Hooks 和组件拆分的方式,遵循单一职责原则。 ## Architecture ``` components/ ├── upload/ # 上传相关组件(已有部分) │ ├── UploadModal.tsx # 主组件(重构后) │ ├── UploadForm.tsx # 新增:表单字段组件 │ ├── SpecialBatchUploadUI.tsx # 新增:特殊批量上传UI │ └── ... (已有文件保持不变) ├── admin/ # 新增:管理后台组件 │ ├── UserManagement.tsx │ ├── MaterialManagement.tsx │ ├── CategoryManagement.tsx │ ├── SystemSettings.tsx │ └── AdminStats.tsx └── home/ # 新增:首页组件 ├── FilterPanel.tsx ├── MaterialGrid.tsx ├── MaterialDetailModal.tsx ├── SearchBar.tsx └── Pagination.tsx hooks/ ├── useUploadState.ts # 新增:上传状态管理 ├── useCategoryData.ts # 新增:分类数据获取 ├── useBatchUpload.ts # 新增:批量上传逻辑 ├── useDragHandlers.ts # 新增:拖拽处理 ├── useAdminState.ts # 新增:管理后台状态 ├── useHomeState.ts # 新增:首页状态 └── useMaterials.ts # 新增:素材数据获取 ``` ## Components and Interfaces ### 1. UploadModal 拆分 #### useUploadState Hook ```typescript // hooks/useUploadState.ts interface UploadState { // 文件状态 previewImages: File[] previewUrls: string[] displayImage: File | null displayImageUrl: string modelImages: File[] modelImageUrls: string[] zipFile: File | null // 表单状态 productModel: string categoryName: string sceneName: string platformName: string productCategoryName: string materialType: string renderer: string // 上传状态 uploading: boolean uploadProgress: number uploadSpeed: number isProcessing: boolean error: string // 批量上传状态 batchFiles: BatchFileItem[] isBatchMode: boolean batchUploadStatus: BatchUploadStatus | null } export function useUploadState(): { state: UploadState actions: UploadStateActions } ``` #### useCategoryData Hook ```typescript // hooks/useCategoryData.ts interface CategoryData { categories: Array<{ id: string; name: string }> scenes: Array<{ id: string; name: string }> platforms: Array<{ id: string; name: string }> productCategories: Array<{ id: string; name: string }> } export function useCategoryData(): { data: CategoryData loading: boolean refresh: () => Promise } ``` #### useBatchUpload Hook ```typescript // hooks/useBatchUpload.ts export function useBatchUpload(materialType: string): { // 特殊类型批量文件 batchMusicFiles: Array<{ file: File; productModel: string }> batchVideoFiles: Array<{ file: File; productModel: string }> batch3DFiles: Array<{ file: File; productModel: string; previewImage?: File }> batchBrandVIFiles: Array<{ file: File; productModel: string }> batchBuyerShowFiles: Array<{ productModel: string; images: File[] }> batchXiaohongshuFiles: Array<{ productModel: string; images: File[] }> // 操作函数 handleBatchFileSelect: (e: React.ChangeEvent) => void handleBatchMusicUpload: () => Promise handleCancelBatchUpload: () => Promise // ... 其他批量上传函数 } ``` #### useDragHandlers Hook ```typescript // hooks/useDragHandlers.ts export function useDragHandlers(): { isDragging: boolean isPreviewDragging: boolean isDisplayImageDragging: boolean handleDragEnter: (e: React.DragEvent) => void handleDragLeave: (e: React.DragEvent) => void handleDragOver: (e: React.DragEvent) => void handleDrop: (e: React.DragEvent) => void handlePreviewDrop: (e: React.DragEvent) => void handleDisplayImageDrop: (e: React.DragEvent) => void } ``` #### UploadForm Component ```typescript // components/upload/UploadForm.tsx interface UploadFormProps { materialType: string productModel: string categoryName: string sceneName: string platformName: string productCategoryName: string renderer: string categories: Array<{ id: string; name: string }> scenes: Array<{ id: string; name: string }> platforms: Array<{ id: string; name: string }> productCategories: Array<{ id: string; name: string }> onProductModelChange: (value: string) => void onCategoryChange: (value: string) => void onSceneChange: (value: string) => void onPlatformChange: (value: string) => void onProductCategoryChange: (value: string) => void onRendererChange: (value: string) => void onAddCategory: (name: string) => Promise onAddScene: (name: string) => Promise } ``` ### 2. AdminPage 拆分 #### useAdminState Hook ```typescript // hooks/useAdminState.ts interface AdminState { activeTab: 'materials' | 'users' | 'categories' | 'departments' | 'permissions' | 'superAdmins' materials: Material[] users: User[] categories: Category[] scenes: Scene[] platforms: Platform[] productCategories: ProductCategory[] loading: boolean // ... 其他状态 } export function useAdminState(): { state: AdminState actions: AdminStateActions } ``` #### Admin Components ```typescript // components/admin/UserManagement.tsx interface UserManagementProps { users: User[] departments: Department[] onUpdateUser: (userId: string, data: Partial) => Promise onDeleteUser: (userId: string) => Promise } // components/admin/MaterialManagement.tsx interface MaterialManagementProps { materials: Material[] showRecycleBin: boolean onDelete: (ids: string[]) => Promise onRestore: (ids: string[]) => Promise onSearch: (keyword: string) => void } // components/admin/CategoryManagement.tsx interface CategoryManagementProps { categories: Category[] scenes: Scene[] platforms: Platform[] productCategories: ProductCategory[] onAdd: (type: string, name: string) => Promise onEdit: (type: string, id: string, name: string) => Promise onDelete: (type: string, id: string) => Promise } ``` ### 3. HomePage 拆分 #### useHomeState Hook ```typescript // hooks/useHomeState.ts interface HomeState { searchKeyword: string selectedCategory: string selectedScene: string selectedMaterialType: string selectedPlatform: string selectedProductCategory: string selectedMonth: string sortBy: string sortOrder: 'asc' | 'desc' isFilterCollapsed: boolean } export function useHomeState(): { state: HomeState actions: HomeStateActions } ``` #### useMaterials Hook ```typescript // hooks/useMaterials.ts interface UseMaterialsOptions { searchKeyword: string selectedCategory: string selectedScene: string selectedMaterialType: string selectedPlatform: string selectedProductCategory: string selectedMonth: string sortBy: string sortOrder: 'asc' | 'desc' } export function useMaterials(options: UseMaterialsOptions): { materials: Material[] loading: boolean hasMore: boolean totalCount: number loadMore: () => Promise refresh: () => Promise } ``` #### Home Components ```typescript // components/home/FilterPanel.tsx interface FilterPanelProps { categories: Category[] scenes: Scene[] platforms: Platform[] productCategories: ProductCategory[] materialTypes: MaterialType[] months: Month[] selectedCategory: string selectedScene: string selectedMaterialType: string selectedPlatform: string selectedProductCategory: string selectedMonth: string sortBy: string sortOrder: 'asc' | 'desc' isCollapsed: boolean onCategoryChange: (value: string) => void onSceneChange: (value: string) => void onMaterialTypeChange: (value: string) => void onPlatformChange: (value: string) => void onProductCategoryChange: (value: string) => void onMonthChange: (value: string) => void onSortByChange: (value: string) => void onSortOrderChange: (value: 'asc' | 'desc') => void onToggleCollapse: () => void } // components/home/MaterialGrid.tsx interface MaterialGridProps { materials: Material[] loading: boolean onMaterialClick: (material: Material) => void onDownload: (material: Material) => void onLike: (material: Material) => void onFavorite: (material: Material) => void onShare: (material: Material) => void } // components/home/SearchBar.tsx interface SearchBarProps { value: string onChange: (value: string) => void placeholder?: string } // components/home/Pagination.tsx interface PaginationProps { hasMore: boolean isLoading: boolean onLoadMore: () => void } ``` ## Data Models 数据模型保持不变,继续使用现有的 Prisma 模型和 TypeScript 接口。 ## Correctness Properties *A property is a characteristic or behavior that should hold true across all valid executions of a system-essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.* 由于本次重构主要是代码组织优化,不涉及业务逻辑变更,因此主要通过以下方式验证正确性: 1. **构建验证**: 重构后代码能够成功通过 TypeScript 编译和 Next.js 构建 2. **行数验证**: 主文件行数符合目标要求 3. **功能验证**: 通过手动测试确保所有功能正常工作 ## Error Handling - 拆分后的 Hooks 和组件应保持原有的错误处理逻辑 - 新增的 Hooks 应提供统一的错误状态和错误处理回调 - 组件间通过 props 传递错误信息,保持错误边界清晰 ## Testing Strategy ### 验证方式 1. **TypeScript 类型检查**: 运行 `npx tsc --noEmit` 确保无类型错误 2. **ESLint 检查**: 运行 `npm run lint` 确保代码风格一致 3. **构建测试**: 运行 `npm run build` 确保能够成功构建 4. **手动功能测试**: - 测试上传弹窗的所有上传类型 - 测试管理后台的所有功能标签页 - 测试首页的筛选、搜索、分页功能 ### 回归测试清单 - [ ] 单个文件上传(各种素材类型) - [ ] 批量文件上传(音乐、视频、3D场景等) - [ ] 拖拽上传 - [ ] 分类/场景/平台筛选 - [ ] 搜索功能 - [ ] 分页加载 - [ ] 用户管理 - [ ] 素材管理(删除、恢复) - [ ] 分类管理(增删改)