Initial import

tasks/analysis/NavSea_AnalysisProductLine.md

@@ -0,0 +1,338 @@
+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 初始化
+
+若修改旧文件，必须先由用户提供原文件