Initial import

tasks/NavSea_LandSeaMaskFoundation.md

@@ -0,0 +1,276 @@
+# Task: NavSea_LandSeaMaskFoundation
+Version: codex6
+Architecture: NavSea V11
+Domain: geo-mask
+Status: planned
+
+---
+
+## 1. 任务名称
+
+`NavSea_LandSeaMaskFoundation`
+
+---
+
+## 2. 任务目标
+
+建立 NavSea 的 `land/sea mask` 基础能力，作为天气 Display Product 服务端生成链的独立地理基础层。
+
+该任务的目标不是生成天气数据，而是建立一个可复用的海陆判定资产，使后续天气显示产品能够支持：
+
+- 海域正常显示
+- 陆地弱化或屏蔽
+- 海岸过渡带处理
+- 不同天气产品按海陆语义应用不同 compositing 规则
+- 不同 zoom 下稳定一致的海陆判定
+
+本任务必须明确：
+
+- land/sea mask 是独立基础地理资产
+- 不从天气 pbf 中反推海陆边界
+- mask 需服务于 Display Product，但不依附于某个天气产品
+- mask 后续也可复用于其它海图/航海场景
+
+---
+
+## 3. 问题定义
+
+当前 NavSea 天气显示层需要区分海域与陆地，否则会出现：
+
+- 陆地区域被整体染色
+- 底图地名和地形被压脏
+- 海岸线附近视觉边界不干净
+- wave/current 等本应海域专属的产品错误显示到陆地
+- wind 等产品缺少“海域优先、陆地弱化”的语义控制
+
+这些问题无法通过天气数据本身稳定解决。
+
+因此必须建立独立 land/sea mask 基础层。
+
+---
+
+## 4. 核心原则
+
+### 4.1 Mask 必须独立于天气产品
+land/sea mask 不得从 weather pbf、weather raster、weather contour 结果中推断。
+
+### 4.2 Mask 是基础地理资产
+它应来源于独立海岸线、陆地面、水域面或底图地理数据。
+
+### 4.3 Mask 必须可复用
+同一套 mask 应可服务于：
+- wind display
+- wave display
+- current display
+- pressure display
+- 后续其它海图叠加产品
+
+### 4.4 产品规则独立于 mask 数据本身
+mask 只回答“哪里是 land / sea / coast transition”，
+具体如何使用由各 weather product policy 决定。
+
+---
+
+## 5. 推荐数据来源方向
+
+本任务允许并建议调研与选型以下来源：
+
+### 5.1 日本本地官方方向
+- 国土地理院（GSI）相关地理数据 / 地理院瓦片体系 / 可复用海岸线或陆地区域数据
+
+### 5.2 全球通用基础源
+- Natural Earth
+- GSHHG
+- OpenStreetMap 派生 coastline / land polygons / water polygons
+
+### 5.3 复用现有底图数据
+若 NavSea 当前底图体系已经具备：
+- land polygon
+- water polygon
+- coastline vector data
+
+则优先复用，不重复建设平行数据链。
+
+
+建议按 OSM land polygons → GSHHG → GSI 来尝试模型。
+---
+
+## 6. 任务范围
+
+本任务关注：
+
+- land/sea mask 数据源选型
+- mask 数据模型
+- mask 生成规则
+- mask tile / mask asset 组织方式
+- coastline transition 基础能力
+- mask 元数据定义
+- 与 Display Product 的服务端对接边界
+
+本任务不包括：
+
+- 天气 raster 生成
+- palette 生成
+- Analysis Product 查询
+- Offline Package 打包
+- 前端 layer 实现
+- 航线规划算法
+
+---
+
+## 7. 目标产物
+
+本任务完成后，应至少形成：
+
+1. `land/sea mask` 数据来源选型结论
+2. `mask asset` 组织方案
+3. `mask tile` 或 `mask data block` 输出方案
+4. `coast transition` 基础定义
+5. `mask metadata` 结构
+6. 给 Display Product 复用的服务端接口或内部资产规范
+
+---
+
+## 8. 推荐实现方向
+
+### 8.1 最小可行版本
+先建立基础二值判定：
+
+- land
+- sea
+
+并支持：
+- land attenuate
+- land mask out
+
+### 8.2 第二阶段增强
+增加海岸过渡带：
+
+- coast transition band
+- 渐变衰减
+- 防止海岸线处硬切边
+
+### 8.3 输出形式建议
+推荐至少评估以下两种输出之一：
+
+#### A. Raster mask tiles
+例如：
+`/geo-mask/land-sea/{z}/{x}/{y}.png`
+
+适合快速接入服务端 display compositing。
+
+#### B. Vector / polygon asset
+例如：
+- 预处理 land polygons
+- 预处理 coastline bands
+- 服务端生成 tile 时内部引用
+
+适合更高质量生成链。
+
+---
+
+## 9. 必须定义的数据语义
+
+至少定义：
+
+- `land`
+- `sea`
+- `coastTransition`（如实现第二阶段）
+- no-data / out-of-coverage 行为
+- 不同 zoom 下精度与简化策略
+- mask 版本号
+- 源数据来源标识
+
+---
+
+## 10. Display Product 对接要求
+
+本任务必须为后续天气显示产品提供可复用能力，使不同产品可采用不同策略，例如：
+
+### wind
+- sea: normal
+- land: attenuate
+
+### wave
+- sea: normal
+- land: mask
+
+### current
+- sea: normal
+- land: mask
+
+### pressure
+- sea: normal
+- land: normal
+
+因此本任务输出的不是某个固定产品规则，而是支持这些规则的统一 mask 基础层。
+
+---
+
+## 11. 选型评估要求
+
+执行任务时，必须对候选数据源至少从以下维度进行比较：
+
+- 日本沿岸适用性
+- 海岸线精度
+- 岛屿细节表现
+- 许可与使用约束
+- 全球/区域覆盖能力
+- 数据更新便利性
+- 预处理复杂度
+- 与当前底图体系兼容性
+- 服务端 tile 生成链接入难度
+
+---
+
+## 12. 第一阶段最小可交付
+
+### 必做
+1. 数据源选型结论
+2. land/sea mask 数据模型
+3. mask 资产组织方式
+4. 基础 land / sea 判定
+5. 给 Display Product 的对接方式
+
+### 第二阶段
+1. coast transition band
+2. 多 zoom 精度策略
+3. 日本重点海域精度优化
+4. 与 Offline Package 的复用关系定义
+
+---
+
+## 13. 接受标准
+
+任务完成时，必须满足：
+
+- land/sea mask 被正式定义为独立基础层
+- 不再从天气 pbf 推断海陆边界
+- 已有明确数据源选型结论
+- 已定义 mask 资产和输出组织方式
+- 已能支撑 Display Product 的海陆差异化显示
+- 已为 coastline transition 预留扩展空间
+- 符合 NavSea V11 非破坏式扩展要求
+
+---
+
+## 14. Codex 执行要求
+
+执行此任务时：
+
+- 优先产出选型文档、mask 类型定义、mask asset 组织规则
+- 若修改已有文件，必须等待用户提供原文件
+- 若新建 `.ts/.tsx` 文件，必须包含 NavSea logger 初始化
+- 不引入未知依赖
+- 不把天气产品逻辑混入 mask 基础层
+- 不把 mask 简化成前端临时判断逻辑
+
+---
+
+## 15. 一句话定义
+
+本任务的本质是：
+
+**为 NavSea 建立一个独立、可复用、可服务于天气显示产品的 land/sea mask 基础地理资产层。**
+
+---

tasks/WeatherServer_GridBuilder_v2.md

@@ -0,0 +1,215 @@
+# NavSea Weather Server
+Task: WeatherServer_GridBuilder_v2
+Architecture: NavSea V11
+Codex: codex6
+Status: TODO
+
+---
+
+# 1 任务目标
+
+升级 Grid Builder：
+
+grid_builder.py → GridBuilder v2
+
+目标：
+
+1 裁剪日本区域 grid  
+2 使用数组结构保存 grid  
+3 大幅减少 JSON 文件大小  
+
+---
+
+# 2 当前问题
+
+旧版 GridBuilder：
+
+生成全球 grid：
+
+1440 × 721  
+≈ 1,038,240 points
+
+JSON 文件：
+
+≈ 215MB
+
+这是不可接受的。
+
+Downloader 已经只下载：
+
+120E – 150E  
+20N – 50N
+
+GridBuilder 必须只输出这个区域。
+
+---
+
+# 3 区域范围
+
+REGION：
+
+lon_min = 120
+lon_max = 150
+
+lat_min = 20
+lat_max = 50
+
+理论 grid：
+
+(150-120)/0.25 = 120  
+(50-20)/0.25 = 120  
+
+≈ 14400 grid points
+
+---
+
+# 4 新 Grid 数据结构
+
+旧结构：
+
+points list
+
+{
+ "points":[
+  {lat,lon,...}
+ ]
+}
+
+新结构：
+
+grid arrays
+
+{
+ "time": "...",
+ "lat": [...],
+ "lon": [...],
+ "wind_speed": [...],
+ "wind_dir": [...],
+ "rain": [...],
+ "temp": [...],
+ "pressure": [...]
+}
+
+优点：
+
+1 文件更小  
+2 读取更快  
+3 tile generator 更容易  
+
+---
+
+# 5 创建文件
+
+weather_server/grid/grid_builder_v2.py
+
+---
+
+# 6 实现代码
+
+```python
+import os
+import json
+import numpy as np
+import xarray as xr
+
+INPUT_DIR = "data/grib"
+OUTPUT_DIR = "data/grid"
+
+os.makedirs(OUTPUT_DIR, exist_ok=True)
+
+REGION = {
+    "lon_min":120,
+    "lon_max":150,
+    "lat_min":20,
+    "lat_max":50
+}
+
+
+def compute_wind(u, v):
+
+    speed = np.sqrt(u**2 + v**2)
+
+    direction = (np.degrees(np.arctan2(u, v)) + 360) % 360
+
+    return speed, direction
+
+
+def process_file(path):
+
+    ds = xr.open_dataset(path, engine="cfgrib")
+
+    u = ds["u10"].values
+    v = ds["v10"].values
+    rain = ds["tp"].values
+    pressure = ds["msl"].values
+    temp = ds["t2m"].values
+
+    lat = ds.latitude.values
+    lon = ds.longitude.values
+
+    wind_speed, wind_dir = compute_wind(u, v)
+
+    lat_idx = np.where(
+        (lat >= REGION["lat_min"]) &
+        (lat <= REGION["lat_max"])
+    )[0]
+
+    lon_idx = np.where(
+        (lon >= REGION["lon_min"]) &
+        (lon <= REGION["lon_max"])
+    )[0]
+
+    lat_region = lat[lat_idx]
+    lon_region = lon[lon_idx]
+
+    wind_speed = wind_speed[np.ix_(lat_idx, lon_idx)]
+    wind_dir = wind_dir[np.ix_(lat_idx, lon_idx)]
+
+    rain = rain[np.ix_(lat_idx, lon_idx)]
+    temp = temp[np.ix_(lat_idx, lon_idx)]
+    pressure = pressure[np.ix_(lat_idx, lon_idx)]
+
+    return {
+        "lat": lat_region.tolist(),
+        "lon": lon_region.tolist(),
+        "wind_speed": wind_speed.tolist(),
+        "wind_dir": wind_dir.tolist(),
+        "rain": rain.tolist(),
+        "temp": temp.tolist(),
+        "pressure": pressure.tolist()
+    }
+
+
+def main():
+
+    for file in os.listdir(INPUT_DIR):
+
+        if not file.endswith(".grib2"):
+            continue
+
+        path = os.path.join(INPUT_DIR, file)
+
+        print("processing", file)
+
+        grid = process_file(path)
+
+        output = os.path.join(
+            OUTPUT_DIR,
+            f"grid_{file.replace('.grib2','')}.json"
+        )
+
+        data = {
+            "time": file.replace(".grib2",""),
+            "grid": grid
+        }
+
+        with open(output, "w") as f:
+
+            json.dump(data, f)
+
+        print("saved", output)
+
+
+if __name__ == "__main__":
+
+    main()

tasks/WeatherServer_VectorTileGenerator.md

@@ -0,0 +1,248 @@
+# NavSea Weather Server
+Task: WeatherServer_VectorTileGenerator
+Architecture: NavSea V11
+Codex: codex6
+Status: TODO
+
+---
+
+# 1 任务目标
+
+实现 Vector Tile Generator。
+
+功能：
+
+将 Weather Grid JSON 转换为 MapLibre Vector Tile (PBF)。
+
+输入：
+
+data/grid/*.json
+
+输出：
+
+output/weather/{time}/{z}/{x}/{y}.pbf
+
+用于 NavSea 客户端加载天气图层。
+
+---
+
+# 2 使用库
+
+需要安装：
+
+pip install mercantile
+pip install mapbox-vector-tile
+
+---
+
+# 3 输入数据
+
+GridBuilder v2 生成：
+
+data/grid/
+
+grid_20260312_00_f000.json
+grid_20260312_00_f003.json
+
+结构：
+
+{
+ "time": "...",
+ "grid": {
+   "lat": [...],
+   "lon": [...],
+   "wind_speed": [[...]],
+   "wind_dir": [[...]],
+   "rain": [[...]],
+   "temp": [[...]],
+   "pressure": [[...]]
+ }
+}
+
+grid 尺寸：
+
+121 × 121
+
+---
+
+# 4 Tile Zoom 设计
+
+Weather tile 只需要 4 个 zoom：
+
+2
+4
+6
+8
+
+---
+
+# 5 Tile 输出结构
+
+output/weather/
+
+time/
+   z/
+      x/
+        y.pbf
+
+示例：
+
+output/weather/20260312_00_f000/4/10/7.pbf
+
+---
+
+# 6 Feature 结构
+
+每个 grid 点 → 一个 feature
+
+geometry：
+
+POINT(lon lat)
+
+properties：
+
+{
+ "ws": wind_speed
+ "wd": wind_dir
+ "r": rain
+ "t": temp
+ "p": pressure
+}
+
+字段缩写减少 tile 大小。
+
+---
+
+# 7 创建文件
+
+weather_server/tiles/vector_tile_generator.py
+
+---
+
+# 8 实现代码
+
+```python
+import os
+import json
+import mercantile
+import mapbox_vector_tile
+
+GRID_DIR = "data/grid"
+OUTPUT_DIR = "output/weather"
+
+ZOOMS = [2,4,6,8]
+
+def load_grid(path):
+
+    with open(path) as f:
+        data = json.load(f)
+
+    return data["time"], data["grid"]
+
+
+def grid_to_features(grid):
+
+    lat = grid["lat"]
+    lon = grid["lon"]
+
+    ws = grid["wind_speed"]
+    wd = grid["wind_dir"]
+    rain = grid["rain"]
+    temp = grid["temp"]
+    pres = grid["pressure"]
+
+    features = []
+
+    for i in range(len(lat)):
+        for j in range(len(lon)):
+
+            feature = {
+                "geometry":{
+                    "type":"Point",
+                    "coordinates":[lon[j], lat[i]]
+                },
+                "properties":{
+                    "ws":ws[i][j],
+                    "wd":wd[i][j],
+                    "r":rain[i][j],
+                    "t":temp[i][j],
+                    "p":pres[i][j]
+                }
+            }
+
+            features.append(feature)
+
+    return features
+
+
+def generate_tiles(time, features):
+
+    for z in ZOOMS:
+
+        tiles = mercantile.tiles(120,20,150,50,z)
+
+        for tile in tiles:
+
+            bounds = mercantile.bounds(tile)
+
+            tile_features = []
+
+            for f in features:
+
+                lon, lat = f["geometry"]["coordinates"]
+
+                if (
+                    bounds.west <= lon <= bounds.east
+                    and bounds.south <= lat <= bounds.north
+                ):
+                    tile_features.append(f)
+
+            if not tile_features:
+                continue
+
+            layer = {
+                "weather": tile_features
+            }
+
+            tile_data = mapbox_vector_tile.encode(layer)
+
+            path = os.path.join(
+                OUTPUT_DIR,
+                time,
+                str(z),
+                str(tile.x)
+            )
+
+            os.makedirs(path, exist_ok=True)
+
+            filename = os.path.join(
+                path,
+                f"{tile.y}.pbf"
+            )
+
+            with open(filename,"wb") as f:
+                f.write(tile_data)
+
+            print("tile", time, z, tile.x, tile.y)
+
+
+def main():
+
+    for file in os.listdir(GRID_DIR):
+
+        if not file.endswith(".json"):
+            continue
+
+        path = os.path.join(GRID_DIR, file)
+
+        print("processing", file)
+
+        time, grid = load_grid(path)
+
+        features = grid_to_features(grid)
+
+        generate_tiles(time, features)
+
+
+if __name__ == "__main__":
+    main()

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

tasks/display/NavSea_DisplayProductLine.md

@@ -0,0 +1,301 @@
+Version: codex6
+Architecture: NavSea V11
+Domain: weather-display
+Status: planned
+
+1. 任务名称
+
+NavSea_DisplayProductLine
+
+2. 任务目标
+
+建立 NavSea 天气系统中的 Display Product 生成线。
+
+该生成线负责把服务端天气数据产出为前端可直接显示的天气产品，服务于地图叠加、图层控制、图例展示与时间帧切换。
+
+该任务明确规定：
+
+前端不参与天气颜色渲染
+
+前端不参与天气场插值重建
+
+显示图层由服务端直接生成或直接定义显示语义
+
+Display Product 只对“显示可用性”负责，不对精确分析复用负责
+
+3. 任务范围
+
+本任务关注的是服务端显示产品体系，不包含分析查询，也不包含离线包。
+
+本任务要定义并落地的主要内容包括：
+
+显示产品命名规范
+
+显示产品接口规划
+
+raster weather tiles 体系
+
+vector isoline / isoband 体系
+
+display metadata 结构
+
+legend metadata 结构
+
+frame index 与产品索引结构
+
+前端接入所需的最小语义边界
+
+4. 目标产物
+
+本任务完成后，应形成一套完整的 Display Product 基础能力，至少可支持：
+
+风速 raster tile
+
+浪高 raster tile
+
+气压 isoline MVT
+
+与之配套的显示元数据
+
+与之配套的图例元数据
+
+多时间帧显示切换基础
+
+5. 核心原则
+5.1 Display Product 不是分析接口
+
+Display Product 面向地图显示，而不是数值精确查询。
+
+5.2 服务端负责颜色
+
+色带、颜色区间、推荐显示范围、图例语义，均由服务端定义。
+
+5.3 前端只消费
+
+前端负责图层接入、开关、透明度、顺序、时间帧切换、图例显示，不负责场构建与色带映射。
+
+5.4 产品化输出
+
+不要再输出“稀疏点等前端自行加工”的中间形态作为主显示方案。
+
+6. 推荐产品类型
+6.1 Raster Products
+
+优先用于：
+
+wind
+
+wave
+
+temperature
+
+rain
+
+current（如后续需要）
+
+推荐接口命名：
+
+/weather-display/raster/{product}/{time}/{z}/{x}/{y}.png
+6.2 Vector Products
+
+优先用于：
+
+pressure isoline
+
+wind isoband（后续）
+
+wave isoband（后续）
+
+推荐接口命名：
+
+/weather-display/vector/{product-variant}/{time}/{z}/{x}/{y}.pbf
+
+示例：
+
+/weather-display/vector/pressure-isoline/{time}/{z}/{x}/{y}.pbf
+/weather-display/vector/wind-isoband/{time}/{z}/{x}/{y}.pbf
+/weather-display/vector/wave-isoband/{time}/{z}/{x}/{y}.pbf
+7. 必须定义的元数据
+7.1 Display Meta
+
+至少包含：
+
+product
+
+time
+
+unit
+
+display type
+
+palette id
+
+recommended min/max
+
+data min/max
+
+no-data definition
+
+supported zoom range
+
+opacity suggestion
+
+示例方向：
+
+/weather-display/meta/{product}/{time}
+7.2 Legend Meta
+
+至少包含：
+
+title
+
+subtitle
+
+unit
+
+legend sections
+
+scale type
+
+color stops / discrete buckets
+
+contour levels（如适用）
+
+7.3 Frame Index
+
+至少包含：
+
+available frames
+
+frame step
+
+earliest / latest
+
+product availability
+
+8. 服务端职责
+
+本任务要求服务端承担：
+
+原始天气数据插值/重采样到显示适合形式
+
+色带映射
+
+等值线 / 等值带生成
+
+多时间帧组织
+
+显示元数据输出
+
+图例元数据输出
+
+no-data 透明化或规避策略
+
+产品一致性控制
+
+9. 前端职责边界
+
+Display Product 接入后，前端只负责：
+
+source / layer 注册
+
+图层可见性控制
+
+opacity 调整
+
+z-index / layer ordering
+
+时间帧切换
+
+图例读取与展示
+
+点击地图后跳转到 Analysis Product 查询
+
+前端不得承担：
+
+主显示色带生成
+
+连续场构建
+
+contour 生成
+
+稀疏点插值渲染
+
+10. 非目标
+
+本任务不包括：
+
+点位天气查询接口
+
+多小时 sample bundle
+
+航线采样接口
+
+离线天气包下载
+
+前端本地天气数值采样
+
+路线规划算法
+
+航速极图/性能模型耦合
+
+11. 第一阶段最小可交付
+必做
+
+wind raster display product
+
+wave raster display product
+
+pressure isoline display product
+
+display metadata
+
+legend metadata
+
+frame index
+
+可后续增强
+
+wind isoband
+
+wave isoband
+
+current raster
+
+rain raster
+
+temperature raster
+
+12. 接受标准
+
+任务完成时，必须满足：
+
+已建立 Display Product 正式命名与结构
+
+已形成前端可直接消费的显示产品体系
+
+前端无需参与颜色渲染
+
+前端无需自行插值天气场
+
+至少具备 wind / wave raster 与 pressure isoline 的最小闭环
+
+已定义 display meta / legend meta / frame index
+
+与 Analysis / Offline 保持清晰边界
+
+符合 NavSea V11 非破坏式扩展要求
+
+13. Codex 执行要求
+
+执行此任务时：
+
+优先产出系统设计文件、接口定义文件、元数据结构文件
+
+若新建 .ts/.tsx 文件，必须加 logger 初始化
+
+若修改已有文件，必须等待用户提供原文件
+
+不得擅自假设现有前端地图实现细节
+
+不得把 Analysis 或 Offline 内容混入 Display Product 任务范围

tasks/display/NavSea_DisplayProductReadabilityTuning.md

@@ -0,0 +1,474 @@
+# Task: NavSea_DisplayProductReadabilityTuning
+Version: codex6
+Architecture: NavSea V11
+Domain: weather-display-server
+Status: planned
+
+---
+
+## 1. 任务名称
+
+`NavSea_DisplayProductReadabilityTuning`
+
+---
+
+## 2. 任务目标
+
+对 NavSea 服务端天气显示产品生成链进行可读性改进，解决当前 Display Product 存在的以下核心问题：
+
+- 图层发糊
+- 格网块感明显
+- 色带对比不足
+- 底图被脏化
+- 海岸线附近显示不干净
+- 地名、标注、底图细节可读性下降
+
+该任务不是前端样式调整任务，而是**服务器端显示产品生成质量改进任务**。
+
+目标是让服务端输出的天气显示产品达到如下效果：
+
+- 连续但不模糊
+- 平滑但不发灰
+- 有梯度但不脏底图
+- 海区信息清晰
+- 陆地区域不过度染色
+- 更接近成熟气象图层，而不是低分辨率半透明遮罩
+
+---
+
+## 3. 问题定义
+
+当前天气显示图层存在以下典型表现：
+
+### 3.1 粗格网直接暴露
+表现为：
+- tile 内部出现明显方块
+- 放大后格子边界可见
+- 海上场层缺少连续性
+
+根因方向：
+- 服务端显示栅格分辨率不足
+- 直接对粗网格着色输出
+- 未在服务端完成足够细的显示级重采样
+
+### 3.2 过度平滑导致发糊
+表现为：
+- 图层像一层雾
+- 局部梯度被抹平
+- 海岸附近过渡模糊
+- 场层“连续”但不可读
+
+根因方向：
+- 依赖 blur / 强平滑伪造连续感
+- 输出后重采样策略过软
+- 服务端未区分“插值连续”与“视觉模糊”
+
+### 3.3 色带功能对比不足
+表现为：
+- 值域差异不明显
+- 蓝灰一片
+- 用户无法快速判断强弱变化
+- 叠到底图后视觉信息被稀释
+
+根因方向：
+- 色带饱和度不足
+- 中低值区分度不足
+- alpha 与色差组合不合理
+- palette 设计更像氛围图，而不是功能图层
+
+### 3.4 底图被压脏
+表现为：
+- 地名变灰
+- 海岸线发脏
+- 地形层失真
+- 地图整体发蒙
+
+根因方向：
+- 天气层整体覆盖过重
+- 未考虑陆地弱化策略
+- 图层输出未考虑与底图混合后的实际视觉效果
+
+---
+
+## 4. 任务范围
+
+本任务只关注**服务端 Display Product 的生成质量改进**，包括：
+
+- 服务端显示栅格精度策略
+- 服务端插值与重采样策略
+- 服务端平滑策略
+- 服务端色带可读性策略
+- 海陆差异化输出策略
+- 显示元数据中的可读性控制参数
+- tile 生成规则调整
+
+本任务不包括：
+
+- 前端图层组件重写
+- Analysis Product 数值查询接口
+- Offline Package 设计
+- 航线规划算法
+- 前端局部滤镜或 shader 补救
+- 客户端重新着色
+
+---
+
+## 5. 核心原则
+
+### 5.1 可读性优先于柔和感
+天气显示层首先是功能图层，不是背景氛围层。
+
+优先满足：
+1. 梯度清楚
+2. 海区强弱清楚
+3. 底图仍可辨认
+4. 再考虑视觉柔和
+
+### 5.2 连续不等于模糊
+连续天气场应通过：
+- 更合理插值
+- 更细显示栅格
+- 更稳的色带映射
+
+来实现，而不是通过重 blur 获得。
+
+### 5.3 服务端负责显示质量
+前端不负责补救服务器输出质量问题。
+
+本任务必须通过**服务端产品改进**解决：
+- 块
+- 糊
+- 灰
+- 脏
+
+### 5.4 海图场景优先
+NavSea 是航海场景，显示应优先保障：
+- 海区天气阅读
+- 港口与沿岸识别
+- 航线叠加清晰
+- 标注可读
+
+而不是追求整幅陆地区域统一渲染存在感。
+
+---
+
+## 6. 目标效果定义
+
+改进后的服务器 Display Product 应满足：
+
+- 不出现明显粗网格块
+- 不形成大面积发灰发糊遮罩
+- 海上梯度变化可快速识别
+- 底图文字可保持清晰
+- 海岸线附近不过脏
+- 陆地部分显示影响弱于海区
+- 在典型 zoom 下保持视觉稳定
+- 相同产品在不同时间帧下风格一致
+
+---
+
+## 7. 必须改进的服务端方向
+
+---
+
+## 7.1 显示栅格分辨率提升
+
+### 目标
+避免“粗网格直接着色输出”的方块感。
+
+### 要求
+服务端在生成 raster display tile 前，必须先将天气场转换为足够细的显示级栅格。
+
+### 明确要求
+- 不允许直接对粗规则网格做简单颜色映射后输出 tile
+- 必须存在 display-oriented resampling / interpolation 步骤
+- 输出分辨率需以视觉连续性为目标，而不是以原始数据点数量为目标
+- 需要针对不同 zoom 设计显示级栅格策略
+
+### 预期效果
+- tile 放大后块感显著下降
+- 连续场更接近参考图风格
+- 后续不再依赖重 blur 补救
+
+---
+
+## 7.2 插值与重采样策略修正
+
+### 目标
+通过更合适的插值获得连续感，而不是用后处理模糊掩盖粗糙输入。
+
+### 要求
+- 审查当前服务端插值方式
+- 区分“数值场插值”和“图像后处理”
+- 优先提高插值质量，而不是提高 blur 强度
+- 显示产品必须以插值结果为基础，不得以图像模糊为主要连续手段
+
+### 不允许
+- 简单依赖高斯模糊作为主平滑方法
+- 先粗糙上色，再模糊成“柔和图层”
+
+### 推荐方向
+- 更细显示网格
+- 合理双线性/双三次/场级重采样
+- 按 zoom 自适应重采样精度
+
+---
+
+## 7.3 限制过度平滑
+
+### 目标
+避免场层发雾、发灰、局部梯度消失。
+
+### 要求
+- 明确平滑策略的上限
+- 将 blur 从主手段降为可选轻量辅助
+- 若存在平滑，必须以“不损失局部结构”为前提
+- 海岸线附近不得出现明显雾化边缘
+
+### 输出要求
+服务端需能区分：
+- interpolation smoothing
+- image blur smoothing
+
+并优先保留前者，抑制后者。
+
+---
+
+## 7.4 色带可读性重构
+
+### 目标
+让天气层成为可读功能层，而不是半透明灰蓝遮罩。
+
+### 要求
+服务端 palette / legend 配置必须重新评估以下指标：
+
+- 值域层次区分度
+- 色相迁移清晰度
+- 中值区与低值区可分离性
+- 高值区视觉警示性
+- 与底图叠加后的可读性
+- alpha 与底图混合后的实际效果
+
+### 改进方向
+- 提高有效对比
+- 减少灰化区间
+- 保留风/浪场常见直觉映射
+- 让用户一眼看出强弱变化
+- 避免整幅图“蓝灰糊一片”
+
+### 注意
+色带配置属于服务端产品定义的一部分，必须在服务端正式配置，不得依赖前端临时猜测。
+
+---
+
+## 7.5 海陆差异化输出
+
+### 目标
+减少陆地被整体染色导致的“底图发脏”。
+
+### 要求
+服务端 Display Product 生成需考虑海陆差异化策略。
+
+### 推荐方向
+- 海域正常输出天气层
+- 陆地区域降低存在感
+- 陆地可采用更低 alpha 或更弱显示权重
+- 海岸过渡区需平滑但干净
+- 避免整片内陆都被天气层压灰
+
+### 场景理由
+NavSea 的核心使用场景是海图 / 航海气象，不应让陆地渲染强度干扰海区判断。
+
+---
+
+## 7.6 No-Data 与边界处理优化
+
+### 目标
+避免边缘发脏、异常色块、无数据区域污染。
+
+### 要求
+- 明确 no-data 颜色与透明规则
+- tile 边界拼接必须稳定
+- 海岸 / 数据边界不得产生脏边
+- 不允许无数据区域被错误平滑扩散成虚假值
+
+### 必须注意
+- no-data 不能简单当低值色
+- 边界外推必须受控
+- 显示层边缘必须尽量干净
+
+---
+
+## 7.7 Display Meta 增强
+
+### 目标
+把显示质量控制正式产品化，而不是靠隐性实现细节。
+
+### 建议新增元数据字段
+- paletteId
+- displayMin
+- displayMax
+- suggestedOpacity
+- landAttenuationMode
+- noDataMode
+- supportedZoomMin
+- supportedZoomMax
+- renderResolutionClass
+- smoothingClass
+
+### 作用
+让前端明确知道服务端输出的产品语义与使用方式，也便于后续产品版本控制。
+
+---
+
+## 8. 服务端实施内容
+
+本任务要求服务端至少完成以下工作项：
+
+1. 审查当前 raster display 生成链
+2. 定位粗网格暴露点
+3. 定位 blur / smoothing 位置与强度
+4. 重构显示级重采样策略
+5. 重构 palette 可读性配置
+6. 增加海陆差异化 compositing 规则
+7. 优化 no-data / tile 边界处理
+8. 更新 display meta 结构
+9. 形成新的显示产品生成基线
+10. 形成可对比验证样例
+
+---
+
+## 9. 推荐验证场景
+
+必须至少用以下场景验证：
+
+### 9.1 沿海复杂区域
+例如：
+- 日本沿岸
+- 群岛区域
+- 港湾附近
+
+验证：
+- 海岸附近不脏
+- 港口可辨认
+- 海区梯度仍清晰
+
+### 9.2 大范围海区
+验证：
+- 不出现大面积块状
+- 连续场稳定
+- 不发雾
+
+### 9.3 不同 zoom 级别
+验证：
+- 放大后不过度块化
+- 缩小时不过度灰化
+- 不同 zoom 的视觉风格连续
+
+### 9.4 底图叠加效果
+验证：
+- 地名仍清楚
+- 海岸线仍清楚
+- 天气层不盖死底图
+
+### 9.5 多时间帧一致性
+验证：
+- 不同时刻切换时风格稳定
+- 不出现某些帧特别灰或特别糊
+
+---
+
+## 10. 接受标准
+
+任务完成时，必须满足：
+
+- 服务端输出的 Display Product 块感显著降低
+- 不再依赖重 blur 获得连续感
+- 色带在底图上可读性明显提升
+- 底图文字与海岸线不再被明显压脏
+- 海陆差异化显示策略已建立
+- no-data 与边界处理明确可控
+- display meta 已补充显示质量相关语义
+- 改进属于服务器端生成线，而不是前端补救方案
+- 符合 NavSea V11 非破坏式扩展原则
+
+---
+
+## 11. 非目标
+
+本任务不包括：
+
+- Analysis Product 查询接口
+- Offline Package 打包
+- 前端图层管理器重构
+- 图例面板 UI 重构
+- 航线规划天气采样
+- 客户端 shader 渲染方案
+- 客户端重新着色
+
+---
+
+## 12. 与其它任务的关系
+
+本任务属于：
+
+`Display Product` 生成线内部的质量改进任务
+
+它应作为以下任务的增强子任务或并行任务存在：
+
+- `NavSea_DisplayProductLine`
+
+它不替代：
+- `NavSea_AnalysisProductLine`
+- `NavSea_OfflinePackageLine`
+
+---
+
+## 13. Codex 执行要求
+
+执行此任务时：
+
+- 必须从服务端显示产品生成链入手，不得把修正责任转嫁给前端
+- 优先输出显示生成规则、palette 配置结构、display meta 结构、海陆 compositing 策略
+- 如果需要改旧文件，必须等待用户提供现有文件
+- 如果新增 `.ts/.tsx` 文件，必须包含 NavSea logger 初始化
+- 不引入未知依赖
+- 不做与任务无关的服务端大重构
+- 保持 V11 wrapper-safe integration
+
+---
+
+## 14. 推荐交付物
+
+建议本任务至少输出以下内容之一或组合：
+
+1. 服务端 Display Product 可读性改进设计文件
+2. palette / display meta / render config 类型定义
+3. raster display generation policy 文件
+4. 海陆差异化 compositing 规则文件
+5. no-data / edge handling 规则文件
+6. 验证用对比基线说明
+
+---
+
+## 15. 推荐下一步执行顺序
+
+建议后续执行顺序为：
+
+1. 先固化本任务文档
+2. 审查当前服务端 display 生成链
+3. 先修正显示栅格与重采样
+4. 再修正 blur/smoothing
+5. 再修正 palette 与 opacity 语义
+6. 最后补充海陆差异化与 display meta
+
+---
+
+## 16. 一句话定义
+
+本任务的本质不是“把天气层调柔和一点”，而是：
+
+**把 NavSea 服务端天气显示产品从“低分辨率半透明糊层”改造成“清晰、连续、可读、不会压脏底图的正式显示产品”。**
+
+---
+

tasks/offline/NavSea_OfflinePackageLine.md

@@ -0,0 +1,340 @@
+Version: codex6
+Architecture: NavSea V11
+Domain: weather-offline
+Status: planned
+
+1. 任务名称
+
+NavSea_OfflinePackageLine
+
+2. 任务目标
+
+建立 NavSea 天气系统中的 Offline Package 生成线。
+
+该生成线负责为离线或弱网络环境提供可安装、可索引、可本地使用的天气包，使 NavSea 在无网络场景下仍能支持：
+
+地图天气显示
+
+点击某点未来多小时天气查询
+
+航线天气采样
+
+航线规划
+
+航线模拟
+
+基本趋势判断
+
+该任务明确：
+
+Offline Package 是第三条独立生成线
+
+它不是 Display Product 或 Analysis Product 的简单缓存
+
+它必须同时覆盖 display 使用与 analysis 使用
+
+它必须考虑体积、区域、时间、变量集与本地索引
+
+3. 任务范围
+
+本任务关注的是离线天气包的定义、打包、索引与本地可用结构。
+
+本任务要定义并落地的主要内容包括：
+
+offline package 命名规范
+
+package manifest
+
+package content model
+
+display cache + analysis cache 双轨结构
+
+区域 / 时间帧 / 变量集裁剪规则
+
+本地索引语义
+
+本地采样所需结构定义
+
+下载与校验基础信息结构
+
+4. 目标产物
+
+本任务完成后，应至少形成：
+
+一个正式的 Offline Package 结构定义
+
+package manifest 结构
+
+analysis cache 结构
+
+display cache 结构
+
+本地点查与本地规划可依赖的最小数据模型
+
+5. 核心原则
+5.1 离线必须基于可采样数值场
+
+仅缓存 png / pbf 显示图层不足以支持点查和规划。
+
+5.2 离线必须双轨
+
+Offline Package 至少包含：
+
+display cache
+
+analysis cache
+
+5.3 离线包必须可控体积
+
+包必须允许按：
+
+区域
+
+时间段
+
+时间步长
+
+变量集合
+
+分辨率级别
+
+进行裁剪与打包。
+
+5.4 在线 / 离线语义尽量一致
+
+同一点、同一时刻、同一变量，离线采样结果应尽量接近在线 Analysis Product 结果。
+
+6. 推荐包结构
+6.1 Package Manifest
+
+建议至少包含：
+
+package id
+
+version
+
+createdAt
+
+bbox
+
+products
+
+variables
+
+frames
+
+resolution summary
+
+unit definitions
+
+no-data definitions
+
+file list
+
+checksum / hash
+
+size
+
+display support flags
+
+analysis support flags
+
+6.2 Display Cache
+
+建议至少包含：
+
+raster tile cache
+
+display metadata snapshot
+
+optional lightweight vector overlay
+
+6.3 Analysis Cache
+
+建议至少包含：
+
+规则网格块
+
+多时间帧 values
+
+风/流的 u-v 分量或等价表达
+
+单位
+
+no-data 标记
+
+局部索引信息
+
+7. 推荐数据组织方式
+7.1 按区域组织
+
+离线包应以明确 bbox 或预定义区域为组织单元。
+
+7.2 按时间帧组织
+
+应显式列出：
+
+forecast frames
+
+frame step
+
+start / end
+
+7.3 按变量组织
+
+应允许用户只下载必要变量，例如：
+
+wind
+
+wave
+
+current
+
+pressure
+
+7.4 按分辨率组织
+
+应支持离线分辨率等级控制，避免包体积失控。
+
+8. 本地能力目标
+
+Offline Package 必须能支撑以下本地能力：
+
+8.1 本地显示
+
+使用 display cache 显示天气图层
+
+8.2 本地点查
+
+对某点做多时间帧采样
+
+生成未来多小时时间序列
+
+8.3 本地沿线采样
+
+沿 route polyline 做天气采样
+
+为离线航线规划提供基础能力
+
+8.4 本地 fallback
+
+网络不可用时，优先从离线包提供天气数据
+
+网络恢复时可切回在线 Analysis / Display
+
+9. 服务端职责
+
+本任务要求服务端承担：
+
+离线区域裁剪
+
+多时间帧天气打包
+
+变量集裁剪
+
+display cache 生成
+
+analysis cache 生成
+
+manifest 生成
+
+checksum / integrity 信息生成
+
+下载包版本控制
+
+10. 客户端职责
+
+客户端负责：
+
+下载任务管理
+
+包安装
+
+包校验
+
+本地索引
+
+查询某区域是否有离线包
+
+优先使用本地离线包
+
+display / analysis 本地读取分流
+
+客户端不应负责：
+
+从显示图层反推分析值
+
+自行拼装离线包结构
+
+以临时缓存代替正式离线产品
+
+11. 非目标
+
+本任务不包括：
+
+在线 raster display 接口实现
+
+在线 point sample API 实现
+
+完整路线规划算法
+
+完整 UI 下载管理器实现
+
+前端具体面板样式
+
+服务器天气源解码细节
+
+12. 第一阶段最小可交付
+必做
+
+offline package manifest 定义
+
+display cache 结构定义
+
+analysis cache 结构定义
+
+离线区域 / 时间 / 变量裁剪规则
+
+本地点查可依赖的数据模型
+
+第二阶段
+
+本地 route sampling
+
+更强压缩策略
+
+多包拼接策略
+
+版本升级与差分更新
+
+13. 接受标准
+
+任务完成时，必须满足：
+
+Offline Package 被正式定义为第三条独立生成线
+
+已有 manifest、display cache、analysis cache 的正式结构
+
+离线包可支持本地点查未来多小时天气
+
+离线包可作为未来航线规划与模拟的数据基础
+
+不依赖单纯 png / pbf 缓存完成分析能力
+
+与 Display / Analysis 保持清晰边界
+
+符合 NavSea V11 扩展原则
+
+14. Codex 执行要求
+
+执行此任务时：
+
+优先产出离线包结构定义、manifest 类型、索引规则文件
+
+不得把在线 display 或在线 analysis 逻辑混写进离线任务
+
+不得把离线包简化成“tile cache”
+
+若生成新 .ts/.tsx 文件，必须包含 logger 初始化
+
+若修改旧文件，必须先由用户提供原文件