338 lines
4.7 KiB
Markdown
338 lines
4.7 KiB
Markdown
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 初始化
|
||
|
||
若修改旧文件，必须先由用户提供原文件 |