cosmo/PHASE5_PLAN.md

Phase 5: APP Connectivity & Social Features Plan

🎯 阶段目标

本阶段致力于打通移动端 APP 与后端平台的连接，增强系统的社会化属性（关注、频道），并引入天体事件自动发现机制。同时优化底层数据获取性能。

---

🛠 功能规划

1. 资源增强：天体图标 (Icons)

• 需求: 为每个天体增加专属图标（320x320 PNG/JPG），用于 APP 列表页和详情页头部展示。
• 实现:
  • 利用现有的 resources 表。
  • 确保 resource_type 支持 'icon' 枚举值。
  • 后端 API POST /celestial/resources/upload 需支持上传到 upload/icon/ 目录。
  • 前端/APP 端在获取天体列表时，优先加载 icon 资源。

2. 天体事件系统 (Celestial Events)

• 需求: 自动计算/拉取天体动态事件（如“火星冲日”、“小行星飞掠”）。
• 数据源:
  • 小天体 (Comets/Asteroids): NASA JPL SBDB Close-Approach Data API (https://ssd-api.jpl.nasa.gov/cad.api).
  • 主要行星: 基于 skyfield 或 ephem 库进行本地计算（冲日、合月等），或解析 Horizons 数据。
• 实现:
  • 新增 celestial_events 表。
  • 新增定时任务脚本 fetch_celestial_events.py (注册到 Scheduled Jobs)。
  • API: GET /events (支持按天体、时间范围筛选)。

3. 性能优化：JPL Horizons Redis 缓存

• 需求: 减少对 NASA 接口的实时请求，针对“同天体、同一日”的请求进行缓存。
• 策略:
  • Key: nasa:horizons:{body_id}:{date_str} (例如 nasa:horizons:499:2025-12-12).
  • Value: 解析后的 Position 对象或原始 Raw Text。
  • TTL: 7天或更久（历史数据永不过期）。
  • 在 HorizonsService 层拦截，先查 Redis，无数据再请求 NASA 并写入 Redis。

4. 社交功能：关注与频道

• 关注 (Subscriptions/Follows):
  • 用户可以关注感兴趣的天体（如关注“旅行者1号”）。
  • 新增 user_follows 表。
  • API: 关注、取消关注、获取关注列表。
• 天体频道 (Body Channels):
  • 每个天体拥有一个独立的讨论区（Channel）。
  • 只有关注了该天体的用户才能在频道内发言。
  • 存储: Redis List (类似于弹幕 danmaku 的设计)，不持久化到 PostgreSQL。
  • Key: channel:messages:{body_id}。
  • TTL: 消息保留最近 100-500 条或 7 天，过旧自动丢弃。
  • API: 发送消息、获取频道消息流。
• 消息推送 (Notification):
  • 当关注的天体发生 celestial_events 时，系统应生成通知（本阶段先实现数据层关联，推送推迟到 Phase 6 或 APP 端轮询）。

---

🗄 数据库变更 (Database Schema)

新增表结构

1. celestial_events (天体事件表)

Column	Type	Comment
id	SERIAL	PK
body_id	VARCHAR(50)	FK -> celestial_bodies.id
title	VARCHAR(200)	事件标题 (e.g., "Asteroid 2024 XK Flyby")
event_type	VARCHAR(50)	类型: 'approach', 'opposition', 'conjunction'
event_time	TIMESTAMP	事件发生时间 (UTC)
description	TEXT	事件描述
details	JSONB	技术参数 (距离、相对速度等)
source	VARCHAR(50)	来源 ('nasa_sbdb', 'calculated')

2. user_follows (用户关注表)

Column	Type	Comment
user_id	INTEGER	FK -> users.id
body_id	VARCHAR(50)	FK -> celestial_bodies.id
created_at	TIMESTAMP	关注时间
Constraint	PK	(user_id, body_id) 联合主键

---

🗓 实施步骤 (Execution Steps)

1. 数据库迁移: 执行 SQL 脚本创建新表（celestial_events, user_follows）。
2. 后端开发:
   • Horizons缓存: 修改 HorizonsService 增加 Redis 缓存层。
   • 关注功能: 实现 /social/follow API。
   • 频道消息: 实现 /social/channel API，使用 Redis 存储。
   • 天体事件: 实现 NASA SBDB 数据拉取逻辑与 API。
3. 验证:
   • 测试关注/取关。
   • 测试频道消息发送与接收（验证 Redis 存储）。
   • 测试 Horizons 缓存生效。