# 天体轨道自动生成功能使用说明

**版本**: 1.0
**最后更新**: 2025-12-10

---

## 功能概述

Cosmo项目现已支持为**行星**和**矮行星**自动生成公转轨道。该功能通过调用NASA JPL Horizons API获取真实的天体位置数据，预先计算并存储完整的轨道路径，供前端高效渲染。

---

## 适用天体类型

| 天体类型 | 是否支持轨道生成 | 说明 |
|----------|------------------|------|
| ✅ 行星 (planet) | 是 | 太阳系八大行星 |
| ✅ 矮行星 (dwarf_planet) | 是 | 冥王星、谷神星、阋神星等 |
| ❌ 卫星 (satellite) | 否 | 当前版本不支持 |
| ❌ 恒星 (star) | 否 | 恒星无需轨道 |
| ❌ 探测器 (probe) | 否 | 当前版本不支持 |
| ❌ 彗星 (comet) | 否 | 当前版本不支持 |

---

## 使用方法

### 方法一：为新增天体生成轨道（推荐）

#### 步骤1: 新增天体时填写轨道参数

1. 进入 **管理后台 > 天体数据管理**
2. 选择恒星系统（例如"太阳系"）
3. 点击 **"新增"** 按钮
4. 填写基本信息：
   - JPL Horizons ID
   - 英文名 / 中文名
   - **类型**: 选择"行星"或"矮行星"
   - 描述

5. **填写轨道参数**（当类型为行星/矮行星时自动显示）：

   ![轨道参数示例]

   - **轨道周期（天）**: 天体完整公转一周所需的天数
     - 例如：地球 = 365.25天
     - 例如：冥王星 = 90560天（约248年）

   - **轨道颜色**: 轨道线的显示颜色（HEX格式）
     - 例如：地球 = #4A90E2（蓝色）
     - 例如：火星 = #CD5C5C（红色）
     - 点击颜色选择器可视化选择

6. 保存天体

#### 步骤2: 生成轨道

1. 保存后返回天体列表
2. 找到刚才新增的天体
3. 点击该行右侧的 **"生成轨道"** 按钮
4. 等待生成完成（通常需要5-30秒）
5. 成功后会显示："轨道生成成功！共 XXX 个点"

---

### 方法二：为已有天体补充轨道参数并生成

#### 步骤1: 编辑天体添加轨道参数

1. 进入 **管理后台 > 天体数据管理**
2. 选择对应的恒星系统
3. 找到目标天体，点击 **"编辑"** 按钮
4. 在"基础信息"Tab中找到"轨道参数"部分
5. 填写：
   - 轨道周期（天）
   - 轨道颜色
6. 保存

#### 步骤2: 生成轨道

1. 返回列表，点击 **"生成轨道"** 按钮
2. 等待生成完成

---

### 方法三：批量生成（适合系统管理员）

如果您已经在代码中定义了轨道参数（通过硬编码的ORBITAL_PERIODS字典），可以使用批量生成：

1. 进入 **管理后台 > NASA数据下载**
2. 点击 **"生成所有轨道"** 按钮
3. 系统会自动为所有已定义轨道周期的行星/矮行星生成轨道

---

## 轨道参数参考

### 太阳系行星轨道周期

| 天体 | 轨道周期（天） | 建议颜色 |
|------|---------------|----------|
| 水星 | 88.0 | #8C7853 |
| 金星 | 224.7 | #FFC649 |
| 地球 | 365.25 | #4A90E2 |
| 火星 | 687.0 | #CD5C5C |
| 木星 | 4333.0 | #DAA520 |
| 土星 | 10759.0 | #F4A460 |
| 天王星 | 30687.0 | #4FD1C5 |
| 海王星 | 60190.0 | #4169E1 |

### 太阳系矮行星轨道周期

| 天体 | 轨道周期（天） | 建议颜色 |
|------|---------------|----------|
| 谷神星 (Ceres) | 1680.0 | #9E9E9E |
| 冥王星 (Pluto) | 90560.0 | #8B7355 |
| 阋神星 (Eris) | 203500.0 | #E0E0E0 |
| 妊神星 (Haumea) | 104000.0 | #D4A574 |
| 鸟神星 (Makemake) | 112897.0 | #C49A6C |

---

## 技术细节

### 轨道采样策略

系统会根据轨道周期智能决定采样点数量：

- **短周期天体**（<10年）：约每天1个点，最少100个点
  - 例如：地球（365天）→ 365个采样点

- **长周期天体**（≥10年）：约每月1个点，最多1000个点
  - 例如：冥王星（90560天）→ 1000个采样点

### 数据存储

生成的轨道数据存储在 `orbits` 表中：

```sql
SELECT * FROM orbits WHERE body_id = '999';  -- 查看冥王星的轨道
```

返回字段：
- `body_id`: 天体ID
- `points`: 轨道点数组（JSONB）
- `num_points`: 点数量
- `period_days`: 轨道周期
- `color`: 轨道颜色
- `updated_at`: 最后更新时间

### 前端渲染

前端通过API获取轨道数据后，使用Three.js的Line对象渲染：

```typescript
GET /celestial/orbits?body_type=planet
```

响应示例：
```json
{
  "orbits": [
    {
      "body_id": "399",
      "body_name": "地球",
      "points": [
        {"x": 1.0, "y": 0.0, "z": 0.0},
        {"x": 0.99, "y": 0.01, "z": 0.0},
        ...
      ],
      "num_points": 365,
      "period_days": 365.25,
      "color": "#4A90E2"
    }
  ]
}
```

---

## 常见问题

### Q1: 为什么生成轨道需要这么长时间？

**A**: 轨道生成需要调用NASA JPL Horizons API获取天体在整个公转周期内的位置数据。对于长周期天体（如冥王星），需要查询数百年的数据，因此耗时较长（通常10-30秒）。

---

### Q2: 我新增的矮行星没有"生成轨道"按钮？

**A**: 请检查以下几点：
1. 确认天体类型是否为"行星"或"矮行星"
2. 确认在列表中能看到该天体
3. 刷新页面重试

---

### Q3: 轨道生成失败，提示"No orbital period defined"？

**A**: 这表示系统无法获取该天体的轨道周期。解决方法：

1. **方法一**（推荐）：编辑天体，在"轨道参数"中手动填写轨道周期
2. **方法二**：联系管理员在代码的 `ORBITAL_PERIODS` 字典中添加该天体的周期

---

### Q4: 如何修改已生成的轨道颜色？

**A**:
1. 编辑天体，修改 `extra_data.orbit_color` 字段
2. 重新点击"生成轨道"按钮
3. 系统会覆盖旧轨道数据

---

### Q5: 轨道数据需要多久更新一次？

**A**:
- **行星**: 轨道相对稳定，建议每年更新一次
- **矮行星**: 建议每5年更新一次
- **特殊情况**: 如果发现轨道显示不准确，可随时重新生成

---

### Q6: 生成轨道时提示"NASA API超时"怎么办？

**A**:
1. 检查网络连接
2. 稍后重试（NASA API可能繁忙）
3. 如果持续失败，联系管理员检查代理配置

---

## 数据优先级说明

轨道参数的读取优先级：

```
1. extra_data.orbit_period_days (用户填写的轨道周期)
   ↓ 如果没有
2. ORBITAL_PERIODS字典 (代码中硬编码的周期)
   ↓ 如果没有
3. 跳过该天体，不生成轨道
```

颜色优先级：

```
1. extra_data.orbit_color (用户选择的颜色)
   ↓ 如果没有
2. DEFAULT_COLORS字典 (代码中硬编码的颜色)
   ↓ 如果没有
3. 使用默认灰色 #CCCCCC
```

---

## 示例：新增一个矮行星并生成轨道

### 场景：新增塞德娜（Sedna）

1. **基本信息**：
   - JPL Horizons ID: `90377` (Sedna的JPL ID)
   - 英文名: `Sedna`
   - 中文名: `塞德娜`
   - 类型: `矮行星`
   - 所属系统: `太阳系`
   - 描述: `极远距离的外海王星天体`

2. **轨道参数**：
   - 轨道周期：`4155150天` (约11,400年)
   - 轨道颜色：`#B8860B` (深金色)

3. **保存后生成**：
   - 点击"生成轨道"
   - 等待20-30秒
   - 成功后前端会显示塞德娜的椭圆轨道

---

## 最佳实践

### ✅ 推荐做法

1. **使用标准周期数据**: 从维基百科或NASA查询准确的轨道周期
2. **颜色统一规范**: 使用天文学上约定俗成的颜色（例如地球用蓝色）
3. **批量生成**: 对于太阳系已知天体，使用批量生成功能更高效

### ❌ 避免的做法

1. **随意填写周期**: 不准确的周期会导致轨道显示错误
2. **频繁重复生成**: 轨道生成消耗NASA API配额，避免无意义的重复
3. **不填轨道参数**: 忘记填写参数会导致无法生成轨道

---

## 未来改进方向

- [ ] 支持卫星轨道生成
- [ ] 支持彗星椭圆轨道
- [ ] 自动从NASA API获取轨道周期
- [ ] 异步后台生成，不阻塞用户操作
- [ ] 轨道预览功能

---

## 相关文档

- [天体轨道生成系统技术文档](./ORBIT_GENERATION_SYSTEM.md)
- [NASA JPL Horizons API文档](https://ssd.jpl.nasa.gov/horizons/)

---

**文档作者**: Claude Code AI
**反馈渠道**: 项目Issues