# Earth News Source Configuration And Collector Plan

## Why

当前 Earth 的“态势新闻”由 [earth_news.py](/home/ray/dev/linkong/planet/backend/app/services/earth_news.py) 直接在请求时抓取 RSS / Google News feed，再按当前地球视角中心区域聚合返回。

这条链已经可用，但存在两个明显限制：

- 新闻源写死在代码里，不能像 TV 直播源一样从后台维护
- 新闻并未进入统一采集体系，没有采集状态、失败监控、历史数据和后续 AI 复用能力

因此这块更合理的路线不是一步到位重写，而是分阶段推进：

1. 先做“新闻源配置化”
2. 再做“新闻采集器化”

## Current State

当前实现分布在：

- 新闻接口
  - [news.py](/home/ray/dev/linkong/planet/backend/app/api/v1/news.py)
- 实时聚合逻辑
  - [earth_news.py](/home/ray/dev/linkong/planet/backend/app/services/earth_news.py)
- 前端消费
  - [news.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/news.js)

当前新闻源包含：

- `BBC World` RSS
- `DW Top Stories` RSS
- 按区域关键词拼出来的 `Google News RSS`
  - `Global`
  - `Americas`
  - `Europe`
  - `Middle East / Africa`
  - `Asia Pacific`

当前不是采集器，也不落库，只做内存缓存。

## Phase 1: Source Configuration

### Goal

把 `NEWS_FEED_SOURCES` 从硬编码列表升级成可配置新闻源目录，但继续保留当前“实时聚合”的工作方式。

### Scope

- 为 Earth news 建立独立配置结构
- 支持后台维护 feed 源
- 支持启用/禁用、优先级、区域、源类型
- 保持现有 `/api/v1/news/earth-feed` 输出协议不变

### Proposed Shape

建议配置字段至少包括：

- `id`
- `name`
- `region`
- `feed_url`
- `homepage_url`
- `source_type`
- `priority`
- `is_enabled`
- 可选 `query_profile`
- 可选 `language`
- 可选 `notes`

### Suggested Storage

优先走系统设置或单独的 news source settings payload，而不是先建复杂新表。

推荐原因：

- 改动小
- 易上线
- 和当前 TV settings 维护体验更接近
- 先解决“写死在代码里”的问题

### Non-goals

这一阶段不做：

- 新闻入库
- 新闻历史回看
- 新闻采集任务监控
- 新闻去重流水线

## Phase 2: News Collectorization

### Goal

把“态势新闻”升级为真正的采集器链路，使其进入采集系统和数据层。

### Scope

- 新增专用 news collector
- 按配置源定时采集 RSS / feed
- 做标题/链接级去重
- 建立统一新闻记录模型
- 为 Earth、控制台、AI 研判复用同一份新闻数据

### Benefits

- 有采集状态
- 有失败监控
- 有历史缓存
- 可以做时间轴 / 区域新闻基线
- 可以作为 AI 引用证据

### Required Design Work

需要提前明确：

- 新闻数据模型
- 去重策略
- 过期清理策略
- 区域映射策略
- 聚合排序策略
- 新闻与 Earth 当前视角/区域的关联方式

### Candidate Output Model

至少应包含：

- `source_id`
- `headline`
- `summary`
- `url`
- `publisher`
- `region`
- `published_at`
- `language`
- `tags`
- `raw_feed_source`
- `reference_date`

## Recommended Order

推荐执行顺序：

1. 先完成 Phase 1 配置化
2. 保持 Earth 继续实时聚合，但改为读取配置源
3. 等新闻源稳定后，再设计 Phase 2 的 collector / storage / dedupe

## Decision

当前结论：

- TV 直播源：优先采集器化
- 态势新闻：优先配置化，再采集器化

## Source Note

This plan is newly created for the Planet repo to separate the short-term "configurable source directory" work from the longer-term "collectorized news pipeline" work.