Add full stage manifests

2026-08-04 11:37:20 +08:00
parent 0b7e69770c
commit 5874cf9379
9 changed files with 516 additions and 21 deletions
--- a/.trellis/spec/pipeline/cli-and-stages.md
+++ b/.trellis/spec/pipeline/cli-and-stages.md
@@ -300,9 +300,10 @@ const gate = classifyAreaQuality(result);

 ### 1. Scope / Trigger

-Stage manifest 是构建阶段完成后的机器可读产物契约。第一版覆盖 GLB 相关阶段：
-`cesium` 和 `compress`。它用于诊断产物是否存在、是否 stale、体量是否超预算，以及后续
-`check:area` / 增量构建判断。
+Stage manifest 是构建阶段完成后的机器可读产物契约。它覆盖完整区域链：
+`intermediates`、`reimport`、`blender`、`cesium`、`preview` 和 `compress`。
+它用于诊断产物是否存在、是否 stale、体量是否超预算，以及后续 `check:area` /
+增量构建判断。

 ### 2. Signatures

@@ -315,7 +316,11 @@ Manifest 路径固定：
 当前会写：

 ```text
+<areaDir>/_pipeline/stages/intermediates.manifest.json
+<areaDir>/_pipeline/stages/reimport.manifest.json
+<areaDir>/_pipeline/stages/blender.manifest.json
 <areaDir>/_pipeline/stages/cesium.manifest.json
+<areaDir>/_pipeline/stages/preview.manifest.json
 <areaDir>/_pipeline/stages/compress.manifest.json
 ```

@@ -357,18 +362,65 @@ File records use this shape:
 }
 ```

+`intermediates` manifest:
+
+- `inputs.config`
+- `inputs.osm`
+- `outputs.derivedConfig`
+- `outputs.geojsonDir`
+- `outputs.<nine scene layers>`、`outputs.osm2streets_scene.geojson`、
+  `outputs.osm2streets_scene_style.json`
+- `outputs.gpkg`、`outputs.qgisProject`、可选 `outputs.qgisPreview`
+- `summary.geojson`：各 layer / merged scene 的 feature count
+
+`reimport` manifest:
+
+- `inputs.config`
+- `inputs.derivedConfig`
+- `inputs.gpkg`
+- `outputs.geojsonDir`
+- `outputs.<nine scene layers>`、merged scene/style
+- `summary.geojson`
+
+`intermediates` 和 `reimport` 是同一批 GeoJSON 的互斥 ownership：
+成功运行 `intermediates` 删除旧 `reimport.manifest.json`；成功运行 `reimport` 删除旧
+`intermediates.manifest.json`。诊断只要求当前 ownership 路径的 manifest，不要求两者同时存在。
+
+`blender` manifest:
+
+- `inputs.config`
+- `inputs.osm`
+- `inputs.geojsonDir`、`inputs.<nine scene layers>`、merged scene/style
+- `outputs.blend`
+- `outputs.render`
+- `summary.geojson`、`summary.blendBytes`、`summary.renderBytes`
+
 `cesium` manifest:

 - `inputs.blend`
 - `outputs.glb`
 - `outputs.metadata`
- `outputs.cesiumPreview`
- `outputs.vehicleRoute`
- `outputs.vehicleModel`
 - `summary.glb.fileBytes`
 - `summary.glb.counts`
 - `summary.glb.extensionsUsed`

+`cesium` 会调用 preview 生成函数，但 preview HTML / route / vehicle model 的 freshness
+所有权属于独立 `preview` manifest。否则单跑 `--stages preview` 会把 Cesium manifest
+错误判 stale。
+
+`preview` manifest:
+
+- `inputs.config`
+- `inputs.osm`
+- `inputs.glb`
+- `inputs.metadata`
+- `inputs.previewCss`
+- `inputs.previewJs`
+- `outputs.cesiumPreview`
+- `outputs.vehicleRoute`
+- `outputs.vehicleModel`
+- `summary.glbName`、`summary.metadataName`、`summary.routeSegments`
+
 `compress` manifest:

 - `inputs.glb`
@@ -395,12 +447,19 @@ Manifest files are written atomically via `*.tmp` then `renameSync`.
 | Manifest JSON 无法解析 | 诊断报告 invalid warning |
 | Manifest 记录的 input / output sha/bytes 与当前文件不同 | 诊断报告 stale warning |
 | GLB size / nodes / images 超保守预算 | manifest `warnings[]` 记录，诊断继续独立报警 |
+| `intermediates` 后留有旧 reimport manifest | 成功后删除旧 reimport manifest |
+| `reimport` 后留有旧 intermediates manifest | 成功后删除旧 intermediates manifest |

 ### 5. Good/Base/Bad Cases

- Good: `--stages cesium` 成功后写 `cesium.manifest.json`，诊断显示 `ok cesium`。
+- Good: `--stages intermediates` 成功后写 `intermediates.manifest.json`，诊断显示
+  `ok intermediates`。
+- Good: `--stages blender` 成功后写 `blender.manifest.json`，诊断显示 `ok blender`。
+- Good: `--stages cesium` 成功后写 `cesium.manifest.json` 和 `preview.manifest.json`。
+- Good: `--stages preview` 只更新 preview manifest，不让 cesium manifest stale。
 - Good: `--stages compress` 成功后写 `compress.manifest.json`，summary 记录压缩比和节省字节。
- Base: 旧产物没有 manifest，诊断显示 expected manifest missing，提示重跑对应阶段。
+- Base: 旧产物没有当前 ownership 路径的 manifest，诊断显示 expected manifest missing，
+  提示重跑对应阶段。
 - Bad: 手工编辑 GLB 后不重跑阶段，诊断显示 manifest stale。

 ### 6. Tests Required
@@ -408,10 +467,15 @@ Manifest files are written atomically via `*.tmp` then `renameSync`.
 - `node --check scripts/lib/stage-manifest.js`
 - `node --check scripts/build-area.js`
 - `node --check scripts/diagnose-area.js`
+- `node --check scripts/check-area.js`
+- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages intermediates`
+- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages blender`
 - `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages cesium`
+- `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages preview`
 - `npm run build:area -- --config config/areas/nantaizi-lake-innovation-valley.json --stages compress`
 - `npm run diagnose:area -- --config config/areas/nantaizi-lake-innovation-valley.json`
- JSON parse both generated manifests and assert `manifestVersion`, `stage`, `inputs`,
+- `npm run check:area -- --config config/areas/nantaizi-lake-innovation-valley.json`
+- JSON parse generated manifests and assert `manifestVersion`, `stage`, `inputs`,
  `outputs`, `summary`, and `warnings` fields exist.

 ### 7. Wrong vs Correct
--- a/.trellis/spec/pipeline/index.md
+++ b/.trellis/spec/pipeline/index.md
@@ -38,14 +38,17 @@ config/areas/<id>.json
      │                     → 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
@@ -55,6 +58,7 @@ config/areas/<id>.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
@@ -83,10 +87,10 @@ config/areas/<id>.json

 | 文件 | 行数 | 职责 |
 |---|---|---|
-| `build-area.js` | 815 | 主入口：区域配置读取、阶段调度、Cesium 预览页、车辆巡航和 stage manifest 写入 |
+| `build-area.js` | 961 | 主入口：区域配置读取、阶段调度、Cesium 预览页、车辆巡航和 stage manifest 写入 |
 | `diagnose-area.js` | 36 | 快速诊断入口：调用共享 area diagnostics 并打印完整报告 |
 | `check-area.js` | 74 | 区域质量门入口：调用共享 area diagnostics，输出 PASS/FAIL 并设置退出码 |
-| `lib/area-diagnostics.js` | 660 | 共享区域诊断事实源：OSM、产物、metadata、stage manifest、GLB digest 和质量门分类 |
+| `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 工程生成 |