分钟级计数界面里，一个“0”可能表示实际测量值，也可能只是接口没有返回数据。把这两种状态混在一起，图表会显得连续，读者却无法知道哪里缺了证据。本文用一组可运行的 Python 合成样例，说明怎样把有效零值、缺失、陈旧和时间错误分开。
先固定三个时间，别只保留刷新时间
这里区分三个字段：数据所属周期period，系统观察到这条数据的时间observed_at，以及本次检查的时间now。页面刚刚刷新，不代表数据所属周期也是最新的；刚刚收到的数据，也可能属于上一分钟。
判断前还要固定本次需要的周期expected_period。刷新时间新、数值正常，但周期对不上时，应该显示“周期不匹配”，而不是把它填进当前格子。下面的例子使用带时区的时间对象，统一在 UTC 中构造样例；展示给读者时再转换到明确标注的时区。
缺失和零值用不同状态表示
None表示没有样本，不应补成 0。只有样本存在、周期匹配、时间有效且数值通过检查之后，0 才是有效测量值。
同样，不把布尔值当数字使用。Python 中bool是int的子类；只写isinstance(value, (int, float))，会把True接受为 1。还应拒绝 NaN 和无穷值。这个教程只处理整数与浮点数的简单计数样例，字符串、Decimal 和真实业务单位需要另订输入合同。
一个只读分类器
以下代码不请求外部数据源、不调用模型、不改变原始样本。75 秒是演示使用的延迟阈值，实际系统应根据数据来源和采样周期确定，不能照搬为通用标准。
fromdatetimeimportdatetimefrommathimportisfinitedefclassify_sample(sample,*,now,expected_period,max_delay_seconds=75):ifnow.tzinfoisNoneorexpected_period.tzinfoisNone:raiseValueError('now and expected_period require timezones')ifsampleisNone:return'missing'observed=sample.get('observed_at')period=sample.get('period')value=sample.get('value')ifnotisinstance(observed,datetime)orobserved.tzinfoisNone:return'invalid_timestamp'ifnotisinstance(period,datetime)orperiod.tzinfoisNone:return'invalid_timestamp'ifobserved>noworperiod>now:return'future_timestamp'ifperiod!=expected_period:return'wrong_period'if(now-observed).total_seconds()>max_delay_seconds:return'stale'ifisinstance(value,bool)ornotisinstance(value,(int,float))ornotisfinite(value):return'invalid_value'return'valid_zero'ifvalue==0else'valid_value'这个函数一次只返回一个原因，顺序就是原因的优先级。如果业务需要同时展示多项错误，应返回错误列表，而不是把首个原因当成唯一原因。它也不证明输入来自可信数据源，更不能替代真实系统的重复记录、乱序和周期完整性检查。
用合成数据检查边界
下列样例需与上一节的 classify_sample 在同一解释器中运行。每一项都可以手动改动，观察状态如何变化。所有时间和数值都是构造的计数数据，不是真实业务记录。
fromdatetimeimportdatetime,timedelta,timezone now=datetime(2026,10,14,4,31,10,tzinfo=timezone.utc)period=datetime(2026,10,14,4,30,tzinfo=timezone.utc)base={'period':period,'observed_at':now-timedelta(seconds=5),'value':0}cases=[('missing',None),('valid_zero',base),('valid_value',{**base,'value':8}),('stale',{**base,'observed_at':now-timedelta(seconds=120)}),('wrong_period',{**base,'period':period-timedelta(minutes=1)}),('future_timestamp',{**base,'observed_at':now+timedelta(seconds=1)}),('invalid_timestamp',{**base,'period':period.replace(tzinfo=None)}),('invalid_value',{**base,'value':float('nan')}),('invalid_value',{**base,'value':True}),]forexpected,sampleincases:actual=classify_sample(sample,now=now,expected_period=period)assertactual==expected,(expected,actual)print(actual)本地执行时这 9 个样例通过断言。它们验证的是本文分类器在这些输入下的行为，不能据此宣布生产数据链路已经完整、实时或可靠。
把状态带到界面和统计里
有效零值显示“0”，缺失显示“缺失”，陈旧显示对应数据时间。折线遇到缺失应保留断点；如果为了展示做了插值，应显著区分并保留原始缺口。用最近值填充时，原时间也要保留，不能把填充值重新打上当前时间。
后台统计同样分开记录：应该收到多少个周期、实际收到多少个周期、有效多少、缺失多少、陈旧多少。只统计成功记录、把缺失样本从分母删掉，会让质量比例显得过分漂亮。
对已经完成的周期和仍在变化的周期，也应建立不同状态。完整性、数据新鲜度和界面刷新速度分别核对，才能让读者知道眼前的数字代表什么。
参考：Python 官方 datetime 文档中关于 aware / naive 时间对象、时区与时间差运算的说明：https://docs.python.org/3/library/datetime.html
作者说明：本文由 AI 辅助撰写，示例代码使用合成数据在本地执行验证，讨论范围是数据工程与界面表达。
