Initial import

docs/Architecture.md

@@ -0,0 +1,513 @@
+# NavSea Weather Server V1 设计文档
+Architecture: NavSea V11
+Codex: codex6
+Component: Weather Server
+Version: Draft v1
+
+---
+
+# 1 设计目标
+
+NavSea Weather Server 负责：
+
+1 下载气象 GRIB 数据
+2 解析 GRIB 数据
+3 生成天气网格数据
+4 生成 Vector Tile (PBF)
+5 通过 HTTP 提供 tile 服务
+
+系统原则：
+
+- 客户端不解析 GRIB
+- 所有计算在服务器完成
+- 客户端只加载 Vector Tile
+- 数据结构稳定可扩展
+- 支持未来 routing 算法
+
+技术栈：
+
+Python + Nginx
+
+---
+
+# 2 系统总体架构
+
+系统分为两个主要组件：
+
+Weather Processing System
+Tile HTTP Server
+
+架构：
+
+GRIB Source
+      │
+      ▼
+Downloader
+      │
+      ▼
+GRIB Parser
+      │
+      ▼
+Grid Builder
+      │
+      ▼
+Tile Generator
+      │
+      ▼
+Tile Storage
+      │
+      ▼
+Nginx HTTP Service
+      │
+      ▼
+NavSea Client
+
+---
+
+# 3 技术栈
+
+Python版本：
+
+Python 3.11+
+
+Python库：
+
+cfgrib
+xarray
+numpy
+mercantile
+mapbox-vector-tile
+shapely
+
+Web服务器：
+
+Nginx
+
+任务调度：
+
+cron
+
+---
+
+# 4 项目目录结构
+
+weather_server/
+
+    config/
+        config.py
+
+    downloader/
+        gfs_downloader.py
+
+    grib/
+        grib_parser.py
+
+    grid/
+        grid_builder.py
+
+    tiles/
+        tile_generator.py
+
+    pipeline/
+        pipeline.py
+
+    utils/
+        geo_utils.py
+
+    data/
+        grib/
+        grid/
+
+    output/
+        weather_tiles/
+
+---
+
+# 5 数据目录
+
+GRIB 下载目录：
+
+data/grib/
+
+示例：
+
+gfs_20260312_00.grib
+
+Grid 中间数据：
+
+data/grid/
+
+示例：
+
+grid_20260312_00.json
+
+Vector Tile 输出：
+
+output/weather_tiles/
+
+结构：
+
+/weather_tiles/{time}/{z}/{x}/{y}.pbf
+
+示例：
+
+weather_tiles/20260312_12/4/10/7.pbf
+
+---
+
+# 6 GRIB 下载模块
+
+模块：
+
+downloader/gfs_downloader.py
+
+职责：
+
+从 NOAA GFS 下载 GRIB 文件。
+
+下载参数：
+
+分辨率：
+
+0.25°
+
+区域：
+
+120E – 150E
+20N – 50N
+
+预测时间：
+
+0h
+3h
+6h
+9h
+12h
+24h
+48h
+72h
+
+输出：
+
+data/grib/
+
+---
+
+# 7 GRIB 解析模块
+
+模块：
+
+grib/grib_parser.py
+
+职责：
+
+解析 GRIB 数据。
+
+读取字段：
+
+UGRD
+VGRD
+HTSGW
+DIRPW
+PERPW
+APCP
+TMP
+PRMSL
+
+输出：
+
+grid 数据结构。
+
+示例：
+
+{
+ "lat": 34.5,
+ "lon": 138.2,
+ "wind_u": -3.2,
+ "wind_v": 4.1,
+ "wave_h": 2.4,
+ "wave_dir": 210,
+ "wave_period": 9,
+ "rain": 0.2,
+ "temp": 21,
+ "pressure": 1012
+}
+
+---
+
+# 8 Grid Builder
+
+模块：
+
+grid/grid_builder.py
+
+职责：
+
+构建统一天气网格。
+
+网格间距：
+
+0.25°
+
+grid 示例：
+
+120 × 120
+
+输出：
+
+data/grid/
+
+格式：
+
+JSON
+
+示例：
+
+grid_20260312_12.json
+
+---
+
+# 9 Tile Generator
+
+模块：
+
+tiles/tile_generator.py
+
+职责：
+
+生成 MapLibre Vector Tile。
+
+Tile Layer：
+
+weather
+ ├ wind
+ ├ wave
+ ├ rain
+ ├ sst
+ └ pressure
+
+---
+
+# 10 Wind Layer
+
+Geometry：
+
+Point
+
+属性：
+
+speed
+dir
+
+speed 由 U/V 分量计算：
+
+speed = sqrt(u² + v²)
+
+dir = atan2(u,v)
+
+---
+
+# 11 Wave Layer
+
+Geometry：
+
+Point
+
+属性：
+
+h
+dir
+p
+
+h  浪高
+dir 浪方向
+p  浪周期
+
+---
+
+# 12 Rain Layer
+
+Geometry：
+
+Point
+
+属性：
+
+rain
+
+单位：
+
+mm
+
+---
+
+# 13 SST Layer
+
+Geometry：
+
+Point
+
+属性：
+
+temp
+
+单位：
+
+摄氏度
+
+---
+
+# 14 Pressure Layer
+
+Geometry：
+
+Point
+
+属性：
+
+pressure
+
+单位：
+
+hPa
+
+---
+
+# 15 Tile 坐标系统
+
+使用：
+
+WebMercator
+
+tile库：
+
+mercantile
+
+Zoom级别：
+
+2
+4
+6
+8
+
+---
+
+# 16 Tile URL 结构
+
+Nginx 提供：
+
+/weather/{time}/{z}/{x}/{y}.pbf
+
+示例：
+
+/weather/20260312_12/4/10/7.pbf
+
+---
+
+# 17 Tile 生成流程
+
+tile_generator 处理流程：
+
+加载 grid
+↓
+计算 tile bounds
+↓
+筛选 grid 点
+↓
+生成 feature
+↓
+编码 vector tile
+↓
+写入 pbf
+
+---
+
+# 18 Pipeline
+
+模块：
+
+pipeline/pipeline.py
+
+流程：
+
+download_grib
+↓
+parse_grib
+↓
+build_grid
+↓
+generate_tiles
+
+执行一次生成全部天气 tile。
+
+---
+
+# 19 定时任务
+
+CRON：
+
+每6小时执行：
+
+pipeline.py
+
+示例：
+
+30 0 * * * python pipeline.py
+30 6 * * * python pipeline.py
+30 12 * * * python pipeline.py
+30 18 * * * python pipeline.py
+
+---
+
+# 20 Nginx 配置
+
+Nginx 直接提供 tile：
+
+location /weather/ {
+    root /weather_server/output/weather_tiles;
+}
+
+---
+
+# 21 数据量估算
+
+日本区域：
+
+grid ≈ 120 × 120
+
+points ≈ 14400
+
+tile后：
+
+≈ 2MB / 时间
+
+72小时：
+
+≈ 70MB
+
+---
+
+# 22 系统扩展
+
+未来可增加：
+
+海流 Current
+台风 Typhoon
+等压线
+等温线
+风流动画
+航线天气预测
+
+---
+
+# 23 下一开发阶段
+
+下一阶段任务：
+
+1 环境安装
+2 GRIB 下载模块
+3 GRIB 解析模块
+4 Grid Builder
+5 Tile Generator
+6 Pipeline
+7 Nginx 部署