# 播放控制脱离 LocalMusic 宿主设计 ## 背景 当前项目里的统一播放控制入口是 `MusicPlaybackController`，但它本质上仍然只是一个动作分发器或事件桥接层： - `playOrPause`、`playNext`、`playPrevious`、`seekTo` 等动作依赖 `LocalMusic` 在页面生命周期里注册 actions。 - 起播一首歌或一组歌时，页面侧通常还是通过 `EVENT_PLAYLIST_PLAY` 发送请求，再由 `LocalMusic` 监听并执行真实播放。 - 播放器实例、播放队列、当前歌曲、当前索引、AVSession、投播联动等核心逻辑都沉在 `LocalMusic` 内部。 这导致一个结构性问题：任何页面想直接调用 controller 播放，实际上仍然依赖 `LocalMusic` 充当“播放器宿主页面”。 ## 本阶段目标 第一阶段只解决“播放核心依赖 LocalMusic 宿主”的问题，不做整站 UI 重构。 完成标准： - 任意页面可以直接通过 `MusicPlaybackController` 起播单曲或队列。 - 任意页面可以直接通过 `MusicPlaybackController` 调用 `play/pause/next/previous/seek`。 - `LocalMusic` 不再负责接收 `EVENT_PLAYLIST_PLAY` 作为主播放入口。 - 迷你播放条、全屏播放器、播放页显隐、列表高亮等 UI 显示状态，暂时仍保留在 `NewIndex/LocalMusic` 层。 - 允许 `LocalMusic` 继续常驻隐藏挂载，但它不再是播放指令的宿主。 非目标： - 本阶段不把迷你播放条状态完全抽成独立 store。 - 本阶段不强行拆完 `LocalMusic` 的所有播放相关字段。 - 本阶段不重写投播、歌词、AVSession 的全部实现方式，只调整宿主归属和调用链。 ## 推荐方案 采用“抽离 `PlaybackCoordinator`，保留现有 UI 宿主”的方案。 核心思想： - `MusicPlaybackController` 升级成真正的统一控制入口。 - 新增 `PlaybackCoordinator` 承接真实播放核心逻辑。 - `LocalMusic` 从“播放逻辑宿主”降级为“播放 UI 容器”。 - 页面层不再依赖 `EVENT_PLAYLIST_PLAY -> LocalMusic` 这条链路起播。 不采用以下方案： - 仅继续做事件桥接。这样 controller 仍然不是实际播放入口，后续还要返工。 - 一次性把 UI 状态和核心状态全部独立。首轮改动面过大，容易同时打坏迷你播放条、投播、AVSession 与歌词联动。 ## 目标架构 ### 1. MusicPlaybackController 职责： - 提供全局统一 API。 - 对外暴露直接控制接口，而不是依赖页面注册 actions。 - 将页面请求转发给 `PlaybackCoordinator`。 第一阶段期望接口： - `playSong(song: VideoItem, options?)` - `playQueue(songs: VideoItem[], startIndex: number, options?)` - `playOrPause()` - `playNext()` - `playPrevious()` - `seekTo(value: string, source?: string)` 兼容策略： - 旧的 `setActions/clearActions` 暂时保留，但标记为过渡能力。 - controller 内部优先走 `PlaybackCoordinator`；仅对尚未迁出的能力允许短期回退。 ### 2. PlaybackCoordinator 新增协调层，负责播放核心链路。 职责： - 持有当前播放队列、当前索引、当前歌曲、基础播放状态。 - 承接起播单曲、起播队列、切歌、暂停/恢复、seek。 - 协调底层 player、AVSession、投播模块与播放元数据同步。 - 向 UI 层暴露可订阅的最小播放状态。 第一阶段必须迁出的逻辑： - `doPlay` 主链路及其前后置准备逻辑。 - 当前歌曲切换。 - 播放队列切换。 - `play/pause/next/previous/seek` 的控制主路径。 第一阶段允许仍留在 UI 层的逻辑： - 播放页打开关闭。 - 迷你播放条显示/隐藏状态。 - 纯视觉动画与页面交互状态。 ### 3. LocalMusic 迁移后职责： - 读取 `PlaybackCoordinator` 暴露的播放状态并渲染 UI。 - 负责全屏播放器、播放列表界面、迷你播放条相关视觉层逻辑。 - 保留页面内交互，但交互结果改为调用 controller，而不是直接执行播放核心流程。 迁移后不再承担的职责： - 监听 `EVENT_PLAYLIST_PLAY` 作为主播放入口。 - 持有独占的起播核心流程。 - 作为 controller actions 的唯一宿主。 ### 4. NewIndex 保持当前职责： - 承载页面级 UI 容器。 - 继续持有迷你播放条显示层状态。 - 通过共享播放状态决定何时展示播放 UI。 ## 数据流 迁移前： 1. 页面点击歌曲。 2. 页面发事件或调用桥接逻辑。 3. `LocalMusic` 监听事件。 4. `LocalMusic` 执行 `doPlay` 与后续播放流程。 迁移后： 1. 页面点击歌曲。 2. 页面直接调用 `MusicPlaybackController.playSong(...)` 或 `playQueue(...)`。 3. controller 直接调用 `PlaybackCoordinator`。 4. `PlaybackCoordinator` 更新播放队列、当前歌曲、底层播放器与共享播放状态。 5. `LocalMusic/NewIndex` 作为 UI 消费者响应状态变化。 关键变化： - 页面到播放核心的入口从“事件 + LocalMusic”改为“controller + coordinator”。 - `LocalMusic` 从命令执行者变成状态消费者。 ## 状态拆分原则 为降低风险，第一阶段只抽“核心播放状态”，不抽“全部 UI 状态”。 核心播放状态建议包含： - 当前歌曲 `currentSong` - 播放队列 `songList` - 当前索引 `curIndex` - 是否正在播放 `isPlaying` - 当前进度/时长 - 当前播放模式 继续留在 UI 层的状态： - 播放页是否展开 - 迷你播放条显隐 - 页面动画状态 - 手势、滚动、弹窗、浮层相关状态 判断标准： - 影响实际播放行为的状态，属于 coordinator。 - 只影响视觉表现的状态，留在 UI。 ## 分阶段迁移计划 ### 阶段 1：抽出起播入口 目标： - 从 `LocalMusic` 中抽离 `doPlay` 主链路到 `PlaybackCoordinator`。 - 支持 `playSong(song)` 和 `playQueue(songs, startIndex)`。 - 首批页面切到新入口：`ChartsCount`、歌单页、发现页等最直接的列表页。 验收： - 不经 `EVENT_PLAYLIST_PLAY` 也能直接起播。 - 首次起播后迷你播放条和播放器界面仍能正常响应。 ### 阶段 2：抽出基础控制动作 目标： - 将 `playOrPause`、`playNext`、`playPrevious`、`seekTo` 从 `LocalMusic` 挪到 `PlaybackCoordinator`。 - `MusicPlaybackController.setActions/clearActions` 进入兼容态，不再作为主路径。 验收： - 页面级 controller 调用不再依赖 `LocalMusic` 注册 actions。 ### 阶段 3：UI 状态改为消费共享状态 目标： - `LocalMusic` 改为从共享状态读取当前歌曲、索引、播放状态、进度等。 - 清理 UI 层对核心播放状态的直接写入。 验收： - `LocalMusic` 只做 UI 响应，不再承担核心状态源头角色。 ### 阶段 4：清理旧事件桥接 目标： - 清理 `EVENT_PLAYLIST_PLAY` 作为本地主播放主链的职责。 - 清理为桥接页面播放而存在的过渡数据仓库和 pending request 逻辑。 验收： - 本地播放主链全部走 controller -> coordinator。 ## 兼容与回退策略 为了避免一次改坏所有场景，第一阶段允许短期双轨： - 新页面入口优先调用 `controller -> coordinator`。 - 未迁移完的少数路径可保留旧逻辑，直到对应页面切换完成。 但有两条硬约束： - 不允许新增新的 `EVENT_PLAYLIST_PLAY -> LocalMusic` 依赖。 - controller 对外文档和新代码一律以 direct API 为准。 ## 风险与约束 ### 1. 强耦合字段风险 `LocalMusic` 当前很可能把播放器状态、UI 状态、动画状态、投播状态混在同一个大组件中。 应对： - 第一阶段先只迁移真正决定播放行为的字段。 - 对一时拆不开的字段，先通过只读映射或桥接读取，避免一轮就全部改写。 ### 2. AVSession / 投播联动风险 如果 AVSession 与投播流程深度耦合 `LocalMusic` 内部字段，直接搬迁会有回归风险。 应对： - 优先保证 coordinator 成为“命令主入口”。 - AVSession 与投播在第一阶段可通过适配层接入 coordinator，不要求同一轮完全重构。 ### 3. UI 不同步风险 若 coordinator 成为状态源，但 `LocalMusic` 仍在局部直接写旧字段，容易出现 UI 与实际播放状态分裂。 应对： - 每迁一类动作，就同步把对应 UI 读取切到共享状态。 - 禁止同一字段同时存在“coordinator 写”和“UI 自己写”两套主路径。 ## 测试与验证 第一阶段验证重点不是全量 UI，而是播放主链切换是否成功。 必须验证： - controller 直接调用可起播单曲。 - controller 直接调用可起播队列。 - `play/pause/next/previous/seek` 不依赖 `LocalMusic` actions。 - `LocalMusic` 不再作为 `EVENT_PLAYLIST_PLAY` 的主执行入口。 - 迷你播放条和全屏播放器仍能跟随共享状态更新。 建议测试层次： - 控制器与 coordinator 的纯逻辑测试。 - 队列切换与索引切换的回归测试。 - AVSession / 投播的冒烟验证。 - 真机手工验证：统计页、歌单页、发现页直接起播。 ## 决策结论 本阶段采用以下明确决策： - 可以接受 `LocalMusic` 继续常驻隐藏挂载。 - 不再接受 `LocalMusic` 作为播放指令宿主。 - 先保留 `NewIndex/LocalMusic` 的 UI 显示状态。 - 先抽播放核心，再逐步抽状态与显示层。 这保证第一阶段的目标聚焦为：让 controller 真正变成任何页面都能直接调用的播放入口，同时把风险控制在可验证范围内。