# SUMMIT - 全球 14 座 8000 米级雪山 3D 可视化平台

## 1. 项目概述 (Project Overview)
本项目旨在构建一个**完全免费、零商业依赖、高性能**的 Web 3D 地球可视化平台，专注于展示全球 14 座 8000 米级雪山。
项目采用 **"硬核极客"** 路线，核心理念是 **Data Autonomy (数据自主)**：直接从 NASA 获取原始地形数据，自行构建数据生产流水线，结合 **PostgreSQL + Redis** 多级缓存架构，提供极致的性能体验。前端使用开源的 **MapLibre GL JS** 结合 **Three.js** 进行高保真渲染。

---

## 2. 系统架构 (System Architecture)

系统采用经典的前后端分离架构，辅以离线数据处理流水线。

### 2.1 顶层设计
*   **Frontend (Web):** SPA 单页应用，负责 3D 地图交互、渲染与漫游控制。通过 **Proxy (代理)** 访问后端 API 和静态资源。
*   **Backend (API):** 提供 RESTful API，负责元数据查询、路线数据分发、用户系统等。同时作为一个静态文件服务器，托管地形瓦片。
*   **Data Pipeline (Offline):** 负责将 NASA 原始数据 (GeoTIFF) 处理为 Web 可用的地形瓦片 (Terrain-RGB)。
*   **Database & Cache:** PostgreSQL 存储核心结构化数据，Redis 提供热点数据高速缓存。

---

## 3. 技术栈 (Tech Stack)

### 3.1 前端 (Frontend)
*   **Framework:** React 18 + TypeScript + Vite
*   **Map Engine:** **MapLibre GL JS** (Mapbox 开源分支，负责地图瓦片调度与底图渲染)
*   **3D Engine:** **Three.js** (负责渲染攀登路线、营地、光效、粒子系统)
*   **UI Library:** TailwindCSS + Lucide Icons
*   **State Management:** Zustand / React Context

### 3.2 后端 (Backend)
*   **Framework:** Python 3.11+ (FastAPI)
*   **Server:** Uvicorn (ASGI)
*   **ORM:** SQLAlchemy (Async) / Tortoise ORM
*   **Geo Processing:** GDAL / Rasterio (用于后端动态分析地形)

### 3.3 数据存储与缓存 (Storage & Caching)
*   **Primary DB:** **PostgreSQL 15+** (with **PostGIS** extension)
    *   存储山峰元数据、GeoJSON 路线、用户数据。
*   **Cache:** **Redis 7+**
    *   Layer 1: API 响应缓存 (Response Cache)。
    *   Layer 2: 高频地理空间查询缓存 (Spatial Cache)。
    *   Layer 3: 瓦片元数据缓存 (如果自建瓦片服务)。

### 3.4 数据流水线 (Data Pipeline)
*   **Source:** NASA SRTM (30m DEM), Esri World Imagery.
*   **Tools:** GDAL (`gdal_translate`, `gdalwarp`), `rio-rgbify`, `gdal2tiles`.
*   **Output:** Mapbox Terrain-RGB compatible tiles (`.png` / `.webp`)，输出至 `backend/upload`。

---

## 4. 核心功能模块 (Core Modules)

### 4.1 数据生产流水线 (The Pipeline)
自动化脚本集，负责从 NASA 下载数据并处理。
1.  **Ingest:** 下载 SRTM GeoTIFF。
2.  **Process:** 重投影 (EPSG:4326 -> EPSG:3857) -> 拼接 (Merge) -> 编码 (RGBify)。
3.  **Tile:** 切片生成 Z10-Z14 瓦片金字塔。
4.  **Export:** 将产物存入 `backend/upload/tiles`。

### 4.2 3D 可视化引擎 (Visualization Engine)
*   **地形渲染:** 加载自定义 Terrain-RGB 瓦片，实现真实地形起伏。
*   **混合渲染:** MapLibre 负责底图与地形，Three.js 自定义图层负责覆盖物 (Routes, Camps)。
*   **光照模拟:** 基于太阳位置算法 (SunCalc) 的实时光照与阴影。

### 4.3 后端服务与缓存 (Backend & Cache)
*   **Peaks API:** 提供 14 座山峰的详细信息 (高度、位置、首登记录)。
    *   *Cache Strategy:* 永久缓存 (除非数据更正)，Redis Key: `peak:{id}:info`.
*   **Routes API:** 提供 GPX/GeoJSON 格式的攀登路线。
    *   *Cache Strategy:* LRU 缓存，Redis Key: `route:{id}:geojson`.
*   **Elevation API:** (可选) 后端直接查询 GeoTIFF 返回特定坐标高度。

---

## 5. 项目目录结构 (Directory Structure)

```text
summit/
├── .github/                # CI/CD workflows
├── backend/                # FastAPI Application
│   ├── app/
│   │   ├── api/            # Routes
│   │   ├── core/           # Config, Database connection
│   │   ├── models/         # SQLAlchemy Models
│   │   └── services/       # Business Logic
│   ├── upload/             # [NEW] Static Resources Root
│   │   ├── tiles/          # Generated Terrain-RGB Tiles ({z}/{x}/{y}.png)
│   │   └── shapes/         # Route GeoJSONs / GPX files
│   └── tests/
├── data/                   # Data Processing Workspace (Offline)
│   ├── raw/                # NASA GeoTIFFs (Source)
│   └── scripts/            # Python/Shell processing scripts (GDAL)
├── frontend/               # React Application
│   ├── src/
│   │   ├── components/     # UI Components
│   │   ├── map/            # MapLibre & Three.js logic
│   │   └── store/          # State Management
│   ├── public/             # Static Assets (Favicon, etc.)
│   └── vite.config.ts      # Proxy Configuration
├── CONFIG.md               # [NEW] Configuration Guide (Env, DB, Redis)
├── DATABASE.md             # Database Design
├── PROJECT.md              # Project Documentation
└── ROADMAP.md              # Roadmap
```