16: 设备点位模型口径与资产来源规格（来自决策票 10）

Type: spec Status: ready-for-agent Label: ready-for-agent Blocked by: 10 Category: spec

本规格固化决策票 10的维护者确认结果，作为同一张 map的子规格单。它定义“模型”在本期的产品口径、位置符号视觉、正式资产替换接缝、未来真三维模型接入边界、地形关系和降级可见性；不覆盖 14 号规格的关联监测设备图层生命周期，也不覆盖 15 号规格的面板选设备与三维设备点联动。

进度：100%

规格文档已发布为 ready-for-agent 并挂到同一决策 map；100% 仅指规格交付，不表示设备位置符号、正式图片素材或真三维模型已经实现。当前仓库没有本地设备级 glTF/GLB，当前形状簇只可作为临时视觉；后续实现须保留可替换资产接缝，并以正式素材作为最终视觉验收依据。未经本对话明确要求，本次不运行 build、dev 或浏览器走查。

Problem Statement

需求“展示该监测点下所有设备点位的模型及坐标图标”中的“模型”没有明确产品含义。若按字面实现为真三维模型，当前仓库没有可用的本地设备级 glTF/GLB，远程 demo 资产也不能成为生产依赖；若直接把图标当成真模型，又会把临时占位视觉误报为已经交付的三维能力。

监测点和监测设备还需要在同一张一张图中保持可辨。两者可以使用同样式、甚至同一份素材，但它们是不同业务对象，状态来源也不同：监测点使用点位状态，监测设备使用监测设备自身状态。设备位置必须来自设备自己的有效坐标并结合地形贴地，不能使用监测点坐标或人工偏移。资产缺失、加载失败、地形未就绪和性能降级也不能让设备从清单中静默消失，或被误读为真模型已成功显示。

Solution

本期将需求中的“设备点位模型”正式解释为监测设备在三维场景中的位置符号：由可替换的图片/图标素材、渲染尺寸、对象自身状态视觉和既有 hover/选中/定位反馈组成；本期不承诺、不加载真三维设备几何模型，也不把图标模式称为真模型。

监测点和监测设备使用相同样式或未来统一提供的坐标点图片素材，通过程序控制实际渲染大小区分类型，监测点始终大于监测设备。设备图标默认不显示长文本，悬停或选中时以设备名称为主、设备编码为辅显示。未来可以按设备类型逐步接入真三维模型，同一关联监测设备图层允许真模型与图标混合呈现；每台设备都保留可靠的图标兜底和如实的降级原因。

有效设备坐标结合地形采样贴地。地形未就绪或采样失败时不上图，但设备仍保留在设备清单中并提示位置待确认；坐标缺失、非法或后端 renderable=false 时继续按无地图位置处理。所有位置表达遵守正常场景深度关系，不为设备图标或真模型开启穿透轻量体块的特殊例外。

User Stories

作为值班人员，我想看到“模型”实际代表设备在三维场景中的位置符号，以便不会把图标误认为已加载的真实设备几何模型。
作为值班人员，我想在选中监测点后看到其所有具备有效位置的关联监测设备符号，以便观察点位内设备分布。
作为值班人员，我想监测点和监测设备使用统一的视觉风格，以便一张图保持一致的品牌和识别体验。
作为值班人员，我想通过大小区分监测点和监测设备，以便即使两者使用同一素材也能判断对象层级。
作为值班人员，我想监测点始终比监测设备更大，以便监测点的承载关系在不同镜头距离下保持清楚。
作为值班人员，我想图标能随相机距离进行动态缩放，以便近景可读、远景不至于占满画面。
作为值班人员，我想动态缩放不破坏监测点大于监测设备的关系，以便视觉层级不会因镜头变化反转。
作为值班人员，我想默认地图不显示设备长文本，以便设备较多时画面不被文字覆盖。
作为值班人员，我想悬停或选中设备时看到设备名称，以便快速理解设备用途。
作为值班人员，我想在设备名称旁看到设备编码作为辅助信息，以便稳定追踪和核对具体设备。
作为值班人员，我想长名称有明确的截断或换行边界，以便标签不遮挡其它地图对象。
作为值班人员，我想“坐标图标”只代表空间位置，不显示经纬度数字，以便界面保持面向值班工作的简洁信息密度。
作为值班人员，我想监测点颜色表达点位状态，以便读取后端发布的点位业务状态。
作为值班人员，我想监测设备颜色表达设备自身状态，以便设备状态不会被所属监测点的聚合状态替代。
作为值班人员，我想即使两类对象使用同一套颜色外观，图例也能说明它们的状态来源，以便不混淆点位状态与设备状态。
作为值班人员，我想设备 hover 和选中反馈继续使用既定的放大、外环、引线和状态特效，以便资产替换不会改变已经熟悉的交互。
作为值班人员，我想正式图片素材可以替换临时形状簇，以便最终视觉不被原型占位资产限制。
作为维护者，我想资产替换不改变设备拾取身份，以便地图、面板和设备详情的联动契约保持稳定。
作为维护者，我想资产替换不改变状态语义、尺寸层级和定位锚点，以便视觉升级不重新打开既有交互决策。 > 2026-10-08 就地修订（由蓝湖素材替换票 05 Q18=B / Q19=C / Q24=B 裁定）：本条「不改变…定位锚点」与「尺寸层级」的具体数值口径被取代——正式水滴徽标改为尖端锚定（尖端落真实坐标；原为中心锚定），MARKER_SIZE 语义由「边长」改为「宽度基准」并抬高数值以保证横向占位与今天一致（监测点宽 18、设备宽 14；高度按素材 378:475 比例约 22.6 / 17.6），内层图标圆心对齐帽心而非画布几何中心。不变的部分：监测点恒大于设备的层级关系、deviceCode 拾取身份、设备状态语义、选中反馈与面板联动契约仍不得改变。
作为值班人员，我想有效设备位置随当前地形贴地，以便设备符号不会漂浮或埋入地表。
作为值班人员，我想地形尚未就绪时设备保留在清单里并显示位置待确认，以便暂时看不到符号不会被误解为没有设备。
作为值班人员，我想地形采样失败与坐标本身无效被区分提示，以便知道应该等待地图资源还是检查设备数据。
作为值班人员，我想坐标缺失、非法或未通过后端校验的设备不上图但保留原因，以便系统不制造虚假位置。
作为值班人员，我想系统不使用监测点坐标代替设备坐标，以便同一点位下的设备不会被错误堆到监测点上。
作为值班人员，我想系统不通过人工偏移制造设备位置，以便图上位置始终有数据依据。
作为值班人员，我想设备符号和未来真模型遵守正常场景遮挡，以便它们与地形和示意体块的空间关系可信。
作为值班人员，我想未来某一设备类型有合格真模型时可以先启用该类型，以便不必等待所有类型资产同时交付。
作为值班人员，我想同一关联监测设备图层可以同时看到真模型和图标，以便逐步升级不会阻塞其它设备类型。
作为值班人员，我想真模型缺失时仍看到设备专属图标，以便资产交付进度不会影响设备位置巡检。
作为值班人员，我想真模型加载失败时仍看到可靠图标，以便单台资产故障不会让整层白屏或静默丢点。
作为值班人员，我想性能预算不足时系统退回图标而不是静默删点，以便仍能知道设备存在。
作为值班人员，我想在悬停或选中时知道当前设备处于图标模式或真模型不可用，以便理解当前视觉表现的真实状态。
作为值班人员，我想详情卡片显示资产未提供、加载失败、性能降级、地形未就绪或视觉资源异常等具体原因，以便能区分不同问题。
作为值班人员，我想默认地图不被大量错误角标覆盖，以便设备状态和空间分布仍然易读。
作为值班人员，我想图标资源自身失败时仍有通用位置符号，以便最基础的位置表达不会因单个图片资源故障而消失。
作为维护者，我想通用位置符号的使用在详情中被记录为视觉资源异常，以便最后兜底不被误报为正式资产或真模型。
作为资产提供方，我想知道真模型的最低格式和坐标约束，以便交付的资产可以被可靠接入。
作为资产提供方，我想知道模型必须明确 up 轴、前向方向、原点和基准面，以便不同设备类型不会出现朝向或落地不一致。
作为实现人员，我想通过构造确定模型到设备地理坐标的 ENU 变换，以便运行时不需要猜测模型原点。
作为项目负责人，我想外部资产和项目方另立制作事项都能成为未来来源，以便本票不提前承诺未确认的美术工作量。
作为项目负责人，我想真模型的三角面数、同屏数量和实例化策略在实际资产与规模明确后再定，以便性能契约有真实依据。
作为验收人员，我想以驾驶舱外部行为验证位置符号、标签、地形状态和降级状态，以便验收用户实际看到的结果。
作为验收人员，我想确认正式视觉使用可替换的统一素材，而不是把临时形状簇宣布为最终交付，以便产品视觉标准得到落实。
作为验收人员，我想确认关联设备图例独立于监测点摘要图例，以便两种状态语义不被混在一处。

Implementation Decisions

“模型”在本期的正式产品定义是监测设备在三维场景中的位置符号，不是真三维几何模型。位置符号由可替换素材、渲染尺寸、对象自身状态视觉和既有交互反馈组成。
本期不加载真三维设备模型，也不把图标模式命名为真模型。仓库现有内联 SVG 形状簇只能作为临时方案，不能作为最终视觉验收资产。
监测点和监测设备使用相同样式或同一份正式坐标点图片素材。通过程序控制渲染大小区分类型，监测点始终大于监测设备；具体像素值、缩放倍率和相机距离曲线由实现与人工走查校准，不在本规格预设数值。
资产必须有单一可替换接缝。临时形状、正式图片素材和未来其它视觉资源都通过同一资产选择层注入，不把形状字符串或资源地址散落到地图绘制、图例和详情表现中。
素材替换不得改变设备的 deviceCode 拾取身份、所属监测点身份、设备状态语义、尺寸层级、选中反馈、定位锚点或设备与面板的联动契约。 > 2026-10-08 就地修订（由蓝湖素材替换票 05 Q18=B / Q24=B 裁定）：其中「定位锚点」与「尺寸层级的具体数值」两项口径被取代——正式水滴徽标的锚点由中心改为尖端（尖端落真实坐标），尺寸基准由边长改为宽度（监测点宽 18 / 设备宽 14，高度按素材比例约 22.6 / 17.6）。此修订不覆盖本条其余部分：deviceCode 拾取身份、所属监测点身份、设备状态语义、选中反馈与面板联动契约仍不得改变，「监测点恒大于设备」的层级关系亦保持不变。
默认不显示设备长文本。悬停或选中时显示设备名称为主、设备编码为辅；文本需要有稳定的可读边界，过长内容不得撑大地图布局或遮挡前后内容。
“坐标图标”只表示设备的空间位置符号，不直接显示经纬度数字，不把经纬度文本当作标签内容。
颜色按业务对象自身状态解释：监测点使用后端发布的点位状态；监测设备使用监测设备自身状态。两类对象可以使用同一组色彩风格，但不得共用状态来源或用点位状态猜设备状态。
设备状态的颜色、形状、文字和特效继续遵守票 07；面板 hover、三维 hover、选中外环、放大、引线、设备级定位和独立拾取继续遵守票 06/15。本规格不重新定义这些反应。
设备位置只接受后端设备自身的有效经纬度和坐标准入结果。坐标缺失、非法、未通过验证或 coordinateValidation.renderable 为假时不上图，设备保留在关联监测设备清单中并显示明确的无地图位置/不可用原因。
不使用监测点坐标代替设备坐标，不进行人工坐标偏移，不把视觉分离手段伪装成真实设备位置。
有效设备位置需要结合地形采样贴地。地形未加载、采样尚未完成或采样失败时不上图，设备保留在清单中并显示地形未就绪/位置待确认；该状态不能被归类为坐标无效，也不能被算作已上图。
设备位置符号和未来真模型遵守正常地形、示意体块和其它场景对象的深度关系，不开启穿透体块的特殊可见性例外。
真三维模型未来按设备类型逐步接入。某一类型拥有合格资产即可独立启用，尚未提供资产的类型继续使用图标；同一关联监测设备图层允许真模型和图标混合呈现。
真模型资产可以由甲方/业务方提供，也可以由项目方后续另立资产生产事项制作。本票只定义接入边界，不承诺资产生产和版本维护工作已经排期。
真模型最低接入契约为 glTF/GLB、米制、明确 up 轴、前向朝向、原点和模型基准面。接入侧必须由构造确定模型到设备地理坐标的 ENU 变换，不靠运行时猜测原点或朝向。
真模型的三角面预算、同屏数量上限和同型号实例化策略留给未来资产/实施事项，必须在真实设备类型和规模明确后通过实测确定。没有实测依据时不得在本规格写死数字。
真模型资产未提供、格式/坐标契约不合格、加载失败或性能超预算时，单台设备退回设备专属图标，不影响其它设备和其它资产类型继续显示。
降级图标仍必须保持设备的身份、状态和交互能力，不能把图标兜底计为真模型成功加载，也不能把未绘制的设备静默计入逐台真模型呈现。
地图默认不增加统一错误角标。悬停或选中时显示图标模式/模型不可用等可理解状态；详情卡片显示具体原因，至少区分资产未提供、资产加载失败、性能降级、地形未就绪和视觉资源异常。
正式设备图片资源自身加载失败时使用内置通用位置符号作为最后兜底，并在详情中标明视觉资源异常；通用符号不是正式素材，也不是真模型。
关联监测设备使用独立图例，不并入监测点摘要图例。颜色不是唯一线索，仍需结合形状、文字、尺寸层级和票 06 的选中反馈表达对象与状态。
资产状态和位置状态必须能被关联监测设备清单解释。没有图标、没有真模型或暂不上图不等于设备不存在；“未确认”“无地图位置”“资产降级”和“模式隐藏”需保持可区分，具体图层计数沿票 14/15 和票 11 的契约执行。

Testing Decisions

最高测试接缝是驾驶舱外壳的外部可观察行为：从地图或监测点台账选中监测点，观察关联监测设备图层中的位置符号、监测点/设备大小关系、标签出现、状态语义、地形状态、降级提示和图例边界。验收不读取 Cesium 私有实体，不依赖组件私有变量。
领域纯逻辑测试覆盖资产选择与降级分类：本期图标模式与未来真模型模式可区分；资产未提供、加载失败、性能超预算、图标资源失败、地形未就绪、坐标无效等原因不能混成成功或不存在；真模型可用性按设备类型独立决定。
领域纯逻辑测试覆盖尺寸层级：在所有允许的相机距离和配置范围内，监测点渲染尺寸始终大于监测设备；动态缩放不得改变这一关系。
领域纯逻辑测试覆盖状态来源：监测点读取点位状态，监测设备读取设备自身状态；设备不得从所属监测点状态推导。状态未知必须保持未知或待确认，不猜成正常。
驾驶舱走查覆盖正式素材替换接缝：临时形状可以用于开发期验证，但最终视觉验收必须使用正式可替换的坐标点图片素材，且地图标记、独立图例和详情表现不会各自使用不同资源。
驾驶舱走查覆盖同一关联设备图层的混合呈现：已配置真模型的设备显示模型，未配置或不可用的设备显示图标，并且两者的拾取身份、状态表达、选中反馈、定位锚点和清单归属一致。
驾驶舱走查覆盖地形状态：地形就绪时有效设备符号贴地；地形未就绪或采样失败时设备不上图但清单显示位置待确认；无效坐标显示无地图位置；任何情形都不使用监测点坐标或人工偏移。
驾驶舱走查覆盖正常场景遮挡：位置符号和真模型遵守地形与示意体块的深度关系，不穿透显示。
驾驶舱走查覆盖标签：默认无长文本，悬停或选中显示名称为主、编码为辅；长内容不会撑破布局或遮挡不相关对象。
驾驶舱走查覆盖降级可见性：地图不被统一错误角标污染；悬停/选中与详情卡片能说明图标模式、模型不可用和具体原因；图标资源自身失败时通用位置符号仍可见且详情记录视觉资源异常。
驾驶舱走查覆盖图例边界：监测点摘要图例和关联监测设备图例分开；相同颜色外观不会导致两类业务状态被当成同一种状态。
真模型未来接入的专项验收应在资产事项或实施事项中补充真实设备类型的朝向、尺寸、原点、ENU 落点、加载成功率、同屏数量和性能实测；本规格不以静态资源存在作为当前实现已完成的证据。
回归沿用票 14 的关联监测设备图层生命周期、票 15 的设备拾取与双向联动、票 07 的设备状态视觉和票 11 的重叠/超量呈现验收先例。规格阶段只写验收契约，不运行 build、dev 或浏览器调试。

Out of Scope

本期设备级真三维模型的制作、采购、授权、版本维护和全量资产交付。
固定的模型三角面预算、同屏设备数量上限、实例化实现和具体性能数字。
设备坐标与坐标校验后端契约的补齐，以及设备状态来源的后端改造；由票 09 和后续后端工作负责。
关联监测设备图层的触发、生命周期、快照差异、模式可见性和计数体系；由票 05/14 负责。
面板与三维设备点的 hover、选中、引线、设备级定位、独立拾取和双向联动；由票 06/15 负责。
设备状态五态、动态特效、并发动画和特效开关；由票 07 负责。
同坐标或极近设备的聚合、视觉展开、逐台拾取和极端量级降级；由票 11 负责。
跨监测点的点位聚合、设施/管线/事件等其它地图图层的模型和资产口径。
经纬度数字标签、管理端写操作、登录权限、移动端、竖屏和多屏拼接。
覆盖或改写票 03 的点位级/设备级相机数值、票 04/12 的面板锚点契约或票 13 的完整一级模式矩阵。

Further Notes

本规格的唯一决策来源是票 10 的 ## Answer，并吸收票 08 原型验收留下的硬前提：临时内联 SVG 形状不是最终视觉，必须存在可替换的正式资产接缝。
当前仓库没有本地设备级 glTF/GLB；未来 src/plugins/zoneFreeScene 中的远程 demo 资源不能直接成为驾驶舱生产资产。真模型必须经过独立资产校验和接入事项。
“设备点位”在本规格中只描述监测设备在关联监测设备图层中的空间显示，不新增业务对象。领域文档继续使用“监测设备”和“关联监测设备图层”区分业务对象与显示概念。
点位状态与监测设备自身状态可以使用相同颜色风格，但它们必须由各自的图例、对象身份和状态来源解释；实现不得重新引入“用点位状态给设备配色”的越界。
本规格发布后，后续实现应以票 09 的设备级坐标/状态契约或明确的清单降级为前提，并同时消费票 14、15 及本规格。当前规格交付不表示设备图层或正式视觉资产已经实现。

Comments

规格验收核对

已依据维护者确认的 Q1–Q20 结论、CONTEXT.md 领域词汇、票 05/06/07/08/14/15 的既有边界和当前仓库资产事实编写。测试接缝采用驾驶舱外壳外部行为为主、领域纯逻辑为辅；没有把具体实现文件路径或未经确认的性能数字写成规格契约。本次只发布规格文档和更新决策票状态，不运行 build、dev 或浏览器调试。

16-device-model-and-asset-spec.md 21 KB History Raw