10-device-model-asset-definition.md 9.3 KB
设备点位「模型」的口径与资产来源
Type: grilling Status: resolved Labels: wayfinder:grilling Blocked by: 01, 05
进度：100%
讨论已完成，维护者已确认 Q1–Q20；resolved 表示本票决策完成，不表示设备位置符号、正式图片素材或真三维模型已经实现。规格已通过 16 号设备点位模型与资产规格 固化，并挂到同一张决策 map；后续实现仍受票 09 的设备级坐标/状态契约或明确清单降级约束。
01 已给出硬事实：仓库没有本地设备级 glTF/GLB；现有形状簇只能作为临时视觉。08 原型验收进一步确认临时内联 SVG 不是最终视觉，必须保留可替换的正式坐标点图片素材接缝。
Question
需求②原句是「展示该监测点下所有设备点位的模型及坐标图标」——「模型」这个词必须被定死，否则实现票要么去加载并不存在的资产，要么静默降级成图标而没人知道。
Answer
目标与边界
- 本期“模型”正式解释为监测设备在三维场景中的位置符号，由可替换的图片/图标素材、渲染尺寸、对象自身状态视觉和既有交互反馈组成；本期不承诺、不加载真三维设备几何模型，也不把图标模式称为真模型。
- “设备点位”在这里是监测设备在关联监测设备图层中的空间显示，不是新的业务对象；监测点、监测设备和关联监测设备图层继续按
CONTEXT.md区分。 - 本期不制作、不采购、不承诺真三维设备资产。未来可按设备类型逐步接入真模型，资产来源可以是外部提供，也可以后续另立资产生产事项由项目方制作。
位置符号与视觉
- 监测点和监测设备使用相同样式或同一份正式坐标点图片素材；本期临时形状簇只用于开发期占位，未来统一提供正式图片素材后通过可替换资产接缝替换。
- 通过程序控制实际渲染大小区分类型，监测点始终大于监测设备；允许随相机距离动态缩放，但具体像素值和缩放倍率留给实现与人工走查，不在本票编造固定数字。
- 设备默认不显示长文本；悬停或选中时显示设备名称为主、设备编码为辅，长内容不得撑破布局或遮挡其它对象。
- “坐标图标”只表示空间位置符号，不直接展示经纬度数字。
- 监测点按后端发布的点位状态着色，监测设备按监测设备自身状态着色。两者可以使用相同颜色风格，但不得混用状态来源或用点位状态猜设备状态；颜色不是唯一线索，继续结合形状、文字、尺寸层级和选中反馈。
- 设备状态视觉遵守票 07；设备 hover、选中、定位、独立拾取和面板联动遵守票 06/15。本票不重新定义这些既有反应。
地形、坐标与遮挡
- 设备位置只接受设备自身的有效经纬度和后端坐标准入结果。坐标缺失、非法或
coordinateValidation.renderable为假时不上图，保留在设备清单中并显示明确的无地图位置/不可用原因。 - 有效设备位置必须结合地形采样贴地。地形未加载、采样未完成或采样失败时不上图，设备保留在清单中并显示“地形未就绪/位置待确认”；该状态不能算作坐标无效，也不能算作已上图。
- 不使用监测点坐标代替设备坐标，不进行人工坐标偏移，不制造没有数据依据的设备位置。
- 位置符号和未来真模型遵守正常地形、示意体块与其它场景对象的深度关系，不开启穿透体块的特殊可见性例外。
真模型演进与降级
- 真模型未来按设备类型逐步接入；同一关联监测设备图层允许真模型与图标混合显示，未提供资产的类型继续使用图标。
- 真模型最低接入契约为 glTF/GLB、米制、明确 up 轴、前向朝向、原点和模型基准面；接入侧由构造确定模型到设备地理坐标的 ENU 变换，不靠运行时猜测原点或朝向。
- 三角面预算、同屏数量上限和同型号实例化策略不在本票固定，未来资产/实施事项必须按真实设备类型和规模实测确定。
- 真模型未提供、契约不合格、加载失败或性能超预算时，单台设备退回设备专属图标，不影响其它设备或其它资产类型；图标兜底不计为真模型成功加载。
- 地图默认不增加统一错误角标。悬停/选中时显示“图标模式/模型不可用”等可理解状态；详情卡片显示具体原因，至少区分资产未提供、加载失败、性能降级、地形未就绪和视觉资源异常。
- 正式图标资源自身失败时使用内置通用位置符号作为最后兜底，并在详情中标明视觉资源异常；通用符号不是真模型，也不是正式素材。
- 关联监测设备使用独立图例，不并入监测点摘要图例；位置符号缺失、资产降级、无地图位置和模式隐藏必须保持可区分，不得静默当成设备不存在。
Decision Tree Closure
- Q1：C——本期位置符号，未来可升级真模型。
- Q2：C——本期不承诺真模型资产，后续可能另立事项由项目方制作。
- Q3：统一样式/素材，程序控制尺寸；监测点始终大于设备；状态按各自业务对象解释；默认无长标签，悬停/选中显示名称为主、编码为辅；坐标图标不显示经纬度。
- Q4：有效设备坐标结合地形采样贴地；地形未就绪或采样失败不上图；遵守正常遮挡关系。
- Q5：真模型缺失、失败或超预算退回图标，并在交互/详情中如实说明；图标资源失败再退回通用位置符号。
- Q6：监测点与设备可使用同一素材，仅程序控制尺寸；沿用票 06/07 既有设备交互；未来素材只替换视觉资源。
- Q7：A——严格等待地形；坐标有效但地形不可用时清单保留、地图不上图。
- Q8：A——按设备类型逐步接入真模型，允许同层混合显示。
- Q9：C——外部提供和项目方另立事项制作均可，本票不承诺美术生产。
- Q10：B——地图保持可识别图标；悬停/选中和详情显示降级及原因，不堆统一错误角标。
- Q11：确认本期“模型”=位置符号，不加载真三维设备模型。
- Q12：A+C——锁定监测点大于设备点，并允许同倍率随相机距离缩放；数值由实现/走查确定。
- Q13：确认地形未就绪与无地图位置分开；不替代坐标、不人工偏移。
- Q14：确认 glTF/GLB、米制、up/前向/原点/基准面明确、ENU 构造变换和独立校验。
- Q15：确认悬停/选中提示图标模式或模型不可用，详情给出具体原因，资源失败有通用符号兜底。
- Q16：B——设备名称为主、编码为辅。
- Q17：A——监测点按点位状态，监测设备按设备自身状态；颜色风格可同但语义不混。
- Q18：允许不同设备类型在同一关联监测设备图层中混合真模型与图标。
- Q19：B——性能数字与实例化策略留给未来资产/实施事项实测，超预算按图标兜底。
- Q20：接受独立关联监测设备图例；颜色不是唯一线索。
Further Notes
- 规格子票：16: 设备点位模型与资产来源规格。它是本票结论的实施输入，不表示功能或正式资产已交付。
- 后续实现应同时消费 14 号关联监测设备图层规格、15 号面板与三维设备点对应规格、本票的 16 号规格，以及票 09 的设备坐标/状态契约或明确降级方案。
- 本票只决定视觉/资产口径，不重新打开票 03 的相机数值、票 04/12 的面板锚点、票 07 的设备状态特效或票 11 的重叠设备策略。
Comments
讨论收口（Q1–Q20）
维护者已确认以上目标、边界、风险、选项权衡与决策；本票状态更新为 resolved。本次只完成决策正文与规格发布，未运行 build、dev 或浏览器调试。
2026-09-24 维护者新增前提（来自票 08 原型验收，本票裁决时必须吸收）
维护者在票 08 验收时明确：原型里的临时图标（内联 SVG 形状）只是占位，最终验收不使用它们；点位与设备图标必须预留可替换的资产接缝，未来换成正式视觉资产（参考图为带辉光的圆形徽标 + 行业图标：水滴/火焰/燃气等）。
对本票三条子问题的直接影响：
- 问题 3（走图标路线）：「图标」必须是单一替换接缝，不是把形状字符串写死在标记绘制里。现状可复用的接缝已存在且只此一处：
domain/pointStatus.js的SHAPES+markerSvg(shape, color, size)，由services/mapService.js:678的imageOf回调注入 —— 正式资产落地时只改这一个注入点（或把它升级为可加载图片/glTF 的资产表），地图标记、图例、详情卡片三处自动跟随。 - 问题 1/2（模型 vs 图标）：参考图显示目标是图标徽标观感（非真三维模型），且 01 已核实仓库无设备级 glTF 资产。本票裁决时仍需正式定口径，但「资产可替换」是维护者已给的硬前提，与选哪条路线正交。
- 验收口径：正式验收不使用当前临时形状；资产缺失/未交付时按本票问题 5 的降级链如实呈现，不得把临时图标当作最终态宣布验收通过。