v3.4: 本地存储 (SAF) 双源支持、动态取色与架构深化

💾 本地设备存储（SAF）双源架构与离线播放 (ADR-0032b)

• 本地 SAF 目录持久化授权：支持通过 Storage Access Framework (SAF) 挂载本地存储目录，确立 LOCAL_STORAGE_ID = 0L 双源拓扑，实现本地曲库毫秒级层级遍历与 SWR 缓存。
• 跨源混合歌单与离线自愈：支持在同一歌单内混合收藏 WebDAV 远程与本地音频并无缝过渡切歌；本地存储断连/移除时自动置灰降级，重新授权后秒级自愈点亮。

🎨 全天候动态取色与沉浸式舞台黑胶光晕 (ADR-0032a)

• HCT 感知色调推导与中性灰保护：基于 androidx.palette 推导深邃暗夜舞台背景（Tone 6~8）与石板墨炭色高对比排版（WCAG AAA >= 8.5:1）；内置 isMonochrome 保护网，彻底根除黑白灰阶封面偏红偏暖问题。
• 沉浸式舞台全屏播放器与双层光晕：28dp 超椭圆自然景深大封面，漫延双层高斯环境光晕，切歌时伴随 450ms 流体弹簧平滑渐变换肤；音质角标（Audiophile Specs）动态配色协调。

🔍 双源曲库统一增量索引与全文检索 (ADR-0033)

• 统一本地媒体索引表：基于 media_track_index 建立复合 B-Tree 索引，毫秒级即打即搜双源音频；向未缓存目录穿梭时后台自动静默低并发增量同步。
• 分段药丸搜索范围切换舱：新增硬件绘制的 SegmentedSliderPill，在“当前源”与“全部曲库”间零闪烁平滑滑动切换，单源模式严格源隔离。

🧹 物理清除 CUE 虚拟分轨与纯粹流式降维 (ADR-0034)

• 物理剔除 4,500+ 行 CUE 模块：彻底移除 CUE 内存解析器与虚拟时间轴映射，终结进度条跳跃与切歌爆音风险，回归“单音频文件即单曲目”的 1:1 纯粹流式。
• Room v8 数据库平滑迁移：自动化数据清洗废弃虚拟分轨字段，底层播放管道与测试表面积精简逾 50%。

🧱 仓储层与会话中枢深度解耦 (ADR-0035 ~ ADR-0039)

• 跨源会话双轨解耦 (ADR-0035)：彻底解绑在播源（activeServer）与浏览源（browsingServer），支持后台播放远程音频的同时自由浏览本地曲库。
• 深度收拢媒体库仓储 (ADR-0036)：合并目录与搜索浅层仓储为单一高内聚深度模块 MediaLibraryRepository。
• 存储级联失效反转 (ADR-0037)：提炼 StorageCascadeInvalidator 窄接口，彻底消除仓储环形依赖与 Application 容器向下转型。
• 独立连通性追踪器 (ADR-0038)：提炼 StorageReachabilityTracker 深模块，将服务器探活与故障自愈从歌单完全剥离。
• 彻底剥离浏览游标 (ADR-0039)：从播放会话与 DataStore 中拔除 lastBrowsingPath，彻底消除目录切换引发的频繁写盘风暴。

🎬 UI 动效与交互微规范深化

• GPU 绘制阶段全屏容器形变：MorphingPlayerContainer 尺寸与圆角下沉至 GPU Draw Phase（graphicsLayer / drawBehind），杜绝每帧 CPU 重排，保障 120Hz 丝滑体验。
• 多选排队与副标题规范内聚：DirectoryBrowserViewModel 内聚多选状态机并支持原子“下一首播放”；统一音轨行缺少元数据时兜底显示 "未知"，严格维持 72dp 双行高度平齐。

📦 架构守门与包体积硬预算

• 全量测试与体积守门：1,202 项单元测试 100% 通过；Release APK 总包体严控在 6.87 MB（预算 <= 7.5 MB），classes.dex 4.16 MB（预算 <= 4.25 MB），纯 64 位 arm64-v8a 现代高效架构。

v3.3: Material 3 Expressive 动效系统与胶囊全屏连续形态蜕变

🎬 Material 3 Expressive 动效系统与连续形态蜕变体系 (ADR-0031)

• 动效基础设施与物理修饰符：收拢统一 Material 3 Expressive 刚度与阻尼物理常量（SpatialSpring 空间位移、EffectsSpring 透明度平滑、FastSpatialSpring 触控回弹），原生支持系统无障碍“减少动态效果（Reduce Motion）”自动折叠为 0ms 瞬间完成；封装全局触控微缩修饰符 Modifier.expressivePress() 与 Modifier.bouncyClickable()，赋予音轨行、服务器卡片与独立按钮 0.965f 物理微缩与果冻弹簧回弹触感。
• 单一真实实体胶囊全屏连续形态蜕变 (Single Living View)：彻底废除过渡替身组件与终点偷换机制，确立 FullPlayerView 为全屏展开阶段的单一真实实体，随容器高度自底层平滑浮现并微移归位；封面尺寸精准锚定全屏真实物理规格（280dp，与 PlayerVinylArtwork 严格一致），并在 GPU Draw 阶段通过 Modifier.graphicsLayer 进行矩阵变换，全程锁定 0° 绝对静止，终点零组件替换，彻底根除了展开瞬间全屏所有控件剧烈抖动与跳跃的顽疾；针对内存缓存命中优化，移除多余的 250ms 二次 Crossfade 渐变，实现秒级硬绘制；为 LyricsView 歌词视口内边距增加 .coerceAtLeast(0.dp) 保护，彻底杜绝极端低高度下崩溃。
• M3 双向共享轴向 Tab 导航与流体指示器：彻底移除旧有的暴力离屏与硬性 alpha 切换，在 MainNavigationCoordinator 中建立前后目的地索引跟踪，严格沿水平 X 轴执行 20% 短距双向推移与交叉淡化，两视窗协同过渡，杜绝白屏与瞬态闪烁；底部导航栏 52dp 药丸指示仓新增横向流体弹性拉伸微动效（Modifier.fluidIndicator），增强底栏动态反馈；歌单详情层级下钻全面接入 100% 右侧推入伴随父级 25% 视差后退。
• M3E 悬浮药丸搜索舱与层级穿梭：顶栏 38dp 放大镜按钮以弹性弹簧向四周撑开为 26dp 饱满圆角悬浮搜索舱，全屏搜索结果与历史 Chips 柔和下展；增加搜索框 Focus 请求挂载门禁（expansionProgress >= 0.35f），根除未挂载直接请求焦点引发的闪退；媒体库向未缓存目录穿梭时，新视窗立即呈现居中加载菊花与 正在加载远程目录...，彻底杜绝父级旧目录内容残留；退场父级 targetAlpha 修正为彻底淡出至 0.0f 并附加不透光背景，根除左侧残留虚影。
• 全域音轨行高严格对齐规范 (Row Height Parity via "未知" Fallback)：针对缺少艺术家或专辑信息的音频，副标题统一回退显示 "未知"，坚决不完全隐藏 supportingContent；歌单、媒体库、搜索、队列所有列表项 100% 保持统一的双行 72dp 规格，视觉严整协调，消除行高跳变。
• 播放队列模式循环与平滑洗牌排版：MD3 AssistChip 循环流转 列表循环 🔁 ⇄ 单曲循环 🔂 ⇄ 随机播放 🔀；重构 LazyColumn 为稳定唯一键契约（key = { _, track -> track.id }），条目挂载 Modifier.animateItemPlacement() 实现硬件级平滑交错滑行；将列表自动滚动限制为仅在打开抽屉时触发一次（hasScrolledOnOpen），消除滚动打断洗牌动效的冲突。
• 全局系统级弹窗 M3E 缩放：为全局 Dialogs（新建歌单、服务器编辑、音频详情）配置 Modifier.expressiveDialog() 0.92f 弹簧微缩淡入。

📦 架构与体积

• 架构守门：APK 总大小稳定控制在 6.83 MB（预算 <= 7.5 MB），纯 64 位 arm64-v8a 现代高效架构，0 外部第三方动画库引入。

v3.2: Aoffee Player 品牌升级与全链路服务器故障自愈

☕ 品牌更名为 Aoffee Player 与全新自适应图标 (ADR-0029)

• 品牌全域升级：应用名称正式由 WebDAVPlayer 升级为 Aoffee Player，树立专为家庭 NAS、私有云高保真流式音频打造的独立品牌形象；底层 com.webdav.player 包名与 Room / DataStore 存储架构保持稳定向后兼容，平滑升级无缝迁移。
• 解构主义方案 A「脉冲切片播放三角」图标：将朝向右侧的 Play 播放大三角创新解构为 4 根垂直圆角胶囊等化脉冲柱（高 46dp ~ 9dp），彻底修复矢量胶囊宽度翻倍导致重叠粘连的底层 Bug，移除非对称底托，远看为纯正 Play 播放按键，近看为高保真律动声浪，浑然一体。
• Android 全机型自适应居中与 66dp 安全区法则：前景图案尺寸严格收拢在 36dp × 46dp 绝对安全区内（最大离心半径仅 28.02dp，留白充足）；背景深紫夜渐变（#24143D ~ #07030C）与前景重心 100% 同轴锁死在 (54, 54) 几何正中心，在原生圆、三星方圆、MIUI/ColorOS 圆角矩形等任意遮罩下彻底消除偏心与边缘挤压。
• 全套传统 Mipmap PNG 资产补全：在 �pp/src/main/res/ 为 mdpi、hdpi、xhdpi、xxhdpi、xxxhdpi 全 5 档主流屏幕密度补充预编译位图（包含方圆与圆形），消除国产 ROM 桌面重绘、近期任务与分享面板在无位图时的拉伸失真与强制加白底小方块。

🔄 全链路服务器故障自愈与多触发恢复网络 (ADR-0030)

• 故障诊断域扩展与整机一致性：将服务端重启/网关拉起初期认证未就绪引发的瞬态 401/403（SERVER_CREDENTIAL_INVALID）与网络不可达（SERVER_UNREACHABLE）统一纳入服务器级自愈管理；在遇到服务器级连接或认证异常时，统一整机批量标记该节点全部曲目，杜绝同源歌曲“半灰半亮”的展示割裂。
• 四重自愈与状态恢复触发网络 (Multi-Trigger Network)：
  • 歌单主动探活：进入歌单详情页及点击任意服务器置灰曲目时，后台并发发起 PROPFIND 探活，服务器恢复后秒级点亮；
  • 测试连接联动：在服务器管理界面点击“测试连接”成功后，即时联动仓储清除该节点的不可达与凭据失效标记；
  • 物理播放出声反哺 (Playback Success Feedback)：当底层 ExoPlayer 成功解码出声进入 Playing 状态时，自动反哺清除当前服务器的所有置灰状态；
  • 系统网络重连广播：保留系统网络连通性广播监听作为全局兜底。
• UI 响应性与状态对称闭环：在歌单详情列表差异比对中加入 inactiveReason 诊断维度，确保数据库自愈后即时触发重组点亮，彻底消除置灰曲目点击拦截的交互死锁。

📦 架构与体积

• 架构守门：APK 总大小稳定控制在 6.81 MB（预算 <= 7.5 MB），DEX 大小 4.06 MB（预算 <= 4.25 MB），纯 64 位 �rm64-v8a 现代高效架构。

v3.1: Material 3 Expressive UI Redesign & Fluid Interaction

🎨 Material 3 Expressive 界面重构与流体交互 (ADR-0028)

• 品牌名称规范化：全域统一产品名称为符合行业标准的 WebDAVPlayer（DAV 全部大写）。
• 全天候全域音轨动态取色：解绑系统壁纸色（锁定 dynamicColor = false），整机背景与卡片随当前专辑封面柔和渐变换肤；浅色模式次级文本升级为石板墨炭色（#3A3546），文字与胶囊对比度严格达到 WCAG AAA 8.5:1 超高清标准。
• 60dp 紧凑流体底栏与绝对居中：采用 60dp 紧凑交互区并自适应手势条，内部以 52dp x 28dp M3 药丸指示舱搭配 20dp 图标与标签文字绝对垂直居中，消除底栏笨重压迫感。
• 流体微光 Mini 播放器 (Liquid Fill)：60dp 饱满胶囊内嵌 42dp 正圆黑胶唱片封面（CircleShape），全域落地「流体微光背景进度填充」，内部组件 100% 垂直居中无挤压，告别突兀底线。
• 全机型动态自适应 FAB 避让：以动态流体公式驱动，在 MiniPlayer 出现时维持 24dp 黄金律动净空，隐藏时优雅回落，彻底消除元素遮挡。
• FluidTopAppBar 连续折叠顶栏：遵循 Compose 嵌套滚动协议，左右校准为 16dp 对称外边距，全程左对齐平滑收起；集成 Coordinated Pull-to-Refresh 手势协同仲裁，根除与下拉刷新的手势冲突。
• 纯正 M3E 药丸搜索舱与悬浮多选：顶部 44dp 避让悬浮 26dp 独立药丸搜索舱，集成历史胶囊即打即搜；长按触发 16dp 卡片多选流，底部弹出 28dp 悬浮多选操作胶囊（下一首播放 / 添加到歌单）。
• 歌单卡片内部居中与 80dp Hero Header：卡片内部元素绝对几何对称垂直居中，拔除全域灰线，顶部落地 80dp 渐变大封面卡片与「播放全部」胶囊。
• 全屏大封面与流体氛围聚焦歌词：28dp 方形大圆角封面（Squircle 250x250 带环境光晕）与 68dp Squircle 播控按键；轻量顶栏动态呈现活跃服务器名；全新「流体氛围聚焦流歌词（Scheme 1）」，在播句动态锁定屏幕垂直正中央，22sp 特粗字号搭配 3.5dp 原色垂直指示条，未唱行靠左平滑微透渐隐；660dp+ 宽屏自适应左右双栏分屏。

🌐 WebDAV 协议与网络韧性加固

• RFC 3986 路径百分号规范解码：完美支持含 + 及特殊字符的音频文件与目录。
• 外置封面清单感知预过滤：彻底消除无内嵌封面专辑浏览时的数十次盲目 404 请求风暴。
• HTTP Digest 摘要认证支持：原生支持 RFC 7616 / RFC 2617 Digest 认证，完美兼容群晖等专属私有云。
• Happy Eyeballs 双栈快速回退：消除家庭双栈网络 IPv6 路由黑洞导致的起播握手挂死。

📦 架构与体积

• 架构守门：APK 体积仅 6.73 MB（预算 <= 7.5 MB），纯 64 位 arm64-v8a 现代高效架构。

v3.0 - 跨服务器歌单、CUE虚拟分轨流式回放、全局架构加固与统一依赖容器

🚀 新增 (Added)

• 跨服务器多源歌单与自愈式离线置灰体系 (Cross-Server Playlists & Self-Healing)：全新支持跨多个 WebDAV Server 收藏音频资产构建自定义歌单。建立服务器离线与文件丢失（401/403/404）的置灰减淡状态（InactivePlaylistTrack），提供精准失效原因反馈，流式切歌平滑静默跳跃；内置后台异步封面自愈机制，自动修补缺失的缩略图快照。
• 即时曲库全文检索与历史管理 (Instant Library Search & History)：基于已访问目录镜像在本地构建毫秒级全文索引，支持多维即时匹配目录、音频标题/艺术家/专辑及 CUE 虚拟分轨；原生集成 LRU 20 项搜索历史持久化。
• 通用音轨呈现接缝组件 (Unified AudioTrackRow Seam)：提炼高内聚、基于 Slot API 的通用条目组件 AudioTrackRow，内置跑马灯标题、副标题拼接、自适应等化器动态脉冲及高解析度音质角标；100% 覆盖媒体库、歌单、搜索、播放队列及 CUE 专辑分轨，削减逾千行重复 UI 样板。
• 全应用统一依赖容器 (Unified AppContainer & AppViewModelFactory)：在 Application 层确立 AppContainer 契约，以单一依赖源泉统领仓储与会话单例，提供集中类型分发的 AppViewModelFactory，彻底消灭散落的工厂文件与并行影子依赖图。
• 聚合播控意图契约 (Cohesive PlaybackActions Seam)：提炼强类型 PlaybackActions 契约，收敛大播放器与 MiniPlayer 的散碎回调参数（由 17 个缩减至 5 个），终结外部容器接线板代码。
• 架构边界确定性门禁 (Deterministic Architecture Seam Verification)：在 PackagingSeamVerificationTest 中建立自动化边界守卫，强制断言 ui.common 单向依赖、CUE 内部类封装及防僵尸壳文件复活，并以 CODING_STANDARDS.md 确立基于职责正交性与模块深度的代码审查标尺。

⚡ 优化与架构深化 (Changed & Refactored)

• 播放引擎内核深度化与媒体源内聚 (Deepen Player Engine & Consolidate MediaSource)：折叠单一适配器假性接口 WebDavMediaSourceAdapter，将流式数据源与 ProgressiveMediaSource 装配收敛为引擎内部私有协作者 WebDavMediaSourceBuilder，拔除单测中全部 10 处强制向下强转。
• 解除宿主伪引擎委托并打破启动循环依赖 (Decouple PlaybackSessionHost & Session)：移除 PlaybackSessionHost 对底层播放引擎的类委托，宿主专职作为 Android 系统前台服务与 MediaSession 适配器；纯物理流引擎直连会话，彻底根除启动期 (playerEngine as? PlaybackSessionHost) 运行时强转。
• 双源歌词完全并入元数据仓储 (Consolidate Dual-Source Lyrics)：将远程 .lrc 探测与内嵌歌词回退统一收拢至深层 TrackMetadataRepository 内部，消除独立的 100 条二级歌词内存缓存，彻底删除浅层仓储 LyricsRepository 与 LyricsRepositoryImpl，消除双重 Mock 负担。
• 会话中枢时间轴协作者解耦 (PlaybackTimelineCoordinator)：引入第 5 个包级私有协作者，将底层 5 处协程流监听与虚拟时间轴双向换算完全剥离，核心会话类 MusicPlayerAppSessionImpl 由 789 行精简至 497 行，彻底回归至 600 行熔断线内。
• 物理清除过渡期僵尸壳文件 (Purge Zombie Forwarding Shells)：删除 4 个旧 ViewModel 工厂、废弃的全局静态缓存 CueTextCache 及 105 行未使用的兼容别名文件 AudioTrackItemRowCompat.kt。
• 拔除字节码反射测试 (Purge Implementation-Locking Reflection Tests)：清理所有针对内部 Kotlin 文件名的 Class.forName 测试与局部死板行数限制，测试表面 100% 聚焦于真实行为契约。
• 架构决策记录 (ADR)：归档落地 ADR 0020、ADR 0021、ADR 0022、ADR 0023、ADR 0024 与 ADR 0025。

---

📦 安装包体积硬性预算指标 (Release Packaging Budget)

• Release APK 总包体：6.67 MB（硬预算 <= 7.5 MB，较 v2.1 缩减 88%）
• classes.dex 未压缩大小：3.97 MB（硬预算 <= 4.0 MB，单 DEX 极致压缩）
• CPU 架构：纯 64 位 �rm64-v8a 原生 FFmpeg JNI 动态库支持

v2.6 - 系统音频焦点弹性、流媒体管线解耦与架构深化

🚀 新增 (Added)

• 单向系统音频焦点意图路由与幽灵自恢复防护 (Unidirectional Focus Routing & Ghost Resumption Guard)：构建专职 AudioFocusHandler 与单向焦点意图管道，系统音频焦点（AUDIOFOCUS_GAIN、AUDIOFOCUS_LOSS、LOSS_TRANSIENT、LOSS_TRANSIENT_CAN_DUCK）变更 100% 规范化路由至应用会话层 MusicPlayerAppSession 集中仲裁。建立严格的幽灵自恢复拦截状态机，杜绝在外部断开或永久失去焦点后意外后台自动起播；规范化音量压低（Ducking）系数并在冷启动重建时支持焦点平滑恢复。
• 缓冲期 Becoming-Noisy 智能防外放兜底 (Buffering Becoming-Noisy Guard)：将防外放保护延伸覆盖至“网络缓冲等待态（Buffering）”。在弱网加载或冷启动缓冲期间若发生有线耳机拔出或蓝牙设备断连，立即拦截挂起并收敛至安全暂停状态，杜绝音频缓冲就绪后意外大声公放的尴尬。
• 动态物理音频路由感知与底层 AudioSink 强同步刷新 (Dynamic Routing Observer & Sink Flush)：接入 AudioRoutingObserver 监听系统 AudioDeviceCallback，精准识别物理发声端点（isSink == true）的动态接入与移除。在多音频外设切换或车载蓝牙迁移时，顺应系统仲裁策略并调度底层 activeAudioSink?.flush() 强行对齐缓冲管道与硬件驱动时钟，彻底根除“进度条走动、硬件无声音”的时钟错位假死问题。

⚡ 优化与架构演进 (Changed & Refactored)

• 深度模块演进：会话宿主收拢硬件锁与 MediaSession 所有权 (PlaybackSessionHost Consolidation)：依据深层模块设计原则，将 Wi-Fi 高性能锁、CPU 唤醒锁以及 MediaSession / sessionPlayer 的所有权完全收拢至 PlaybackSessionHost，彻底消除播放引擎与数据源适配器中的硬件锁泄漏；底层播放引擎收敛为高内聚、职责纯粹的流式渲染管道。
• 消除跨接缝向下转型 (Eliminate Cross-Seam Downcasts)：重构 PlaybackSessionHost 与底层引擎协作契约，消除所有对具体引擎实现类的向下强制类型转换，统一通过 AudioPlayerEngine 抽象多态驱动，提高测试置换性与架构扩展性。
• 浅层辅助工具精简与领域模型内聚 (Prune Shallow Helpers)：依照深度模块理念，彻底剔除 AudioQualityBadgeHelper、BreadcrumbNavigationHelper、PlayerTimeFormatter 与 WebDavDataSourceFactory 等浅层静态工具类，将面包屑推导、音质徽章计算及时间格式化直接内聚到领域实体与 Navigation Coordinator，显著收窄代码表面积。

🧪 质量保证与自动化门禁 (Testing & Quality Assurance)

• 端到端音频焦点与路由弹性全链路回归套件 (End-to-End System Focus & Route Regression Suite)：新增 EndToEndSystemFocusAndRouteRegressionTest，覆盖瞬态抢占、暂时压低、耳机插拔、弱网断流并发等多种极端边界工况的确定性状态机流转。
• 回放管线集成与包体积硬预算门禁：通过 EndToEndPlaybackPipelineIntegrationTest 验证端到端回放管线完整生命周期；持续执行 verifyReleasePackaging 门禁守门：Release APK 稳定控制在 6.61 MB（预算 <= 7.5 MB），classes.dex 保持在 3.99 MB（预算 <= 4.0 MB），纯 64 位 arm64-v8a 架构无任何冗余。

v2.5 - 音频防意外外放保护、路由自愈与规范化重采样

[2.5] - 2026-10-18

🚀 新增 (Added)

• Becoming Noisy 防意外外放系统级拦截：在 PlaybackSessionHost 中接入 becomingNoisyReceiver 动态监听 AudioManager.ACTION_AUDIO_BECOMING_NOISY 广播。当正在播放的蓝牙音箱断连、超出范围、电量耗尽关机或有线耳机拔出时，毫秒级主动拦截并触发 appSession.pause()，停止播放时钟推进、取消弱网看门狗、持久化保存毫秒级断点进度并释放 CPU/Wi-Fi 硬件锁；同时配置底层 ExoPlayer .setHandleAudioBecomingNoisy(true) 双重保底；设备重连后严格遵循保守安全策略保持暂停，彻底消除公共场合或安静环境下的意外大声外放尴尬。
• 与播放状态绑定的动态接收器生命周期：Becoming Noisy 广播接收器仅在播放状态跃迁为 Playing 或服务前台提升时动态注册，在 Paused、Idle、Ended、Error、服务脱离或释放时自动注销，杜绝后台广播泄漏与非播放状态下的意外误触。
• 规范化音频重采样管道 (Canonical Sample Rate Resampling Pipeline)：对齐主流商业流媒体播放器工业标准，构建 CanonicalResamplingAudioProcessor，设定标准采样率下限阈值 44,100 Hz。凡采样率低于 44.1kHz（如 22050Hz 评书、16000Hz 有声书等老旧音频）的输入流，由应用层在内存中无损超采样至标准 44,100 Hz 双声道立体声 PCM；彻底绕开各大 Android 厂商底层 HAL/A2DP 驱动重采样器的时钟错位缺陷，从源头消灭高通平台蓝牙重混音卡死的前提条件；标准采样率与高解析母带（>= 44.1kHz，含 16-bit/Float）100% 直通零损耗。
• 音频路由观察者与底层 AudioSink 刷新自愈 (Audio Routing Observer & Sink Flush)：构建 AudioRoutingObserver 监听系统 AudioDeviceCallback，实时过滤感知物理发声端点（isSink == true）的动态增减。当多蓝牙设备抢占或输出路由迁移时，顺应系统仲裁策略并主动触发底层 activeAudioSink?.flush()，清空输出缓冲管道并强制驱动层重新握手时钟对齐，彻底消除“进度条空跑、硬件无声”的静音假死现象，确保新设备切换后立刻正常出声。
• 统一系统级播控意图路由 (Unified System Playback Intent Routing)：全量系统播控意图（蓝牙线控按键、耳机按键、系统媒体会话命令、通知栏快捷操作）100% 统一路由至应用会话层 MusicPlayerAppSession 仲裁与执行，消除了底层播放引擎的反向耦合与幽灵通道，确保所有播放控制操作严格遵循统一的响应式单向数据流。
• 架构决策记录 (ADR)：归档落地 ADR 0018: 统一系统级播控意图接缝至应用会话层及音频路由防外放与自愈补遗。

---

v2.4 - 弹性后台播放保活、双硬件锁与厂商电池白名单

[2.4] - 2026-10-16

🚀 新增 (Added)

• 15 分钟延迟前台服务降级状态机 (Deferred Foreground Demotion)：用户暂停播放时，应用不再立即注销前台服务与通知栏，而是保持高优先级前台身份并启动 15 分钟延迟降级协程计时器。15 分钟内通过通知栏、耳机线控或界面恢复播放时实现零延迟无缝秒播；超时未操作则优雅调用 service.stopForeground(STOP_FOREGROUND_DETACH) 释放前台身份以节约系统电量；彻底消除了 Android 10+ 与定制 ROM 在暂停数分钟内因系统闲置判定（app idle）强行停止服务的问题。
• 流式双硬件锁联动守护 (Dual Streaming Hardware Locks)：抽象出专职的 StreamingHardwareLockManager，ExoPlayer 内核显式配置网络唤醒模式（setWakeMode(C.WAKE_MODE_NETWORK)），底层流式数据源装配 Wi-Fi 高性能锁（WIFI_MODE_FULL_HIGH_PERF，标签 "WebDavPlayer:StreamingWifiLock"）。回放与网络缓冲阶段自动申请并持有双锁，彻底杜绝息屏后 CPU 停步与 Wi-Fi 芯片降频节能导致的流式断流挂死；暂停与停止时瞬间释放双锁，允许手机锁屏正常进入深层节能休眠。
• 全机型双轨电池防护与厂商跳转 (Dual-Track Battery Whitelist Flow)：对标椒盐音乐等业界标杆，在全屏大播放器顶栏下方提供“双轨直通”保活机制——【快速授权】直接调起 AOSP 原生弹窗加入 Doze 忽略电池优化白名单；【电池设置】面向全机型直达系统应用信息页并引导用户勾选「无限制（Unrestricted）」，针对小米设备自动直达自启动与神隐模式权限页，彻底免疫锁屏降频与进程强制清理（如 MIUI LockScreenClean）。
• 渐进式两阶段横幅交互 (Progressive Two-Stage Banner Flow)：优化白名单引导交互体验。用户在阶段一点击【快速授权】并允许后，横幅不突兀消失，而是平滑变更为绿色的阶段二成功状态，继续引导用户从容点击【电池设置】完成终极设置或点击【我知道了】优雅收起。
• 会话健康退出追踪与系统强杀研判 (Session Health Tracking & Kill Detection)：持久化存储记录 cleanExit 健康状态，流式播放中置为 false，正常暂停/退出写回 true。冷启动若检测到异常中断，准确识别上次被系统强杀并在状态流中置位 wasKilledBySystem = true，自动在横幅中动态强化风险警示文案。
• 服务前台窗口主动预热 (First-Frame Service Pre-warming)：在 MainActivity.onStart() 前台窗口期主动预热并绑定媒体播放服务，彻底杜绝从后台唤起服务引发的 Background start not allowed 崩溃。
• 退后台内存自洁机制 (TrimMemory Guard)：在 MainActivity 与 WebDavApplication 中监听 TRIM_MEMORY_UI_HIDDEN 信号，应用切后台或息屏时立即清空 ThumbnailMemoryCache 大图缓存，将后台常驻内存压降 60%（至约 50MB），消除触发 Low Memory Killer (LMK) 的风险。
• 会话接管切歌权与队列调度集中化 (Session-Managed Queue Progression)：剥夺底层播放器内核自主跨曲跳过权，将切歌决策、循环模式流转与 CUE 虚拟分轨调度 100% 收拢至应用会话层（MusicPlayerAppSessionImpl），ExoPlayer 物理时间线仅维持单轨或受控的双轨预热窗口。
• 伪播放结束双重熔断防线 (Premature EOF Guard)：在底层数据源引入传输字节计数校验（比对 Content-Range 与已收字节，未达标抛出 UnexpectedEndOfStreamException 转入断点重连），并在会话层建立时长比对熔断（currentPositionMs < durationMs - 5000ms 时判定为网络异常截断并就地自愈），彻底消除弱网、NAS 硬盘休眠或闪断时意外跳过章节的顽疾。
• 底层透明断点续连机制 (Transparent Range Reconnection)：数据源在遭遇读取超时或网络抖动时，在传输层透明记录字节偏移量并以退避重试发起 HTTP Range 请求续传，解码管道不销毁、进度不跳变，对上层播放器与 UI 完全透明。
• 弱网纯内存自适应大缓冲 (Expanded Weak-Network Buffer)：坚守纯在线流式零持久化落盘约束，弱网配置将最大缓冲弹性提升至 90 秒（maxBufferMs = 90_000），利用网络空闲窗口大幅拓宽抗抖动冗余。
• 架构决策记录 (ADR)：归档落地 ADR 0015、ADR 0016 与 ADR 0017。

⚡ 优化与工程变更 (Changed)

• 底层播放引擎收窄为纯流式渲染管道 (Streaming Playback Pipeline)：重构 AudioPlayerEngine，彻底剔除 playTracks(List)、seekToTrack、removeTrack 等 10 余个多曲目列表遗留方法与无用的 shufflePermutation 幽灵属性，收窄为 loadTrack、prerollTrack、clearPrerollTrack 与 updateTrackMetadata 4 个核心流管道方法，接口内聚度提升 60% 以上。
• 根除切歌反向回调回旋镖 (Direct Skip Intent)：系统媒体会话（WebDavMediaSessionCallback）与蓝牙线控按键直接将切歌意图派发给应用会话层，消除跨接缝反向回调与双向耦合。
• 净化测试表面 (Purify Test Surface)：依照“接口即测试表面”原则，大幅瘦身 FakeAudioPlayerEngine，删除全部模拟列表管理逻辑，测试表面与底层真实流式渲染完全一致。
• 服务粘性与任务划卡守护：WebDavMediaService.onStartCommand() 明确声明 START_STICKY 粘性，且在 onTaskRemoved() 中守护正在播放或处于 15 分钟延迟降级宽容期内的回放服务，用户在最近任务列表划掉主界面卡片时音乐持续稳定播放。
• 发布包体积预算自动化验证：微调 ProGuard 精确保护规则，在增加硬件锁、电池白名单及两阶段横幅组件后，Release APK 体积依然稳定保持在 6.59 MB（预算 <= 7.5 MB）、classes.dex 保持在 3.96 MB（预算 <= 4.0 MB），持续通过自动化门禁检验。

---

v2.3 - CUE 虚拟分轨与流式无缝衔接

WebDavPlayer v2.3 发布说明

WebDavPlayer v2.3 专注于 CUE 虚拟分轨流内映射、无缝流式回放与文件夹闭环循环。在坚守“纯流式无本地磁盘持久化缓存”核心架构底线的前提下，为发烧友用户群体带来原汁原味的整轨无损专辑（FLAC / WAV / APE）分轨点选与绝对无缝回放体验！

---

🚀 核心更新亮点

1. 单物理流 + 逻辑虚拟轨（Bit-Perfect Gapless Streaming）

• 物理流持久连接：针对整轨大音频文件（如 �lbum.flac），底层流媒体引擎始终维持单条持久化 HTTP 长连接（单一 Authenticated MediaSource），回放跨越 CUE 分轨时物理流绝对不断开、零网络重连握手、零解码器 Flush，彻底根除传统物理切片方案在纯流式下的网络缓冲间隙与爆音。
• 虚拟时间轴映射引擎 (Virtual Timeline Engine)：会话层引入高频动态双向映射，将底层大文件物理时间转换为当前虚拟分轨的相对进度（�1:23 / 04:12），Seek 范围精确约束在当前分轨区间内。
• 跨轨零打扰元数据广播 (Non-Disruptive Metadata Enrichment)：自然播放跨越分轨分界点时，响应式向 UI、通知栏及系统 MediaSession 广播更新曲目标题与表演者，实现声学级物理真无缝。

2. 纯内存 CUE 状态机解析器 (In-Memory CueParser Module)

• 独立轻量状态机：纯 Kotlin 实现、无第三方库依赖的流式文本解析器，强力兼容双引号/无引号、多空白字符、REM 注释等常见 CUE 变种格式。
• 高精度帧率转换：精确将 CUE 标准的 分:秒:帧（75 fps）换算为毫秒级数值（1 frame = 1000 / 75 ms）。
• 零本地磁盘缓存：CUE 元数据仅在目录浏览与点选时瞬态驻留内存，绝不持久化落盘，严格遵守纯在线流式设计红线。

3. 待播队列与目录浏览器内联展开 (Inlined Virtual Tracks in PlaybackQueue)

• 无缝内联展开：目录浏览与播放队列抽屉支持将包含 CUE 的整轨大音频平滑原地展开为完整分轨项，支持直观查看分轨序号、曲目标题、表演者及精确时长。
• 流内直达起播：点击任意虚拟分轨瞬间流式起播，并支持当前播放分轨与归属大文件的动态等化器跳动指示（Equalizer Track Indicator）。
• 统一导航抽象：扩展 PlaybackQueue 领域模型，统一管理常规音轨与虚拟分轨，保证上一曲/下一曲平滑跳转。

4. 文件夹环形闭环循环 (Folder Ring Playback)

• 严格目录边界：播放队列范围严格锁定在当前活跃远程目录。列表循环模式下播放至末尾曲目时，自动平滑回环至首曲，坚决杜绝跨越父级或同级兄弟目录进行无休止漫游。

5. 双轨预卷流式缓冲 (Streaming Pre-roll Buffering)

• 持久连接池复用：OkHttp 客户端保持持久化 Keep-Alive 连接池（空闲超时 5 分钟，保留空闲连接），切歌网络握手耗时降至 0ms。
• 交叠预加载调优：配置 10 秒回退缓冲区并在曲目接近尾声时提前装填前导数据流与格式探针，普通多曲目切换零声学空白。

6. 会话现场持久化扩展与冷启动精准续播

• 会话状态扩展：DataStore 记录当前播放的 cuePath 与分轨序号/相对偏移量。
• 零感知无缝还原：应用冷启动时优先建立物理大音频流，静默 Seek 还原分轨相对进度。

---

📑 架构决策记录 (ADR)

• 归档落地 ADR 0014: CUE 虚拟分轨流内映射与目录闭环流式播放。

---

📦 安装包文件

• WebDavPlayer-v2.3.apk (6.59 MB) - 专注 arm64-v8a 64 位架构，内置完整 FFmpeg 软解引擎与 CUE 虚拟时间轴映射。

v2.2 - 极致二进制瘦身、64位单架构与构建接缝守门

WebDavPlayer v2.2 发布说明

WebDavPlayer v2.2 迎来重大构建工程与打包接缝（Packaging Seam）革新，专注于极致二进制瘦身、64 位现代架构精简与构建质量自动化门禁。发布安装包体积从上一版本的 56.8 MB 断崖式锐减至 6.57 MB（缩减达 88%），为移动网络下载与低端设备运行带来飞跃式的轻量化体验！

---

🚀 核心更新与工程优化

1. 彻底根除 DEX 死代码膨胀（-40+ MB 字节码）

• 局部化 AppIcons 资产接缝：全面剔除体积庞大的 androidx.compose.material:material-icons-extended 依赖，建立局部显式管理的 AppIcons 目录，从源头杜绝未引用的数万个矢量图标类编译入包。
• classes.dex 结构缩减：DEX 文件数量从 3 个缩减为单一 classes.dex，未压缩字节码由 44.56 MB 降至 3.91 MB，极大地减少了系统 ART 虚拟机的类加载耗时，冷启动响应显著加快。

2. 全面开启 R8 混淆、资源缩减与精准保护

• 深度代码混淆与资源剔除：在 Release 构建中全面启用 isMinifyEnabled = true 与 isShrinkResources = true。
• 纵深保护规则（ProGuard Keep Rules）：针对 Room 实体/DAO、Media3 Session 回调、Native JNI 桥接接口（FfmpegAudioDecoder、AsfExtractor、ExtractorInput）、OkHttp Interceptor/Authenticator 及 WebSocket 回调建立严格防御规则，确保混淆后网络流媒体回放与本地数据库零异常。

3. 专注 64 位单架构 Native 过滤（-50% Native 体积）

• 剥离过时的 32 位 armeabi-v7a：基于项目 minSdk = 29 (Android 10) 基线，全面拥抱现役 64 位 ARMv8 架构，在 Release 打包中仅保留 arm64-v8a，剥离全部 32 位冗余 .so 文件，原生动态库体积直降 50%。

4. 优化独立分发 APK 字节码压缩

• 显式配置 dex.useLegacyPackaging = true：针对 GitHub Releases 独立 APK 直装分发场景，强制使用 DEFLATE 算法压缩 classes.dex（压缩比达 0.49，由 4.09 MB 压缩至 1.90 MB），直接消除 AGP 默认未压缩模式带来的 2.19 MB 传输体积膨胀，为蜂窝网络下载提供极致轻量体验。

5. 发布体积预算硬性守门门禁

• 自动化门禁闭环：在构建流中引入 verifyReleasePackaging 任务与 PackagingSeamVerificationTest 单元测试，强制约束 Release APK 硬性指标：总包体 <= 7.5 MB（实测 6.57 MB）、单一 classes.dex <= 4.0 MB、Native 动态库仅包含 arm64-v8a。

---

📦 安装包文件

• WebDavPlayer-v2.2.apk (6.57 MB) - 专注 arm64-v8a 64 位架构，内置完整 FFmpeg WMA/FLAC 原生软解引擎与深层流媒体管道。