Pinia 状态与持久化数据流

本页说明项目中 Pinia 的插件装配、已核实的 playerStore 与 userStore 状态边界，以及从浏览器存储恢复、筛选和写回数据的实际路径。

Purpose and Scope

面向需要调整全局状态或排查刷新后状态异常的开发者。重点是 Pinia 装配、播放器状态的存储适配器 与 用户状态的持久化配置。播放音频本身、账号接口、歌单加载等业务实现不在本页展开；相关业务应分别查阅其对应模块。本页不推断尚未读取的其他 store 的持久化策略，也不把插件内部实现当作项目自有代码。

Overview

项目在 pinia.js 创建 Pinia 实例并注册 pinia-plugin-persistedstate；两个已检查的 store 都以 defineStore 声明状态，通过 persist.pick 将有限字段交给插件持久化。播放器 store 另设自定义 storage：读取时兼容旧音量值，写入时跳过与上次值相同的内容；进度 progress 则单独在状态初始化阶段从 playerStore 键读取，而不在持久化字段列表内。用户 store 直接指定 localStorage，账号及部分页面状态的持久化范围由 pick 决定。播放器定义 · 用户定义。

Architecture

Source: pinia.js, playerStore.js, userStore.js

箭头从 pinia 指向 store 表示二者属于同一 Pinia 状态体系，不代表这里已核实应用入口的调用顺序。pinia.js 创建一个 createApp() 实例以调用 app.use(pinia)，随后导出 pinia；此处源码未显示应用根组件的挂载细节。播放器的 storage 适配器与直接访问 localStorage 的用户 store，是两条不同的持久化路径。

装配与字段边界

装配代码先 createPinia()，再 pinia.use(piniaPluginPersistedstate)，随后 app.use(pinia)，最后导出实例。插件在 store 的 persist 配置上工作；本页只描述项目配置及项目定义的 storage 方法，不替插件承诺未在本仓库验证的写回时机或序列化细节。

播放器的 playing、currentMusic、songList、lyric、DOM 引用等没有列入 pick；volume、playMode、歌曲标识与索引、音质、歌词偏移、播放与输出偏好则列入其中。状态存在不等于被持久化：新增字段如需跨刷新保存，须明确检查并修改 pick。状态声明与筛选。用户 store 同理：loginMode、likelist、appOptionShow 等不在筛选列表，而 user 和 biliUser 在其中；调试登出行为时需要把运行时清空与存储筛选分别考虑。用户状态与筛选。

Core Flow：播放器恢复与写入

Source: playerStore.js, playerStore.js

这里有两种互不等价的读取。readInitialProgress() 在 state() 构建时读取键 playerStore，解析其中的 progress；只接受有限且大于零的数值，否则回退到 0。它不是 persist.pick 的一部分，所以本页不能据此声称当前进度一定会通过此配置写回。另一方面，插件使用 playerPersistStorage 作为 persist.storage：getItem 读取字符串，交给 normalizePlayerStorePayload 处理，记录该次返回值；setItem 对比将写入的字符串与缓存或实际存储中的旧值，完全相同时直接返回。初始化路径 · 适配器。

音量迁移语义

适配器只处理键严格等于 playerStore 且值为非空字符串的内容。JSON 解析失败、解析结果不是对象或缺少 volume 时保留原值。有效音量先转数字：非有限数字设为 0.3；(1, 100] 映射为百分比除以 100；其余夹取到 [0, 1]。如果转换结果与原字段严格相等，不重新序列化；否则把修改后的对象序列化为新字符串返回。此处理发生在读取返回值上，代码未在迁移函数中直接写回存储。迁移规则。