weather/docs/Architecture.md

# 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 部署