Files
osmWorkflow/.trellis/tasks/archive/2026-08/08-04-add-area-asset-budgets/prd.md

3.6 KiB
Raw Blame History

Add area asset budgets

Goal

让区域 GLB 的性能和体量约束成为可配置、可追踪、可定位的契约。手工改 OSM、资产或场景 生成逻辑后,使用者应能知道是否超出预算,以及节点、三角面和贴图主要来自哪一类资产。

Confirmed Facts

  • 原有全局保守阈值为 25 MB、1000 nodes、24 images本任务将它扩展为统一预算评估并 新增 250k render triangles 与 20 MB embedded image bytes。
  • scripts/glb-digest.js 已可无依赖读取 GLB JSON chunk且提供 node、mesh、material、 image、accessor 和 primitive vertex/index 计数。图片可通过 image 的 bufferView 计算嵌入 字节;三角面可由 primitive index count 计算。
  • 现有南台子基线为 21.37 MB、933 nodes、117 meshes、18 images当前未超固定预算。
  • GLB node/mesh 命名已经包含可用来源线索,如 Building_*Shapespark_* 与道路/植被 资产名;可用于诊断“渲染实例和三角面”来源,但不能把交织二进制 buffer 的静态文件字节精确 分配给单一节点。
  • check:area 已将超预算作为 failure新增策略必须保持这个默认阻断方向。

Requirements

  1. 区域配置新增可选 budget 对象,可覆盖全局默认的 GLB size、nodes、images、triangles 和 embedded image bytes 限额;未配置时保持现有默认约束,并为新增指标提供保守默认值。
  2. 任何比全局默认更宽松的区域覆盖必须提供非空 budget.reason,使例外可审计;更严格覆盖 不需要理由。
  3. 扩展共享 GLB digest提供总 triangles、embedded image bytes以及按稳定 node-name 分类的 source summary节点数、mesh instances、triangles。不虚构无法可靠归因的“每类文件字节”。
  4. diagnose:area 显示实际值、有效预算、超标项,以及 top source / top embedded images。
  5. check:area 复用相同预算计算,将任何超标项作为 failure不在入口脚本复制阈值或 GLB 解析逻辑。
  6. Cesium/compress stage manifest 写入其对应 GLB 的 budget、usage 和 budget warnings供 之后检查 stale 或回溯。
  7. 更新区域配置模板、README、pipeline/config specs 和 changelog只验证南台子。

Acceptance Criteria

  • normalizeAreaConfig() 对合法 budget 覆盖归一化,对负数、非数值或放宽默认值但缺 reason 的配置明确报错。
  • 南台子 diagnostics 显示有效预算、总 triangles、embedded image bytes、source summary 与 top images且当前默认 GLB 仍通过质量门。
  • 临时配置/fixture 将任一预算压低后,check:area 以非零退出并指出实际值和阈值。
  • stage manifest 包含和当前 GLB digest 对应的 budget/usage/warnings不重跑 Blender 或 Cesium 也可通过独立逻辑测试验证 payload。
  • 对 GLB digest 的新统计和预算分类有纯 Node 回归测试。
  • Node 语法检查、相关测试和 git diff --check 通过。

Out Of Scope

  • 不自动压缩、删减或替换资产;预算只报告和阻断。
  • 不改变默认 GLB、Cesium preview 或 Blender 的视觉结果。
  • 不尝试对共享/交织 GLB buffer 做不可靠的按节点文件字节归因。
  • 不验证 hanyang-block

Key Decisions

  • 默认预算仍是阻断性质量门;区域只可通过显式配置覆盖。
  • 放宽全局默认的例外必须在配置中写明原因;收紧预算不需理由。
  • 归因以准确的节点实例/三角面和嵌入图片字节为准,不把静态 GLB 总字节伪分配给资产类别。