Initial import

2026-03-17 19:52:51 +08:00
commit c957fef15b
39 changed files with 7108 additions and 0 deletions
--- a/tasks/display/NavSea_DisplayProductLine.md
+++ b/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 任务范围
--- a/tasks/display/NavSea_DisplayProductReadabilityTuning.md
+++ b/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 服务端天气显示产品从“低分辨率半透明糊层”改造成“清晰、连续、可读、不会压脏底图的正式显示产品”。**
+
+---
+