Nekosonic-Music/CHANGELOG.md

## v0.9.0

本次版本为音源系统与播放器核心重构版本，新增多音源融合系统、歌曲标签体系、搜索建议、播放器稳定性优化等重大功能。

### ✨ 新功能

#### 🎵 多音源系统
- **可配置多音源**：支持配置多个音源（波点、酷狗、酷我），可独立启用/禁用/排序，支持自定义音源扩展
- **音质优化**：酷我音源支持更高音质播放，提供更多音质选择
- **多源自动切换**：歌曲播放时自动尝试多个音源，版本一致性匹配（原版/DJ/Live/混音）
- **多源融合搜索**：搜索结果聚合多个音源，按歌名+歌手组合去重，提供更多选择

#### 🏷️ 歌曲标签体系
- **智能标签显示**：自动识别并显示歌曲标签（音质/版本/音源），提供清晰的歌曲信息展示
- **权限信息聚合**：统一管理歌手、歌单、专辑、每日推荐、收藏页的歌曲权限信息

#### 🔍 搜索体验优化
- **实时搜索建议**：输入时自动显示搜索建议，支持中文拼音输入，120ms 防抖优化
- **compositionend 支持**：正确处理中文输入法的组合输入过程，实时响应
- **浮层定位优化**：Teleport + fixed 定位，避免被父容器裁剪，显示更完整

### 🎨 播放器改进

#### 🎧 核心播放优化
- **网络流 seek 支持**：sharedBuffer 下载完成后支持拖动进度条跳转（byte_len 可用）
- **切歌流程优化**：停止旧歌曲播放后再加载新歌曲，进度条正确归零，避免音频叠加
- **加载状态可视化**：切歌时按钮显示加载状态并禁用，提供清晰的交互反馈
- **tick generation 防竞态**：无 tick 时不覆盖新歌曲位置，避免播放位置跳变

#### 🖥️ 系统媒体控制
- **跨平台媒体键支持**：系统媒体控制集成（Windows/Linux/macOS），支持媒体键、通知栏、锁屏控制
- **Windows hwnd 就绪检查**：增加窗口句柄就绪检查，避免 panic，提升稳定性

## v0.8.1

### 🐛 修复
- **关闭到托盘不生效**：点击关闭按钮选择「最小化到托盘」或「直接退出」时，窗口未隐藏/退出。原因是 `capabilities/default.json` 缺少 `core:window:allow-hide` 权限，前端调用 `currentWindow.hide()` 被 Tauri 2 权限系统静默拦截。补齐 `allow-hide` 与 `allow-show` 权限

## v0.8.0

本次版本为架构重构与交互升级版本，涵盖皮肤系统、详情页架构、侧边栏交互、播放器稳定性、底层模块拆分等方面的系统性优化。

### ✨ 新功能
- **皮肤系统重构**：新增 `skins.ts` 模块，定义 `SkinColors` 色板（bg/surface/subtle/muted/emphasis/content×4/line×2/accent×4/danger×2/warning/info 共 19 个语义色），通过 `applySkinColors()` 写入 CSS 变量到 `document.documentElement`。内置 14 套预设皮肤（7 色 × 深浅），支持自定义皮肤（颜色 + 壁纸 + 模糊度 + 透明度）
- **设置页皮肤模块**：Settings.vue 新增「皮肤」分区——深浅外观切换、7 色主题色选择、自定义皮肤网格（带壁纸预览）、皮肤编辑器（19 个颜色色板 + 壁纸选择 + 模糊/透明度滑杆）。壁纸通过 Rust 命令读取本地图片转 data URL 渲染
- **顶栏导航**：新增 TopBar 组件，集成前进/后退按钮和搜索框，前进后退按钮仅在与主内容区对齐的位置显示，搜索可直接在顶栏输入，无需再点击搜索选项
- **可折叠侧边栏**：侧边栏支持展开/折叠/抽屉三种模式，折叠时仅显示图标，窗口过窄自动切换为抽屉模式。折叠/展开触发条采用 SPlayer 风格的双竖条设计，hover 时通过 ±12deg 旋转形成方向箭头（参考 naive-ui n-layout-toggle-bar）
- **折叠态歌单浮层**：侧边栏折叠后，hover「我的歌单」「收藏的歌单」图标弹出浮层显示歌单列表，通过 Teleport 渲染到 body 避免被裁剪。浮层高度动态计算，底部永不越过 PlayerBar
- **首页内容扩展**：首页新增「新歌速递」「热门歌手」「新碟上架」三个区块，配合原有的「推荐歌单」「每日推荐」「热门歌单」，共 6 个内容区块
- **通用卡片组件**：新增 PlaylistCard、ArtistCard、AlbumCard、SectionHeader、CardGrid 五个可复用卡片组件，统一封面、标题、副标题、悬浮播放按钮的展示风格
- **虚拟歌曲列表**：新增 VirtualSongList 组件，复用 SongListItem 并支持自定义配置
- **推荐 API**：后端新增 personalized、personalized_newsong、top_artists、top_song、album_newest 五个 Tauri 命令，前端新增 rec.ts API 模块
- **详情页统一架构**：新增 DetailLayout 组件，统一歌单/专辑/歌手三个详情页布局——头部常驻 + 内容独立滚动 + 滚动触发紧凑态（参考 SPlayer ListDetail/useListScroll）。`absolute;inset:0` 脱离主滚动流，flex 列布局让 header `flex-shrink:0` 不被带走，content `flex-1 min-h:0` 独立滚动
- **紧凑态动画**：滚动列表超过 10px 时触发头部收缩，封面/标题缩小、元信息折叠隐藏、按钮缩小，所有过渡统一 `cubic-bezier(0.4, 0, 0.2, 1)` 0.3s，参考 SPlayer `.small` 类行为
- **歌曲/评论 tab 切换**：三个详情页头部均加入歌曲/评论（或热门歌曲/专辑）tab 切换。songs 用 `v-if` 仅激活时渲染，comments 用「首次激活后保活」模式（`v-if` 控制挂载 + `v-show` 控制显示），保留滚动位置且不提前发起评论 API 请求
- **专辑模糊搜索**：专辑详情页头部加入模糊搜索框，按歌名/歌手/专辑名实时过滤歌曲列表，播放全部时只播过滤结果
- **本地音乐多文件夹管理**：本地音乐支持添加多个扫描文件夹，每条可独立启用/禁用/移除，扫描时跳过禁用文件夹

### 🐛 修复
- **个性化推荐错乱**：首页聚合缓存在未登录时生成，登录后未清除导致「依据口味推荐」显示的全站数据。改为登录/登出时清除首页缓存并重新加载，区分登录态调用 `recommend_resource`（个性化）和 `personalized`（全站）
- **播放竞态条件**：切歌、播放/暂停、拖动进度条等异步操作可能产生竞态冲突。引入序列号（`_playSeq`）和状态锁（`_switchingSong`）防护
- **拖动进度条暂停修复**：seek 过程中状态不一致导致播放/暂停混乱
- **折叠态歌单不可用**：折叠时歌单图标用 popover 浮层但被 `overflow-y-auto` 容器裁剪，导致「空有两个按钮没有实际作用」。改用 Teleport + fixed 定位渲染浮层
- **折叠态浮层被 PlayerBar 遮挡**：浮层原用固定 `max-h-60`，触发图标靠下时底部歌单被 PlayerBar 盖住。改为按视口高度动态计算 maxHeight，浮层底部永不越过 PlayerBar 顶部
- **详情页头部被滚走**：原实现头部和列表在同一滚动容器中，向下滚动时封面/标题/按钮全部滚走。重构为 DetailLayout 后头部 `flex-shrink:0` 常驻顶部，列表独立滚动
- **评论 tab 提前加载**：原 PlaylistDetail 用 `v-show` 包裹 CommentSection 导致组件挂载即触发评论 API。改为懒加载 + 保活模式，首次切到评论 tab 才发起请求
- **切换 tab 紧凑态卡死**：评论/歌曲高度差异大，切换 tab 后紧凑态可能卡在错误状态。新增 `watch(currentTab)` 调用 `resetScroll()` 重置滚动和紧凑态
- **侧边栏折叠按钮非箭头**：原实现用单根竖条倾斜，hover 时呈斜线非箭头。改为 naive-ui 双竖条方案：两根 4×38px 竖条 4px 重叠，旋转 ±12deg 形成 `<` 或 `>` 箭头
- **箭头重叠区颜色加深**：opacity 应用到单个竖条导致重叠区颜色叠加变深。改为 opacity 应用到容器（默认 0.5，hover 1.0），竖条使用纯色
- **歌词截断与抖动**：长歌词被 `whitespace-nowrap` 截断。移除该属性并加 `word-break:break-word` + `overflow-wrap:anywhere`；活跃行字号变化导致抖动，锁定 `line-height:1.5`
- **滚动条主题色丢失**：之前误将 `--c-content-3` 用作 thumb 颜色。从 git 历史恢复原实现：hover 容器显示 `--c-muted`，hover thumb 变 `--c-emphasis`，主题切换自动跟随
- **专辑标题字号变化抖动**：从 30px 切到 22px 时容器高度变化导致布局抖动。固定 `line-height:1.3` + `min-height:39px`，过渡期间容器高度恒定
- **AlbumDetail 重复绑定滚动**：keep-alive 首次挂载时 onMounted 和 onActivated 都触发 `bindScroll()`。重构后 DetailLayout 自管滚动监听，AlbumDetail 移除全部 bindScroll/unbindScroll 逻辑

### 🎨 变更
- **侧边栏布局重构**：侧边栏改为全高布局，TopBar 仅在主内容区上方，前进/后退按钮与主内容对齐。侧边栏顶部新增 Logo 占位区（与 TopBar 等高）
- **侧边栏透明化**：移除侧边栏和顶栏的不透明背景色，仅靠一条 40% 透明度的边框线分隔，壁纸/主题色从底层透出，实现「半隐藏」视觉
- **文字不乱跳**：侧边栏展开/折叠过渡时，菜单文字改为 `max-width` + `overflow-hidden` + `whitespace-nowrap` 平滑过渡，不再因宽度变化导致换行乱跳
- **顶栏透明化**：TopBar 移除背景色，加底部细线与侧边栏右边框呼应
- **专辑封面立体感**：专辑详情页封面加入模糊阴影背板（`blur(12px) opacity(0.6) scale(0.92,0.96)`）和顶部渐变遮罩，紧凑时遮罩淡出，参考 SPlayer `.cover-shadow`/`.cover-mask`
- **漫游抽屉外观一体化**：RoamDrawer 改用 `backdrop-blur-xl` 配合皮肤系统色板，外观跟随当前皮肤
- **全局样式精简**：`style.css` 精简约 298 行，原硬编码色值迁移至皮肤 CSS 变量系统

### ⚡ 优化
- **音频模块拆分**：将单文件 audio.rs（1228 行）拆分为 audio/ 目录下 8 个模块（mod/buffer/commands/controller/decoder/device/download/output），提升可维护性
- **状态管理职责分离**：将单一 player store 拆分为 player、liked、recent、ui 四个职责单一的 store
- **类型定义抽取**：Song 等类型定义抽取到 types/song.ts
- **API 层领域分离**：将 api.ts（225 行）拆分为 api/ 目录下 song/playlist/artist/album/search/rec/comment/device 等领域模块，index.ts 作向后兼容层
- **两级缓存**：页面数据和歌词实现 L1 内存 + L2 localStorage 两级缓存，带 TTL 和配额管理
- **设置迁移**：设置数据引入版本号和迁移机制（migrations/settingsMigrations.ts），支持未来 schema 变更
- **AlbumDetail 重构接入 DetailLayout**：原本自行实现 absolute 布局 + isCompact + 滚动监听，与 DetailLayout 逻辑重复。重构后改用 DetailLayout 组件 + slot prop，删除约 100 行重复代码（onScroll/bindScroll/unbindScroll/resetScrollState/listScrollRef/rafId 等）
- **窗口控制逻辑抽取**：TitleBar 与 TopBar 重复实现 minimize/toggleMaximize。抽取为 `composables/useWindowControls.ts` 共用
- **溢出检测抽取**：PlaylistDetail 与 ArtistDetail 重复实现 `checkDescOverflow`。抽取为 `utils/dom.ts` 的 `checkOverflow` 函数共用
- **骨架动画全局化**：`@keyframes pulse` 原在三个详情页分别定义，移至全局 `style.css` 共用
- **死代码清理**：删除未使用的 `pageCacheDelete`（与 `pageCacheInvalidate` 重复）、`getAlbumDisplay`、`stores/player.ts` 中冗余的 `Song/PlayMode` re-export
- **错误日志可读性**：9 处裸 `console.error(e)` 添加描述性前缀（如 `console.error('获取歌单详情失败', e)`），方便定位
- **AlbumDetail watcher 合并**：原本监听 `route.params.id` 的两个 watcher（一个重置状态、一个 fetchAlbum）合并为一个
- **新增后端命令**：`read_image_as_data_url`（读取本地图片转 data URL，供壁纸预览使用）、`show_item_in_folder`（在文件管理器中打开文件位置）

## v0.7.0

### ✨ 新功能
- **音乐云盘**：新增云盘页面，可浏览、播放云盘中的歌曲，查看文件详情（文件名、大小、比特率、上传时间），删除云盘歌曲，查看存储空间使用情况
- **云盘上传**：支持上传本地音频文件到云盘，上传过程显示实时进度，支持 mp3/flac/wav/ogg/aac/m4a 格式
- **下载音乐**：本地音乐拆分为「本地音乐」和「下载音乐」两个独立页面，下载音乐只显示通过应用下载的歌曲
- **本地音乐多文件夹**：本地音乐支持添加多个扫描文件夹，通过三点按钮+弹窗管理文件夹路径
- **歌手关注**：歌手详情页新增关注/取关按钮，关注状态在离开页面后不会丢失
- **粘性导航栏**：页面滚动较深时顶部自动显示返回按钮和功能按钮，渐变模糊效果，不影响阅读
- **骨架屏加载**：首页、歌单、歌手、专辑、云盘等多个页面加载时显示骨架占位动画，不再只有"加载中"文字

### 🐛 修复
- 网络较差时播放启动超时，音乐实际已开始播放但界面仍显示暂停
- 全屏漫游抽屉打开时点击评论按钮无法切换到评论页
- 关闭漫游抽屉后再打开，始终显示评论而非歌词
- 歌手详情页关注后离开再回来，关注状态丢失
- 切歌时偶尔触发上一首歌的播放结束事件导致异常
- 评论点赞无限叠加（改为服务端状态驱动）
- 播放栏进度条上方多余分隔线

### 🎨 变更
- 歌手详情页头像改为圆形，简介从独立标签页移至头部内嵌显示，溢出时可展开查看完整介绍
- 歌单详情页描述溢出时显示"查看完整介绍"按钮
- 首页推荐和排行榜加载失败时显示重试按钮，支持分别重试
- 多个页面的返回按钮统一为粘性导航栏组件
- 消息提示增加去重和数量限制，避免重复弹出

### ⚡ 优化
- 页面切换更流畅，路由全部改为懒加载
- 页面缓存管理优化，30 秒未访问自动释放，多级跳转时保留导航链上的页面，「我喜欢的音乐」常驻缓存
- 本地音乐扫描不再阻塞界面导航
- 应用启动不再等待网络请求完成


## v0.6.0

### ✨ 新功能
- **亮色主题**：新增浅色外观模式，支持深色/浅色切换，7 种主题色各有对应亮色变体
- **封面主色背景**：全屏漫游抽屉背景自动提取封面图主色调，沉浸感更强；抽屉打开时底部播放栏也跟随封面主色，视觉融为一体
- **发现页重做**：支持多类型搜索（歌曲/歌手/专辑），输入时自动显示搜索建议，搜索历史和热门搜索
- **漫游增强**：全屏抽屉支持歌词/评论切换，播放栏新增减少推荐按钮
- **减少推荐**：FM 模式下可标记"不推荐这首歌"或"不推荐这个歌手"，后续不会再收到类似推荐
- **列表风格统一**：正在播放的歌曲序号位置显示跳动动画，鼠标悬停显示播放图标；红心/下载等图标统一使用图标库

### 🐛 修复
- 专辑页艺术家过多时窗口缩小会竖排显示，现在支持自动换行
- FM 播放时退出登录后首页仍可点击下一首
- 本地音乐播放时缓冲进度条未重置
- 亮色主题下多处文字看不见
- 退出 FM 模式时状态未正确清理
- 暗色模式下关闭抽屉时播放栏短暂闪烁亮色

### 🎨 变更
- 移除播放列表按钮上的数字角标
- 主页每日推荐和 FM 卡片标题固定为白色，不随主题变化

### 🧹 清理
- 内部代码优化和冗余清理


## v0.5.1

### 🐛 修复
- 修复页面缓存不刷新的问题：切换回已缓存的页面时数据永远不更新，现在超过 5 分钟会自动重新加载
- 修复本地音乐页面空列表时刷新按钮不显示的问题
- 修复修改下载路径后本地音乐列表不更新的问题，现在会自动刷新
- 修复私人 FM 播放约二三十首后循环重复的问题：新增听歌打卡上报，服务端推荐不再重复
- 修复歌词界面切换翻译开关时歌词未居中的问题
- 修复 Linux 下从外部控制暂停时进度条跳回 0 的问题：MPRIS 现在正确报告播放进度位置

### ⚡ 优化
- 私人 FM 预取队列优化，队列剩余不足时自动后台拉取下一批


## v0.5.0

### ✨ 新功能
- **蓝牙耳机/键盘媒体键控制**：支持通过蓝牙耳机按钮、键盘媒体键、系统通知栏/锁屏面板控制播放、暂停、切歌（Windows / Linux / macOS）
- **网络状态检测**：断网和恢复时弹出提示，网络恢复后自动重新加载页面内容
- **音量记忆**：关闭应用后音量设置不丢失，下次打开自动恢复
- **歌词翻译**：支持显示歌词翻译，可在漫游页面切换开关
- **登录页优化**：已登录用户访问登录页会自动跳转回首页

### 🎨 变更
- 默认主题色改为天蓝色
- 全局快捷键显示顺序调整为 Ctrl + Alt（之前是 Alt + Ctrl）
- 快捷键显示优化：按键名更简洁，如 KeyP 显示为 P
- 页面缓存优化：更多页面切换时保留状态，窗口隐藏时自动释放
- 登录页等待确认时的文字颜色修正

### 🐛 修复
- 手动检查更新时，之前跳过的版本现在会正常弹出更新提示
- 点击正在播放的歌曲无法恢复播放的问题
- 部分内部类型定义问题导致的潜在隐患

### ⚡ 底层优化
- 音频播放引擎全面重构，播放更稳定
- 后端 API 调用模式统一，代码更易维护
- 歌曲数据模型统一，各页面显示更一致


## v0.4.1

添加音频输出外设选择


## v0.4.0

### ✨ 新功能
- 添加歌曲的艺术家入口，歌曲的艺术家现可点击查看其他歌曲、专辑和介绍
- 添加歌曲的评论查看功能

### 🐛 修复
- 修复私人漫游自动播放下一首调用多次问题

### ⚡ 优化
- 优化播放逻辑，歌曲列表在点击时候不再单首累加，而是直接获取当前列表所有的歌曲作为播放内容


## v0.3.0

### ✨ 新功能
- **本地音乐页面**：支持浏览、播放本地歌曲，横向菜单添加「从磁盘删除」功能
- **下载系统**：支持下载歌曲到自定义路径，保存完整元数据（封面/专辑/时长）
- **封面补全**：本地音乐缺少封面时尝试从网易云 API 获取
- **更新信息**：添加查看最新版更新日志按钮 
- **下载路径**：支持自定义下载路径
- **本地音乐**：支持本地音乐播放
- **下载提示**：下载进度与完成提示
- **快捷键绑定**：支持自定义全局和本地快捷键（播放/暂停、上一首/下一首、音量调节）

### 🐛 修复
- 修复私人漫游播完一首歌后跳三首的问题
- 修复全屏漫游抽屉和漫游页面无封面歌曲显示破损图片
- 修复 PlayerBar 无封面歌曲显示破损图片
- 修复播放网络歌曲时进度条先走但无声音

### ⚡ 优化
- **流式播放**：边下载边播放，缓冲 64KB 后即刻开始，无需等待完整下载


## v0.2.0

### 🎵 播放
- 优化私人漫游（个人 FM）功能
- 新增歌曲喜欢/取消喜欢红心
- 新增播放历史本地记录（最近 200 首）

### 📋 歌单
- 修改逻辑 我的歌单 不再显示收藏按钮
- 收藏歌单支持取消收藏
- 实现我的音乐功能
- 实现历史播放记录功能

### 🎨 外观
- 全局复选框与选择框优化
- 部分UI优化，统一风格

### 🖥️ 窗口
- 关闭窗口弹出确认弹窗：最小化到托盘 / 退出程序
- 支持"不再询问"选项，可在设置中修改
- 修复退出时 WebView2 报错（Error 1410）
- 修复歌词抽屉全屏时候顶栏无法接收事件问题

### 💾 持久化
- Cookie 存储迁移至 Tauri app_data_dir
- 播放历史持久化到 localStorage

### ⚙️ 其他
- 添加设置功能
- 关于添加链接可直接访问仓库


## v0.1.0

Nekosonic 是一款基于 Tauri 2 + Rust 的跨平台桌面音乐播放器，音源主要来自网易云音乐，开箱即用。