Initial import
This commit is contained in:
OpenAI Codex
513
docs/Architecture.md
Normal file
513
docs/Architecture.md
Normal file
@@ -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 部署
|
||||
127
docs/GeoMaskFoundation.md
Normal file
127
docs/GeoMaskFoundation.md
Normal file
@@ -0,0 +1,127 @@
|
||||
# NavSea Geo Mask Foundation
|
||||
|
||||
Version: codex6
|
||||
Architecture: NavSea V11
|
||||
Domain: geo-mask
|
||||
Status: implemented-v1
|
||||
|
||||
## 1. Selection Conclusion
|
||||
|
||||
NavSea `land/sea mask` foundation v1 uses `Natural Earth 10m land` as the default source asset.
|
||||
|
||||
Selection result:
|
||||
|
||||
- Primary source: `Natural Earth 10m land`
|
||||
- Backup direction: `GSHHG`
|
||||
- Local refinement direction: `GSI coastline / local land assets`
|
||||
|
||||
Why this was chosen for v1:
|
||||
|
||||
- Good enough coastline detail for Japan and nearby waters
|
||||
- Stable global coverage
|
||||
- Easy to automate in a server-side pipeline
|
||||
- Lightweight preprocessing path without adding new geo stack dependencies
|
||||
- Independent from weather products and reusable by multiple display lines
|
||||
|
||||
## 2. Source Comparison
|
||||
|
||||
### Natural Earth 10m land
|
||||
|
||||
- Japan coastal suitability: good for v1 display masking
|
||||
- Coastline detail: medium-high
|
||||
- Island detail: good, but not the highest fidelity
|
||||
- Licensing: permissive and easy to operationalize
|
||||
- Coverage: global
|
||||
- Update cadence: moderate
|
||||
- Preprocess complexity: low
|
||||
- Integration difficulty: low
|
||||
|
||||
### GSHHG
|
||||
|
||||
- Japan coastal suitability: very strong
|
||||
- Coastline detail: higher than Natural Earth in many coastal areas
|
||||
- Island detail: stronger
|
||||
- Licensing / operational complexity: acceptable but heavier than Natural Earth for this repo
|
||||
- Coverage: global
|
||||
- Preprocess complexity: medium
|
||||
- Integration difficulty: medium
|
||||
|
||||
### GSI local assets
|
||||
|
||||
- Japan coastal suitability: strongest for Japan-specific refinement
|
||||
- Coastline detail: potentially best
|
||||
- Coverage: Japan-focused
|
||||
- Operational complexity: medium-high because it should be layered as a refinement source, not as the only source
|
||||
- Integration difficulty: medium-high
|
||||
|
||||
## 3. V1 Asset Model
|
||||
|
||||
V1 outputs a reusable raster mask tile asset:
|
||||
|
||||
```text
|
||||
/geo-mask/land-sea/{z}/{x}/{y}.png
|
||||
```
|
||||
|
||||
Semantics:
|
||||
|
||||
- `sea`: pixel alpha `0`
|
||||
- `land`: pixel alpha `255`
|
||||
- `coastTransition`: reserved for v2, not yet emitted
|
||||
|
||||
PNG interpretation:
|
||||
|
||||
- RGB is white for land pixels
|
||||
- Alpha carries the effective mask
|
||||
|
||||
## 4. Metadata Model
|
||||
|
||||
V1 metadata fields:
|
||||
|
||||
- `maskId`
|
||||
- `version`
|
||||
- `source`
|
||||
- `classes`
|
||||
- `encoding`
|
||||
- `coverage`
|
||||
- `supportedZoom`
|
||||
- `coastTransition`
|
||||
- `noDataMode`
|
||||
- `displayPolicies`
|
||||
|
||||
## 5. Display Integration Boundary
|
||||
|
||||
The geo mask layer is product-independent and only answers geography semantics.
|
||||
|
||||
Recommended display product policy binding:
|
||||
|
||||
- `wind`: sea normal, land attenuate
|
||||
- `wave`: sea normal, land mask
|
||||
- `current`: sea normal, land mask
|
||||
- `pressure`: sea normal, land normal
|
||||
|
||||
These policies are separate from the mask asset itself.
|
||||
|
||||
## 6. Directory Layout
|
||||
|
||||
Source asset:
|
||||
|
||||
```text
|
||||
data/geo_mask/source/ne_10m_land.geojson
|
||||
```
|
||||
|
||||
Generated output:
|
||||
|
||||
```text
|
||||
/home/wwwroot/weather/geo-mask/land-sea/{z}/{x}/{y}.png
|
||||
/home/wwwroot/weather/geo-mask/metadata/land-sea.json
|
||||
/home/wwwroot/weather/geo-mask/policies/display-product-policies.json
|
||||
```
|
||||
|
||||
## 7. V2 Extension Path
|
||||
|
||||
Planned next steps:
|
||||
|
||||
- add `coastTransition` band
|
||||
- blend-friendly shoreline attenuation
|
||||
- multi-zoom simplification strategy
|
||||
- Japan hotspot refinement using higher-resolution local coast assets
|
||||
643
docs/V1.NavSea Weather Product System Build File
Normal file
643
docs/V1.NavSea Weather Product System Build File
Normal file
@@ -0,0 +1,643 @@
|
||||
# 文件 1：NavSea Weather Product System Build File
|
||||
Version: codex6
|
||||
Architecture: NavSea V11
|
||||
Domain: weather-system
|
||||
Status: active-foundation
|
||||
|
||||
---
|
||||
|
||||
## 1. 系统名称
|
||||
|
||||
`NavSea 天气产品系统`
|
||||
|
||||
该系统用于定义 NavSea 天气能力的长期基础架构。
|
||||
|
||||
它明确把天气体系拆分为三条**不同的生成线**：
|
||||
|
||||
1. `Display Product`
|
||||
2. `Analysis Product`
|
||||
3. `Offline Package`
|
||||
|
||||
这三条线不是同一份数据的不同展示形式，而是三类**目标不同、消费者不同、约束不同、实现方式不同**的产品线。
|
||||
|
||||
本文件是系统级构建文件，用于统一：
|
||||
|
||||
- 架构边界
|
||||
- 服务端职责
|
||||
- 前端职责
|
||||
- 数据生成方向
|
||||
- 后续 codex 任务拆分依据
|
||||
|
||||
---
|
||||
|
||||
## 2. 系统目标
|
||||
|
||||
构建一个面向 NavSea 的天气产品体系，使其同时支持：
|
||||
|
||||
- 地图天气显示
|
||||
- 点击地图点位查询天气
|
||||
- 某点未来多小时天气展示
|
||||
- 航行匹配
|
||||
- 航线规划
|
||||
- 航线模拟
|
||||
- 离线天气使用
|
||||
- V11 架构下稳定扩展
|
||||
- 后续多天气变量统一纳管
|
||||
|
||||
该系统必须确保：
|
||||
|
||||
- 前端不负责天气颜色渲染
|
||||
- 前端不负责从稀疏点重建连续天气场
|
||||
- 显示产品与分析产品严格分离
|
||||
- 离线能力被显式设计，而不是依赖显示缓存“顺便可用”
|
||||
- 服务端成为天气产品定义与生成中心
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心原则
|
||||
|
||||
### 3.1 天气必须在服务端完成产品化
|
||||
NavSea 天气不能再被视为“前端拿到原始点数据后自行解释”。
|
||||
|
||||
服务端必须把天气组织成正式产品。
|
||||
|
||||
服务端负责：
|
||||
|
||||
- 插值
|
||||
- 规则场构建
|
||||
- 显示色带映射
|
||||
- 等值线 / 等值带生成
|
||||
- 多时间帧组织
|
||||
- no-data 规则
|
||||
- 产品元数据
|
||||
- 离线包打包规则
|
||||
|
||||
前端消费产品，而不是重建产品。
|
||||
|
||||
### 3.2 显示与分析不能混用
|
||||
“地图上能显示”不等于“可用于规划计算”。
|
||||
|
||||
显示产品优先满足：
|
||||
|
||||
- 稳定显示
|
||||
- 快速加载
|
||||
- 统一视觉
|
||||
- 图层叠加
|
||||
|
||||
分析产品优先满足：
|
||||
|
||||
- 数值准确
|
||||
- 可采样
|
||||
- 可沿航线计算
|
||||
- 可参与时间步进模拟
|
||||
|
||||
离线包优先满足：
|
||||
|
||||
- 可本地持续使用
|
||||
- 可在无网络环境下支持点查与规划
|
||||
- 可控下载体积
|
||||
- 可按区域和时间帧组织
|
||||
|
||||
### 3.3 Offline Package 是独立生成线，不是 Display/Analysis 的简单缓存
|
||||
离线包不是“把在线接口结果多存一份”。
|
||||
|
||||
离线包是面向无网络场景单独设计的数据产品，必须从一开始就作为独立生成线建设。
|
||||
|
||||
---
|
||||
|
||||
## 4. 三条生成线定义
|
||||
|
||||
---
|
||||
|
||||
## 4.1 Display Product
|
||||
|
||||
### 4.1.1 目标
|
||||
为前端地图提供**可直接显示**的天气产品。
|
||||
|
||||
### 4.1.2 消费方
|
||||
- 地图图层系统
|
||||
- 图层管理器
|
||||
- 图例面板
|
||||
- 时间帧切换器
|
||||
- 天气点查 UI 外壳
|
||||
|
||||
### 4.1.3 主要特征
|
||||
- 以显示为目标，不以精确数值复用为目标
|
||||
- 服务端已经完成颜色映射或几何表达
|
||||
- 前端直接叠图
|
||||
- 适合交互显示与稳定渲染
|
||||
- 不要求前端进行天气场重建
|
||||
|
||||
### 4.1.4 推荐产品类型
|
||||
- raster weather tiles
|
||||
- isoline vector tiles
|
||||
- isoband vector tiles
|
||||
- display metadata
|
||||
- legend metadata
|
||||
|
||||
### 4.1.5 典型接口方向
|
||||
```text
|
||||
/weather-display/raster/wind/{time}/{z}/{x}/{y}.png
|
||||
/weather-display/raster/wave/{time}/{z}/{x}/{y}.png
|
||||
/weather-display/vector/pressure-isoline/{time}/{z}/{x}/{y}.pbf
|
||||
/weather-display/vector/wind-isoband/{time}/{z}/{x}/{y}.pbf
|
||||
/weather-display/meta/{product}/{time}
|
||||
|
||||
|
||||
4.1.6 服务端职责
|
||||
|
||||
原始天气数据转连续场
|
||||
|
||||
生成色带图层
|
||||
|
||||
生成等值线 / 等值带
|
||||
|
||||
输出显示元数据
|
||||
|
||||
输出图例配置
|
||||
|
||||
输出 frame 列表和显示推荐参数
|
||||
|
||||
4.1.7 前端职责
|
||||
|
||||
加载 source / layer
|
||||
|
||||
时间帧切换
|
||||
|
||||
opacity / visibility 控制
|
||||
|
||||
图例展示
|
||||
|
||||
点击交互触发分析查询
|
||||
|
||||
不做色带映射
|
||||
|
||||
不做连续场重建
|
||||
|
||||
4.2 Analysis Product
|
||||
4.2.1 目标
|
||||
|
||||
为点查、航行匹配、航线规划、模拟提供可计算、可采样、可组合的天气数值产品。
|
||||
|
||||
4.2.2 消费方
|
||||
|
||||
地图点击查询
|
||||
|
||||
weather point panel
|
||||
|
||||
route weather matcher
|
||||
|
||||
route planner
|
||||
|
||||
simulation engine
|
||||
|
||||
ETA / cost model
|
||||
|
||||
未来的船型性能耦合模块
|
||||
|
||||
4.2.3 主要特征
|
||||
|
||||
数值优先
|
||||
|
||||
不带显示色带依赖
|
||||
|
||||
可做点位采样
|
||||
|
||||
可做时间序列采样
|
||||
|
||||
可做沿线采样
|
||||
|
||||
可服务于算法，而不是只服务于 UI
|
||||
|
||||
4.2.4 推荐产品类型
|
||||
|
||||
point sample
|
||||
|
||||
multi-hour sample bundle
|
||||
|
||||
bbox grid block
|
||||
|
||||
route sample
|
||||
|
||||
forecast frame index
|
||||
|
||||
variable bundle sample
|
||||
|
||||
4.2.5 典型接口方向
|
||||
/weather-analysis/sample-point
|
||||
/weather-analysis/sample-bundle
|
||||
/weather-analysis/grid/{product}
|
||||
天气-analysis/route-sample
|
||||
/weather-analysis/frame-index/{product}
|
||||
4.2.6 推荐查询能力
|
||||
|
||||
单点单时刻采样
|
||||
|
||||
单点多小时采样
|
||||
|
||||
多变量同点打包采样
|
||||
|
||||
bbox 网格数据块查询
|
||||
|
||||
给定航线与起航时间的沿线天气采样
|
||||
|
||||
给定 forecast frame 的变量集合访问
|
||||
|
||||
4.2.7 服务端职责
|
||||
|
||||
提供标准化数值场查询
|
||||
|
||||
提供时间维度组织
|
||||
|
||||
提供多变量统一采样结果
|
||||
|
||||
控制插值方式与 no-data 行为
|
||||
|
||||
保证在线查询结果与离线包语义一致
|
||||
|
||||
4.2.8 前端/规划侧职责
|
||||
|
||||
请求分析接口
|
||||
|
||||
展示点位时间序列
|
||||
|
||||
驱动规划器调用 route-sample
|
||||
|
||||
不自己从显示图层反推出数值
|
||||
|
||||
4.3 Offline Package
|
||||
4.3.1 目标
|
||||
|
||||
为无网络或弱网络场景提供本地可用天气包，使系统在离线状态下仍可支持：
|
||||
|
||||
地图天气查看
|
||||
|
||||
点击点位未来天气查询
|
||||
|
||||
航线规划采样
|
||||
|
||||
航线模拟
|
||||
|
||||
基础趋势判断
|
||||
|
||||
4.3.2 消费方
|
||||
|
||||
本地天气缓存系统
|
||||
|
||||
离线地图天气层
|
||||
|
||||
本地点查采样器
|
||||
|
||||
本地航线采样器
|
||||
|
||||
本地模拟/规划组件
|
||||
|
||||
4.3.3 主要特征
|
||||
|
||||
是单独打包的离线产品
|
||||
|
||||
可按区域、时间段、变量集下载
|
||||
|
||||
同时覆盖显示需求与分析需求
|
||||
|
||||
不能仅靠 raster cache 代替
|
||||
|
||||
需控制体积与分辨率
|
||||
|
||||
4.3.4 离线包建议双轨组成
|
||||
A. display cache
|
||||
|
||||
预生成 raster tiles
|
||||
|
||||
必要的 display metadata
|
||||
|
||||
可选少量 vector overlay
|
||||
|
||||
B. analysis cache
|
||||
|
||||
压缩后的规则网格
|
||||
|
||||
多时间帧数值块
|
||||
|
||||
多变量字段
|
||||
|
||||
本地可采样结构
|
||||
|
||||
4.3.5 典型内容
|
||||
|
||||
区域 bbox
|
||||
|
||||
time frames
|
||||
|
||||
product list
|
||||
|
||||
units
|
||||
|
||||
no-data 规则
|
||||
|
||||
grid geometry
|
||||
|
||||
values / u-v components
|
||||
|
||||
display metadata
|
||||
|
||||
package manifest
|
||||
|
||||
4.3.6 服务端职责
|
||||
|
||||
离线区域切片与打包
|
||||
|
||||
时间帧裁剪
|
||||
|
||||
分辨率控制
|
||||
|
||||
变量集控制
|
||||
|
||||
manifest 生成
|
||||
|
||||
下载校验信息生成
|
||||
|
||||
4.3.7 客户端职责
|
||||
|
||||
下载包管理
|
||||
|
||||
包安装 / 校验
|
||||
|
||||
本地索引
|
||||
|
||||
本地点位采样
|
||||
|
||||
本地沿线采样
|
||||
|
||||
优先使用本地包，缺失时再回退在线
|
||||
|
||||
5. 三条线之间的关系
|
||||
5.1 关系概述
|
||||
|
||||
三条线共享同一个天气源体系，但生成目标不同。
|
||||
|
||||
原始天气源 / 预处理层
|
||||
│
|
||||
├── Display Product -> 面向地图显示
|
||||
├── Analysis Product -> 面向采样 / 规划 / 模拟
|
||||
└── Offline Package -> 面向无网络使用
|
||||
5.2 不允许的混淆
|
||||
|
||||
以下边界必须明确：
|
||||
|
||||
不允许把 raster tile 当成分析数据源
|
||||
|
||||
不允许把显示色带当成数值语义来源
|
||||
|
||||
不允许把 offline package 简化成“只缓存 png”
|
||||
|
||||
不允许前端自己构建主天气显示逻辑
|
||||
|
||||
不允许把离线点查建立在“颜色反推数值”上
|
||||
|
||||
5.3 允许的共享
|
||||
|
||||
以下内容可以由三条线共享：
|
||||
|
||||
forecast frame index
|
||||
|
||||
产品定义
|
||||
|
||||
单位定义
|
||||
|
||||
no-data 定义
|
||||
|
||||
变量命名规范
|
||||
|
||||
palette 配置源
|
||||
|
||||
contour level 配置
|
||||
|
||||
时间轴组织规则
|
||||
|
||||
6. 统一产品定义层
|
||||
|
||||
为了让三条线长期一致，系统必须建立统一天气产品定义层。
|
||||
|
||||
6.1 每个天气产品至少要有
|
||||
|
||||
product id
|
||||
|
||||
title
|
||||
|
||||
unit
|
||||
|
||||
value type
|
||||
|
||||
time frame rule
|
||||
|
||||
no-data rule
|
||||
|
||||
display recommendation
|
||||
|
||||
analysis semantics
|
||||
|
||||
offline packaging eligibility
|
||||
|
||||
6.2 典型产品
|
||||
|
||||
wind
|
||||
|
||||
gust
|
||||
|
||||
wave
|
||||
|
||||
swell
|
||||
|
||||
current
|
||||
|
||||
pressure
|
||||
|
||||
temperature
|
||||
|
||||
rain
|
||||
|
||||
cloud
|
||||
|
||||
visibility（未来可选）
|
||||
|
||||
6.3 对向量类产品的建议
|
||||
|
||||
对风和流，分析线最好保留：
|
||||
|
||||
u/v 分量
|
||||
或
|
||||
|
||||
speed/dir 组合但需保证采样语义稳定
|
||||
|
||||
7. 元数据中心要求
|
||||
|
||||
系统必须有统一元数据概念，至少覆盖：
|
||||
|
||||
frame list
|
||||
|
||||
unit
|
||||
|
||||
display type
|
||||
|
||||
palette id
|
||||
|
||||
legend model
|
||||
|
||||
contour levels
|
||||
|
||||
data min/max
|
||||
|
||||
display recommended min/max
|
||||
|
||||
supported zoom range
|
||||
|
||||
no-data definition
|
||||
|
||||
package generation limits
|
||||
|
||||
元数据必须以服务端定义为主，不由前端自行假设。
|
||||
|
||||
8. 地图点击查询的系统归属
|
||||
|
||||
地图上点击某地，展示该点未来多小时天气信息，这一能力归属于：
|
||||
|
||||
Analysis Product
|
||||
|
||||
在线模式：
|
||||
|
||||
前端点击点位
|
||||
|
||||
向 analysis API 请求多小时时间序列
|
||||
|
||||
服务端返回 sample bundle
|
||||
|
||||
离线模式：
|
||||
|
||||
前端点击点位
|
||||
|
||||
由本地 Offline Package 中的 analysis cache 做本地采样
|
||||
|
||||
返回本地时间序列
|
||||
|
||||
因此点查 UI 是前端组件，但其数值来源属于 Analysis / Offline 体系，而不属于 Display Product。
|
||||
|
||||
9. 航线规划与模拟的系统归属
|
||||
|
||||
未来的航行匹配、航线规划、模拟不应依赖 Display Product。
|
||||
|
||||
其天气来源必须是：
|
||||
|
||||
在线：Analysis Product
|
||||
|
||||
离线：Offline Package 中的 analysis cache
|
||||
|
||||
规划器未来需要：
|
||||
|
||||
任意点采样
|
||||
|
||||
沿线采样
|
||||
|
||||
多时间帧采样
|
||||
|
||||
多变量打包采样
|
||||
|
||||
可重复计算的稳定数值接口
|
||||
|
||||
因此规划系统与天气系统的正式对接点应该在 Analysis / Offline，而不是 Display。
|
||||
|
||||
10. NavSea V11 架构约束
|
||||
|
||||
本系统必须遵守 NavSea V11：
|
||||
|
||||
不做破坏性架构修改
|
||||
|
||||
不把天气逻辑散落到前端显示层
|
||||
|
||||
所有新增模块保持职责单一
|
||||
|
||||
不引入未知依赖
|
||||
|
||||
每个新文件遵守 NavSea logger 规则
|
||||
|
||||
旧文件修改必须基于用户提供的现有代码
|
||||
|
||||
返回完整替换文件，不返回零散 patch
|
||||
|
||||
保持 wrapper-safe integration
|
||||
|
||||
11. 第一阶段建设顺序
|
||||
|
||||
建议的第一阶段顺序如下：
|
||||
|
||||
第一阶段 A：系统框架定型
|
||||
|
||||
明确三条线边界
|
||||
|
||||
明确命名规范
|
||||
|
||||
明确元数据结构
|
||||
|
||||
明确 display / analysis / offline 的职责分离
|
||||
|
||||
第一阶段 B：优先落地产品
|
||||
|
||||
Display Product 最小闭环
|
||||
|
||||
wind raster
|
||||
|
||||
wave raster
|
||||
|
||||
pressure isoline
|
||||
|
||||
display metadata
|
||||
|
||||
Analysis Product 最小闭环
|
||||
|
||||
sample-point
|
||||
|
||||
sample-bundle
|
||||
|
||||
grid query
|
||||
|
||||
Offline Package 最小闭环
|
||||
|
||||
离线包 manifest
|
||||
|
||||
局部区域 analysis cache
|
||||
|
||||
本地点查可用
|
||||
|
||||
基础 display cache
|
||||
|
||||
第一阶段 C：前端接入
|
||||
|
||||
display 层接入地图
|
||||
|
||||
analysis 层接入点查 panel
|
||||
|
||||
offline 层接入本地采样 fallback
|
||||
|
||||
12. 本系统文件的作用
|
||||
|
||||
该文件不是某一个具体实现任务，而是：
|
||||
|
||||
作为 NavSea 天气系统的顶层构建文件
|
||||
|
||||
作为 codex 任务拆分依据
|
||||
|
||||
作为后续接口命名与模块落地的统一约束
|
||||
|
||||
作为 display / analysis / offline 三条线的系统级说明
|
||||
|
||||
13. 后续 codex 任务拆分
|
||||
|
||||
基于本系统文件，下一步拆出三个主任务：
|
||||
|
||||
NavSea_DisplayProductLine
|
||||
|
||||
NavSea_AnalysisProductLine
|
||||
|
||||
NavSea_OfflinePackageLine
|
||||
|
||||
三者必须分别实现，不得混淆为一个泛化任务。
|
||||
Reference in New Issue
Block a user