cstb-next/todo/refactor-plan.md

代码重构规划文档

统计结果

超过300行的文件列表

文件路径	行数	优先级	状态
src/components/cstb/FpsTest.tsx	1949	🔴 高	待重构
src/components/cstb/VideoSetting.tsx	579	🟡 中	待重构
src/components/cstb/SteamUsers.tsx	432	🟡 中	待重构

重构目标

1. 组件封装：将大组件拆分为更小的、职责单一的组件
2. 功能复用：提取可复用的逻辑和工具函数
3. 文件拆分：将大文件拆分为多个小文件，提高可维护性
4. 代码组织：按功能模块组织代码结构

---

1. FpsTest.tsx (1949行) - 高优先级

问题分析

• 文件过大，难以维护和调试
• 包含多个职责：测试执行、结果读取、UI渲染、CSV导出等
• 大量状态管理和副作用逻辑混在一起
• 工具函数、常量、组件定义都在同一文件

重构方案

1.1 文件结构拆分

src/components/cstb/FpsTest/
├── index.tsx                    # 主组件（精简后约200行）
├── types.ts                     # 类型定义
├── constants.ts                 # 常量定义（BENCHMARK_MAPS, PRESET_RESOLUTIONS等）
├── utils/
│   ├── vprof-parser.ts          # VProf报告解析工具
│   ├── timestamp.ts             # 时间戳处理工具
│   ├── fps-metrics.ts           # FPS指标提取工具
│   └── csv-export.ts            # CSV导出工具
├── hooks/
│   ├── useGameMonitor.ts        # 游戏运行状态监控
│   ├── useTestMonitor.ts        # 测试结果监控
│   ├── useBatchTest.ts          # 批量测试逻辑
│   └── useHardwareInfo.ts       # 硬件信息获取
├── components/
│   ├── TestConfigPanel.tsx      # 测试配置面板
│   ├── ResolutionConfig.tsx     # 分辨率配置组件
│   ├── TestResultsTable.tsx     # 测试结果表格
│   ├── TestResultDisplay.tsx    # 测试结果展示
│   ├── BatchTestProgress.tsx    # 批量测试进度
│   └── NoteCell.tsx             # 备注单元格
└── services/
    ├── testRunner.ts            # 测试执行服务
    └── resultReader.ts          # 结果读取服务

1.2 功能模块拆分

工具函数模块 (utils/)

• vprof-parser.ts: parseVProfReport, extractFpsMetrics
• timestamp.ts: compareTimestamps, 时间戳格式化
• fps-metrics.ts: FPS相关计算和格式化
• csv-export.ts: handleExportCSV, handleExportAverageCSV

自定义Hooks (hooks/)

• useGameMonitor.ts: 游戏运行状态检测和监控
• useTestMonitor.ts: 测试结果文件监控逻辑
• useBatchTest.ts: 批量测试状态管理和执行逻辑
• useHardwareInfo.ts: 硬件信息获取和管理

组件拆分 (components/)

• TestConfigPanel.tsx: 测试地图、批量测试次数、备注配置
• ResolutionConfig.tsx: 分辨率设置、全屏/窗口化、分辨率组管理
• TestResultsTable.tsx: 测试结果表格展示（包含删除、编辑备注）
• TestResultDisplay.tsx: 当前测试结果显示（时间戳、avg、p1）
• BatchTestProgress.tsx: 批量测试进度显示组件
• NoteCell.tsx: 备注单元格组件

服务层 (services/)

• testRunner.ts: runSingleTest, startTest 等测试执行逻辑
• resultReader.ts: readResult 结果读取逻辑

1.3 预期效果

• 主组件文件从1949行减少到约200行
• 每个子文件控制在100-300行以内
• 提高代码可维护性和可测试性
• 便于功能扩展和bug修复

---

2. VideoSetting.tsx (579行) - 中优先级

问题分析

• 视频设置配置数组过长（约200行）
• 编辑/只读模式切换逻辑复杂
• 文件监听和自动刷新逻辑可以提取

重构方案

2.1 文件结构拆分

src/components/cstb/VideoSetting/
├── index.tsx                    # 主组件（精简后约200行）
├── types.ts                     # 类型定义
├── config/
│   └── videoSettingsConfig.ts   # 视频设置配置数组
├── hooks/
│   ├── useVideoConfig.ts         # 视频配置读取/写入
│   ├── useFileWatcher.ts        # 文件监听逻辑
│   └── useGameRunning.ts        # 游戏运行状态检测
└── components/
    ├── VideoSettingsEditor.tsx  # 编辑模式组件
    └── VideoSettingsViewer.tsx  # 只读模式组件

2.2 功能模块拆分

配置模块 (config/)

• videoSettingsConfig.ts: 提取 videoSettings 函数和配置数组

自定义Hooks (hooks/)

• useVideoConfig.ts: 视频配置的读取、写入、刷新逻辑
• useFileWatcher.ts: 文件变动监听和自动刷新
• useGameRunning.ts: 游戏运行状态检测（可复用）

组件拆分 (components/)

• VideoSettingsEditor.tsx: 编辑模式下的所有控件
• VideoSettingsViewer.tsx: 只读模式下的展示

2.3 预期效果

• 主组件文件从579行减少到约200行
• 配置数据独立管理，便于维护
• 编辑/查看逻辑分离，代码更清晰

---

3. SteamUsers.tsx (432行) - 中优先级

问题分析

• 三种视图模式的渲染逻辑重复
• 用户项渲染函数较长
• 可以提取为独立组件

重构方案

3.1 文件结构拆分

src/components/cstb/SteamUsers/
├── index.tsx                    # 主组件（精简后约150行）
├── types.ts                     # 类型定义
├── components/
│   ├── UserCard.tsx             # 卡片视图用户项
│   ├── UserListItem.tsx         # 列表视图用户项
│   └── UserListLargeItem.tsx    # 大列表视图用户项
└── hooks/
    └── useSteamUsers.ts         # 用户数据获取和管理

3.2 功能模块拆分

组件拆分 (components/)

• UserCard.tsx: 卡片样式用户项组件
• UserListItem.tsx: 列表样式用户项组件
• UserListLargeItem.tsx: 大列表样式用户项组件

自定义Hooks (hooks/)

• useSteamUsers.ts: 用户数据获取、刷新、模拟数据逻辑

3.3 预期效果

• 主组件文件从432行减少到约150行
• 每种视图模式独立组件，便于维护
• 减少代码重复

---

重构执行计划

阶段1: FpsTest.tsx 重构（最高优先级）

1. ✅ 创建目录结构和基础文件
2. ✅ 提取工具函数到 utils/ 目录
   • ✅ vprof-parser.ts - VProf报告解析
   • ✅ timestamp.ts - 时间戳处理
   • ✅ fps-metrics.ts - FPS指标提取
   • ✅ csv-export.ts - CSV导出功能
3. ✅ 提取自定义Hooks到 hooks/ 目录
   • ✅ useGameMonitor.ts - 游戏运行状态监控
   • ✅ useHardwareInfo.ts - 硬件信息获取
   • ⏳ useTestMonitor.ts - 测试结果监控（待完成）
   • ⏳ useBatchTest.ts - 批量测试逻辑（待完成）
4. ✅ 提取部分UI组件到 components/ 目录
   • ✅ NoteCell.tsx - 备注单元格组件
   • ⏳ TestConfigPanel.tsx - 测试配置面板（待完成）
   • ⏳ ResolutionConfig.tsx - 分辨率配置（待完成）
   • ⏳ TestResultsTable.tsx - 测试结果表格（待完成）
   • ⏳ TestResultDisplay.tsx - 测试结果展示（待完成）
   • ⏳ BatchTestProgress.tsx - 批量测试进度（待完成）
5. ⏳ 提取服务层逻辑到 services/ 目录
   • ⏳ testRunner.ts - 测试执行服务（待完成）
   • ⏳ resultReader.ts - 结果读取服务（待完成）
6. ⏳ 重构主组件，整合所有子模块（进行中）
   • ✅ 创建类型定义文件
   • ⏳ 完整重构主组件（需要继续）
7. ⏳ 测试验证功能完整性（待完成）

阶段2: VideoSetting.tsx 重构

1. ⏳ 提取配置数据
2. ⏳ 提取自定义Hooks
3. ⏳ 拆分编辑/查看组件
4. ⏳ 重构主组件

阶段3: SteamUsers.tsx 重构

1. ⏳ 提取用户项组件
2. ⏳ 提取数据管理Hook
3. ⏳ 重构主组件

---

重构原则

1. 保持功能完整性：重构过程中确保所有功能正常工作
2. 渐进式重构：分步骤进行，每步完成后验证
3. 向后兼容：不改变对外接口，保持组件使用方式不变
4. 代码复用：提取公共逻辑，避免重复代码
5. 类型安全：保持TypeScript类型完整性

---

已完成的工作

FpsTest.tsx 重构进度

✅ 已完成

1. 目录结构创建

   • ✅ src/components/cstb/FpsTest/ 目录结构已创建

2. 常量提取

   • ✅ constants.ts - BENCHMARK_MAPS, PRESET_RESOLUTIONS, TEST_TIMEOUT

3. 工具函数提取

   • ✅ utils/vprof-parser.ts - parseVProfReport函数
   • ✅ utils/timestamp.ts - compareTimestamps, formatCurrentTimestamp, timestampToISO
   • ✅ utils/fps-metrics.ts - extractFpsMetrics函数
   • ✅ utils/csv-export.ts - handleExportCSV, handleExportAverageCSV, formatVideoSettingSummary

4. 自定义Hooks提取

   • ✅ hooks/useGameMonitor.ts - 游戏运行状态监控
   • ✅ hooks/useHardwareInfo.ts - 硬件信息获取

5. 组件提取

   • ✅ components/NoteCell.tsx - 备注单元格组件

6. 类型定义

   • ✅ types.ts - Resolution, BatchTestProgress, FpsMetrics, ResolutionGroupInfo

⏳ 待完成

1. 更多Hooks

   • hooks/useTestMonitor.ts - 测试结果文件监控逻辑
   • hooks/useBatchTest.ts - 批量测试状态管理和执行逻辑

2. 更多组件

   • components/TestConfigPanel.tsx - 测试地图、批量测试次数、备注配置
   • components/ResolutionConfig.tsx - 分辨率设置组件
   • components/TestResultsTable.tsx - 测试结果表格
   • components/TestResultDisplay.tsx - 当前测试结果显示
   • components/BatchTestProgress.tsx - 批量测试进度显示

3. 服务层

   • services/testRunner.ts - 测试执行服务（runSingleTest, startTest）
   • services/resultReader.ts - 结果读取服务（readResult）

4. 主组件重构

   • 使用提取的模块重构 index.tsx
   • 确保所有功能正常工作

注意事项

1. 重构前确保有完整的测试覆盖（如果有）
2. 重构过程中注意保持状态管理的一致性
3. 提取Hook时注意依赖项的正确传递
4. 组件拆分时注意props的类型定义
5. 工具函数提取时注意副作用处理
6. 重要: 原文件 FpsTest.tsx 暂时保留，待重构完成并测试通过后再删除
7. 当前状态: 已提取基础模块，主组件重构需要继续完成