在线文档

9.1 App 点播台

1. 首页「点播台」：有播放历史时展示历史（最新在前）；无历史时展示专辑前 4 个；下架专辑不展示
2. 点击专辑 → 弹出歌曲列表（封面、专辑名、曲目数、曲目行与播放按钮）
3. 点击「>>」→ 完整点播台，含「播放历史」「专辑」两个 Tab；Tab 内点专辑同样进入歌曲列表
4. 在歌曲列表点击播放 → 以专辑为单位从该曲起播；时间线提示「已请求点播…」；设备经 agent /v2/devices/:sn/@ondemand-play，与语音点播共用「固定口播（当前角色音色）→ playing」编排后再播曲；连播由 agent 队列负责（会话 origin=remote）
5. 起播后设备进入「播放中（playing）」，设备卡片下方出现播放控制条（上一首/下一首、播放模式等）；MQTT 指令在日志中以 JSON 展示
6. 多媒体失败时时间线显示「点播失败：…」；错误码对齐设备协议（media_* 与近期起播窗口内的通用 command_*）
7. Seed 专辑「多媒体错误码演示」（默认不上架）用于联调：正常可播对照 / media_url_unreachable / media_unsupported_format / media_decode_error；未起播时点暂停可验 media_not_playing。曲目 URL 可带 x-haivivi-media-error=<code> 强制回码；OSS 素材用 packages/services/scripts/upload-media-error-demo-assets.ts 上传到 assets/media/错误码演示/

9.2 语音点播

• 对话中说「放首歌」「讲个故事」等（需开启「语音点播音乐」）
• 设备设置将「语音回复语言」设为 English 时，也可用 “Play a song”“Stop playing” 等英文指令验证；固定确认口播为英文
• 与 App 点播共用播放链路；自然对话播放中可能无法同时打开专辑
• 曲目有歌词时，agent 会把歌词推到对话区（MQTT chat）并写入对话历史；卡片展示播放进度条，卡片上不展示歌词（chat 仍会推送）

---