五个入口，
一张自己的节目单。

页面结构

榜单
├─ 顶部来源选择        网易云 / QQ / 酷狗…
├─ 主推榜单            趋势信息 + 前 3 首
├─ 更多榜单            该平台可用的榜单列表
├─ 平台热歌            当前来源的热门单曲
└─ 迷你播放器 + 五栏底导

进入榜单
├─ 封面、名称、更新频率、曲目数
├─ 播放全部 / 换源设置
└─ 排名列表
   ├─ 点击歌曲：播放并打开播放器
   └─ 更多：换源、其他版本、合并/拆分、收藏、下载

为什么这样分

原首页的“排行榜”只是推荐位；榜单作为主入口后，需要承载来源切换、榜单列表、热歌和详情页。与其把四种模块塞进首页，不如让榜单成为可反复浏览的空间。

结构

歌单
├─ 来源：网易云 / QQ / 酷狗 / 酷我…
├─ 推荐 | 分类
│
├─ 推荐
│  ├─ 主推歌单：大封面 + 标题 + 曲目数
│  ├─ 横向推荐行
│  └─ 分类快捷入口
│
└─ 分类
   ├─ 分类 chip 组（可折叠）
   ├─ 两列封面网格
   └─ 上一页 / 下一页

详情
├─ 封面、标题、来源、曲目数
├─ 播放全部 / 收藏整张歌单
└─ 与榜单详情相同的歌曲列表

刻意不做的事

不在歌单页做“聚合歌单内容”。同名歌单只是名字相同，曲目、顺序和版本都可能不同。搜索页可以把多个平台的同名歌单并列展示；歌单页本身只读取一个平台。

页面结构

我的
├─ 顶部：云同步入口（状态点）
├─ 统计条：喜欢 / 自建歌单 / 已下载
├─ 段控件：喜欢 | 歌单 | 最近 | 下载
│
├─ 歌单
│  ├─ 同步状态横幅
│  ├─ 歌单列表（已同步 / 待同步 / 冲突）
│  └─ 新建歌单
│
├─ 喜欢 / 最近
│  └─ 歌曲行，支持播放与加入歌单
│
└─ 下载
   └─ 完成 / 下载中的本地文件

自建歌单详情
├─ 播放全部 / 添加歌曲
├─ 同步状态
├─ 排序与移除
└─ 更多：改名、删除、导出

为什么默认停在“歌单”

“喜欢”是一组自动形成的歌，“自建歌单”是用户主动维护、最需要同步和编辑能力的部分。作为本次改版的重点，进入“我的”默认展示歌单，其余段按用户上次选择记忆。

设置索引

设置
├─ 外观
│  └─ 主题 / 动态配色 / 减少动画
├─ 播放与换源
│  └─ 换源模式 / 优先平台 / 试听 / 匹配严格度
├─ 均衡器
│  └─ 开关 / 预设 / 频段 / 自定义曲线
├─ 搜索与浏览
│  └─ 聚合平台 / 搜索范围 / 默认浏览来源
├─ 平台账号
│  └─ Cookie / 扫码登录 / 退出
├─ 音乐库同步
│  └─ 同步账户 / 自动同步 / Wi-Fi / 冲突
├─ 存储
│  └─ 播放缓存 / 匹配缓存 / 下载
└─ 关于与更新
   ├─ 版本、构建号、更新检查
   ├─ 开源许可、项目主页
   └─ 隐私说明、诊断信息

交互约定

设置项即改即存，没有底部“保存”按钮。令牌、Cookie 等敏感输入离开页面即清空明文，只保留加密存储。危险操作（清空缓存、断开同步、退出账号）都需要二次确认，并说明会影响什么。

界面与交互

设置
├─ 播放与换源
│  ├─ 换源模式
│  ├─ 优先平台
│  └─ 试听 / 严格匹配
└─ 均衡器
   ├─ 开关与当前输出
   ├─ 预设
   └─ 频段 / 自定义

均衡器
├─ 开关 + 当前输出状态
├─ 预设：平直 / 流行 / 摇滚 / 爵士 / 人声 / 自定义
├─ 频段滑杆（按设备实际频段绘制）
│  ├─ 拖动立即生效
│  ├─ 数值以 dB 显示
│  └─ 手动改动后自动切到“自定义”
├─ 恢复平直 / 保存为自定义
└─ 兼容性说明与当前播放源

为什么不做成浮层

均衡器是多参数、需要反复试听的页面。把它塞进播放器浮层会遮挡封面，也不方便精细拖动。独立页面能容纳完整频段、预设和兼容性说明，并能在播放器继续播放的同时操作。

控制器职责

class EqualizerController(
    private val store: EqualizerSettingsStore,
) {
    fun attach(sessionId: Int)     // 创建或重建 Equalizer
    fun detach()                   // 播放器销毁 / session 失效
    fun setEnabled(enabled: Boolean)
    fun applyPreset(preset: EqPreset)
    fun setBandLevel(band: Short, millibels: Short)
    fun resetFlat()
    fun saveAsCustom()
}

// Media3：Player.Listener.onAudioSessionIdChanged
// 与 Player.getAudioSessionId() 获取会话。
// ExoPlayer 的相关 API 标注为 UnstableApi，
// 需要在 PlaybackService 中显式 OptIn。

保存与生效

DataStore 只保存 enabled、presetId 和自定义频段增益（dB）。应用启动或 PlaybackService 重建时读取并重新应用，不把设置写进歌曲或歌单。

预设曲线由应用定义：平直全 0 dB；流行强调低频与高频；摇滚提升低频和 3 kHz 附近；爵士轻微提升低频与高频；人声压低 60–230 Hz 并抬高中频。设备支持的频段数不同，就按中心频率做对数插值，而不是硬套五段。

本机模型

playlists
  id TEXT PK (UUID)
  name TEXT
  createdAt / updatedAt
  dirty INTEGER
  deletedAt TEXT?

playlist_entries
  playlistId TEXT FK
  position INTEGER
  songKey TEXT
  payload TEXT

sync_accounts
  provider TEXT PK
  remoteId TEXT
  fileName TEXT
  lastSyncedAt INTEGER
  remoteRevision TEXT
  autoSync INTEGER
  wifiOnly INTEGER

sync_base
  accountId TEXT PK
  snapshot TEXT
  remoteRevision TEXT

sync_conflicts
  playlistId TEXT PK
  localSnapshot TEXT
  remoteSnapshot TEXT
  detectedAt INTEGER

凭据与迁移

令牌使用 Android Keystore 的 AES-GCM 密钥加密，存入独立的 SecretStore，不进入 Room，也不进入同步 JSON。应用备份规则排除 SecretStore；断开同步时删除令牌和基线，但保留本机歌单。

现有 LocalPlaylist(id: Long, songs: JSON) 迁移到 UUID 歌单和逐条曲目表：开新表、解析旧 JSON、复制曲目和顺序、最后切换读取路径。迁移必须在事务中完成，旧表保留一个版本周期再删除。

自动检查不打扰

启动时如果发现稳定版更新，只在设置索引的“关于与更新”旁显示一个圆点，不弹窗。用户进入关于页才看到版本差异与更新说明。同一版本被“稍后”后，24 小时内不再提示。手动检查则无论是否有更新都给出明确结果。

只提供稳定通道。当前 main 发布稳定版，dev 为预发布；V1 不跟随预发布，避免用户被开发版打断。将来要加测试通道时，在清单里增加 channel 并由用户显式选择。

必须处理的失败

保留为全局

这些状态会跨页签存在，且播放不能被搜索或音乐库页面的生命周期打断。播放器与 MediaController 仍由全局持有者管理。

下沉为页面状态

每个页面只持有自己需要的状态。切换页签时保留，离开应用后不要求恢复草稿；搜索历史、歌单来源等需要持久化的内容写入 DataStore。