ADR-025: 不开 xgplayer 逃生舱,结束覆盖层与清晰度菜单归团队层

Status: Accepted Date: 2026-07-15

Context

契约冻结(protocol → 1.0.0)前,examples 里两个业务场景引用了当前 TeamVideoPlayer 尚未接入的能力,是冻结前最后需要定性的两个"疑似契约缺口":

结束覆盖层倒计时(VideoPageWithRec.vue):播完后显示"X 秒后播下一集" 的倒计时覆盖层,带 onTick / onComplete / cancellable。当前通过 :end-overlay prop 传入,但 TeamVideoPlayer 没声明该 prop → Vue fallthrough 静默失效。
清晰度门槛菜单(AuthGatedVideoPlayer.vue):未登录只能看标清,高清档位显示"高清(登录享)"且禁用,点击触发登录流程。当前通过 :xgplayer-config 把一段原始 xgplayer 配置(controls.definition.list)透传进播放器来定制清晰度菜单 → 同样 fallthrough 静默失效。

场景 2 的写法逼出一个契约层决策:要不要给 protocol 开一个 xgplayer 逃生舱 (通用 passthrough,让业务方塞任意 xgplayer 配置进 iframe 内的播放器)?

两个都不进 protocol,归团队层 UI;protocol 不新增任何 schema。

结束覆盖层 = 团队层 UI,建立在已有的 ended 事件上。 TeamVideoPlayer 新增 endOverlay prop + EndOverlay.vue,监听 ended 后在团队层自己跑倒计时(setInterval)、自己渲染覆盖层、自己处理 cancel/complete。 SDK / iframe / 契约一律不参与。依据 ADR-021(SDK 不做团队 UI)。
清晰度菜单 = 团队层 UI,建立在已有的清晰度契约上:
- ready 事件的 quality: QualityLevel[](events.ts)提供档位清单
- setQuality 命令(methods.ts)切换档位
- qualitychange 事件(events.ts)回报切换结果
TeamVideoPlayer 用 Vant 自己画清晰度菜单,AuthGatedVideoPlayer 在其上叠加 "登录门槛"这一业务概念(requiresAuth 是团队自己的 prop,不进契约)。
明确不开通用 xgplayer 逃生舱(xgplayer?: Record<string, unknown> 透传)。它与"契约防漂移"红线正面冲突:一旦业务方能塞任意 xgplayer 配置,契约就无法再保证跨接入方式行为一致(cross-mode-parity 硬红线失效),也无法做版本兼容判断。

场景 2 用已有契约即可完整实现——setQuality / qualitychange / ready.quality 三件套足够撑起团队层菜单 + 登录门槛,逃生舱是不必要的复杂度。
逃生舱是"SDK API 不合理"的一类——按 examples 验收规则(examples 是标准, 除非 SDK API 不合理或违反 ADR),此处改 examples(重写 AuthGatedVideoPlayer 走团队层菜单),而非为迁就 examples 而破坏契约红线。
冻结形态最干净——两个缺口都不需要新 schema,protocol 可直接进 1.0.0 冻结, 后续插件实现若需新增可选字段,走 minor(1.x 向后兼容),不受 0.x "minor 即破坏" 规则拖累。

好:

代价 / 待办:

需重写 examples/team-video-vue/AuthGatedVideoPlayer.vue:去掉 xgplayer-config, 改用团队层清晰度菜单 + 已有 setQuality/qualitychange。
TeamVideoPlayer 需补两个能力:endOverlay prop + 覆盖层,清晰度菜单 + qualityChange emit。
player-core 需实现 setQuality / qualitychange / 填充 ready.quality (当前 embed-app dispatch-command 对 setQuality 抛"尚未实现")——属实现工作,非契约变更。
若未来确有业务需要 xgplayer 的某个具体能力,走"把该能力建成一等契约字段" (如 ADR 扩展 ControlsConfigSchema),不退回通用逃生舱。