60 lines
3.6 KiB
Markdown
60 lines
3.6 KiB
Markdown
# 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
|
||
|
||
- [x] `normalizeAreaConfig()` 对合法 budget 覆盖归一化，对负数、非数值或放宽默认值但缺
|
||
`reason` 的配置明确报错。
|
||
- [x] 南台子 diagnostics 显示有效预算、总 triangles、embedded image bytes、source summary
|
||
与 top images，且当前默认 GLB 仍通过质量门。
|
||
- [x] 临时配置/fixture 将任一预算压低后，`check:area` 以非零退出并指出实际值和阈值。
|
||
- [x] stage manifest 包含和当前 GLB digest 对应的 budget/usage/warnings；不重跑 Blender 或
|
||
Cesium 也可通过独立逻辑测试验证 payload。
|
||
- [x] 对 GLB digest 的新统计和预算分类有纯 Node 回归测试。
|
||
- [x] Node 语法检查、相关测试和 `git diff --check` 通过。
|
||
|
||
## Out Of Scope
|
||
|
||
- 不自动压缩、删减或替换资产；预算只报告和阻断。
|
||
- 不改变默认 GLB、Cesium preview 或 Blender 的视觉结果。
|
||
- 不尝试对共享/交织 GLB buffer 做不可靠的按节点文件字节归因。
|
||
- 不验证 `hanyang-block`。
|
||
|
||
## Key Decisions
|
||
|
||
- 默认预算仍是阻断性质量门；区域只可通过显式配置覆盖。
|
||
- 放宽全局默认的例外必须在配置中写明原因；收紧预算不需理由。
|
||
- 归因以准确的节点实例/三角面和嵌入图片字节为准，不把静态 GLB 总字节伪分配给资产类别。
|