7.0 KiB
7.0 KiB
Pipeline：Node 构建管线
覆盖
scripts/*.js与scripts/lib/scene-layers.js。 运行时：宿主机 Node（CommonJS，无构建步骤）。 这是管线里唯一能启动外部进程的层。
先读哪一篇
| 你要做的事 | 读 |
|---|---|
| 改九个 osm2streets 图层（增/删/改顺序/改色） | 图层表 ← 最容易出静默错误 |
| 调 QGIS / GDAL / Blender 子进程 | 外部工具调用 |
| 加阶段、加 CLI 参数、改配置字段 | CLI 与阶段 |
| 改区域诊断/质量门命令或共享区域配置归一化 | CLI 与阶段 和 质量门 |
| 改 stage manifest 写入、读取或 stale 判断 | CLI 与阶段 |
改复合路口几何（buildComplexJunctionGeometry、车道控制避让、人行道转角） |
CLI 与阶段 的复合路口小节 |
| 改预览页生成 | ../preview/ |
| 声称"纯重构，产物不变" | 产物一致性指南 |
| Native road compiler CLI、输入或完成标记 | 编译器契约指针 |
数据流全景
config/areas/<id>.json
│
▼ lib/area-config.js — normalizeAreaConfig() 推导全部输出路径
│
▼ build-area.js — 阶段调度
_pipeline/osm2streets-qgis.config.json （派生配置）
│
├─[intermediates]─▶ build-osm2streets-qgis.js（显式 legacy/reference）
│ osm2streets-js-node 解析 .osm
│ → splitLayers() 拆成九个图层
│ → normalize-lane-arrows.py（QGIS Python）
│ → osm2streets_web_out/*.geojson
│ → osm2streets_scene.geojson + _scene_style.json
│ → ogr2ogr 导入 <id>.gpkg
│ → QGIS 生成 .qgz + -preview.png
│ → _pipeline/stages/intermediates.manifest.json
│
├─[reimport]──────▶ reimport-gpkg.js （反向，与 intermediates 互斥）
│ ogr2ogr 从 .gpkg 导出 → 校验 → 覆写 *.geojson
│ → 重建 scene.geojson + scene_style.json
│ → _pipeline/stages/reimport.manifest.json
│
├─[blender]───────▶ native-road ZIP importer + Blender + blender/generate_scene.py
│ 默认读 .osm + validated ZIP cache/
│ → <id>.blend + <id>.png
│ → _pipeline/stages/blender.manifest.json
│
├─[cesium]────────▶ Blender + blender/export_cesium.py
│ 读 .blend → _pipeline/package-staging/models/<id>.glb
│ + staged manifest，动态预览 GLB 写入 _preview/
│ → _pipeline/stages/cesium.manifest.json
│
├─[compress]──────▶ 压缩 staging 内主 GLB 并更新 staged manifest
│ → _pipeline/stages/compress.manifest.json
│
├─[package]───────▶ 校验 manifest 与全部静态模型，原子发布 package/
│ → package/manifest.json + package/models/*.glb
│ → _pipeline/stages/package.manifest.json
│
└─[preview]───────▶ 生成 <id>-cesium-preview.html（native 可无车辆路线）
│ + 拷贝 lib/cesium-preview.{js,css}
+ _preview/ 车辆巡航路线、模型、动态信号
│ → _pipeline/stages/preview.manifest.json
阶段之间只通过磁盘产物耦合，不传内存状态。这是单跑任意阶段能work 的前提。
三条贯穿全层的约定
-
单一事实源优先于同步 九个图层的定义在
lib/scene-layers.js，四个派生函数覆盖了全部合法用法。看到第二处 枚举这些图层，就是 bug 温床。详见 图层表。 -
有副作用之前先把能验的都验完 数值参数 → 输入文件 → 外部可执行文件 → 才
mkdirSync。 见build-osm2streets-qgis.js:41-70。 -
外部工具的产物先落 staging，校验通过才覆盖
ogr2ogr失败会留 0 字节文件。详见 外部工具调用。
文件速查
| 文件 | 行数 | 职责 |
|---|---|---|
build-area.js |
主入口：区域配置读取、阶段调度、package 发布、preview 文件写入和 stage manifest ownership | |
diagnose-area.js |
36 | 快速诊断入口：调用共享 area diagnostics 并打印完整报告 |
check-area.js |
74 | 区域质量门入口：调用共享 area diagnostics，输出 PASS/FAIL 并设置退出码 |
lib/area-diagnostics.js |
776 | 共享区域诊断事实源：OSM、产物、metadata、stage manifest、GLB digest 和质量门分类 |
lib/area-config.js |
135 | 区域配置归一化与输出路径推导，供 build / diagnose 复用 |
lib/stage-manifest.js |
100 | stage manifest 路径、文件记录、GLB budget warning 和原子 JSON 写入 |
build-osm2streets-qgis.js |
1468 | intermediates：osm2streets 解析、图层拆分、人行道转角合成、GeoPackage 与 QGIS 工程生成 |
reimport-gpkg.js |
179 | reimport：GeoPackage → GeoJSON 反向导出 |
lib/scene-layers.js |
164 | 九个图层的单一事实源 + 四个派生函数 |
lib/vehicle-route.js |
约 180 | 从 OSM 提取确定性预览巡航路线 |
lib/vehicle-model.js |
约 150 | 生成内嵌 buffer 的预览车辆 glTF |
lib/area-preview.js |
约 110 | 复制 preview runtime、生成 HTML 与转义配置注入 |
lib/package-contract.js |
package manifest 校验、相对 URI 与 SHA-256 完整性记录 | |
lib/cesium-preview.js / .css |
672 / 230 | 预览页运行时，见 ../preview/ |
normalize-lane-arrows.py |
182 | 合并 osm2streets 的三角网箭头（跑在 QGIS Python 里） |
parity.js |
270 | 产物一致性校验驱动 |
glb-digest.js |
132 | GLB 结构摘要，CLI、build manifest 和诊断脚本共用 |
技术选型现状
- CommonJS，无构建、无 TypeScript、无 lint 配置。保持现状；引入工具链是独立决定， 不要夹带在功能改动里
- 零运行时依赖（
osm2streets-js-node是唯一 dependency）。加依赖前先确认标准库 真的做不到 - 同步 API 优先（
execFileSync/spawnSync/readFileSync）。这是一次性跑完 的批处理工具，不是服务，异步只会增加错误处理复杂度 - macOS 专用路径假设（
.app/Contents/MacOS/...）。跨平台不在当前范围内