93eb41a9f7
Release 0.58.0 includes the Earth high-precision boundary PMTiles/MVT pipeline, standardized Earth boundary source collectors, China POV boundary configuration templates, and removal of the legacy low-precision GeoJSON fallback. It also adds Earth news target-location queueing/archive support, fixes datasource task status visibility, documents the Earth surface depth-spacing rules that prevent far-zoom z-fighting snow/black blocks, and updates bilingual operations/developer docs.
132 lines
4.1 KiB
Markdown
132 lines
4.1 KiB
Markdown
# EarthFeed 新闻坐标与异步精修计划
|
||
|
||
## 目标
|
||
|
||
EarthFeed 的每条新闻都直接携带巡航可用坐标。初始响应使用新闻所属大区的锚点坐标，后台通过消息队列异步推理更精确的目标地址，完成后用实时补丁替换原新闻坐标，实现前端无感更新。
|
||
|
||
## 返回结构
|
||
|
||
`GET /api/v1/news/earth-feed` 返回：
|
||
|
||
```json
|
||
{
|
||
"generated_at": "2026-05-15T03:16:43Z",
|
||
"focus": {
|
||
"lat": null,
|
||
"lon": null,
|
||
"region": "global",
|
||
"label": "全球焦点",
|
||
"accent": "#d6e6ff"
|
||
},
|
||
"sources": [
|
||
{
|
||
"id": "bbc-world",
|
||
"name": "BBC World",
|
||
"region": "global",
|
||
"homepage_url": "https://www.bbc.com/news/world"
|
||
}
|
||
],
|
||
"items": [
|
||
{
|
||
"id": "bbc-world:af01519ba7dd",
|
||
"title": "Flattery and fanfare as Trump welcomed to China - but thorny issues remain",
|
||
"summary": "The leaders of the world's two superpowers were all smiles...",
|
||
"url": "https://www.bbc.com/news/articles/cdxpypg9dgeo",
|
||
"source": "BBC World",
|
||
"feed_name": "BBC World",
|
||
"region": "global",
|
||
"homepage_url": "https://www.bbc.com/news/world",
|
||
"published_at": "2026-05-14T13:02:13Z",
|
||
"latitude": 39.9057136,
|
||
"longitude": 116.3912972,
|
||
"location_label": "北京市, 中国",
|
||
"location_source": "headline_location_hint",
|
||
"verified": true,
|
||
"location_meta": {
|
||
"resolution_stage": "headline_location_hint",
|
||
"ai_attempted": false,
|
||
"ai_status": "skipped_text_hint",
|
||
"ai_error": null,
|
||
"debug_note": "text hint matched 北京市, 中国",
|
||
"target": {
|
||
"latitude": 39.9057136,
|
||
"longitude": 116.3912972,
|
||
"label": "北京市, 中国",
|
||
"source": "headline_location_hint",
|
||
"confidence": 0.78,
|
||
"country": "中国",
|
||
"city": "Beijing"
|
||
},
|
||
"anchor": {
|
||
"region": "global",
|
||
"label": "全球",
|
||
"latitude": 20.0,
|
||
"longitude": 0.0
|
||
}
|
||
},
|
||
"is_focus_match": true
|
||
}
|
||
],
|
||
"errors": [],
|
||
"stale": false
|
||
}
|
||
```
|
||
|
||
字段规则：
|
||
|
||
- `latitude` / `longitude`：前端巡航唯一读取的坐标。
|
||
- `location_label`：当前坐标展示名。
|
||
- `location_source`：`region_anchor`、`headline_location_hint`、`headline_country_hint`、`ai_inferred_target` 等。
|
||
- `verified`：`false` 表示仍是大区锚点；`true` 表示已经由标题规则、国家规则或 AI 得到目标地址。
|
||
- `location_meta`：调试、诊断、AI 状态、目标地址和锚点详情都放这里，不再展开成 `t_*` 主字段。
|
||
|
||
## 后台队列
|
||
|
||
当前使用 Redis Streams：
|
||
|
||
- stream：`earth_news:target_location:jobs`
|
||
- consumer group：`earth_news_target_location`
|
||
- result cache：`earth_news:target_location:result:{item_id}`
|
||
- dedupe key：`earth_news:target_location:queued:{item_id}`
|
||
|
||
请求流程：
|
||
|
||
1. RSS 拉取并排序。
|
||
2. 每条新闻先生成大区锚点坐标，`verified=false`。
|
||
3. 若 Redis 已有该新闻的精修结果，则合并结果返回。
|
||
4. 若没有精修结果，则把新闻 job 入队，接口立即返回。
|
||
|
||
Worker 流程：
|
||
|
||
1. 从队列消费新闻 job。
|
||
2. 先跑标题/国家规则，再视情况调用 AI。
|
||
3. 写入 result cache。
|
||
4. 广播 WebSocket 补丁：
|
||
|
||
```json
|
||
{
|
||
"type": "data_frame",
|
||
"channel": "earth_news",
|
||
"timestamp": "2026-05-15T03:17:00Z",
|
||
"payload": {
|
||
"item_id": "bbc-world:af01519ba7dd",
|
||
"patch": {
|
||
"latitude": 39.9057136,
|
||
"longitude": 116.3912972,
|
||
"location_label": "北京市, 中国",
|
||
"location_source": "headline_location_hint",
|
||
"verified": true,
|
||
"location_meta": {}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 可迁移性
|
||
|
||
业务代码只调用队列接口，不直接依赖 Redis Streams 细节。以后迁移 Kafka 时新增 Kafka adapter，保持 job payload、result patch 和 worker 推理逻辑不变。
|
||
|
||
## 前端规则
|
||
|
||
新闻面板和巡航都只读取新闻项内的 `latitude` / `longitude`。实时补丁到达后按 `item_id` 合并到现有 `payload.items`，重新渲染并触发 `earth:news-payload-updated`，巡航下一轮自然使用精修坐标。
|