MusicWorkshop/docs/superpowers/specs/2026-05-07-exception-center-redesign.md

异常中心页面优化 — 设计规格

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

概述

对 MusicWorkshop 异常中心页面（ExceptionPage.jsx）进行全面的视觉、交互、流程和代码结构优化。

核心痛点

• 页面不够美观（首要痛点）
• 操作太繁琐
• 向导流程太长（保留 5 步但优化界面）
• 代码维护困难（800+ 行单文件）

设计决策

维度	决策
视觉风格	深色专业（Dark Professional）— 暗色主题 + 靛蓝高亮 + 微弱边框
页面布局	向导聚焦布局（Wizard Focus）— 顶部步骤条 + 左侧队列 + 右侧操作区
向导步骤	保持 5 步（确保入库数据精准性）
代码重构	按功能区拆分组件 + 提取自定义 hooks
后端改动	无需改动（API 和数据结构不变）

视觉设计

配色方案

背景: #0f172a (slate-900) — 主背景
卡片: #1e293b (slate-800) — 面板/卡片背景
边框: #334155 (slate-700) — 微弱的组件边框
文字: #e2e8f0 (slate-200) — 主文字
次要: #94a3b8 (slate-400) — 辅助文字/标签
高亮: #6366f1 (indigo-500) — 主要操作/选中状态
成功: #22c55e (green-500) — 完成/入库操作
警告: #f59e0b (amber-500) — 需注意的异常
错误: #ef4444 (red-500) — 失败状态

异常类型标签色

元数据缺失: amber (amber-700 背景, amber-400 文字)
匹配失败: red (red-900 背景, red-400 文字)
匹配分过低: amber
转码失败: red
文件重复: slate
入库失败: red

排版

• 字体: 继承项目现有 Tailwind 配置（系统字体栈）
• 步骤标题: text-lg font-semibold
• 歌曲名称: text-sm font-medium
• 元数据标签: text-xs text-slate-400
• 按钮: text-sm font-medium rounded-lg

页面布局

┌──────────────────────────────────────────────────┐
│  🏠 异常中心                          [高级视图] │
├──────────────────────────────────────────────────┤
│  ①选择歌曲 ── ②试听确认 ── ③推荐匹配 ── ④手动编│
│  辑 ── ⑤入库确认                                │
├────────────┬─────────────────────────────────────┤
│ 队列 (12)  │  🎵 01 - 夜曲.mp3                   │
│            │  ┌─────────────────────────────────┐│
│ ▸ 01-夜曲  │  │ 匹配候选:                      ││
│   track_02 │  │ ▸ 夜曲 / 周杰伦 · 十一月的萧邦  ││
│   unknown  │  │   95% · MusicBrainz             ││
│            │  │   Nocturne / Jay Chou           ││
│            │  │   78% · Spotify                 ││
│            │  └─────────────────────────────────┘│
│            │  [确认选择] [手动编辑] [跳过 →]     │
├────────────┴─────────────────────────────────────┤
│  ⚡ 修复任务: 3/12 完成 · running                 │
└──────────────────────────────────────────────────┘

组件架构

src/
├── pages/
│   └── ExceptionPage.jsx              # 页面容器（路由入口 + 顶层状态协调）
├── components/exceptions/
│   ├── ExceptionStatsBar.jsx          # 顶部统计概览条
│   ├── ExceptionTypeNav.jsx           # 异常类型筛选标签
│   ├── ExceptionWizard.jsx            # 5步向导主控制器
│   ├── ExceptionListView.jsx          # 高级列表视图（备用，对应高级模式）
│   ├── steps/
│   │   ├── StepSelect.jsx             # 步骤1：选择歌曲
│   │   ├── StepListen.jsx             # 步骤2：试听确认
│   │   ├── StepMatch.jsx              # 步骤3：推荐匹配
│   │   ├── StepEdit.jsx               # 步骤4：手动编辑
│   │   └── StepConfirm.jsx            # 步骤5：入库确认
│   ├── RepairTaskPanel.jsx            # 修复任务实时状态面板
│   └── ActionPreviewModal.jsx         # 操作预览/确认弹窗
├── hooks/
│   ├── useExceptionSummary.js         # 异常概览数据获取
│   ├── useExceptionList.js            # 异常列表（分页/筛选/队列）
│   ├── useExceptionDetail.js          # 单条异常详情
│   ├── useRepairTask.js               # WebSocket 修复任务跟踪
│   └── useWizardState.js              # 向导步骤状态管理

组件职责

ExceptionPage — 页面容器，轻量级

• 仅持有顶层路由和视图模式切换（wizard / advanced）
• 通过 props 传递共享状态
• 不包含任何步骤逻辑或 UI 细节

ExceptionStatsBar — 顶部统计概览

• Props: summary (总数/分类统计)
• 显示：开放中 / 处理中 / 已解决 三个统计卡片
• 深色主题：渐变靛蓝背景卡片

ExceptionTypeNav — 类型筛选标签

• Props: activeFilter, onFilterChange, counts
• 水平滚动的胶囊标签，显示各类型数量
• 深色主题：选中靛蓝填充，未选中 slate 边框

ExceptionWizard — 5步向导控制器

• 管理 5 个步骤的切换（由 useWizardState hook 驱动）
• 渲染当前步骤组件，传递必要的 props
• 步骤条 UI：圆形步骤编号 + 连接线，已完成绿色/当前靛蓝/待完成 slate

步骤组件 (StepSelect, StepListen, StepMatch, StepEdit, StepConfirm)

• 每个步骤是独立组件
• 通过 props 接收：detailRecord, action, params, previewState
• 通过回调通知：onActionChange, onParamsChange, onPreview, onExecute

RepairTaskPanel — 修复任务面板

• 显示当前修复任务的进度
• WebSocket 实时日志流
• 可折叠设计

ActionPreviewModal — 操作预览弹窗

• 显示批量操作的预览结果
• 风险等级标识（低/中/高）
• 确认/取消操作

自定义 Hooks

useExceptionSummary

• 封装 fetchExceptionSummary API 调用
• 返回 { summary, error, refresh }

useExceptionList

• 封装 fetchExceptionItems API（分页/筛选/队列模式）
• 管理 items, total, page, filter 状态
• 返回 { items, total, page, filter, setFilter, setPage, refresh, loading, error }

useExceptionDetail

• 封装 fetchExceptionItem API
• 由 selectedExceptionId 驱动自动获取
• 返回 { detail, loading, error, refresh }

useRepairTask

• 封装 WebSocket 连接 + repair task 状态
• 管理 repairTask, repairLogs
• 自动处理重连

useWizardState

• 管理：wizardStep, selectedAction, actionParams, previewState, executeError
• 步骤切换逻辑：inferDefaultAction, buildDefaultParams
• 返回 { wizardStep, setWizardStep, selectedAction, setSelectedAction, ... }

数据流

ExceptionPage (顶层)
  │
  ├─ useExceptionSummary() ──→ ExceptionStatsBar
  ├─ useExceptionList()    ──→ 左侧歌曲队列
  ├─ useExceptionDetail()  ──→ 当前选中歌曲详情
  ├─ useWizardState()      ──→ ExceptionWizard → 5 步骤组件
  └─ useRepairTask()       ──→ RepairTaskPanel

数据通过 props 向下流动，回调通过 props 向上通知。不使用 Context（避免不必要的心智负担）。

交互优化

平滑过渡

• 步骤切换：CSS transition 淡入淡出（150ms）
• 列表项选择：背景色过渡（150ms）
• 弹窗：fade + scale 动画（200ms）

微交互

• 悬停状态：列表项 hover 时背景微亮（slate-700）
• 操作按钮：hover 时颜色加深 10%
• 统计卡片：hover 时轻微上浮 (translateY -2px)
• 加载状态：骨架屏替代纯 spinner

键盘导航

• ← → 键切换向导步骤
• ↑ ↓ 键在歌曲队列中导航
• Enter 确认当前操作
• Escape 关闭弹窗

5步向导流程（保持现有逻辑）

步骤	名称	功能	可操作
1	选择歌曲	从异常队列选择歌曲	点击选中
2	试听确认	播放音频确认文件正确	播放/暂停
3	推荐匹配	查看元数据候选列表	选择候选/确认
4	手动编辑	编辑元数据字段	修改字段值
5	入库确认	确认目标路径并入库	预览/执行

步骤可自由前进后退（已确认的操作不丢失）。

兼容性

保留功能

• 高级列表视图模式（通过右上角切换入口）
• 批量操作（在高级列表模式下）
• 所有现有 API 端点不变
• 所有现有异常类型和操作动作

浏览器支持

• Chrome, Firefox, Safari, Edge 最近 2 个主版本
• 不需要 IE 支持

非目标（不在本次范围）

• 后端 API 修改
• 新增异常类型
• 新增修复操作类型
• 国际化（i18n）
• 移动端适配（保持桌面端优先，响应式布局兜底）

实现顺序

1. Phase 1: 提取自定义 hooks（纯逻辑层，不改变 UI）
2. Phase 2: 拆分步骤组件（保持原有 5 步逻辑）
3. Phase 3: 重构 ExceptionPage 容器（集成 hooks + 组件）
4. Phase 4: 应用深色专业主题样式
5. Phase 5: 添加过渡动画和微交互
6. Phase 6: 更新高级列表视图样式
7. Phase 7: 测试与验证

每个 Phase 完成后进行功能验证，确保不引入回归。