# WorkbenchPage 重构 — 设计规格

> 创建日期: 2026-05-07
> 状态: 设计中

## 概述

将 WorkbenchPage.jsx 从 ~800 行单体组件重构为 5 个聚焦组件 + 2 个自定义 hooks 的模块化架构，继承深色专业主题风格。

### 核心痛点

- 所有逻辑在一个文件（任务加载、WebSocket、配置展示、进度可视化、5阶段统计、文件列表、日志流）
- 事件处理爆炸（handleStreamEvent 处理 10+ 种 WebSocket 事件类型）
- 统计展示冗余（5 个阶段 40+ 个 StatCard 重复渲染）
- 配置和控制耦合（目录配置展示和任务启动/监控逻辑混在一起）

## 设计决策

| 维度 | 决策 |
|------|------|
| 视觉风格 | 继承深色专业主题（indigo/slate，与异常中心一致） |
| 组件拆分 | 6 个功能组件 + 2 个自定义 hooks |
| 事件处理 | `useTaskStream` hook 封装 WebSocket 事件处理 |
| 统计面板 | `StageStatsPanel` 通过 stage/stats props 消除 40+ 重复 StatCard |
| 后端改动 | 无需改动 |

## 组件架构

```
src/
├── pages/
│   └── WorkbenchPage.jsx              # ~120行容器（从~800行精简）
├── components/workbench/
│   ├── TaskControlPanel.jsx           # 目录配置展示 + 启动/重试按钮
│   ├── TaskProgressBar.jsx            # 5阶段进度条（Scan→Preprocess→Match→Dedupe→Organize）
│   ├── StageStatsPanel.jsx            # 5阶段统计面板（消除40+重复StatCard）
│   ├── TaskInfoPanel.jsx              # 当前任务基本信息
│   ├── TaskFileList.jsx               # 任务文件列表
│   └── TaskLogStream.jsx              # 实时日志流
├── hooks/
│   ├── useTaskStream.js               # WebSocket 连接 + 10+ 事件类型处理
│   └── useTaskRunner.js               # 任务启动/状态管理
└── utils/
    └── workbench.js                   # 阶段定义、空统计模板等共享常量
```

### 组件职责

**WorkbenchPage** — 页面容器（~120行）
- 通过 useTaskStream 和 useTaskRunner 管理顶层状态
- 将 task/items/logs/config 通过 props 分发给子组件
- 不包含任何渲染细节

**TaskControlPanel** — 任务控制面板
- Props: config, canStart, isRunning, isCompleted, isFailed, onStart, isStarting, errorMessage
- 显示三个目录配置（输入/输出/回收站）
- 根据状态显示不同的启动按钮和提示

**TaskProgressBar** — 5阶段进度条
- Props: task, isRunning, isCompleted, isFailed, progressWidth, progressLabel, latestFile
- 5个圆形步骤节点 + 连接线 + 进度条
- 状态颜色：running=emerald/active=emerald/completed=emerald/failed=rose

**StageStatsPanel** — 阶段统计面板
- Props: stageName, stats, stageConfig
- 通过 STAGE_STATS_CONFIG 自动渲染该阶段的所有统计卡片
- 消除原来 5 个阶段的重复 StatCard 排列

**TaskInfoPanel** — 任务信息面板
- Props: task, latestLogId, hasMoreLogs
- 显示任务状态、当前阶段、开始/完成时间等基本信息

**TaskFileList** — 任务文件列表
- Props: items, isLoading
- 文件项展示：路径、封面/歌词状态、各阶段状态徽章

**TaskLogStream** — 实时日志流
- Props: logs, logsEndRef
- 分色日志行（error=rose/success=emerald/warning=amber/info=blue）

### 自定义 Hooks

**useTaskStream**
- 封装 WebSocket 连接（createTaskStream）
- 处理 10+ 事件类型：task.snapshot, task.started, stage.started, *.progress, stage.completed, task.completed, task.failed, log.appended
- 管理 task, items, logs 状态
- 返回 { task, items, logs, latestFile, hasMoreLogs, latestLogId, loadCurrentTask, startTask, ... }

**useTaskRunner**
- 封装任务启动/停止逻辑
- runTask API 调用 + 409 冲突处理（已有运行中任务）
- 返回 { isStarting, errorMessage, handleStart }

### 数据流

```
WorkbenchPage (顶层 ~120行)
  │
  ├─ useTaskStream()     ──→ WebSocket → task/items/logs 状态
  ├─ useTaskRunner()     ──→ 启动/停止逻辑
  │
  ├─ TaskControlPanel    ← config, canStart, isRunning, isStarting
  ├─ TaskProgressBar     ← task, stageIndex, progressWidth
  ├─ StageStatsPanel ×5  ← task.stats.{scan,preprocess,match,dedupe,organize}
  ├─ TaskInfoPanel       ← task 基本信息
  ├─ TaskFileList        ← items
  └─ TaskLogStream       ← logs
```

## 阶段统计配置（消除重复）

```javascript
// utils/workbench.js
export const STAGE_STATS_CONFIG = {
  scan: [
    { key: 'total_found', label: '候选音频', color: 'white' },
    { key: 'queued', label: '成功入队', color: 'emerald' },
    { key: 'skipped_locked', label: '最近写入跳过', color: 'amber' },
    { key: 'skipped_invalid', label: '无效文件', color: 'rose', error: true },
    // { key: 'ignored_non_audio', label: '静默忽略非音频', fullWidth: true }
  ],
  preprocess: [
    { key: 'input_items', label: '输入项目', color: 'white' },
    { key: 'output_items', label: '有效输出', color: 'emerald' },
    // ... 其余字段
  ],
  match: [ /* ... */ ],
  dedupe: [ /* ... */ ],
  organize: [ /* ... */ ]
};
```

StageStatsPanel 根据 stageName 查找配置，自动生成 `<StatCard>` 列表。

## 兼容性

- 保留所有现有功能不变
- props 接口与现有 constants/STAGES 定义兼容
- WebSocket 事件处理逻辑不变，仅位置改变
- MissingTagsInlinePanel 保持不变

## 非目标（不在本次范围）

- 后端 API 修改
- 新增任务类型
- 配置表单重构（SettingsPage 独立优化）
- MissingTagsInlinePanel 整合（后续单独优化）

## 实现顺序

1. **Phase 1**: 提取共享常量到 `utils/workbench.js`
2. **Phase 2**: 创建 `useTaskStream` hook（最复杂，WebSocket 事件处理）
3. **Phase 3**: 创建 `useTaskRunner` hook（任务启动逻辑）
4. **Phase 4**: 创建 StageStatsPanel 组件（消除最大重复）
5. **Phase 5**: 创建其余 5 个展示组件
6. **Phase 6**: 重写 WorkbenchPage 为轻量容器
7. **Phase 7**: 构建验证