ADR-021: SDK 不做团队 UI

Status: Accepted Date: 2026-07-13

Context

播放器有些"团队品牌 UI"需求:

• 取消静音按钮的颜色 / 位置
• 自动播放被拒时的 CTA 文案
• 主播卡片信息展示
• SEA 6 种语言的 UI 翻译

这些应该在 SDK 里做,还是团队封装层做?

Decision

SDK 只做技术,团队品牌 UI 由业务团队用原生 UI 库封装,不进 SDK monorepo。

具体:

• SDK 内(packages/)不含团队品牌 UI 组件
• 团队 UI 位于 cend-p0 项目内部 src/shared/video/
• 未来可抽公司内部私服 @sentinel-cend/video-ui
• SDK 对外发布仅"基础 SDK",团队封装保持私有

Rationale

• SDK 的定位是通用能力(交付给多方使用),团队 UI 是私有资产
• SDK 版本节奏 ≠ 团队 UI 版本节奏——team 层可以每周迭代,SDK 半年一发
• 每个业务团队可能有自己的 UI 库,SDK 不该绑定 Vant / shadcn / etc

Consequences

好:

• SDK 通用性强,可对外
• 团队 UI 自由迭代不受 SDK 版本约束
• 4 种 UI 库(shadcn / Vant / Compose / SwiftUI)各自封装

代价:

• 消费方接入成本略高(需要写团队封装层)
• 参考实现必不可少(见 examples/team-video-vue/)

Alternatives Considered

方案 A(SDK 内置主题变量):限制业务方 UI 库选择 方案 B(SDK 提供 UI 插槽):复杂度高,难保证 4 种接入方式一致

References

• examples/team-video-vue/ — 完整参考实现
• docs/USER-GUIDE.md § 14-25 — 团队封装最佳实践