孪生看板把无数据画成零，怎样区分 null、缺字段和真实 0

孪生数值0表示一个真实的零读数，null、缺字段和质量不良则分别有不同含义，不能全用默认0替代。应先判断字段是否存在，再判断null、类型和quality，最后才格式化数值。这样设备确实停机或能耗确实为零时能正常显示，无数据也不会被误画成正常低值。

环境和证据范围

附件定义一套合成契约：value必须是JSON数字，quality=good才可显示。null显示“无数据”，缺字段显示“缺字段”，字符串0为类型错误，bad质量即使带数值也显示质量异常。实际系统的质量码与空值语义要对照设备文档，不用本页标签强行替换。

核对顺序

1. 在点表中把缺采样、数据未授权、设备异常和实际零值分别列出，明确它们怎样进入payload。前端不能仅凭没有颜色变化猜设备正常，图例应能表达未知和错误。

2. 处理顺序先检查成员存在性，再检查null与数值类型。Python中bool也是int的子类，脚本明确排除布尔；JavaScript中也不能用value||0或if(!value)把合法0合并成缺值。

3. 质量检查独立于数值，quality=bad时即使value=0，也不作为正常零值参与告警或统计。缺quality如何处理需要契约；附件要求有good，缺失按质量未知处理，不自行补齐。

4. 展示文字与统计入口使用同一分类，未知值不纳入平均值分母，真实零值则应纳入。趋势图的断线段也应与零线区分，不能为了曲线连续用零填空或默认沿用旧值。

可复算的输入与预期

五类样例依次输出“0”“无数据”“缺字段”“类型错误”“质量异常”；另加value=false得到类型错误。脚本实际解析fixture中的类型与存在性，不只检查文本是不是0。数字0合法显示，证明校验没有用真假判断把它误删。

下载与现场记录

下载本题合成输入与预期JSON、离线只读核验脚本和现场空白记录CSV。放在同一目录，用 Python 3 运行 python verify.py，逐项计算或解析后与预期比较，失败会显示差异。

现场字段包括 point_id、value_present、raw_value、json_type、quality、display_text、included_in_statistics。合成样例保持原样，实测另存并填写型号、版本、证据路径，未采集处留空。本地核验不代表真实设备、代理、浏览器或长期稳定性已测。

失败分支与移交

null不是NaN，JSON规范也不允许直接写NaN或Infinity作为数字。接口用空字符串代替无数据时，应显式记录兼容规则，不能让所有非数字都变0。把坏质量值显示成最后正常值也必须附时间与质量说明，不能让观众误以为数据仍实时可信。

交接资料应包含空值语义、质量枚举、展示文字、统计是否纳入和原始样例。真实现场还要测试断开数据源、权限不足、正常零值与设备坏质量，记录从采集到展示的每一层。本文仅证明合成契约分类，没有执行任何真实断链实验。

基础背景可看孪生数据的实时刷新策略：轮询、订阅与降频怎么定。若数值正确却点亮错对象，再核对孪生点位绑错同名模型，怎样用稳定 ID 检查映射一对多。更多资料在数字孪生技术方案。

需要项目联调时，可按上述字段整理资料，联系企服君核对实际接入范围。

一级资料

• 官方资料：§3 JSON值类型、§4对象成员；质量标签属于业务约定

核对日期：2026-10-24。规范定义与本文应用约定分开，示例门限及脚本不自动代表产品原生能力。