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

基于 NASA JPL Horizons 数据的深空探测器 3D 可视化系统。

## 快速开始

### 前置要求

- Python 3.11+
- Node.js 20+
- Yarn

### 1. 启动后端 API

```bash
cd backend

# 创建虚拟环境并安装依赖
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -r requirements.txt

# 启动服务器
python -m app.main
```

后端将运行在 http://localhost:8000

- API 文档: http://localhost:8000/docs
- 健康检查: http://localhost:8000/health

### 2. 启动前端应用

```bash
cd frontend

# 安装依赖
yarn install --ignore-engines

# 启动开发服务器
yarn dev
```

前端将运行在 http://localhost:5173

## 项目结构

```
cosmo/
├── backend/              # Python FastAPI 后端
│   ├── app/
│   │   ├── main.py      # FastAPI 入口
│   │   ├── api/         # API 路由
│   │   ├── models/      # 数据模型
│   │   └── services/    # 业务逻辑
│   └── requirements.txt
├── frontend/             # React + Three.js 前端
│   ├── src/
│   │   ├── components/  # React 组件
│   │   ├── hooks/       # 自定义 hooks
│   │   ├── types/       # TypeScript 类型
│   │   └── utils/       # 工具函数
│   └── package.json
├── PROJECT.md           # 详细技术方案
├── IMPLEMENTATION_PLAN.md  # 实施计划
└── README.md            # 本文件
```

## 功能特性

### 已实现 ✅

- **后端 API**
  - 从 NASA JPL Horizons 获取实时天体数据
  - 支持时间范围查询
  - 数据缓存机制（每3天更新）
  - RESTful API 设计

- **前端 3D 可视化**
  - React + Three.js 3D 场景
  - 实时显示太阳系天体位置
  - 交互式相机控制（旋转、平移、缩放）
  - 星空背景
  - 响应式设计

- **支持的天体**
  - 探测器: Voyager 1 & 2, New Horizons, Parker Solar Probe, Juno, Cassini, Perseverance
  - 行星: 太阳系八大行星

### 规划中 🚧

- 轨道线绘制
- 时间选择器
- 点击聚焦功能
- 信息面板
- 真实纹理贴图
- 3D 探测器模型
- 动态缩放优化

## 技术栈

### 后端
- FastAPI - 现代 Python Web 框架
- astroquery - NASA JPL Horizons 数据查询
- astropy - 天文计算
- Pydantic - 数据验证

### 前端
- React 18 + TypeScript
- Vite - 快速构建工具
- Three.js - 3D 渲染
- @react-three/fiber - React Three.js 集成
- @react-three/drei - Three.js 辅助工具
- Tailwind CSS - 样式框架
- Axios - HTTP 客户端

## API 端点

### 获取天体位置
```
GET /api/celestial/positions
```

查询参数:
- `start_time`: 起始时间 (ISO 8601)
- `end_time`: 结束时间 (ISO 8601)
- `step`: 时间步长 (如 "1d", "12h")

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

### 列出所有天体
```
GET /api/celestial/list
```

## 使用说明

### 控制方式

- **左键拖动**: 旋转视角
- **右键拖动**: 平移视角
- **滚轮**: 缩放

### 坐标系统

使用日心坐标系（Heliocentric），以太阳为原点，单位为 AU (天文单位)。

## 外部资源需求

### 3D 模型（未来）
- 来源: https://nasa3d.arc.nasa.gov/models
- 格式: GLB/GLTF
- 存放: `frontend/public/models/`

### 行星纹理（未来）
- 来源: https://www.solarsystemscope.com/textures/
- 格式: JPG/PNG
- 存放: `frontend/public/textures/`

## 开发进度

详见 [IMPLEMENTATION_PLAN.md](./IMPLEMENTATION_PLAN.md)

- ✅ Stage 1: 后端基础框架和数据获取
- ✅ Stage 2: 前端基础框架和简单 3D 场景
- ✅ Stage 3: 集成真实数据（部分完成）
- 🚧 Stage 4: 进阶交互和信息面板
- 🚧 Stage 5: 视觉优化和模型加载

## 故障排除

### 后端无法启动
- 确保 Python 3.11+ 已安装
- 检查虚拟环境是否激活
- 尝试升级 pip: `pip install --upgrade pip`

### 前端依赖安装失败
- 使用 `yarn install --ignore-engines`
- 确保 Node.js 版本 >= 20

### 数据加载缓慢
- NASA JPL Horizons API 首次查询较慢（10-30秒）
- 后续请求会使用缓存，速度更快

## 许可证

MIT

## 致谢

- NASA JPL Horizons System
- React Three Fiber 社区
- Astroquery 项目

---

更多技术细节请查看 [PROJECT.md](./PROJECT.md)