MusicWorkshop/docs/superpowers/specs/2026-05-07-workbench-refactor-design.md

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

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

// 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: 构建验证