125 lines
7.0 KiB
Markdown
125 lines
7.0 KiB
Markdown
# Pipeline：Node 构建管线
|
||
|
||
> 覆盖 `scripts/*.js` 与 `scripts/lib/scene-layers.js`。
|
||
> 运行时：宿主机 Node（CommonJS，无构建步骤）。
|
||
> 这是管线里**唯一**能启动外部进程的层。
|
||
|
||
---
|
||
|
||
## 先读哪一篇
|
||
|
||
| 你要做的事 | 读 |
|
||
|---|---|
|
||
| 改九个 osm2streets 图层（增/删/改顺序/改色） | [图层表](./layer-registry.md) ← **最容易出静默错误** |
|
||
| 调 QGIS / GDAL / Blender 子进程 | [外部工具调用](./external-tools.md) |
|
||
| 加阶段、加 CLI 参数、改配置字段 | [CLI 与阶段](./cli-and-stages.md) |
|
||
| 改区域诊断/质量门命令或共享区域配置归一化 | [CLI 与阶段](./cli-and-stages.md#区域诊断命令) 和 [质量门](./cli-and-stages.md#区域质量门命令) |
|
||
| 改 stage manifest 写入、读取或 stale 判断 | [CLI 与阶段](./cli-and-stages.md#stage-manifest-契约) |
|
||
| 改复合路口几何（`buildComplexJunctionGeometry`、车道控制避让、人行道转角） | [CLI 与阶段](./cli-and-stages.md#可编辑信号设施与运行时锚点的跨阶段消费) 的复合路口小节 |
|
||
| 改预览页生成 | [../preview/](../preview/index.md) |
|
||
| 声称"纯重构，产物不变" | [产物一致性指南](../guides/artifact-parity-guide.md) |
|
||
| Native road compiler CLI、输入或完成标记 | [编译器契约指针](./native-road-package.md) |
|
||
|
||
---
|
||
|
||
## 数据流全景
|
||
|
||
```
|
||
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]───────▶ compile-native-roads.js + Blender + blender/generate_scene.py
|
||
│ 默认读 .osm + native-road/
|
||
│ → <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 的前提。
|
||
|
||
---
|
||
|
||
## 三条贯穿全层的约定
|
||
|
||
1. **单一事实源优先于同步**
|
||
九个图层的定义在 `lib/scene-layers.js`，四个派生函数覆盖了全部合法用法。看到第二处
|
||
枚举这些图层，就是 bug 温床。详见 [图层表](./layer-registry.md)。
|
||
|
||
2. **有副作用之前先把能验的都验完**
|
||
数值参数 → 输入文件 → 外部可执行文件 → 才 `mkdirSync`。
|
||
见 `build-osm2streets-qgis.js:41-70`。
|
||
|
||
3. **外部工具的产物先落 staging，校验通过才覆盖**
|
||
`ogr2ogr` 失败会留 0 字节文件。详见 [外部工具调用](./external-tools.md)。
|
||
|
||
---
|
||
|
||
## 文件速查
|
||
|
||
| 文件 | 行数 | 职责 |
|
||
|---|---|---|
|
||
| `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/](../preview/index.md) |
|
||
| `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/...`）。跨平台不在当前范围内
|