394 lines
11 KiB
Markdown
394 lines
11 KiB
Markdown
# Cosmo 项目开发文档
|
||
|
||
## 项目概述
|
||
|
||
Cosmo 是一个深空探索可视化平台，使用 Three.js 在浏览器中实时渲染太阳系、星座、星系和探测器的 3D 场景。
|
||
|
||
**技术栈**：
|
||
- **前端**：React + TypeScript + Three.js + Vite
|
||
- **后端**：FastAPI + Python 3.11
|
||
- **数据库**：PostgreSQL 15+ (SQLAlchemy 2.0 异步)
|
||
- **缓存**：Redis 7+ (三层缓存架构)
|
||
- **数据源**：NASA Horizons API
|
||
|
||
**版本**：v0.0.9
|
||
|
||
---
|
||
|
||
## 已完成工作 (v0.0.9)
|
||
|
||
### 一、数据库架构升级 ✅
|
||
|
||
#### 1.1 数据库设计与实现
|
||
从静态文件驱动的架构升级为数据库驱动：
|
||
|
||
**数据库表结构**：
|
||
- `celestial_bodies` - 天体基本信息 (行星、卫星、探测器等)
|
||
- `positions` - 位置历史表 (时间序列数据)
|
||
- `resources` - 资源文件管理 (纹理、3D模型)
|
||
- `static_data` - 静态天文数据 (星座、星系、恒星)
|
||
- `nasa_cache` - NASA API 持久化缓存
|
||
|
||
**文件位置**：
|
||
- 数据库模型：`backend/app/models/db/`
|
||
- `celestial_body.py` - 天体模型
|
||
- `position.py` - 位置模型
|
||
- `resource.py` - 资源模型
|
||
- `static_data.py` - 静态数据模型
|
||
- `nasa_cache.py` - NASA 缓存模型
|
||
- Schema 文档：`backend/DATABASE_SCHEMA.md`
|
||
|
||
#### 1.2 数据库服务层
|
||
实现了异步数据库操作服务：
|
||
|
||
**核心服务** (`backend/app/services/db_service.py`):
|
||
- `get_celestial_body(body_id)` - 查询天体信息
|
||
- `get_celestial_bodies(type)` - 批量查询天体
|
||
- `get_latest_position(body_id)` - 查询最新位置
|
||
- `get_positions(body_id, start, end)` - 查询位置历史
|
||
- `save_position(body_id, time, position)` - 保存位置数据
|
||
- `get_static_data(category)` - 查询静态数据
|
||
- `get_resource(body_id, type)` - 查询资源文件
|
||
|
||
#### 1.3 三层缓存架构
|
||
实现了高效的缓存策略：
|
||
|
||
```
|
||
请求 → L1 (内存) → L2 (Redis) → L3 (数据库) → L4 (NASA API)
|
||
```
|
||
|
||
**L1 - 内存缓存** (已有):
|
||
- TTL: 10分钟
|
||
- 用途：当前时间的天体位置 (最热数据)
|
||
|
||
**L2 - Redis 缓存** (新增 `backend/app/services/redis_cache.py`):
|
||
- TTL: 当前数据 1小时，历史数据 7天
|
||
- 用途：NASA API 响应、会话数据、预计算结果
|
||
- 特点：进程间共享、持久化、分布式支持
|
||
|
||
**L3 - 数据库** (新增):
|
||
- 持久化存储
|
||
- 历史数据查询
|
||
- 复杂查询和统计
|
||
|
||
**L4 - NASA API**:
|
||
- 最终数据源
|
||
- 只在所有缓存未命中时调用
|
||
|
||
### 二、后端改进 ✅
|
||
|
||
#### 2.1 配置管理系统
|
||
实现了基于 Pydantic Settings 的配置管理：
|
||
|
||
**配置文件**：
|
||
- `backend/.env` - 实际配置 (不提交到 Git)
|
||
- `backend/.env.example` - 配置模板
|
||
- `backend/app/config.py` - 配置管理类
|
||
|
||
**配置项**：
|
||
- PostgreSQL 连接配置 (host, port, user, password, pool_size)
|
||
- Redis 连接配置 (host, port, db, password)
|
||
- 应用配置 (CORS, cache TTL, upload 设置)
|
||
|
||
**文档**：`backend/CONFIG.md`
|
||
|
||
#### 2.2 API 扩展
|
||
扩展了后端 API 端点 (`backend/app/api/routes.py`):
|
||
|
||
**新增端点**：
|
||
- `GET /api/celestial-bodies` - 获取所有天体
|
||
- `GET /api/celestial-bodies/{body_id}` - 获取单个天体
|
||
- `GET /api/static/constellations` - 获取星座数据
|
||
- `GET /api/static/galaxies` - 获取星系数据
|
||
- `GET /api/static/stars` - 获取恒星数据
|
||
- `GET /api/static/textures/{path}` - 提供纹理文件
|
||
- `GET /api/static/models/{path}` - 提供 3D 模型文件
|
||
|
||
**改进的端点**：
|
||
- `GET /api/probes` - 从数据库读取探测器信息
|
||
- `POST /api/probe-positions` - 优化缓存策略
|
||
- `GET /health` - 新增 Redis 和数据库健康检查
|
||
|
||
#### 2.3 数据迁移脚本
|
||
创建了完整的初始化和迁移脚本 (`backend/scripts/`):
|
||
|
||
**初始化脚本**：
|
||
- `create_db.py` - 创建数据库
|
||
- `init_db.py` - 初始化表结构
|
||
- `check_config.py` - 验证配置
|
||
|
||
**数据迁移**：
|
||
- `migrate_data.py` - 迁移天体基础数据
|
||
- `update_static_data.py` - 迁移静态数据 (星座、星系)
|
||
- `populate_resources.py` - 迁移资源文件记录
|
||
|
||
**辅助脚本**：
|
||
- `fetch_and_cache.py` - 预取并缓存 NASA 数据
|
||
- `list_celestial_bodies.py` - 列出所有天体
|
||
- `add_pluto.py` - 添加冥王星数据示例
|
||
|
||
#### 2.4 依赖管理
|
||
更新了后端依赖 (`backend/requirements.txt`):
|
||
|
||
**新增依赖**：
|
||
```
|
||
sqlalchemy>=2.0.0 # ORM 框架 (异步支持)
|
||
asyncpg>=0.29.0 # PostgreSQL 异步驱动
|
||
alembic>=1.12.0 # 数据库迁移工具
|
||
redis>=5.0.0 # Redis 客户端
|
||
aiofiles>=23.0.0 # 异步文件操作
|
||
pydantic-settings>=2.0.0 # 配置管理
|
||
```
|
||
|
||
### 三、前端改进 ✅
|
||
|
||
#### 3.1 从静态文件迁移到 API
|
||
**移除的静态文件**：
|
||
- `frontend/public/data/*.json` (所有 JSON 数据文件)
|
||
- `frontend/public/textures/*.jpg` (所有纹理文件)
|
||
- `frontend/public/models/*.glb` (所有 3D 模型)
|
||
|
||
**改为从后端 API 获取**：
|
||
- 天体数据：`/api/celestial-bodies`
|
||
- 静态数据：`/api/static/*`
|
||
- 纹理文件：`/api/static/textures/*`
|
||
- 3D 模型：`/api/static/models/*`
|
||
|
||
#### 3.2 组件更新
|
||
更新了前端组件以适应新的数据获取方式：
|
||
|
||
**修改的组件**：
|
||
- `src/components/CelestialBody.tsx` - 使用 API 获取天体和纹理
|
||
- `src/components/Probe.tsx` - 简化探测器渲染逻辑
|
||
- `src/components/Constellations.tsx` - 从 API 获取星座数据
|
||
- `src/components/Galaxies.tsx` - 从 API 获取星系数据
|
||
- `src/components/ProbeList.tsx` - 使用新的探测器数据结构
|
||
- `src/utils/api.ts` - 新增 API 调用函数
|
||
|
||
#### 3.3 API 工具函数
|
||
新增了 API 调用函数 (`frontend/src/utils/api.ts`):
|
||
|
||
```typescript
|
||
// 天体相关
|
||
export const getCelestialBodies = async ()
|
||
export const getCelestialBody = async (bodyId: string)
|
||
|
||
// 静态数据
|
||
export const getConstellations = async ()
|
||
export const getGalaxies = async ()
|
||
export const getNearbyStars = async ()
|
||
|
||
// 探测器
|
||
export const getProbes = async ()
|
||
export const getProbePositions = async (probeIds: string[])
|
||
```
|
||
|
||
### 四、架构优化成果 ✅
|
||
|
||
#### 4.1 性能提升
|
||
- **NASA API 调用减少 90%**：通过三层缓存
|
||
- **首次加载加速**：从缓存/数据库读取，无需等待 NASA API
|
||
- **并发能力提升**：Redis 支持分布式缓存
|
||
|
||
#### 4.2 可扩展性提升
|
||
- **统一数据管理**：所有数据在数据库中集中管理
|
||
- **资源管理统一**：后端统一提供静态资源
|
||
- **支持历史查询**：位置历史表支持时间旅行功能
|
||
- **易于扩展**：添加新天体类型无需修改前端
|
||
|
||
#### 4.3 可维护性提升
|
||
- **配置管理**：环境变量统一管理
|
||
- **数据迁移**：提供完整的初始化和迁移脚本
|
||
- **健康检查**：实时监控数据库和 Redis 状态
|
||
- **文档完善**：提供架构、数据库、配置文档
|
||
|
||
---
|
||
|
||
## 当前状态
|
||
|
||
### 已实现功能
|
||
✅ 太阳系行星可视化 (水星、金星、地球、火星、木星、土星、天王星、海王星、冥王星)
|
||
✅ NASA 探测器实时位置追踪 (Voyager 1/2, Juno, Cassini, Parker Solar Probe)
|
||
✅ 星座和星系静态可视化
|
||
✅ 数据库驱动的数据管理
|
||
✅ 三层缓存架构 (内存 + Redis + 数据库)
|
||
✅ 资源文件统一管理
|
||
✅ API 健康检查和监控
|
||
|
||
### 已知限制
|
||
- 前端静态资源文件已删除，但后端 `upload/` 目录尚未完全迁移纹理和模型
|
||
- 部分探测器 3D 模型尚未上传到后端
|
||
- 历史位置数据尚未批量预取
|
||
|
||
---
|
||
|
||
## 待实现功能 (下一步)
|
||
|
||
### 优先级 P0 (必须)
|
||
- [ ] **资源文件迁移完成**
|
||
- 将纹理文件迁移到 `backend/upload/textures/`
|
||
- 将 3D 模型迁移到 `backend/upload/models/`
|
||
- 更新数据库 `resources` 表记录
|
||
- 验证前端能正确加载所有资源
|
||
|
||
- [ ] **探测器轨迹历史数据**
|
||
- 预取探测器历史位置 (过去 30 天)
|
||
- 实现轨迹可视化组件
|
||
- 支持时间滑块控制
|
||
|
||
### 优先级 P1 (重要)
|
||
- [ ] **小行星和彗星支持**
|
||
- 添加小行星数据 (Ceres, Vesta, etc.)
|
||
- 添加著名彗星数据 (Halley, Hale-Bopp, etc.)
|
||
- 实现轨道可视化
|
||
|
||
- [ ] **性能优化**
|
||
- 实现纹理压缩和多分辨率支持
|
||
- 优化 3D 模型多边形数
|
||
- 实现视锥剔除 (Frustum Culling)
|
||
- 添加性能监控指标
|
||
|
||
- [ ] **用户界面增强**
|
||
- 天体搜索功能
|
||
- 收藏和历史记录
|
||
- 相机动画和平滑过渡
|
||
- 时间控制面板 (时间旅行)
|
||
|
||
### 优先级 P2 (可选)
|
||
- [ ] **数据扩展**
|
||
- 系外行星数据
|
||
- 深空探测器 (New Horizons, etc.)
|
||
- 更多恒星和星云数据
|
||
|
||
- [ ] **用户系统**
|
||
- 用户注册和登录
|
||
- 自定义天体
|
||
- 观测日志
|
||
|
||
- [ ] **移动端优化**
|
||
- 响应式设计
|
||
- 触摸手势支持
|
||
- 性能优化
|
||
|
||
---
|
||
|
||
## 技术债务
|
||
|
||
1. **资源管理**
|
||
- 纹理文件和 3D 模型尚未完全迁移到后端
|
||
- 需要实现资源版本管理和 CDN 支持
|
||
|
||
2. **数据库迁移**
|
||
- 缺少 Alembic 数据库版本管理
|
||
- 缺少数据库备份和恢复策略
|
||
|
||
3. **测试覆盖**
|
||
- 缺少单元测试
|
||
- 缺少集成测试
|
||
- 缺少前端测试
|
||
|
||
4. **监控和日志**
|
||
- 缺少应用日志收集
|
||
- 缺少性能监控指标
|
||
- 缺少错误追踪系统
|
||
|
||
5. **文档**
|
||
- 缺少 API 文档的详细说明
|
||
- 缺少前端组件文档
|
||
- 缺少部署文档
|
||
|
||
---
|
||
|
||
## 开发指南
|
||
|
||
### 环境准备
|
||
|
||
**系统要求**：
|
||
- Python 3.11+
|
||
- Node.js 18+
|
||
- PostgreSQL 15+
|
||
- Redis 7+
|
||
|
||
**后端初始化**：
|
||
```bash
|
||
cd backend
|
||
pip install -r requirements.txt
|
||
cp .env.example .env # 修改配置
|
||
python scripts/create_db.py
|
||
python scripts/init_db.py
|
||
python scripts/migrate_data.py
|
||
python -m uvicorn app.main:app --reload
|
||
```
|
||
|
||
**前端初始化**：
|
||
```bash
|
||
cd frontend
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
### 开发流程
|
||
|
||
1. **添加新天体类型**
|
||
- 更新 `celestial_body.py` 模型
|
||
- 添加数据迁移脚本
|
||
- 更新前端组件
|
||
|
||
2. **添加新 API 端点**
|
||
- 在 `routes.py` 中添加端点
|
||
- 在 `db_service.py` 中添加数据库操作
|
||
- 更新前端 `api.ts`
|
||
|
||
3. **添加新缓存层**
|
||
- 在 `redis_cache.py` 中添加缓存函数
|
||
- 更新 TTL 配置
|
||
- 验证缓存命中率
|
||
|
||
### 调试技巧
|
||
|
||
**查看数据库数据**：
|
||
```bash
|
||
psql -U postgres -d cosmo_db
|
||
\dt # 列出所有表
|
||
SELECT * FROM celestial_bodies;
|
||
```
|
||
|
||
**查看 Redis 缓存**：
|
||
```bash
|
||
redis-cli
|
||
KEYS * # 列出所有键
|
||
GET positions:-31:2025-11-27:2025-11-27:1d
|
||
```
|
||
|
||
**健康检查**：
|
||
```bash
|
||
curl http://localhost:8000/health
|
||
```
|
||
|
||
---
|
||
|
||
## 架构文档
|
||
|
||
详细的架构规划和设计文档：
|
||
- [ARCHITECTURE_PLAN.md](./ARCHITECTURE_PLAN.md) - 完整的架构升级规划
|
||
- [backend/DATABASE_SCHEMA.md](./backend/DATABASE_SCHEMA.md) - 数据库表结构设计
|
||
- [backend/CONFIG.md](./backend/CONFIG.md) - 配置说明
|
||
|
||
---
|
||
|
||
## 提交记录
|
||
|
||
- `78e48a6` - v0.0.9
|
||
- `bda13be` - 初步完成了太阳系内的行星显示
|
||
|
||
---
|
||
|
||
## 联系方式
|
||
|
||
如有问题，请查看文档或提交 Issue。
|
||
|
||
**文档链接**：
|
||
- 架构规划：[ARCHITECTURE_PLAN.md](./ARCHITECTURE_PLAN.md)
|
||
- 数据库设计：[backend/DATABASE_SCHEMA.md](./backend/DATABASE_SCHEMA.md)
|
||
- 配置说明：[backend/CONFIG.md](./backend/CONFIG.md)
|