TTMusic/docs/superpowers/specs/2026-04-04-music-card-background-call-design.md

音乐卡片后台控播改造设计

背景

当前 TTMusic 的音乐卡片播放控制没有完全独立：

• 卡片 play_pause/prev/next/seek_to 当前优先走 call 到 EntryAbility
• 当应用进程已被强杀时，call 的接收方不存在，按钮无响应
• FormExtensionAbility 当前只能把事件转发给 eventHub，或兜底拉起 EntryAbility
• 一旦走 EntryAbility 冷启动兜底，就会把应用前台界面拉起，不符合目标

用户目标已经明确：

• 强杀后，点击卡片 播放/暂停/上一首/下一首 仍然可用
• 这些控制动作不能把应用前台界面拉起
• 只有明确点击“打开播放器”的动作，才允许进入前台页面

平台依据

根据用户提供的鸿蒙官方文档《卡片拉起应用UIAbility到后台（call事件）》：

• 卡片 postCardAction(... action: 'call') 可以将指定 UIAbility 拉到后台
• call 事件支持指定方法名和参数
• 该能力依赖 ohos.permission.KEEP_BACKGROUND_RUNNING
• 该路径不要求 ohos.permission.START_INVISIBLE_ABILITY

这意味着本项目不必走 AppServiceExtensionAbility 或 invisible ability 路线，可以直接采用：

卡片 -> call -> 后台 UIAbility -> 独立播放控制入口

现状问题

1. 控制入口仍然绑在 EntryAbility

TTMusic 当前卡片控制动作的接收方是 EntryAbility.callee。这在应用存活时可用，但在进程被强杀后没有稳定的后台控制入口。

2. FormAbility 不能直接控播

MusicCardFormAbility 当前只负责：

• 更新卡片数据
• 将消息转发到 eventHub
• 兜底拉起 EntryAbility

它不是实际的冷启动控播执行者。

3. 播放控制仍依赖页面运行态

当前播放能力虽然已经在做拆分，但仍然与页面侧运行态、页面事件和 LocalMusic 生命周期耦合较深。结果是：

• 热态控播能工作
• 冷态后台控播缺少一个真正独立的宿主

设计目标

本次改造只解决音乐卡片后台控播，不做无关重构。

成功标准：

1. 应用未强杀时，卡片 播放/暂停/上一首/下一首/进度跳转 可正常工作
2. 应用被强杀后，卡片 播放/暂停/上一首/下一首 可直接生效
3. 上述控制动作不会拉起前台页面
4. 卡片“打开播放器”动作仍然可以进入前台播放器页面
5. 卡片状态在控播后能继续刷新

方案对比

方案 A：卡片控制统一走后台 UIAbility

路径：

卡片 -> call -> 后台控播 UIAbility -> 独立播放控制器

优点：

• 与官方文档能力完全一致
• 不需要 START_INVISIBLE_ABILITY
• 能天然满足“强杀后可控播但不拉前台”
• 冷启动路径和热启动路径可以统一到同一个控制接口

缺点：

• 需要把现有控播逻辑进一步从页面侧拆出来

方案 B：卡片走 FormAbility.message

路径：

卡片 -> message -> FormAbility -> 独立播放控制器

优点：

• 保持卡片提供方逻辑集中在 FormAbility

缺点：

• 与官方推荐的“后台拉起 UIAbility 执行 call”路径不一致
• 当前项目里 FormAbility 已经承担卡片数据职责，再承担后台播放器宿主会混杂两类生命周期

方案 C：继续复用 EntryAbility

路径：

卡片 -> call/router -> EntryAbility -> 播放控制器

优点：

• 表面改动最少

缺点：

• 很难稳定保证“不拉前台”
• 会继续把卡片后台控播和主界面生命周期绑在一起

推荐方案

采用方案 A。

具体做法：

• 新增一个专门承接音乐卡片后台 call 的 UIAbility
• 该 UIAbility 不负责页面展示，只负责注册 callee.on(...)
• 卡片上的 播放/暂停/上一首/下一首/进度跳转 全部发送到这个后台控播 UIAbility
• 卡片上的“打开播放器”仍然走 router 到 EntryAbility
• 新增一个真正独立的“卡片后台播放宿主”，它不依赖 LocalMusic 页面实例

目标架构

卡片事件分流

• play_pause -> call -> MusicCardControlAbility
• prev_song -> call -> MusicCardControlAbility
• next_song -> call -> MusicCardControlAbility
• seek_to -> call -> MusicCardControlAbility
• open_player -> router -> EntryAbility

后台控播宿主职责

新增后台控播宿主后，它需要负责：

• 接收卡片 call 方法和参数
• 解析动作、表单 ID、跳转位置
• 恢复已持久化的播放快照和播放队列
• 在没有页面实例时独立执行 play/pause/prev/next/seek
• 执行后刷新卡片快照和卡片 UI

页面侧职责

LocalMusic 和页面运行态继续负责：

• 前台播放器 UI
• 正常播放中的实时状态上报
• 将最新播放状态、队列和当前歌曲写入持久化存储

页面侧不再承担“卡片强杀后冷启动时的唯一执行入口”。

关键设计细节

1. 新增后台控播 UIAbility

建议新增单独能力，例如：

• MusicCardControlAbility

职责：

• 在 onCreate 中注册 callee.on(MusicCardActionConstants.CALL_METHOD_HANDLE_ACTION, ...)
• 接收卡片参数后分发给后台控播宿主
• 不做页面路由，不创建播放器页面
• 生命周期结束时执行 callee.off(...)

该能力在 module.json5 中新增 abilities 配置。

2. 卡片控制动作不再发往 EntryAbility

所有卡片页面中的控制按钮都改成：

• abilityName: 'MusicCardControlAbility'
• action: 'call'

只有“打开播放器”保留：

• abilityName: 'EntryAbility'
• action: 'router'

3. 新增后台独立播放控制入口

建议新增一个面向后台卡片控播的控制器，例如：

• MusicCardBackgroundPlaybackController

职责：

• 从现有持久化快照中恢复当前歌曲
• 从现有持久化队列中恢复播放队列和当前下标
• 执行 toggle/previous/next/seekTo
• 将执行结果写回快照存储
• 触发 MusicCardManager.updateAllForms(...)

该控制器的目标不是替代现有前台控制器，而是提供“无页面实例时也能运行”的最小控播闭环。

4. 播放恢复源

后台控播所需的数据优先来自现有持久化层：

• 当前播放快照
• 当前播放队列
• 当前下标
• 当前文件路径
• 当前播放进度

如果快照存在但队列缺失：

• play_pause 至少应支持恢复当前歌曲
• prev/next 在没有有效队列时退化为保持当前歌曲不切换，并记录日志

5. 热态与冷态统一接口

最终控制接口应统一为：

• 热态：页面/前台宿主调用同一组控制方法
• 冷态：后台控播 UIAbility 也调用同一组控制方法

这样可以避免出现两套播放切换逻辑不一致的问题。

错误处理

• 没有任何可恢复的快照时，play_pause 不做前台拉起，只记录日志
• 队列不可恢复时，prev/next 不做前台拉起，只记录日志
• seek_to 参数非法时忽略
• 后台控播失败时，必须确保不会误触发页面路由

测试策略

自动化

新增或补充以下测试：

• 卡片动作参数解析测试
• 后台控播宿主在只有快照时的恢复测试
• 后台控播宿主在有队列时的上一首/下一首切换测试
• 控制动作不会落到 EntryAbility 的路由测试

手工验证

1. 应用前台运行时，卡片 播放/暂停/上一首/下一首 正常
2. 应用切后台但未强杀时，卡片控制正常且不拉前台
3. 强杀应用后，点击卡片播放可直接播放，不拉前台
4. 强杀应用后，点击卡片上一首/下一首可切歌，不拉前台
5. 点击卡片封面或“打开播放器”时，前台页面正常打开

实施顺序

1. 新增后台控播 UIAbility 配置与空实现
2. 将卡片控制按钮的 call 目标切换到新能力
3. 提炼后台独立播放控制入口
4. 接入快照/队列恢复逻辑
5. 接入卡片刷新
6. 补测试并验证强杀场景

范围外

本次不处理：

• 全量重构现有前台播放器架构
• 远程歌曲缓存策略重做
• 卡片 UI 视觉调整
• 非音乐卡片场景的后台唤起能力复用