# Earth 电视直播模块计划

## 目标

为 `Earth` 页面增加一个可配置、可扩展、可拖拽的电视直播模块：

- 后台可配置新闻直播源
- 默认兜底源为央视 `CCTV-4`
- 未来可通过采集器接入世界各地新闻直播源
- Earth 工具栏 `显示控制` 子菜单新增电视按钮
- 点击后打开一个与其他 HUD 一致的可拖拽/可关闭窗口
- 窗口内部可播放或承载新闻直播页面

## 设计原则

- 第一阶段先交付“后台可配 + Earth 可用 + 默认可回退”的版本
- 公开读取接口与后台管理接口分离
- 手工配置源与采集器源共用统一的前端消费结构
- Earth 里的电视窗口必须复用现有 HUD 拖拽、关闭、布局最大化逻辑
- 小屏下优先保证窗口完整显示，超出部分在窗口内部滚动

## 分阶段实现

### Phase 1：后端配置与公开读取

- 在系统设置中新增 `tv` 分类
- 定义直播源配置结构：
  - `default_source_id`
  - `auto_fallback`
  - `sources[]`
- 每个直播源至少包含：
  - `id`
  - `name`
  - `provider`
  - `region`
  - `language`
  - `source_type`
  - `embed_url`
  - `stream_url`
  - `homepage_url`
  - `is_enabled`
  - `is_fallback`
  - `sort_order`
  - `collector_source`
  - `notes`
- 默认兜底源使用央视官网 `CCTV-4` 直播页
- 新增公开读取接口，供 Earth 页面无登录态读取直播源配置

### Phase 2：采集器扩展位

- 新增 `news_live_streams` collector 占位
- 规范采集器入库数据结构，使其能与后台手工配置源合并
- TV 公开接口支持合并：
  - 后台手工配置源
  - 采集器入库源
- 保持手工配置源优先级更高，避免采集器覆盖人工兜底配置

### Phase 3：后台配置界面

- 在系统配置页新增 `电视直播` tab
- 支持：
  - 查看当前默认源
  - 开关自动回退
  - 新增直播源
  - 编辑直播源
  - 删除直播源
  - 启用/禁用直播源
  - 将某个直播源设为默认源
- 明确区分：
  - 手工配置源
  - 采集器来源

### Phase 4：Earth HUD 集成

- 在 `显示控制` 子菜单加入电视按钮
- 新增 TV HUD 面板：
  - 可拖拽
  - 可关闭
  - 支持显示/隐藏状态同步
  - 参与布局最大化与恢复布局
- 面板内容至少包含：
  - 当前频道标题
  - 源切换下拉菜单
  - 刷新按钮
  - 打开官网按钮
  - 播放区域

### Phase 5：播放策略

- 第一版优先支持 `iframe`/嵌入页类直播源
- 为未来扩展保留：
  - `hls`
  - `video`
  - `external`
- 如果默认源不可用：
  - 优先回退到标记为 `is_fallback=true` 的源
  - 若无明确回退源，则回退到第一个可用源
- 面板内要有清晰的加载、错误、回退提示

### Phase 6：打磨与清理

- 统一 HUD 风格
- 小屏下限制窗口尺寸并启用内部滚动
- 避免窗口超出屏幕
- 补最小验证
- 清理临时代码、重复样式和无用资源

## 首版交付定义

当以下条件满足时，认为首版可用：

- 后台可以配置新闻直播源
- Earth 可以读取并显示默认直播源
- 工具栏可打开电视窗口
- 电视窗口可拖拽、可关闭
- 央视 `CCTV-4` 作为默认兜底源可被使用
- 代码结构已为后续采集器接入预留统一接口