chore: 全量快照提交以防磁盘风险
This commit is contained in:
OpenAI Codex
289
tasks/NavSea V11 核心域定义.md
Normal file
289
tasks/NavSea V11 核心域定义.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# NavSea V11 核心域定义（Core Domain Definition）
|
||||
|
||||
## 版本
|
||||
|
||||
v11-core-domain-1 (CN)
|
||||
|
||||
---
|
||||
|
||||
# 1. 文档目的
|
||||
|
||||
本文件用于定义 NavSea 在 V11 架构下的**核心域边界（Domain Boundaries）**。
|
||||
|
||||
NavSea 被定义为：
|
||||
|
||||
> 一个**航海视觉辅助系统**，在离线可生存的前提下，将海图数据、传感器解析结果与环境信息统一供给显示层。
|
||||
|
||||
本文件只定义：
|
||||
|
||||
* 系统结构
|
||||
* 各域职责边界
|
||||
|
||||
本文件**不涉及具体实现**。
|
||||
|
||||
---
|
||||
|
||||
# 2. 系统核心原则
|
||||
|
||||
NavSea 不是：
|
||||
|
||||
* ❌ 航行控制系统
|
||||
* ❌ 设备控制系统
|
||||
* ❌ 单纯地图显示软件
|
||||
|
||||
NavSea 是：
|
||||
|
||||
> 一个**面向显示的多源数据供给系统（Display-Oriented Data Supply System）**
|
||||
|
||||
所有模块的存在目的只有一个：
|
||||
|
||||
> **为显示层提供可靠、可解释、可降级的数据**
|
||||
|
||||
---
|
||||
|
||||
# 3. 顶层结构
|
||||
|
||||
NavSea 由四个核心域组成：
|
||||
|
||||
1. 海图域（Chart Domain）
|
||||
2. 传感器域（Sensor Domain）
|
||||
3. 环境域（Environment Domain）
|
||||
4. 显示域（Display Domain）
|
||||
|
||||
---
|
||||
|
||||
# 4. 海图域（Chart Domain）
|
||||
|
||||
## 4.1 职责
|
||||
|
||||
海图域负责：
|
||||
|
||||
* 向 MapLibre 提供瓦片数据（PBF）
|
||||
* 管理海图数据来源（预置 / 本地缓存 / 在线）
|
||||
* 保证离线可用
|
||||
* 管理数据版本与更新
|
||||
* 决定每个 tile 请求返回哪份数据
|
||||
|
||||
## 4.2 核心能力
|
||||
|
||||
* Base Pack（预置海图）
|
||||
* Region Cache（区域缓存）
|
||||
* Online Pack（在线最新数据）
|
||||
* Tile Resolver（瓦片解析与选择）
|
||||
* Manifest（本地索引与版本管理）
|
||||
|
||||
## 4.3 输出
|
||||
|
||||
海图域输出：
|
||||
|
||||
> MapLibre 可渲染的矢量瓦片（PBF）及相关资源
|
||||
|
||||
## 4.4 非职责
|
||||
|
||||
海图域不得：
|
||||
|
||||
* ❌ 解析 NMEA
|
||||
* ❌ 做航行判断
|
||||
* ❌ 控制 UI
|
||||
* ❌ 处理非地图业务逻辑
|
||||
|
||||
---
|
||||
|
||||
# 5. 传感器域（Sensor Domain）
|
||||
|
||||
## 5.1 职责
|
||||
|
||||
传感器域负责：
|
||||
|
||||
* 接收船内 UDP 数据
|
||||
* 解析 NMEA 电文
|
||||
* 统一数据结构
|
||||
* 维护本船状态
|
||||
* 进行实时判断与推导
|
||||
* 输出可显示的结果
|
||||
|
||||
## 5.2 输入
|
||||
|
||||
* 船内 UDP 网络
|
||||
* NMEA 电文（如 GNRMC、YDMWV 等）
|
||||
|
||||
## 5.3 核心能力
|
||||
|
||||
* 数据解析与标准化
|
||||
* 状态建模（本船 / 目标）
|
||||
* 计算派生数据（航向、风等）
|
||||
* 风险识别与判断
|
||||
* 生成可展示结果
|
||||
|
||||
## 5.4 输出
|
||||
|
||||
传感器域输出：
|
||||
|
||||
> 已解释的、可直接用于显示的结果（不是原始数据）
|
||||
|
||||
示例：
|
||||
|
||||
* 本船状态
|
||||
* 目标信息
|
||||
* 风信息
|
||||
* 风险提示
|
||||
* 告警
|
||||
|
||||
## 5.5 非职责
|
||||
|
||||
传感器域不得：
|
||||
|
||||
* ❌ 管理海图
|
||||
* ❌ 访问互联网 API
|
||||
* ❌ 控制设备
|
||||
* ❌ 直接渲染 UI
|
||||
|
||||
---
|
||||
|
||||
# 6. 环境域（Environment Domain）
|
||||
|
||||
## 6.1 职责
|
||||
|
||||
环境域负责：
|
||||
|
||||
* 获取天气与海洋数据（API）
|
||||
* 本地缓存环境信息
|
||||
* 离线时提供可用数据
|
||||
* 管理数据时效性（新鲜度）
|
||||
|
||||
## 6.2 输入
|
||||
|
||||
* 互联网 API（天气、海流、气压等）
|
||||
|
||||
## 6.3 核心能力
|
||||
|
||||
* API 请求
|
||||
* 数据缓存（带 TTL）
|
||||
* 离线 fallback
|
||||
* 时间戳管理
|
||||
* 数据新鲜度评估
|
||||
|
||||
## 6.4 输出
|
||||
|
||||
环境域输出：
|
||||
|
||||
> 带时间语义的环境信息
|
||||
|
||||
示例：
|
||||
|
||||
* 风预报
|
||||
* 海流
|
||||
* 天气状态
|
||||
|
||||
## 6.5 非职责
|
||||
|
||||
环境域不得：
|
||||
|
||||
* ❌ 管理地图瓦片
|
||||
* ❌ 解析 NMEA
|
||||
* ❌ 控制 UI
|
||||
* ❌ 生成无时间标记的数据
|
||||
|
||||
---
|
||||
|
||||
# 7. 显示域（Display Domain）
|
||||
|
||||
## 7.1 职责
|
||||
|
||||
显示域负责：
|
||||
|
||||
* 将所有数据呈现给用户
|
||||
* 融合多来源数据
|
||||
* 管理 UI 组件与布局
|
||||
* 表达系统状态（包括降级状态）
|
||||
|
||||
## 7.2 输入
|
||||
|
||||
* 海图域（瓦片）
|
||||
* 传感器域（判断结果）
|
||||
* 环境域（环境信息）
|
||||
|
||||
## 7.3 核心能力
|
||||
|
||||
* MapLibre 地图显示
|
||||
* 覆盖层（目标 / 风险 / 航向等）
|
||||
* 信息面板
|
||||
* 告警展示
|
||||
* 数据新鲜度提示
|
||||
* 降级模式提示
|
||||
|
||||
## 7.4 输出
|
||||
|
||||
> 用户看到的完整视觉系统
|
||||
|
||||
## 7.5 非职责
|
||||
|
||||
显示域不得：
|
||||
|
||||
* ❌ 获取数据
|
||||
* ❌ 解析数据
|
||||
* ❌ 管理缓存
|
||||
* ❌ 执行业务计算
|
||||
|
||||
---
|
||||
|
||||
# 8. 域间交互规则
|
||||
|
||||
## 8.1 允许的数据流
|
||||
|
||||
* 海图域 → 显示域
|
||||
* 传感器域 → 显示域
|
||||
* 环境域 → 显示域
|
||||
|
||||
## 8.2 禁止耦合
|
||||
|
||||
* ❌ 海图域 ↔ 传感器域
|
||||
* ❌ 传感器域 ↔ 环境域
|
||||
* ❌ 显示域依赖内部实现细节
|
||||
|
||||
所有交互必须通过**明确的输出接口**。
|
||||
|
||||
---
|
||||
|
||||
# 9. 离线策略定义
|
||||
|
||||
## 9.1 海图域
|
||||
|
||||
* 必须始终提供可显示内容
|
||||
* Base Pack 提供最低保障
|
||||
|
||||
## 9.2 传感器域
|
||||
|
||||
* 必须完全离线可运行
|
||||
* 不依赖互联网
|
||||
|
||||
## 9.3 环境域
|
||||
|
||||
* 离线时使用缓存数据
|
||||
* 必须标注数据时间
|
||||
|
||||
## 9.4 显示域
|
||||
|
||||
* 必须清晰表达数据缺失或过期
|
||||
* 禁止伪装正常状态
|
||||
|
||||
---
|
||||
|
||||
# 10. V11 架构约束
|
||||
|
||||
后续开发必须遵守：
|
||||
|
||||
* 不破坏域边界
|
||||
* 通过 wrapper / adapter 扩展
|
||||
* 不允许跨域逻辑泄漏
|
||||
* 不允许隐式数据共享
|
||||
|
||||
---
|
||||
|
||||
# 11. 最终定义
|
||||
|
||||
NavSea 架构定义为：
|
||||
|
||||
> 一个由海图域、传感器域、环境域独立生成数据，并由显示域统一呈现的离线可生存视觉系统。
|
||||
|
||||
---
|
||||
654
tasks/pbf/MbTiles/navsea_mbtiles_packaging_spec_task_zh.md
Normal file
654
tasks/pbf/MbTiles/navsea_mbtiles_packaging_spec_task_zh.md
Normal file
@@ -0,0 +1,654 @@
|
||||
# NavSea V11 — MBTiles 打包规范设计任务（base / cache / update 三层统一格式）
|
||||
|
||||
## 任务名称
|
||||
NavSea MBTiles Packaging Spec v1 设计任务
|
||||
|
||||
## 任务ID
|
||||
NAVSEA-V11-MBTILES-PACKAGING-SPEC-V1
|
||||
|
||||
## 架构
|
||||
NavSea V11
|
||||
|
||||
## 模式
|
||||
codex6
|
||||
|
||||
## 类型
|
||||
规范设计任务 / 独立领域任务
|
||||
|
||||
---
|
||||
|
||||
## 一、任务目标
|
||||
|
||||
为 NavSea 建立一套 **统一的 MBTiles 打包规范 v1**，覆盖以下三类数据包：
|
||||
|
||||
- `base`：初始基础海图包
|
||||
- `cache`：边看边存运行期缓存包
|
||||
- `update`：后续更新 / patch 覆盖包
|
||||
|
||||
该规范的目标不是只定义一个“能装 tile 的 sqlite 文件”，而是定义一套 **长期稳定、可验证、可导入、可追踪、可演进** 的包格式约束，使后续这些能力都能建立在统一规则上：
|
||||
|
||||
1. MapLibre 请求 tile 时，NavSea 能稳定找到正确数据
|
||||
2. Catalog 能用统一规则管理 winner
|
||||
3. Base / Cache / Update 三层能在相同数据模型下共存
|
||||
4. 你的 PBF 裁剪系统能按统一格式输出可直接导入的包
|
||||
5. 后续可扩展到批量导入、区域更新、增量替换、回滚和清理
|
||||
|
||||
---
|
||||
|
||||
## 二、任务边界
|
||||
|
||||
### 本任务包括
|
||||
|
||||
- 定义三类 MBTiles 包的统一结构
|
||||
- 定义必须存在的 metadata 键
|
||||
- 定义推荐附加 metadata 键
|
||||
- 定义 tiles 表使用规则
|
||||
- 定义 XYZ / TMS 坐标处理约定
|
||||
- 定义 source identity / version / package identity 规范
|
||||
- 定义 base / cache / update 的差异化要求
|
||||
- 定义导入器需要依赖的最小元数据
|
||||
- 定义与 TileCatalog 的协作规则
|
||||
- 定义包验证规则（lint / validator 目标）
|
||||
- 定义 phase1 可落地、phase2 可扩展的版本策略
|
||||
|
||||
### 本任务不包括
|
||||
|
||||
- 实现实际裁剪器
|
||||
- 实现 SQLite 写入器
|
||||
- 实现 ChartSourceIndexer
|
||||
- 实现 Catalog 批量重建器
|
||||
- 实现 Runtime Cache 回写
|
||||
- 实现 Update 下载器
|
||||
- 实现多源矢量 tile merge
|
||||
- 实现 HTTP 服务
|
||||
- 实现 UI 和 MapLibre 样式层
|
||||
|
||||
---
|
||||
|
||||
## 三、设计原则
|
||||
|
||||
### 1. 同一容器，不同语义
|
||||
三类包都使用 MBTiles 容器，但语义不同：
|
||||
|
||||
- `base`：稳定底座
|
||||
- `cache`：运行期补齐
|
||||
- `update`：权威覆盖
|
||||
|
||||
### 2. 统一读取模型
|
||||
不管包类型是什么，读取路径尽量统一：
|
||||
|
||||
- `metadata`
|
||||
- `tiles`
|
||||
- `zoom_level`
|
||||
- `tile_column`
|
||||
- `tile_row`
|
||||
- `tile_data`
|
||||
|
||||
### 3. 统一导入模型
|
||||
导入器只依赖统一 metadata 规范，不依赖“文件名猜测”。
|
||||
|
||||
### 4. 统一 Catalog 协作
|
||||
Catalog 永远用 XYZ key；MBTiles 内部继续沿用标准 TMS row。
|
||||
|
||||
### 5. 版本优先于猜测
|
||||
凡是影响 winner 语义的内容，必须有明确字段，不允许靠文件名或目录名推断。
|
||||
|
||||
### 6. 先做稳定 v1，再做复杂优化
|
||||
v1 不追求最省空间，不追求最高级 patch merge，只追求长期稳定和工程可控。
|
||||
|
||||
---
|
||||
|
||||
## 四、输出成果要求
|
||||
|
||||
Codex 最终必须输出一份完整规范文档，建议文件名：
|
||||
|
||||
`codex/specs/NavSea-MBTiles-Packaging-Spec-v1.md`
|
||||
|
||||
文档中必须完整定义：
|
||||
|
||||
1. 总体设计说明
|
||||
2. 三类包的角色
|
||||
3. 必须 metadata 列表
|
||||
4. 推荐 metadata 列表
|
||||
5. tiles 表要求
|
||||
6. 坐标规范
|
||||
7. version / package id / source id 规范
|
||||
8. base / cache / update 各自约束
|
||||
9. 导入流程依赖字段
|
||||
10. validator 校验规则
|
||||
11. 与 TileCatalog 协同规则
|
||||
12. 向后兼容与未来扩展点
|
||||
|
||||
---
|
||||
|
||||
## 五、三类包的角色定义（必须锁死）
|
||||
|
||||
### 1. base 包
|
||||
|
||||
角色：
|
||||
- 初始基础海图数据
|
||||
- 稳定、可靠、覆盖广
|
||||
- 通常为长期保留包
|
||||
- 作为缺失情况下的兜底来源
|
||||
|
||||
特点：
|
||||
- 以“完整区域覆盖”为主
|
||||
- 更新频率低
|
||||
- 可多包并存（不同区域/不同精度）
|
||||
|
||||
### 2. cache 包
|
||||
|
||||
角色：
|
||||
- 运行过程中“边看边存”的本地补齐包
|
||||
- 优先服务近期查看区域
|
||||
- 生命周期受容量和策略控制
|
||||
|
||||
特点：
|
||||
- 写入频繁
|
||||
- 内容来源于请求路径
|
||||
- 可删、可重建、可清理
|
||||
|
||||
### 3. update 包
|
||||
|
||||
角色：
|
||||
- 对 base 提供权威更新覆盖
|
||||
- 可表示官方修正、局部重算、修补包
|
||||
|
||||
特点：
|
||||
- 明确带版本语义
|
||||
- 不要求覆盖整个区域
|
||||
- 覆盖规则必须强于 base
|
||||
|
||||
---
|
||||
|
||||
## 六、统一容器规范
|
||||
|
||||
### 6.1 必须使用标准 MBTiles 核心表
|
||||
|
||||
至少要求：
|
||||
|
||||
```sql
|
||||
CREATE TABLE metadata (name TEXT, value TEXT);
|
||||
CREATE TABLE tiles (
|
||||
zoom_level INTEGER,
|
||||
tile_column INTEGER,
|
||||
tile_row INTEGER,
|
||||
tile_data BLOB
|
||||
);
|
||||
```
|
||||
|
||||
### 6.2 推荐索引
|
||||
|
||||
```sql
|
||||
CREATE UNIQUE INDEX IF NOT EXISTS tile_index
|
||||
ON tiles (zoom_level, tile_column, tile_row);
|
||||
```
|
||||
|
||||
### 6.3 可选扩展表
|
||||
|
||||
v1 允许定义扩展表，但读取主路径不能依赖扩展表。
|
||||
|
||||
例如未来可扩展：
|
||||
|
||||
- `navsea_manifest`
|
||||
- `navsea_stats`
|
||||
- `navsea_regions`
|
||||
|
||||
但本规范要求：
|
||||
- 没有这些扩展表时，导入器仍能工作
|
||||
|
||||
---
|
||||
|
||||
## 七、metadata 规范（核心部分）
|
||||
|
||||
下面字段分为：
|
||||
|
||||
- **必须字段**
|
||||
- **推荐字段**
|
||||
- **预留字段**
|
||||
|
||||
---
|
||||
|
||||
## 八、必须 metadata 字段
|
||||
|
||||
### 8.1 `format`
|
||||
|
||||
说明：
|
||||
- tile 内容格式
|
||||
|
||||
允许值：
|
||||
- `pbf`
|
||||
- `mvt`
|
||||
- `png`
|
||||
- `jpg`
|
||||
- `jpeg`
|
||||
- `webp`
|
||||
|
||||
要求：
|
||||
- vector 包建议固定使用 `pbf`
|
||||
- 若写 `mvt`，读取端仍应按 `application/x-protobuf` 处理
|
||||
|
||||
---
|
||||
|
||||
### 8.2 `minzoom`
|
||||
|
||||
说明：
|
||||
- 包中最小 zoom
|
||||
|
||||
要求：
|
||||
- 必须是字符串整数
|
||||
- 必须与实际 tiles 表一致或更宽松但不能错误缩窄
|
||||
|
||||
---
|
||||
|
||||
### 8.3 `maxzoom`
|
||||
|
||||
说明：
|
||||
- 包中最大 zoom
|
||||
|
||||
要求：
|
||||
- 必须是字符串整数
|
||||
|
||||
---
|
||||
|
||||
### 8.4 `bounds`
|
||||
|
||||
说明：
|
||||
- 地理范围
|
||||
|
||||
格式：
|
||||
- `minLon,minLat,maxLon,maxLat`
|
||||
|
||||
要求：
|
||||
- 使用 WGS84 经纬度
|
||||
- 即使是局部 update / cache 包也必须提供
|
||||
|
||||
---
|
||||
|
||||
### 8.5 `navsea_package_type`
|
||||
|
||||
说明：
|
||||
- NavSea 包类型
|
||||
|
||||
允许值：
|
||||
- `base`
|
||||
- `cache`
|
||||
- `update`
|
||||
|
||||
要求：
|
||||
- 不允许缺失
|
||||
- 导入器必须依赖该字段识别包类型
|
||||
- 不允许仅靠文件名识别
|
||||
|
||||
---
|
||||
|
||||
### 8.6 `navsea_package_id`
|
||||
|
||||
说明：
|
||||
- 包唯一标识
|
||||
|
||||
要求：
|
||||
- 全局唯一
|
||||
- 同一个文件重新导出但语义相同，也建议保持新 id
|
||||
- 不得为空
|
||||
|
||||
建议格式：
|
||||
- UUID
|
||||
- 或 `navsea.<type>.<region>.<timestamp>.<shortid>`
|
||||
|
||||
---
|
||||
|
||||
### 8.7 `navsea_source_family`
|
||||
|
||||
说明：
|
||||
- 该包所属图源家族 / 数据源体系
|
||||
|
||||
用途：
|
||||
- 区分不同地图来源，避免不兼容数据混用
|
||||
|
||||
示例：
|
||||
- `navsea.chart.jp.main`
|
||||
- `navsea.chart.user.custom`
|
||||
- `navsea.chart.cache.runtime`
|
||||
|
||||
要求：
|
||||
- 不得为空
|
||||
|
||||
---
|
||||
|
||||
### 8.8 `navsea_schema_version`
|
||||
|
||||
说明：
|
||||
- NavSea 打包规范版本
|
||||
|
||||
v1 固定值：
|
||||
- `1`
|
||||
|
||||
要求：
|
||||
- 导入器必须读取该字段
|
||||
- 后续 schema 演进必须通过该字段区分
|
||||
|
||||
---
|
||||
|
||||
## 九、推荐 metadata 字段
|
||||
|
||||
### 9.1 `name`
|
||||
人类可读名称
|
||||
|
||||
### 9.2 `description`
|
||||
包描述
|
||||
|
||||
### 9.3 `type`
|
||||
允许值通常：
|
||||
- `overlay`
|
||||
- `baselayer`
|
||||
|
||||
### 9.4 `version`
|
||||
原始数据版本 / 切片版本
|
||||
|
||||
### 9.5 `navsea_region_id`
|
||||
区域标识，例如：
|
||||
- `japan-east`
|
||||
- `seto-inland-sea`
|
||||
|
||||
### 9.6 `navsea_generated_at`
|
||||
生成时间（ISO8601）
|
||||
|
||||
### 9.7 `navsea_priority_hint`
|
||||
导入默认优先级提示
|
||||
|
||||
### 9.8 `navsea_tile_count`
|
||||
包内 tile 数量
|
||||
|
||||
### 9.9 `navsea_data_hash`
|
||||
包级 hash / manifest hash
|
||||
|
||||
### 9.10 `navsea_projection`
|
||||
v1 固定建议：
|
||||
- `webmercator`
|
||||
|
||||
---
|
||||
|
||||
## 十、update 包专用推荐字段
|
||||
|
||||
### 10.1 `navsea_update_version`
|
||||
更新版本号，必须可比较
|
||||
|
||||
### 10.2 `navsea_update_parent_family`
|
||||
说明它 intended 覆盖哪个 source family
|
||||
|
||||
### 10.3 `navsea_update_scope`
|
||||
允许值建议：
|
||||
- `partial`
|
||||
- `regional`
|
||||
- `full`
|
||||
|
||||
### 10.4 `navsea_effective_from`
|
||||
生效时间
|
||||
|
||||
### 10.5 `navsea_supersedes`
|
||||
被其覆盖/替代的 package id 列表（逗号分隔或 JSON 字符串）
|
||||
|
||||
---
|
||||
|
||||
## 十一、cache 包专用推荐字段
|
||||
|
||||
### 11.1 `navsea_cache_created_at`
|
||||
缓存包创建时间
|
||||
|
||||
### 11.2 `navsea_cache_policy`
|
||||
例如：
|
||||
- `runtime-view-cache`
|
||||
|
||||
### 11.3 `navsea_cache_mutable`
|
||||
建议值：
|
||||
- `true`
|
||||
|
||||
### 11.4 `navsea_eviction_hint`
|
||||
例如：
|
||||
- `lru`
|
||||
- `manual`
|
||||
- `none`
|
||||
|
||||
---
|
||||
|
||||
## 十二、base 包专用推荐字段
|
||||
|
||||
### 12.1 `navsea_base_edition`
|
||||
基础版次
|
||||
|
||||
### 12.2 `navsea_coverage_tier`
|
||||
例如：
|
||||
- `national`
|
||||
- `regional`
|
||||
- `harbor-detail`
|
||||
|
||||
### 12.3 `navsea_is_fallback`
|
||||
是否兜底层提示
|
||||
- `true`
|
||||
- `false`
|
||||
|
||||
---
|
||||
|
||||
## 十三、tiles 表使用规则
|
||||
|
||||
### 13.1 坐标规则
|
||||
MBTiles 内部使用：
|
||||
- `zoom_level`
|
||||
- `tile_column`
|
||||
- `tile_row`（TMS）
|
||||
|
||||
### 13.2 读取规则
|
||||
NavSea 外部统一使用 XYZ：
|
||||
- HTTP
|
||||
- MapLibre
|
||||
- Catalog
|
||||
- Provider 请求
|
||||
|
||||
仅在 `MbtilesReader` 查询 SQLite 时转换：
|
||||
|
||||
```ts
|
||||
tmsY = (1 << z) - 1 - y
|
||||
```
|
||||
|
||||
### 13.3 tile_data 规则
|
||||
- 必须为该 `format` 对应的合法内容
|
||||
- vector 建议使用 gzip 压缩的 pbf（按你的切片系统惯例执行）
|
||||
- 不允许写入“假 tile”混入生产包
|
||||
|
||||
---
|
||||
|
||||
## 十四、统一 source identity 规范
|
||||
|
||||
规范必须区分以下三个概念：
|
||||
|
||||
### 14.1 package_id
|
||||
某个物理包的唯一标识
|
||||
|
||||
### 14.2 source_family
|
||||
该包所属图源体系
|
||||
|
||||
### 14.3 runtime source record id
|
||||
导入到系统后的 registry/source id
|
||||
|
||||
规范中必须明确：
|
||||
- `package_id` ≠ `source_family`
|
||||
- registry id 可以基于 package_id 生成，但不是同一概念
|
||||
|
||||
---
|
||||
|
||||
## 十五、Catalog 协同规则
|
||||
|
||||
文档必须明确写出：
|
||||
|
||||
1. Catalog key 统一为 XYZ
|
||||
2. Catalog winner 记录的是“哪个 source 胜出”
|
||||
3. MBTiles 包本身不承担 winner 决策
|
||||
4. 包的 metadata 只提供导入决策输入
|
||||
5. winner 决策由导入器 / Catalog / CompositeProvider 组合完成
|
||||
|
||||
---
|
||||
|
||||
## 十六、默认优先级建议（写入规范）
|
||||
|
||||
文档必须给出默认值建议：
|
||||
|
||||
- `update = 300`
|
||||
- `cache = 200`
|
||||
- `base = 100`
|
||||
|
||||
并注明：
|
||||
- 这是系统默认导入优先级
|
||||
- 不要求写死在 MBTiles 内
|
||||
- `navsea_priority_hint` 只能是 hint，真正 winner 以系统侧规则为准
|
||||
|
||||
---
|
||||
|
||||
## 十七、导入器最低依赖字段
|
||||
|
||||
文档必须明确：
|
||||
导入器至少依赖以下 metadata 才能工作：
|
||||
|
||||
- `navsea_package_type`
|
||||
- `navsea_package_id`
|
||||
- `navsea_source_family`
|
||||
- `navsea_schema_version`
|
||||
- `format`
|
||||
- `minzoom`
|
||||
- `maxzoom`
|
||||
- `bounds`
|
||||
|
||||
若缺少这些字段，导入器应拒绝导入或进入明确的修复流程。
|
||||
|
||||
---
|
||||
|
||||
## 十八、Validator / Lint 规则（必须定义）
|
||||
|
||||
Codex 需要在规范里写出一套 validator 目标规则，至少包括：
|
||||
|
||||
### 18.1 结构校验
|
||||
- `metadata` 表存在
|
||||
- `tiles` 表存在
|
||||
- `tile_index` 唯一索引存在（推荐但可自动修复）
|
||||
|
||||
### 18.2 metadata 校验
|
||||
- 必填字段存在
|
||||
- `navsea_package_type` 合法
|
||||
- `format` 合法
|
||||
- `minzoom <= maxzoom`
|
||||
- `bounds` 格式合法
|
||||
|
||||
### 18.3 数据校验
|
||||
- `tile_data` 非空
|
||||
- `zoom_level/tile_column/tile_row` 不为 null
|
||||
- 不允许重复 tile 键
|
||||
|
||||
### 18.4 语义校验
|
||||
- `cache` 包必须标记为 mutable
|
||||
- `update` 包必须有 update version 或明确说明为何没有
|
||||
- `base` 包应有稳定 region/source family 标识
|
||||
|
||||
---
|
||||
|
||||
## 十九、phase 划分建议（规范文档里要写）
|
||||
|
||||
### Phase A：规范落地
|
||||
- 先只写规范文档
|
||||
- 不改已有代码
|
||||
|
||||
### Phase B：打包器适配
|
||||
- 让你的 PBF 裁剪系统按规范输出 metadata
|
||||
- 生成最小合法 MBTiles
|
||||
|
||||
### Phase C：导入器适配
|
||||
- ChartSourceRegistry / TileCatalog 能按 metadata 导入
|
||||
|
||||
### Phase D：运行期写包
|
||||
- cache 包写入
|
||||
- update 包导入与覆盖
|
||||
|
||||
---
|
||||
|
||||
## 二十、对 Codex 的具体写作要求
|
||||
|
||||
Codex 输出的规范文档必须：
|
||||
|
||||
1. 使用中文
|
||||
2. 面向工程实现，不写成纯概念稿
|
||||
3. 要有表格或清晰列表列出 metadata 字段
|
||||
4. 要明确哪些字段是必须、推荐、预留
|
||||
5. 要明确 base / cache / update 的差异
|
||||
6. 要明确 Catalog 与 Reader 的职责边界
|
||||
7. 要包含一个“最小合法 MBTiles 示例”
|
||||
8. 要包含一个“推荐 metadata 示例”
|
||||
9. 要包含一个“错误包示例”
|
||||
10. 要包含未来扩展但当前不启用的字段说明
|
||||
|
||||
---
|
||||
|
||||
## 二十一、建议加入的示例内容
|
||||
|
||||
规范文档中至少需要 3 组示例：
|
||||
|
||||
### 示例 1：base 包 metadata 示例
|
||||
|
||||
```text
|
||||
format = pbf
|
||||
minzoom = 0
|
||||
maxzoom = 12
|
||||
bounds = 122.0,24.0,146.0,46.0
|
||||
navsea_package_type = base
|
||||
navsea_package_id = ...
|
||||
navsea_source_family = navsea.chart.jp.main
|
||||
navsea_schema_version = 1
|
||||
```
|
||||
|
||||
### 示例 2：cache 包 metadata 示例
|
||||
|
||||
```text
|
||||
format = pbf
|
||||
minzoom = 8
|
||||
maxzoom = 14
|
||||
bounds = ...
|
||||
navsea_package_type = cache
|
||||
navsea_package_id = ...
|
||||
navsea_source_family = navsea.chart.cache.runtime
|
||||
navsea_schema_version = 1
|
||||
navsea_cache_mutable = true
|
||||
```
|
||||
|
||||
### 示例 3：update 包 metadata 示例
|
||||
|
||||
```text
|
||||
format = pbf
|
||||
minzoom = 10
|
||||
maxzoom = 14
|
||||
bounds = ...
|
||||
navsea_package_type = update
|
||||
navsea_package_id = ...
|
||||
navsea_source_family = navsea.chart.jp.main
|
||||
navsea_schema_version = 1
|
||||
navsea_update_version = 2026.03.18-01
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 二十二、Definition of Done
|
||||
|
||||
本任务完成的标志是：
|
||||
|
||||
- 已产出一份完整中文规范文档
|
||||
- 规范文档可直接指导你的 PBF 裁剪系统输出 MBTiles
|
||||
- 文档已清楚区分 base / cache / update
|
||||
- 文档已定义必须 metadata
|
||||
- 文档已定义 Validator 规则
|
||||
- 文档已明确 Catalog 与 Reader 的职责边界
|
||||
- 文档已包含最小合法示例
|
||||
|
||||
---
|
||||
|
||||
## 二十三、最短结论
|
||||
|
||||
这个任务的唯一目标是：
|
||||
|
||||
**把 NavSea 的 MBTiles 从“只是一个 sqlite 文件”提升为“有明确角色、明确元数据、明确导入规则、明确演进路径的统一包格式”。**
|
||||
230
tasks/pbf/MbTiles/navsea_mbtiles_validator_task_zh.md
Normal file
230
tasks/pbf/MbTiles/navsea_mbtiles_validator_task_zh.md
Normal file
@@ -0,0 +1,230 @@
|
||||
# NavSea V11 — MBTiles 包验证器（Validator / Lint）任务
|
||||
|
||||
## 任务名称
|
||||
NavSea MBTiles Validator / Lint v1
|
||||
|
||||
## 任务ID
|
||||
NAVSEA-V11-MBTILES-VALIDATOR-V1
|
||||
|
||||
## 架构
|
||||
NavSea V11
|
||||
|
||||
## 模式
|
||||
codex6
|
||||
|
||||
## 类型
|
||||
工具模块（独立可运行 / 可集成）
|
||||
|
||||
---
|
||||
|
||||
## 一、任务目标
|
||||
|
||||
实现一个 **MBTiles 验证器（validator / lint 工具）**，用于：
|
||||
|
||||
- 校验 MBTiles 是否符合 NavSea Packaging Spec v1
|
||||
- 在导入前发现问题
|
||||
- 为裁剪系统输出提供自动质量检查
|
||||
- 为导入器提供“是否允许导入”的判断依据
|
||||
|
||||
---
|
||||
|
||||
## 二、使用场景
|
||||
|
||||
该工具必须支持以下使用方式：
|
||||
|
||||
1. CLI 校验：
|
||||
|
||||
```bash
|
||||
navsea-mbtiles-validate ./test.mbtiles
|
||||
```
|
||||
|
||||
2. 导入前自动校验：
|
||||
|
||||
```ts
|
||||
validator.validate(filePath)
|
||||
```
|
||||
|
||||
3. CI 自动检查：
|
||||
|
||||
- 批量扫描目录
|
||||
- 输出报告
|
||||
|
||||
---
|
||||
|
||||
## 三、模块结构
|
||||
|
||||
```text
|
||||
src/tools/mbtiles-validator/
|
||||
MbtilesValidator.ts
|
||||
rules/
|
||||
MetadataRules.ts
|
||||
SchemaRules.ts
|
||||
TileRules.ts
|
||||
NavSeaRules.ts
|
||||
reporter/
|
||||
ValidationReporter.ts
|
||||
cli/
|
||||
index.ts
|
||||
__tests__/
|
||||
validator.test.ts
|
||||
README.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 四、核心接口
|
||||
|
||||
```ts
|
||||
export type ValidationIssue = {
|
||||
level: "error" | "warning";
|
||||
code: string;
|
||||
message: string;
|
||||
};
|
||||
|
||||
export type ValidationResult = {
|
||||
valid: boolean;
|
||||
issues: ValidationIssue[];
|
||||
};
|
||||
|
||||
export interface MbtilesValidator {
|
||||
validate(path: string): Promise<ValidationResult>;
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 五、校验规则（必须实现）
|
||||
|
||||
### 1. Schema 校验
|
||||
|
||||
- metadata 表存在
|
||||
- tiles 表存在
|
||||
- tiles 字段完整：
|
||||
- zoom_level
|
||||
- tile_column
|
||||
- tile_row
|
||||
- tile_data
|
||||
|
||||
---
|
||||
|
||||
### 2. Metadata 校验（强制）
|
||||
|
||||
必须存在：
|
||||
|
||||
- format
|
||||
- minzoom
|
||||
- maxzoom
|
||||
- bounds
|
||||
- navsea_package_type
|
||||
- navsea_package_id
|
||||
- navsea_source_family
|
||||
- navsea_schema_version
|
||||
|
||||
---
|
||||
|
||||
### 3. Metadata 合法性
|
||||
|
||||
- format ∈ [pbf, mvt, png, jpg, jpeg, webp]
|
||||
- minzoom ≤ maxzoom
|
||||
- bounds 为 4 个数值
|
||||
- navsea_package_type ∈ [base, cache, update]
|
||||
|
||||
---
|
||||
|
||||
### 4. Tile 数据校验
|
||||
|
||||
- tile_data 非空
|
||||
- 不允许重复 (z,x,y)
|
||||
- tile_row 合法（>=0）
|
||||
|
||||
---
|
||||
|
||||
### 5. NavSea 语义校验
|
||||
|
||||
#### base 包
|
||||
- 必须有 source_family
|
||||
- 不允许 mutable
|
||||
|
||||
#### cache 包
|
||||
- 必须 navsea_cache_mutable = true
|
||||
|
||||
#### update 包
|
||||
- 必须 navsea_update_version
|
||||
|
||||
---
|
||||
|
||||
### 6. 推荐校验（warning）
|
||||
|
||||
- metadata.name 存在
|
||||
- metadata.description 存在
|
||||
- navsea_generated_at 存在
|
||||
- navsea_tile_count 与实际一致
|
||||
|
||||
---
|
||||
|
||||
## 六、错误等级定义
|
||||
|
||||
### error（阻止导入）
|
||||
|
||||
- schema 错误
|
||||
- metadata 缺失关键字段
|
||||
- format 非法
|
||||
- navsea_package_type 非法
|
||||
|
||||
### warning（允许导入）
|
||||
|
||||
- 缺少描述信息
|
||||
- 缺少推荐字段
|
||||
- tile_count 不一致
|
||||
|
||||
---
|
||||
|
||||
## 七、CLI 输出要求
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
[ERROR] missing metadata: navsea_package_id
|
||||
[ERROR] invalid format: abc
|
||||
[WARN ] missing metadata: description
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 八、测试要求
|
||||
|
||||
必须覆盖：
|
||||
|
||||
- 合法 mbtiles → valid=true
|
||||
- 缺 metadata → error
|
||||
- 错误 format → error
|
||||
- cache 未标 mutable → error
|
||||
- update 无 version → error
|
||||
|
||||
---
|
||||
|
||||
## 九、完成标准
|
||||
|
||||
- CLI 可运行
|
||||
- validate() API 可调用
|
||||
- 输出结构稳定
|
||||
- 可集成导入流程
|
||||
- 测试通过
|
||||
|
||||
---
|
||||
|
||||
## 十、未来扩展（不要在本任务实现）
|
||||
|
||||
- 自动修复（fix mode）
|
||||
- 批量扫描目录
|
||||
- 可视化报告
|
||||
- 与导入器联动
|
||||
|
||||
---
|
||||
|
||||
## 十一、结论
|
||||
|
||||
该模块是：
|
||||
|
||||
**NavSea 数据入口的“质量闸门”**
|
||||
|
||||
@@ -19,7 +19,7 @@ rules:
|
||||
- field_name_jp: 分類番号
|
||||
field_name_std: class_code
|
||||
field_group: source_legacy
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: legacy_render_code
|
||||
notes: Legacy class code used during transition and audits.
|
||||
@@ -29,39 +29,39 @@ rules:
|
||||
keep_in_delivery: true
|
||||
keep_in_engineering: true
|
||||
normalization_class: legacy_render_code
|
||||
notes: Legacy shape class code used during transition and audits.
|
||||
notes: Legacy shape class code retained for old at-style navigation mark rendering, transition, and audits.
|
||||
- field_name_jp: 表示用番号
|
||||
field_name_std: display_code
|
||||
field_group: source_legacy
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: legacy_render_code
|
||||
notes: Legacy display code retained until all rendering migrates to chart_* fields.
|
||||
- field_name_jp: 灯色
|
||||
field_name_std: light_color_raw_code
|
||||
field_group: light
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: field_value_normalization
|
||||
notes: Legacy raw color code maps into light_color_code.
|
||||
- field_name_jp: 灯略記
|
||||
field_name_std: light_character_remark
|
||||
field_group: light
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: content_text
|
||||
notes: User-visible light remark should remain reversible.
|
||||
- field_name_jp: 明弧/分孤
|
||||
field_name_std: light_sector_remark
|
||||
field_group: light
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: field_value_normalization
|
||||
notes: Legacy light sector remark maps into light_sector_mode and trace fields.
|
||||
- field_name_jp: 表示位置
|
||||
field_name_std: label_position_code_legacy
|
||||
field_group: labels
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: field_value_normalization
|
||||
notes: Legacy label position code maps into chart_label_position_code.
|
||||
@@ -96,28 +96,28 @@ rules:
|
||||
- field_name_jp: 水深値(m)
|
||||
field_name_std: depth_value_m_legacy
|
||||
field_group: normalized_numeric
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: numeric_normalization
|
||||
notes: Legacy depth string is normalized into depth_value_m.
|
||||
- field_name_jp: 高さ(m)
|
||||
field_name_std: clearance_height_m_legacy
|
||||
field_group: normalized_numeric
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: numeric_normalization
|
||||
notes: Legacy height string is normalized into clearance_height_m.
|
||||
- field_name_jp: 高さ/深度(m)
|
||||
field_name_std: height_or_depth_m_legacy
|
||||
field_group: normalized_numeric
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: numeric_normalization
|
||||
notes: Mixed height/depth legacy string maps into least_depth_m or clearance semantics.
|
||||
- field_name_jp: 角度
|
||||
field_name_std: bearing_deg_legacy
|
||||
field_group: normalized_numeric
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: numeric_normalization
|
||||
notes: Legacy angle string is normalized into bearing_deg.
|
||||
@@ -131,21 +131,21 @@ rules:
|
||||
- field_name_jp: 目的分類番号
|
||||
field_name_std: purpose_class_code
|
||||
field_group: source_legacy
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: legacy_render_code
|
||||
notes: Legacy purpose code is preserved under a standardized key.
|
||||
- field_name_jp: 縮尺選択コード
|
||||
field_name_std: scale_selection_code
|
||||
field_group: source_legacy
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: legacy_render_code
|
||||
notes: Legacy scale-selection code is preserved under a standardized key.
|
||||
- field_name_jp: 表示重要度
|
||||
field_name_std: display_priority_code
|
||||
field_group: source_legacy
|
||||
keep_in_delivery: true
|
||||
keep_in_delivery: false
|
||||
keep_in_engineering: true
|
||||
normalization_class: legacy_render_code
|
||||
notes: Legacy display-priority code is preserved under a standardized key.
|
||||
|
||||
Reference in New Issue
Block a user