工厂3D可视化接实时数据，最容易踩的坑不是接口写不出来，而是现场设备、三维模型和数据字段各用各的名字。模型里叫“Pump_01”，设备台账写“循环水泵1”，接口返回“P-101A”，三套名称没有统一，画面再漂亮也可能把数据放错设备。
因此，这类项目应先做设备编码和数据映射，再做状态表现和大屏页面。顺序反过来，后期每接一批数据都可能重新改模型、改接口、改交互。
一、先确认要接的是真实数据还是演示数据
有些项目只需要在汇报或培训时展示生产流程，使用预设动画和模拟数据即可；有些项目需要值班人员查看设备状态、参数和告警，就必须连接生产系统、物联网平台或业务数据库。两种需求都可以做，但验收标准完全不同。
项目开始前要列出数据来源、负责人、接口方式、更新频率、网络环境和可用时间。若真实接口暂时未开放，应明确哪些页面使用模拟值，后续替换需要哪些条件，不能把演示数据包装成实时监控。
二、建立一张可以共同使用的设备编码表
编码表不是开发团队单独整理的技术文件，而是设备人员、数据人员、模型人员和软件开发共同确认的业务底稿。每台关键设备至少应记录唯一标识、名称、类型、区域、模型节点、接口字段、单位和状态规则。
例如现场的一台循环水泵，无论出现在设备台账、三维场景、告警记录还是接口报文中，都应能够通过同一个业务标识找到。显示名称可以根据页面调整，但主标识不能随意变化。
设备编码是数据映射基础
还要提前约定新增设备和改名流程。如果只是让开发人员在代码中临时写死，后续设备更换或产线调整时，维护人员很难判断应该改模型、数据库还是接口。
三、接口字段要同时说明单位、时间和异常值
接口文档不能只有字段名。温度是摄氏度还是华氏度，压力使用MPa还是kPa，产量是当班、当日还是累计值，都需要写清楚。数值还要带更新时间，让用户知道眼前看到的是刚更新的数据，还是接口中断前的最后记录。
建议至少测试四种状态：正常返回、空值、异常值和接口断开。空值不能默认显示为0，断开也不能继续显示绿色“运行中”。系统应明确提示数据不可用，并记录发生时间，避免管理人员误判。
如果数据经过物联网平台、消息队列和业务中台多次转发，还要确认每一层使用的设备标识和时间基准。现场状态已经变化，但中间缓存仍返回旧值时，页面需要根据更新时间判断是否过期，而不是只根据数值本身变色。
接口联调最好由现场人员参与。开发人员可以确认字段是否返回，却不一定知道“停机”“待机”“检修”和“故障”在现场分别代表什么。状态映射表应由业务人员确认，并保留版本记录。
四、状态和告警要能落到具体设备
工业大屏常用绿色表示运行、灰色表示停机、黄色表示待机、红色表示故障，但颜色只是结果。真正有用的告警还要包含设备、级别、时间、内容和处理状态。
用户从告警列表点击记录后，三维视角应定位到对应设备，并显示关键参数。设备被管线或建筑遮挡时，可以使用轮廓高亮、局部透明或区域隔离。否则告警数量一多，用户仍然需要回到二维台账查找。
五、大屏页面不要把所有数据一次塞满
三维场景、设备列表、指标卡、趋势图和告警表同时出现，很容易互相遮挡。更合适的方式是把全局状态、异常和当前任务放在第一层，设备详情和历史趋势通过点击进入第二层。
大屏验收必须使用现场分辨率和观看距离。开发电脑上能看清的小字，放到会议室或车间大屏上可能无法阅读；弹窗在普通显示器里正常，换成超宽屏也可能跑到边界之外。
六、用一段典型产线完成闭环测试
不要一开始就把全厂模型和所有接口同时铺开。可以先选择设备类型比较完整、数据条件较好的典型区域，完成模型轻量化、设备编码、数据刷新、告警定位、页面交互和异常恢复，再把规则扩展到其他区域。
九影网络在石英砂加工虚拟仿真项目中，把破碎、水洗、磁选、搅拌、筛选、酸洗、固液分离、烘干、储存和废水处理等工艺节点放到同一三维场景，并结合产量、产值、时间、设备状态和全流程演示。此类项目测试时，工艺顺序、设备名称、数据口径和大屏阅读需要一起核对，不能分成互不关联的四次验收。
六项验收覆盖模型数据和大屏
七、上线前再检查维护和异常恢复
正式上线前，应测试网络中断、接口超时、浏览器刷新、电脑重启和长时间运行。系统需要说明数据多久未更新会提示离线，恢复连接后是自动同步还是需要人工操作。
交付时还要保留模型文件、设备编码表、接口字段表、状态规则、部署说明和账号权限。工厂3D可视化不是一次性视频，后续设备和业务会变化，能否继续维护应从第一期就写进项目范围。
还可以让一名没有参与开发的值班人员独立完成一次操作：从告警进入设备、查看参数、切换区域并返回全局。只有熟悉项目的人才能操作成功，通常说明页面逻辑和提示仍需调整。
