96 lines
5.0 KiB
Markdown
96 lines
5.0 KiB
Markdown
# 道路包导入与纯消费管线
|
||
|
||
父任务：`.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 `osm2streets` legacy 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 耦合。
|