5.0 KiB
5.0 KiB
道路包导入与纯消费管线
父任务：.trellis/tasks/08-25-road-compiler-extraction/
本任务是集成 parent：导出与导入分别在 road-compiler 和宿主仓库实现，只有两个子任务的 端到端 ZIP 契约都通过后才完成。
Goal
让 road-compiler Web 导出的 native-road-package/v1.1 成为 Blender 管线的唯一
native-road 输入。宿主只校验并消费完整道路包，不再安装、调用或理解道路编译器。
用户价值：人工在 road-compiler Web 编辑后，导出道路包即可稳定交给 Blender / Cesium 构建；编辑成果不再通过发布新的编译器代码版本传播。
Confirmed Facts
- P3 已使 Blender 通过
manifest.json消费layers/*.geojson，并拒绝无效 manifest、 source/file 不一致和未知宿主材质槽。 - 宿主当前仍通过
scripts/build-area.js调用scripts/lib/road-compiler-cli.js；后者安装并 运行@osm-asset/road-compiler，将RoadCompilerInput写入_pipeline/。 - native Blender 构建当前强制使用
outputs/<area>/native-road/，并在每次构建前重新编译； 宿主还持有nativeRoad.edgeLines、junctionTemplates、overrides 和 compiler runtime 路径等编译器内部概念。 osm2streets是显式 legacy/debug provider，应保持现有行为。- 有效验证区域只有
fengshu-er-road与nantaizi-lake-innovation-valley；hanyang-block不参与。
Requirements
R1 纯产物边界
- native provider 只接收一个完整
native-road-package/v1.1目录。 - 宿主不得依赖
@osm-asset/road-compiler，不得调用 compiler CLI，不得写RoadCompilerInput，不得读取或解释 compiler overrides / junction templates。 - 宿主以 manifest 作为道路图层事实源，Blender 不增加 compiler 专用图层表。
R2 ZIP 导入配置和校验
- 每个 native 区域配置一个道路包 ZIP 路径；路径相对于区域配置文件解析并可指向工作区外的 road-compiler Web 导出文件。
- ZIP 根目录必须直接包含
manifest.json和契约定义的文件；不得接受多余顶层目录、绝对路径、..路径或符号链接。 - 在启动 Blender 前，宿主将 ZIP 安全解压到其私有 pipeline staging 目录，校验 manifest
契约版本、
areaId和当前区域一致，并记录 ZIP hash 和展开文件记录到 stage manifest。 - ZIP 永远只读：宿主不复制、覆盖或修改 road-compiler Web 的导出文件；成功或失败后仅清理 自己的临时解压目录。
- Blender 继续校验 manifest 的图层、source、semantic 角色、材质槽和 splitBy 规则。
R3 后续阶段
- Cesium、package、preview 和区域诊断从导入道路包读取原生车道中心线、signals 和 其他既有 native-road 输入；不重新编译或复制道路包。
- build stage manifest 将道路包作为外部输入记录，而非宿主输出。
R4 清理和迁移
- 删除宿主对 compiler npm 包、CLI 封装和编译脚本的生产依赖。
- 删除或替换只测试宿主编译行为的测试；保留 package-contract、Blender 和下游消费测试。
- 更新示例配置、README、pipeline spec 和道路包契约，明确 Web export -> host consume 的单向关系。
Acceptance Criteria
- AC1
package.json/ lockfile 和生产脚本不再引用@osm-asset/road-compiler或其 CLI。 - AC2 两个有效区域均可从配置指定的已导出 ZIP 道路包运行 Blender、Cesium、package 和 preview， 构建期间没有 compiler 子进程。
- AC3 宿主在 Blender 前拒绝缺失包、错误 contract、错误 areaId 和无效 manifest；错误说明 指向导入包和契约，而非 compiler 内部。
- AC4 Blender scene digest 与 P3 control 基线一致；native semantic 层仍不生成几何。
- AC5 stage manifest / diagnose / check area 将导入道路包记录为输入并能识别缺失或变更。
- AC6
osm2streetslegacy provider 行为未变。 - AC7 文档和配置将人工编辑传播路径表述为 road-compiler Web export -> host consume。
Out of Scope
- road-compiler Web 的编辑器功能、认证、部署或 UI 改造。
- 修改道路几何、材质、Blender 建筑/植被/水体渲染。
- 新的 manifest 破坏性版本或 lane graph IR。
- 将道路包上传到远程制品库或实现同步服务。
Key Decision
- Web 导出的是标准 ZIP；宿主配置直接指向 ZIP 而不是目录。ZIP 是跨仓库的不可变交付物， 宿主只在私有 staging 目录中解压和消费，因而没有导出目录 ownership 或覆盖歧义。
Subtask Map
| 子任务 | 仓库 | 交付物 | 依赖 |
|---|---|---|---|
rc-p5a-zip-export |
road-compiler | Web / CLI 可导出的 root-flat native-road-package/v1.1 ZIP |
无 |
rc-p5b-zip-import |
osmWorkflow | 配置、受控解压、校验和纯消费管线 | p5a 的 ZIP fixture |
跨任务验收：同一个 ZIP fixture 必须被 p5b 的两个有效区域构建消费；宿主不得保留 compiler npm 或 CLI 耦合。