458 lines
11 KiB
Markdown
458 lines
11 KiB
Markdown
# PBF Pipeline 正式流程 v1
|
||
|
||
日期：2026-10-06
|
||
状态：实现基线
|
||
适用仓库：`/root/sourceserver/pbf`
|
||
|
||
## 1. 总体边界
|
||
|
||
PBF 项目负责从任意 Provider 的 Style、PBF/MVT、Sprite、Glyph 和 Provider 语义资料生产符合公开 NavSea Provider Contract 的 `NavSea Provider Package`。
|
||
|
||
PBF 项目不生成 `ProviderExecutionPlan`。ProviderExecutionPlan 只属于 NavSea。
|
||
|
||
NavSea 的职责是公开 Contract、验证 Provider Package、生成 Chart Provider Profile、ProviderCompiler 编译、ChartRuntime 安装和 Runtime 消费。
|
||
|
||
第三方可以完全绕过官方 PBF Pipeline，只要自行生产的数据满足公开 NavSea Provider Contract。
|
||
|
||
## 2. Pipeline v1
|
||
|
||
```text
|
||
PBF-01 Provider Source Intake
|
||
↓
|
||
PBF-02 Style Visual Object Extract
|
||
↓
|
||
PBF-03 Actual Visual Object Instantiate
|
||
↓
|
||
PBF-04 Provider → NavSea Standard Mapping
|
||
↓
|
||
PBF-05 Provider Policy Compile
|
||
↓
|
||
PBF-06 Provider Package Validate
|
||
↓
|
||
PBF-07 NavSea Provider Package Export
|
||
```
|
||
|
||
Pipeline 正式终点是 `NavSea Provider Package`，不是 `ProviderExecutionPlan`。
|
||
|
||
## 3. PBF-01 Provider Source Intake
|
||
|
||
目标：把不同 Provider 的原始输入统一整理成可重复、可校验的 Source Intake。
|
||
|
||
输入至少支持：
|
||
|
||
- provider identity
|
||
- dataset identity
|
||
- Style JSON / URL
|
||
- PBF / MVT / MBTiles / XYZ URL
|
||
- Sprite JSON / PNG
|
||
- Glyph URL 或资源
|
||
- Provider semantic metadata
|
||
- sample tiles
|
||
- bounds
|
||
- minZoom / maxZoom
|
||
|
||
建议输出：
|
||
|
||
```text
|
||
work/<provider-id>/
|
||
intake/
|
||
source-manifest.json
|
||
style.snapshot.json
|
||
sprite/
|
||
semantic-source/
|
||
samples/
|
||
intake-report.json
|
||
```
|
||
|
||
`source-manifest.json` 至少记录 providerId、datasetId、providerVersion、style、tileSource、sprite、glyphs、bounds、zoom、sampleTiles、semanticSources、sourceFingerprint。
|
||
|
||
Gate：
|
||
|
||
- Provider identity 已确定
|
||
- Dataset identity 已确定
|
||
- Style 可读取
|
||
- PBF 来源可定位
|
||
- Sprite/Glyph 状态明确
|
||
- 输入 Hash/Fingerprint 已记录
|
||
- 采样范围已确定
|
||
|
||
## 4. PBF-02 Style Visual Object Extract
|
||
|
||
目标：只从 Style + Sprite 中提取视觉事实，不在本阶段直接决定 NavSea Standard Layer。
|
||
|
||
当前工具：
|
||
|
||
```text
|
||
tools/style-visual-object/style_vo_tool.py
|
||
```
|
||
|
||
输入：
|
||
|
||
- style.snapshot.json
|
||
- Sprite
|
||
|
||
输出：
|
||
|
||
```text
|
||
anonymous-catalog.json
|
||
_sprite/sprite.json
|
||
_sprite/sprite.png
|
||
```
|
||
|
||
核心原则：产物为 Anonymous Visual Object。source-layer、Provider 字段名、Provider 对象类名称只作为 provenance/audit evidence，不得直接作为 NavSea Layer 映射依据。
|
||
|
||
Gate：
|
||
|
||
- Anonymous Visual Object 可重复稳定生成
|
||
- 同输入重复执行结果一致
|
||
- 视觉组件与 Style Layer 引用完整
|
||
- 不包含 Provider-specific NavSea Layer 硬编码
|
||
|
||
## 5. PBF-03 Actual Visual Object Instantiate
|
||
|
||
目标：把 Style 定义与真实 PBF feature 结合，生成实际出现的视觉对象实例。
|
||
|
||
当前工具：
|
||
|
||
```text
|
||
tools/visual-object-instantiation/instantiate_pbf_visual_objects.py
|
||
```
|
||
|
||
正式 Pipeline 必须去除 CM95-specific 主逻辑硬编码。Provider-specific 行为只能通过 manifest、adapter config、declarative metadata 或 policy input 表达。
|
||
|
||
输入：
|
||
|
||
- Anonymous Visual Object Catalog
|
||
- Style
|
||
- Sprite
|
||
- 真实 PBF/MVT
|
||
- sample tiles
|
||
- Provider semantic metadata（辅助证据）
|
||
|
||
建议输出：
|
||
|
||
```text
|
||
actual-visual-object-catalog.json
|
||
visual-object-occurrences.json
|
||
instantiation-report.json
|
||
```
|
||
|
||
每个 occurrence 至少可追踪 feature identity、tile、source、source-layer、matched style layers、render components、field evidence、geometry type、zoom、provenance。
|
||
|
||
Gate：
|
||
|
||
- 真实 PBF feature 与 Style 命中关系可对应
|
||
- 同一原始 feature 的多个 render component 可归并
|
||
- 不按屏幕距离拼接对象
|
||
- occurrence 可回溯原始 feature
|
||
|
||
## 6. PBF-04 Provider → NavSea Standard Mapping
|
||
|
||
目标：把 Provider Actual Visual Object / Composite Visual Evidence 映射到 NavSea Frozen Standard Catalog / Standard Layer。
|
||
|
||
输入：
|
||
|
||
- Provider Actual Visual Object Catalog
|
||
- NavSea Frozen Standard Catalog
|
||
- Visual Matcher 建议
|
||
- Provider 官方语义资料
|
||
- 人工审核结果
|
||
|
||
NavSea Frozen Standard Catalog：
|
||
|
||
```text
|
||
tools/style-visual-object/output/navsea-standard/standard-catalog.json
|
||
```
|
||
|
||
默认只读，不重新生成或修改。
|
||
|
||
最终映射状态：
|
||
|
||
- VISUAL_OBJECT_MATCH
|
||
- LAYER_ONLY
|
||
- COMPONENT_ONLY
|
||
- AMBIGUOUS
|
||
- UNKNOWN
|
||
|
||
VISUAL_OBJECT_MATCH：可确定到 Standard Visual Object + Standard Layer。
|
||
|
||
LAYER_ONLY：可确定 Standard Layer，但不要求存在 1:1 Standard Visual Object；这是正常结果。
|
||
|
||
COMPONENT_ONLY：只表示完整视觉对象组成部分，如 topmark、buoy_body、beacon_body、light、auxiliary_mark、fill_pattern、line_pattern、text、other；COMPONENT 自身不决定最终 Standard Layer。
|
||
|
||
AMBIGUOUS：存在多个合理候选，禁止 Runtime 任意选择。
|
||
|
||
UNKNOWN：无法可靠确定 Standard Layer。
|
||
|
||
建议输出：
|
||
|
||
```text
|
||
mapping/
|
||
provider-layer-assignment.json
|
||
provider-layer-assignment.csv
|
||
provider-layer-assignment.html
|
||
mapping-validation-report.json
|
||
```
|
||
|
||
Gate：
|
||
|
||
- 所有 occurrence 有明确状态
|
||
- 无未审核项
|
||
- AMBIGUOUS/UNKNOWN 写入 limitations
|
||
- 人工决定优先于自动 matcher
|
||
- matcher 不覆盖人工结论
|
||
- Provider 语义建议与人工结论冲突只产生 WARN
|
||
|
||
## 7. PBF-05 Provider Policy Compile
|
||
|
||
这是当前 Pipeline 缺失的关键桥梁。
|
||
|
||
输入：
|
||
|
||
```text
|
||
Visual Object / Layer Assignment
|
||
+ Provider Source Facts
|
||
+ Provider Semantic Metadata
|
||
+ Capabilities
|
||
+ Human Review
|
||
```
|
||
|
||
输出：
|
||
|
||
```text
|
||
Provider Policy
|
||
```
|
||
|
||
NavSea Provider、CM95 Provider 和未来第三方 Provider 必须使用同一 Policy Schema。
|
||
|
||
禁止：
|
||
|
||
```text
|
||
NavSea → 特殊 Runtime 直通
|
||
CM95 → Provider Policy
|
||
```
|
||
|
||
统一为：
|
||
|
||
```text
|
||
NavSea Provider → NavSea Provider Policy → NavSea Standard Layer
|
||
CM95 Provider → CM95 Provider Policy → NavSea Standard Layer
|
||
Provider B → Provider B Policy → NavSea Standard Layer
|
||
```
|
||
|
||
建议新增：
|
||
|
||
```text
|
||
tools/provider-policy-compiler/
|
||
README.md
|
||
compile_provider_policy.py
|
||
validate_provider_policy.py
|
||
schema/
|
||
tests/
|
||
```
|
||
|
||
Compiler 输入：
|
||
|
||
- source-manifest.json
|
||
- actual-visual-object-catalog.json
|
||
- provider-layer-assignment.json
|
||
- Provider semantic metadata
|
||
- capability declaration
|
||
- manual review result
|
||
- NavSea Standard Catalog identity
|
||
|
||
Provider Policy 至少覆盖：
|
||
|
||
- schemaVersion
|
||
- provider
|
||
- dataset
|
||
- standardCatalog
|
||
- resources
|
||
- mapping
|
||
- display
|
||
- pickup
|
||
- planning
|
||
- danger
|
||
- capabilities
|
||
- unresolved
|
||
- limitations
|
||
- provenance
|
||
- fingerprints
|
||
|
||
Provider Policy 不包含 ProviderExecutionPlan、Runtime cache、最终 query buckets、Runtime layer handles 或 React/MapLibre Runtime 对象。
|
||
|
||
Gate：
|
||
|
||
- NavSea 和 CM95 Policy 通过同一 validator
|
||
- Schema 无 provider-specific 分叉
|
||
- Python 主逻辑不得写 provider == cm95
|
||
- Mapping 可追溯到 PBF-04
|
||
- unresolved/limitations 不得静默丢失
|
||
|
||
## 8. PBF-06 Provider Package Validate
|
||
|
||
目标：在离开 PBF 项目前验证 Provider Package 是否符合公开 NavSea Provider Contract。
|
||
|
||
验证至少包括：
|
||
|
||
- providerId / datasetId / version
|
||
- Style / PBF / Sprite / Glyph / bounds / zoom
|
||
- Standard Layer mapping
|
||
- Standard Visual Object reference
|
||
- COMPONENT/LAYER_ONLY/UNKNOWN/AMBIGUOUS 约束
|
||
- Display / Pickup / Planning / Danger
|
||
- capabilities
|
||
- schema version
|
||
- file/resource hash
|
||
- package fingerprint
|
||
- standard catalog fingerprint
|
||
- source fingerprint
|
||
- unresolved / unsupported / partial capability / missing resource
|
||
|
||
输出：
|
||
|
||
```text
|
||
validation/
|
||
provider-package-validation.json
|
||
provider-package-validation.md
|
||
```
|
||
|
||
结果只能是：
|
||
|
||
- PASS
|
||
- PASS_WITH_WARNINGS
|
||
- FAIL
|
||
|
||
FAIL 时禁止进入 PBF-07。
|
||
|
||
## 9. PBF-07 NavSea Provider Package Export
|
||
|
||
目标：生成可直接交给 NavSea 或第三方 Validator 的正式 Provider Package。
|
||
|
||
建议：
|
||
|
||
```text
|
||
dist/
|
||
<provider-id>/
|
||
<dataset-id>/
|
||
<version>/
|
||
provider-package.json
|
||
provider-policy.json
|
||
resources/
|
||
style.json
|
||
sprite.json
|
||
sprite.png
|
||
mapping/
|
||
layer-assignment.json
|
||
reports/
|
||
validation.json
|
||
validation.md
|
||
MANIFEST.json
|
||
```
|
||
|
||
URL 型资源允许只保存 URL、hash、expected content identity、availability/fallback policy，不要求将所有 PBF 数据打入包。
|
||
|
||
MANIFEST 至少包含：
|
||
|
||
- package schema version
|
||
- provider identity
|
||
- dataset identity
|
||
- package version
|
||
- createdAt
|
||
- source fingerprint
|
||
- style fingerprint
|
||
- sprite fingerprint
|
||
- standard catalog fingerprint
|
||
- policy fingerprint
|
||
- mapping fingerprint
|
||
- validation result
|
||
- known limitations
|
||
|
||
只有 PASS 或明确允许发布的 PASS_WITH_WARNINGS 才能正式 export。
|
||
|
||
## 10. NavSea Provider Package Contract
|
||
|
||
公开 Contract 至少覆盖：
|
||
|
||
- provider identity
|
||
- dataset identity
|
||
- package/version identity
|
||
- Style resource
|
||
- PBF resource
|
||
- Sprite resource
|
||
- Glyph resource
|
||
- NavSea Standard Layer mapping
|
||
- Provider Policy
|
||
- Display
|
||
- Pickup
|
||
- Planning
|
||
- Danger
|
||
- capabilities
|
||
- validation requirements
|
||
- hash / version / fingerprint
|
||
- unresolved
|
||
- limitations
|
||
- provenance
|
||
|
||
公开 Contract 不要求第三方使用官方 PBF 工具。
|
||
|
||
## 11. NavSea 接收侧
|
||
|
||
```text
|
||
NavSea Provider Package
|
||
↓
|
||
NavSea Contract Validate
|
||
↓
|
||
Chart Profile Tools
|
||
↓
|
||
Chart Provider Profile
|
||
↓
|
||
ProviderCompiler
|
||
↓
|
||
ProviderExecutionPlan
|
||
↓
|
||
ChartRuntime
|
||
↓
|
||
NavSea Runtime
|
||
```
|
||
|
||
NavSea 不再负责 CM95/S-52 语义研究、Visual Object 人工分类、Provider-specific 图标研究或 Provider Policy 推理生成。
|
||
|
||
## 12. 当前工具迁移关系
|
||
|
||
`tools/style-visual-object/style_vo_tool.py` → PBF-02。
|
||
|
||
`tools/visual-object-instantiation/instantiate_pbf_visual_objects.py` → PBF-03，但必须去 CM95 硬编码。
|
||
|
||
`tools/visual-object-matcher/` 和 `visual_anchor_matcher.py` → PBF-04 辅助建议工具，不是最终权威。
|
||
|
||
`tools/style-visual-object/reviewer/` → PBF-04 人工确认。
|
||
|
||
`apply_reviewed_layer_assignment.py` → PBF-04 输出编译。
|
||
|
||
`validate_cm95_classification.py` 暂保留为 CM95 基线校验；后续增加 Provider-neutral validator。
|
||
|
||
## 13. 实施顺序
|
||
|
||
第一优先级：冻结 Provider Policy Schema v1 和 Provider Package Schema v1。
|
||
|
||
第二优先级：实现 `tools/provider-policy-compiler/`，让 NavSea 与 CM95 生成完全同 Schema 的 Provider Policy。
|
||
|
||
第三优先级：实现 Provider Package Validator / Export。
|
||
|
||
第四优先级：调整 NavSea `help/chart-profile-tools/`，收敛为读取公开 Provider Package → Validate → Profile → ProviderCompiler。
|
||
|
||
## 14. 核心原则
|
||
|
||
```text
|
||
PBF = 数据生产者
|
||
NavSea = Contract 定义者 + Validator + Compiler + Runtime
|
||
```
|
||
|
||
以及：
|
||
|
||
```text
|
||
PBF Pipeline 的终点是 Provider Package。
|
||
ProviderExecutionPlan 永远属于 NavSea。
|
||
```
|