118 lines
6.2 KiB
Markdown
118 lines
6.2 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-契约) |
|
||
| 改预览页生成 | [../preview/](../preview/index.md) |
|
||
| 声称"纯重构，产物不变" | [产物一致性指南](../guides/artifact-parity-guide.md) |
|
||
|
||
---
|
||
|
||
## 数据流全景
|
||
|
||
```
|
||
config/areas/<id>.json
|
||
│
|
||
▼ lib/area-config.js — normalizeAreaConfig() 推导全部输出路径
|
||
│
|
||
▼ build-area.js — 阶段调度
|
||
_pipeline/osm2streets-qgis.config.json （派生配置）
|
||
│
|
||
├─[intermediates]─▶ build-osm2streets-qgis.js
|
||
│ 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]───────▶ Blender + blender/generate_scene.py
|
||
│ 读 .osm + osm2streets_web_out/
|
||
│ → <id>.blend + <id>.png
|
||
│ → _pipeline/stages/blender.manifest.json
|
||
│
|
||
├─[cesium]────────▶ Blender + blender/export_cesium.py
|
||
│ 读 .blend → <id>.glb + <id>.json
|
||
│ → 并自动执行 preview
|
||
│ → _pipeline/stages/cesium.manifest.json
|
||
│
|
||
├─[preview]───────▶ 生成 <id>-cesium-preview.html
|
||
│ + 拷贝 lib/cesium-preview.{js,css}
|
||
│ + 车辆巡航路线与模型
|
||
│ → _pipeline/stages/preview.manifest.json
|
||
│
|
||
└─[compress]──────▶ 生成并列压缩 GLB / metadata / preview
|
||
→ _pipeline/stages/compress.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` | 约 530 | 主入口：区域配置读取、阶段调度、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/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/...`）。跨平台不在当前范围内
|