Initial import
This commit is contained in:
OpenAI Codex
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