osmWorkflow/.trellis/tasks/archive/2026-08/08-05-cesium-preview-controls/prd.md

Cesium 预览控制

目标

让 Cesium 预览更便于检查已生成的园区场景，不涉及 QGIS 数据编辑或压缩产物策略。

已确认事实

• 预览已有 Overview、Oblique、Detail、Route 相机预设，以及车辆跟随；重复开发这些控件没有价值。
• 预览已有主场景、路线、车辆的显隐开关；多 GLB 时也会自动提供资产级开关。
• 当前导出物只有一个主 GLB，metadata 只记录场景统计和一个 main 资产，不含可用于点选的要素属性。
• 预览是验证层，改动不应改变 Blender 主资产的几何或 QGIS 工作流。

候选范围

• 按场景类别显隐，例如道路、建筑、植被、水体。
• 点击可识别对象后显示基础信息。
• 保持既有相机预设、车辆控制和单场景加载的兼容性。

已确认决策

• 场景按道路、建筑、植被、水体等语义类别额外导出 GLB，Cesium 预览分别加载。
• 保留现有主 GLB，作为完整场景基线和兼容入口。
• 首版不提供点选要素属性；这需要逐要素 OSM 元数据映射，另行规划。
• 控件遵循现有低干扰预览风格：紧凑分组、清晰状态、克制色彩和无装饰性卡片堆叠。

需求

1. Cesium 导出额外生成道路、建筑、植被、水体四类语义 GLB，并写入 metadata 资产清单。
2. 预览默认加载主 GLB；用户可切换到语义资产检查模式，在该模式独立显示或隐藏每个类别。
3. 预览保留现有相机预设、车辆巡航、主场景开关及单 GLB metadata 的兼容行为。
4. 控件在桌面和窄屏下保持可读、可操作且不遮挡关键画面。

不在范围内

• QGIS 图层、人工数据修补和 reimport 流程。
• 将压缩 GLB 设为默认产物。
• 地图、地形或在线底图功能。
• 点击要素属性、OSM ID 或名称映射。

验收标准

• 一次 Cesium 导出会保留主 GLB，并产出四个可独立加载的类别 GLB。
• metadata 的 assets 同时声明主场景和各类别资产，旧 metadata 仍可作为单资产场景打开。
• 预览可在完整场景与分类检查模式之间切换；分类模式可独立控制道路、建筑、植被、水体。
• 现有 Overview、Oblique、Detail、Route、车辆和诊断控件仍可使用。
• 控件在常规桌面与窄屏宽度下无重叠、无溢出，视觉层级与现有预览一致。