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