4.7 KiB
Version: codex6 Architecture: NavSea V11 Domain: weather-analysis Status: planned
- 任务名称
NavSea_AnalysisProductLine
- 任务目标
建立 NavSea 天气系统中的 Analysis Product 生成线。
该生成线负责提供可计算、可采样、可用于规划和模拟的天气数值产品，用于：
地图点击点位天气查询
某点未来多小时天气展示
航行匹配
航线规划
航线模拟
ETA / 路径代价评估
后续性能模型耦合
该任务强调：
Analysis Product 是正式数值产品，不依附于 Display Product
不允许通过显示图层反推出分析值
Analysis Product 必须提供稳定统一的点采样和时间序列语义
Analysis Product 必须成为未来规划器与模拟器的天气输入基础
- 任务范围
本任务关注的是服务端分析产品体系，不包含显示渲染，不包含离线包打包。
本任务要定义并落地的主要内容包括：
analysis 命名规范
point sample 接口
multi-hour sample bundle 接口
bbox grid query 接口
route-sample 接口规划
frame index / product availability 结构
多变量 bundle 结构
单位、变量语义与 no-data 统一规则
- 目标产物
本任务完成后，应至少能支持：
单点单时刻天气采样
单点未来多小时天气序列采样
多变量同点打包采样
局部区域网格查询
为后续 route-sample 留出稳定接口边界
- 核心原则 5.1 数值优先
Analysis Product 的目标是数值可用性，而不是显示可用性。
5.2 与 Display 解耦
不能把 Display Product 当作 Analysis 的数据来源。
5.3 为规划器服务
Analysis Product 的设计必须天然适合：
路线采样
时间步进
成本计算
船速影响计算
5.4 在线与离线语义一致
未来 Offline Package 中的本地采样结果应尽量与在线 Analysis Product 保持一致语义。
- 推荐接口 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.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[]
- 服务端职责
本任务要求服务端承担：
对规则天气场提供采样服务
统一多变量查询语义
统一 no-data 行为
提供多时间帧时间序列
提供用于规划器的可复用接口
为在线点查和未来路线分析提供同源数值能力
- 前端 / 规划侧职责
前端与规划侧只负责：
发起 sample / bundle / grid / route 查询
展示结果或用于算法
不从 png / mvt 图层反推数值
不自定义分析语义
- 非目标
本任务不包括：
raster / vector display tile 生成
色带图例生成
离线包打包
离线本地采样器实现
前端绘图组件细节
完整规划算法实现
船模极图系统实现
- 第一阶段最小可交付 必做
sample-point
sample-bundle
grid query
frame index / variable bundle definition
第二阶段
route-sample
更丰富变量组合
与规划器直接耦合的高层接口
- 接受标准
任务完成时，必须满足：
已建立 Analysis Product 正式命名与结构
地图点击点位可获取未来多小时天气序列
产品可供未来规划与模拟复用
结果不依赖显示图层反推
已定义点查、多小时序列、局部网格的最小闭环
与 Display / Offline 保持清晰边界
符合 NavSea V11 扩展原则
- Codex 执行要求
执行此任务时：
优先产出接口定义、类型定义、服务契约文件
不得把 display 渲染逻辑写入 analysis 任务
不得假设现有规划器内部结构，除非用户提供文件
若生成新 .ts/.tsx 文件，必须包含 logger 初始化
若修改旧文件，必须先由用户提供原文件