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 初始化

若修改旧文件，必须先由用户提供原文件