Files
osmWorkflow/.trellis/tasks/08-04-add-osm-area-preflight/prd.md
2026-08-04 11:58:12 +08:00

3.5 KiB
Raw Blame History

Add OSM area preflight

Goal

在调用 QGIS、Blender 或 Cesium 前,快速验证区域 OSM 是否包含会导致建筑或场景几何错误的人工编辑问题。使用者应得到明确的通过/失败结果和可定位的问题列表,而不必先跑重型构建阶段。

Confirmed Facts

  • scripts/lib/area-diagnostics.js 已是区域配置和 OSM 解析的事实源;它已覆盖 bounds、building multipolygon、缺失 node 引用及高度标签,并被 diagnose:areacheck:area 共同复用。
  • diagnose:area 是全文诊断包含既有产物、GLB 与 manifest它不适合成为编辑 OSM 后的轻量独立门槛。
  • 当前 nantaizi-lake-innovation-valley 是唯一验证目标。忽略 action=delete 的历史对象后,其 OSM 有 1 个健康的建筑 multipolygon 和 23 个有效显式高度标签。
  • 全阶段 manifest 已存在;新预检不应被实现为 build-area --stages 的构建阶段。

Requirements

  1. 新增 npm run preflight:area -- --config config/areas/<area>.json,只读取区域配置和 OSM XML不得调用 QGIS、Blender、Cesium、压缩或写入场景产物。
  2. 从共享 diagnostics 模块提供结构化 OSM 预检结果,避免新增第二套 XML/建筑关系解析。
  3. 预检应检查:有效 bounds、way 引用的 node、building way 闭合性和最小节点数、建筑 multipolygon 的 outer/inner member、成员存在性、可拼接闭环以及 building height / building:levels 的基本可解析性。
  4. 命令输出简短摘要、错误和警告;存在 blocking error 时以非零退出。
  5. 成功预检写 <areaDir>/_pipeline/stages/preflight.manifest.json,记录配置和 OSM 输入的文件摘要、预检摘要、errors 与 warnings。失败预检不得覆盖此前成功 manifest。
  6. diagnose:area 显示预检 manifest 的状态;check:area 仅在该 manifest 已存在时检查其新鲜度和有效性,避免使历史区域在首次采用前立即失败。
  7. README 和 Pipeline spec 记录命令、退出码与 manifest 所有权。

Acceptance Criteria

  • 当前南台子 OSM 上 npm run preflight:area -- --config config/areas/nantaizi-lake-innovation-valley.json 输出 PASS、写入 fresh preflight.manifest.json,且不触发重型工具。
  • 预检报告包含 buildings、multipolygon、bounds 和几何健康统计。
  • 通过临时 OSM fixture 验证:缺失/无效 bounds、缺失 node、未闭合 building way、破损 building multipolygon、无效显式 height 都能得到定位明确的 blocking error。
  • diagnose:area 显示 preflight manifestcheck:area 对存在但 stale/invalid 的 preflight manifest 失败。
  • 原有 diagnose:areacheck:area 继续通过当前南台子区域。
  • 修改脚本通过 Node 语法检查和 git diff --check

Out Of Scope

  • 不修复 OSM 文件,不自动重组关系或补齐标签。
  • 不检查道路拓扑、转向箭头渲染、osm2streets 的语义兼容性,或任意非建筑面是否合法。
  • 不把预检加入 build-area 的默认阶段,也不要求未运行过预检的历史产物立即失败。
  • 不验证 hanyang-block

Key Decisions

  • 缺失 node 引用一律作为 blocking error。它表示 OSM 引用完整性已损坏,即使当前出现在非建筑 way也不将问题带入后续构建。

Notes

  • 这是跨 CLI、OSM 解析、质量门和 manifest 的改动,按复杂任务处理,需要 design 和 implement 工件后再开始实现。