Version: codex6
Architecture: NavSea V11
Domain: weather-analysis
Status: planned

1. 任务名称

NavSea_AnalysisProductLine

2. 任务目标

建立 NavSea 天气系统中的 Analysis Product 生成线。

该生成线负责提供可计算、可采样、可用于规划和模拟的天气数值产品，用于：

地图点击点位天气查询

某点未来多小时天气展示

航行匹配

航线规划

航线模拟

ETA / 路径代价评估

后续性能模型耦合

该任务强调：

Analysis Product 是正式数值产品，不依附于 Display Product

不允许通过显示图层反推出分析值

Analysis Product 必须提供稳定统一的点采样和时间序列语义

Analysis Product 必须成为未来规划器与模拟器的天气输入基础

3. 任务范围

本任务关注的是服务端分析产品体系，不包含显示渲染，不包含离线包打包。

本任务要定义并落地的主要内容包括：

analysis 命名规范

point sample 接口

multi-hour sample bundle 接口

bbox grid query 接口

route-sample 接口规划

frame index / product availability 结构

多变量 bundle 结构

单位、变量语义与 no-data 统一规则

4. 目标产物

本任务完成后，应至少能支持：

单点单时刻天气采样

单点未来多小时天气序列采样

多变量同点打包采样

局部区域网格查询

为后续 route-sample 留出稳定接口边界

5. 核心原则
5.1 数值优先

Analysis Product 的目标是数值可用性，而不是显示可用性。

5.2 与 Display 解耦

不能把 Display Product 当作 Analysis 的数据来源。

5.3 为规划器服务

Analysis Product 的设计必须天然适合：

路线采样

时间步进

成本计算

船速影响计算

5.4 在线与离线语义一致

未来 Offline Package 中的本地采样结果应尽量与在线 Analysis Product 保持一致语义。

6. 推荐接口
6.1 Sample Point

用于查询单点单时刻一个或多个变量。

推荐方向：

/weather-analysis/sample-point

建议参数：

lon

lat

time

products 或 variable bundle

6.2 Sample Bundle

用于点击地图后展示某点未来多小时天气。

推荐方向：

/weather-analysis/sample-bundle

建议参数：

lon

lat

start

hours

step

variable bundle

建议返回：

点位信息

units

series[]

6.3 Grid Query

用于局部区域网格获取。

推荐方向：

/weather-analysis/grid/{product}

建议参数：

time

bbox

resolution

optional frame mode

6.4 Route Sample

用于航线规划与模拟。

推荐方向：

/weather-analysis/route-sample

建议输入：

route polyline

departure time

optional speed model / step rule

该接口可以作为第一阶段接口定义，第二阶段实现。

7. 推荐返回数据结构
7.1 Sample Bundle 基本结构

至少支持：

lon

lat

units

series[]

each series item:

time

windSpeed / windDir

gust

waveHeight / waveDir / wavePeriod

currentSpeed / currentDir

pressure

temperature（后续）

7.2 Grid Query 基本结构

至少支持：

product

time

bbox

lon0 / lat0

nx / ny

dx / dy

values[]

no-data 定义

unit

对风和流，建议支持：

u[]

v[]

8. 服务端职责

本任务要求服务端承担：

对规则天气场提供采样服务

统一多变量查询语义

统一 no-data 行为

提供多时间帧时间序列

提供用于规划器的可复用接口

为在线点查和未来路线分析提供同源数值能力

9. 前端 / 规划侧职责

前端与规划侧只负责：

发起 sample / bundle / grid / route 查询

展示结果或用于算法

不从 png / mvt 图层反推数值

不自定义分析语义

10. 非目标

本任务不包括：

raster / vector display tile 生成

色带图例生成

离线包打包

离线本地采样器实现

前端绘图组件细节

完整规划算法实现

船模极图系统实现

11. 第一阶段最小可交付
必做

sample-point

sample-bundle

grid query

frame index / variable bundle definition

第二阶段

route-sample

更丰富变量组合

与规划器直接耦合的高层接口

12. 接受标准

任务完成时，必须满足：

已建立 Analysis Product 正式命名与结构

地图点击点位可获取未来多小时天气序列

产品可供未来规划与模拟复用

结果不依赖显示图层反推

已定义点查、多小时序列、局部网格的最小闭环

与 Display / Offline 保持清晰边界

符合 NavSea V11 扩展原则

13. Codex 执行要求

执行此任务时：

优先产出接口定义、类型定义、服务契约文件

不得把 display 渲染逻辑写入 analysis 任务

不得假设现有规划器内部结构，除非用户提供文件

若生成新 .ts/.tsx 文件，必须包含 logger 初始化

若修改旧文件，必须先由用户提供原文件