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. **当前状态**: 已提取基础模块，主组件重构需要继续完成