cosmo/PROJECT.md

# Cosmo - 深空探测器可视化系统

## 项目概述

基于 NASA JPL Horizons 数据的深空探测器 3D 可视化系统，展示旅行者号、火星探测器等深空探测器在太阳系中的实时位置和历史轨迹。

## 技术栈

### 后端
- **框架**: Python 3.11+ with FastAPI
- **核心库**:
  - `fastapi` - Web 框架
  - `astroquery` - NASA JPL Horizons 数据查询
  - `astropy` - 天文计算和时间处理
  - `uvicorn` - ASGI 服务器
  - `pydantic` - 数据验证
  - `python-dotenv` - 环境变量管理

### 前端
- **框架**: React 18 with TypeScript
- **构建工具**: Vite
- **3D 渲染**:
  - `three` - 核心 3D 引擎
  - `@react-three/fiber` - React Three.js 集成
  - `@react-three/drei` - Three.js 辅助组件
- **UI 库**:
  - `tailwindcss` - 样式框架
  - `lucide-react` - 图标库
- **状态管理**: React Hooks (useState, useContext)
- **HTTP 客户端**: `axios`

## 核心功能

### 1. 数据获取
- 从 NASA JPL Horizons 获取探测器和行星的日心坐标 (x, y, z)
- 支持时间序列查询（用户指定起止时间）
- 数据缓存策略：每3天更新一次
- 单位：AU (天文单位)

### 2. 支持的天体

#### 探测器
| 名称 | ID | 备注 |
|------|----|----|
| Voyager 1 | -31 | 最远的人造物体 |
| Voyager 2 | -32 | 访问过天王星海王星 |
| New Horizons | -98 | 冥王星探测器 |
| Parker Solar Probe | -96 | 最接近太阳 |
| Juno | -61 | 木星探测器 |
| Cassini | -82 | 土星探测器（历史数据） |
| Perseverance | -168 | 火星车 |

#### 行星
| 名称 | ID |
|------|----|
| Sun | 10 |
| Mercury | 199 |
| Venus | 299 |
| Earth | 399 |
| Mars | 499 |
| Jupiter | 599 |
| Saturn | 699 |
| Uranus | 799 |
| Neptune | 899 |

### 3. 3D 可视化功能

#### 基础功能
- 太阳系 3D 场景渲染（日心坐标系）
- 行星纹理贴图（diffuse, normal, specular maps）
- 探测器 3D 模型加载（GLB 格式）
- 轨道线绘制（时间序列连线）
- 星空背景（Skybox）

#### 交互功能（进阶）
- **OrbitControls**: 旋转、缩放、平移视角
- **点击聚焦**: 点击探测器/行星，相机平滑飞向目标
- **信息面板**: 显示选中物体的详细信息
  - 名称、距离太阳距离、速度
  - 最近的行星及距离
- **时间选择器**: 用户选择起止时间查看历史位置
- **动态缩放**: 解决尺度问题（远看时放大物体）

### 4. 尺度处理策略

**问题**: 太阳系空间巨大，真实比例下行星会小到看不见

**解决方案**:
- 坐标系统使用真实 AU 单位（计算准确）
- 渲染时应用动态缩放：
  - 远景：行星和探测器放大 1000-10000 倍
  - 近景：逐渐恢复真实比例
  - 探测器在远景时显示为发光图标，近景时显示 3D 模型

## 外部资源需求

### 3D 模型（需下载）
- **来源**: https://nasa3d.arc.nasa.gov/models
- **格式**: GLB/GLTF
- **存放位置**: `frontend/public/models/`
- **需要的模型**:
  - Voyager 1 & 2
  - New Horizons
  - Parker Solar Probe
  - Juno
  - Cassini
  - Perseverance

### 行星纹理（需下载）
- **来源**: https://www.solarsystemscope.com/textures/
- **格式**: JPG/PNG (2K 或 4K)
- **存放位置**: `frontend/public/textures/`
- **每个行星需要**:
  - `{planet}_diffuse.jpg` - 颜色贴图
  - `{planet}_normal.jpg` - 法线贴图（可选）
  - `earth_specular.jpg` - 地球高光贴图（仅地球）

## 项目结构

```
cosmo/
├── backend/
│   ├── app/
│   │   ├── __init__.py
│   │   ├── main.py              # FastAPI 入口
│   │   ├── config.py            # 配置
│   │   ├── models/
│   │   │   ├── __init__.py
│   │   │   └── celestial.py    # 数据模型
│   │   ├── services/
│   │   │   ├── __init__.py
│   │   │   ├── horizons.py     # JPL Horizons 查询
│   │   │   └── cache.py        # 数据缓存
│   │   └── api/
│   │       ├── __init__.py
│   │       └── routes.py       # API 路由
│   ├── requirements.txt
│   └── .env.example
├── frontend/
│   ├── src/
│   │   ├── App.tsx
│   │   ├── main.tsx
│   │   ├── components/
│   │   │   ├── Scene.tsx       # 主场景
│   │   │   ├── CelestialBody.tsx
│   │   │   ├── Probe.tsx
│   │   │   ├── OrbitLine.tsx
│   │   │   ├── InfoPanel.tsx
│   │   │   └── TimeSelector.tsx
│   │   ├── hooks/
│   │   │   └── useSpaceData.ts
│   │   ├── types/
│   │   │   └── index.ts
│   │   └── utils/
│   │       └── api.ts
│   ├── public/
│   │   ├── models/             # 探测器 3D 模型
│   │   └── textures/           # 行星纹理
│   ├── package.json
│   ├── tsconfig.json
│   ├── vite.config.ts
│   └── tailwind.config.js
├── PROJECT.md                   # 本文件
├── IMPLEMENTATION_PLAN.md      # 实施计划
└── README.md
```

## API 设计

### 端点

#### `GET /api/celestial/positions`
获取指定时间的天体位置

**Query Parameters**:
- `start_time`: ISO 8601 格式（可选，默认为当前时间）
- `end_time`: ISO 8601 格式（可选）
- `step`: 时间步长，如 "1d"（可选，默认 "1d"）

**Response**:
```json
{
  "timestamp": "2025-11-26T00:00:00Z",
  "bodies": [
    {
      "id": "-31",
      "name": "Voyager 1",
      "type": "probe",
      "positions": [
        {
          "time": "2025-11-26T00:00:00Z",
          "x": 160.5,
          "y": 20.3,
          "z": -15.2
        }
      ]
    }
  ]
}
```

#### `GET /api/celestial/info/{body_id}`
获取天体详细信息

**Response**:
```json
{
  "id": "-31",
  "name": "Voyager 1",
  "type": "probe",
  "description": "离地球最远的人造物体",
  "launch_date": "1977-09-05",
  "status": "active"
}
```

## 开发阶段

详见 `IMPLEMENTATION_PLAN.md`

## 数据更新策略

- 深空探测器移动缓慢，数据每3天更新一次
- 后端实现缓存机制，避免频繁请求 NASA API
- 缓存存储在内存中（简单实现）或 Redis（生产环境）