weather/docs/V1.NavSea Weather Product System Build File

# 文件 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

三者必须分别实现，不得混淆为一个泛化任务。