MusicWorkshop/docs/superpowers/specs/2026-05-08-settings-page-refactor-design.md

SettingsPage 重构 — 设计规格

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

概述

将 SettingsPage.jsx 从 ~700 行单体组件重构为 8 个聚焦组件 + 1 个自定义 hook 的模块化架构，继承深色专业主题风格。

核心痛点

• 所有配置节（路径/调度/通知/元数据服务）内联渲染
• 导出/导入对话框逻辑（~150 行）耦合在页面组件中
• 调度 cron 解析逻辑（~140 行工具函数）占据文件头部
• Toast 通知、元数据连通性检测、网络状态管理混杂在一处

设计决策

维度	决策
视觉风格	继承深色专业主题（indigo/slate）
组件拆分	5 个配置节组件 + 2 个对话框组件 + 1 个服务状态组件
状态管理	useSettingsForm hook 封装 localConfig、调度更新逻辑
后端改动	无需改动

组件架构

src/
├── pages/
│   └── SettingsPage.jsx                 # ~100行容器
├── components/settings/
│   ├── CorePathsSection.jsx             # 核心目录配置（输入/输出/回收站）
│   ├── ScheduleSection.jsx              # 定时调度配置（每日/每周/Cron）
│   ├── AdvancedStrategySection.jsx      # 高级策略（元数据回退、素材下载等）
│   ├── NotificationSection.jsx          # 通知配置（钉钉/Telegram/邮件）
│   ├── MetadataServicesSection.jsx      # 元数据服务配置（8个provider）
│   ├── ConfigExportDialog.jsx           # 配置导出对话框
│   ├── ConfigImportDialog.jsx           # 配置导入对话框
│   └── ServiceStatusBadge.jsx           # 服务连通性状态徽章
├── hooks/
│   └── useSettingsForm.js               # 配置表单状态 + 调度更新 + 导出/导入
└── utils/
    └── schedule.js                      # 调度工具函数（从 SettingsPage 头部抽取）

组件职责

SettingsPage — 页面容器（~100行）

• 通过 useSettingsForm hook 管理配置状态
• 渲染 5 个配置节组件 + 2 个对话框
• 不包含任何配置渲染细节

CorePathsSection — 核心目录配置

• Props: input, output, trash, onUpdate
• 三个文本输入字段（输入目录/输出目录/回收站）

ScheduleSection — 定时调度配置

• Props: schedule, onUpdate
• 三种调度类型选择（每日/每周/Cron）+ 时间选择 + 星期选择

AdvancedStrategySection — 高级策略配置

• Props: advancedStrategy, onUpdate
• 元数据回退、素材下载等开关

NotificationSection — 通知配置

• Props: notifications, onUpdate
• 钉钉 Webhook/Secret、Telegram Bot Token/ChatID、Email SMTP 配置

MetadataServicesSection — 元数据服务配置

• Props: metadata, netStatus, onUpdate
• 8 个元数据 provider 的 URL/Key 配置 + 连通性状态徽章

ConfigExportDialog — 导出对话框

• Props: isOpen, isExporting, password, passwordConfirm, onClose, onExport, onPasswordChange
• 密码确认 + 导出按钮

ConfigImportDialog — 导入对话框（多阶段：解密密码 → 确认 → 保存）

• Props: importDialog state, onClose, onDecrypt, onConfirm
• 文件选择 → 密码输入 → 配置预览确认

ServiceStatusBadge — 服务状态徽章

• Props: status, latencyMs, message
• 探测中/在线/警告/离线/未检测 五种状态

自定义 Hook

useSettingsForm

• 封装 localConfig 状态管理
• 调度类型/时间/日期/Cron 更新函数
• 保存/导出/导入/网络检测逻辑
• Toast 通知状态
• 返回 { localConfig, netStatus, toast, isSaving, updateField, updateSchedule, handleSave, handleExport, handleImport, ... }

数据流

SettingsPage (顶层 ~100行)
  │
  ├─ useSettingsForm()   ──→ localConfig, updateField, updateSchedule, handleSave...
  │
  ├─ CorePathsSection      ← config.input/output/trash
  ├─ ScheduleSection       ← config.schedule
  ├─ AdvancedStrategySection ← config.advancedStrategy
  ├─ NotificationSection   ← config.notifications
  ├─ MetadataServicesSection ← config.metadata + netStatus
  ├─ ConfigExportDialog    ← exportState, onClose, onExport
  └─ ConfigImportDialog    ← importState, onDecrypt, onConfirm

工具函数抽取

scheduler.js 从 SettingsPage 头部（1-142 行）抽取：

• normalizeSchedule, getScheduleSummary
• buildDailyCron, buildWeeklyCron
• formatTimeFromCron, padCronSegment
• formatBackupTimestamp

兼容性

• 保留所有现有功能不变
• saveConfig API 调用格式不变
• fetchMetadataStatus API 调用不变
• handleSave 同时更新父组件 config 和 taskState

非目标（不在本次范围）

• 后端 API 修改
• 新增配置项
• LibraryPage / HistoryPage / MissingTagsInlinePanel 优化（后续单独处理）

实现顺序

1. Phase 1: 抽取调度工具函数到 utils/schedule.js
2. Phase 2: 创建 useSettingsForm hook
3. Phase 3: 创建 5 个配置节组件
4. Phase 4: 创建 2 个对话框组件 + ServiceStatusBadge
5. Phase 5: 重写 SettingsPage 为轻量容器
6. Phase 6: 构建验证