diff --git a/docs/PBF_Pipeline_正式流程_v1.md b/docs/PBF_Pipeline_正式流程_v1.md new file mode 100644 index 0000000..2e181ea --- /dev/null +++ b/docs/PBF_Pipeline_正式流程_v1.md @@ -0,0 +1,457 @@ +# 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// + 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-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。 +```