## Context

当前 `spectrum-visualizer` 能力仅支持 4 种频谱效果，且效果切换与效果渲染逻辑耦合较高。此次变更需要在不破坏现有 4 种效果体验的前提下，扩展可选效果数量，并保证播放中实时切换稳定、渲染性能可控、用户上次选择可恢复。

约束条件：
- ArkTS UI 和渲染逻辑位于 `entry/src/main/ets/view/` 与 `entry/src/main/ets/viewmodel/`。
- 频谱数据来源与播放链路不变，不引入新的音频解码协议或外部依赖。
- 中低端设备需避免因效果分支增多导致掉帧或明显功耗上升。

## Goals / Non-Goals

**Goals:**
- 将频谱效果扩展为可配置的效果集合，支持后续继续新增。
- 统一效果元数据（ID、名称、默认参数、渲染策略），避免在页面中硬编码分支。
- 支持播放过程中无感切换效果，并记住用户最近一次选择。
- 为每个效果定义最小性能边界（刷新频率、点数/条数上限、降级策略）。

**Non-Goals:**
- 不修改音频 PCM/FFT 数据获取链路。
- 不引入在线下载效果、主题商店或脚本化效果系统。
- 不重做整体播放器 UI 布局，仅在现有入口扩展效果选择体验。

## Decisions

1. 建立效果注册表（Effect Registry）而非继续使用 `switch/case` 扩展。
- 方案：以统一结构维护效果定义（`effectId`、展示名、参数默认值、渲染函数引用、性能等级）。
- 原因：新增效果只需注册配置与渲染实现，减少 UI 与渲染层的重复改动。
- 备选方案：继续在现有渲染组件中追加条件分支。
- 不采用原因：分支增长会快速增加维护成本，且难以统一做性能控制。

2. 采用“共享数据输入 + 效果独立渲染器”的分层。
- 方案：FFT/幅值数据由现有链路统一提供，不同效果仅消费标准化频谱帧。
- 原因：避免每个效果重复处理原始数据，降低行为不一致风险。
- 备选方案：每个效果自行拉取并处理数据。
- 不采用原因：会造成重复计算和状态分散，切换时更易出现抖动。

3. 增加效果状态持久化字段并设置兼容回退。
- 方案：保存 `selectedEffectId`；启动时若配置不存在或无效，回退到历史默认效果。
- 原因：保障升级后配置兼容，避免因效果下线或重命名导致页面异常。
- 备选方案：不持久化，每次启动使用默认效果。
- 不采用原因：用户体验不稳定，无法满足“记忆和恢复”目标。

4. 引入统一性能守卫。
- 方案：按效果定义最大刷新率与采样点上限，在帧耗时过高时触发降级（降低刷新率/简化细节）。
- 原因：新增效果后，性能风险主要来自复杂绘制路径；统一守卫可避免逐个临时修补。
- 备选方案：仅做人工测试，不加运行时守卫。
- 不采用原因：设备差异大，纯人工验证无法覆盖全部场景。

## Risks / Trade-offs

- [效果数量增加导致选择复杂度上升] → 通过分组命名和默认推荐效果降低决策成本。
- [部分高复杂度效果在低端设备掉帧] → 为每个效果设性能等级并启用运行时降级。
- [注册表与现有逻辑并存期间出现双源状态] → 迁移阶段保留单一状态入口（仅 `selectedEffectId` 为真源）。
- [历史配置兼容问题] → 增加配置合法性校验，非法值自动回退并记录日志。

## Migration Plan

1. 新增效果注册表与标准化渲染接口，保持现有 4 种效果先接入新接口。
2. 扩展效果切换 UI，读取注册表动态渲染选项。
3. 添加 `selectedEffectId` 持久化与启动恢复逻辑。
4. 逐步接入新增效果并启用性能守卫。
5. 完成真机冒烟：切换稳定性、后台恢复、中低端设备帧率/功耗观察。

回滚策略：
- 若出现严重性能或崩溃问题，可在配置层禁用新增效果，仅保留原 4 种已验证效果；
- 保留旧默认效果回退逻辑，确保用户可继续播放与可视化。

## Open Questions

- 首批新增效果的目标数量是否固定（例如从 4 扩展到 8）？
- 效果命名和分组是否需要产品/UI 设计参与统一规范？
- 性能守卫的阈值是否需要按设备档位做差异化配置？

## Implementation Notes (2026-02-08)

- 已完成代码实现：效果注册表、动态特效选择、新增脉冲特效、渲染性能守卫、`selectedSpectrumEffectId` 持久化与兼容回退。
- 风险记录更新：性能守卫阈值基于通用策略，仍需真机分档验证后再微调。
- 当前验证结果：已完成静态代码检查与文件级自检；真机冒烟（切页、暂停恢复、中低端性能）待执行。