项目：设备采样数据与趋势面板

先定义一条采样记录意味着什么

这个项目用合成设备数据制作趋势面板。读者可以在本地生成时间序列，观察接收、去重、聚合与图表之间的关系，不需要接入真实设备。第一版回答三个问题：某个时间段收到了哪些有效样本，趋势是否连续，最后一次可靠数据是什么时候。

记录至少包括设备 ID、事件身份、采样时间、接收时间、数值、单位与质量标记。采样时间表示设备声称何时测量，接收时间表示服务何时收到，两者不能混用。网络延迟或设备时钟错误可能造成明显差异；把接收时间画成测量时间，会把迟到样本误当成新的变化。

事件身份可以由设备与序号组成，但必须说明序号是否会在重启后复用。必要时加入设备会话或启动标识。两个设备的序号相同不代表重复，同一事件重复上传则不应增加样本数量。数据模型先固定这些规则，图表才有可解释的输入。

接收端负责验证与可恢复写入

采用 Go 时，可以用 net/http 建立接收接口。认证后的设备身份与记录内设备 ID 必须对应；文本字段、批次数量和请求体都设置上限。MaxBytesReader 可限制读取的请求体大小，读取请求头的超时与读取请求体的期限要分别考虑，不能把 ReadHeaderTimeout 当作整个上传超时。

服务端解析后检查字段类型、时间格式、有限数值与单位。教学范围可以规定一个允许的数值区间，但区间通过不等于传感器经过校准；物理有效性仍取决于设备和测量流程。坏质量、时间异常与格式错误要有明确处理政策，保留原因或拒绝记录，不能静默变成零。

把事件唯一约束与样本写入放进适合的数据库操作。响应丢失后设备会重传，接收端按同一身份识别它。重复身份但数值不同是冲突，应该记录和处理；不要默认后来一条就更正确。接口返回哪些事件被接受、哪些被拒绝，便于客户端有限重试。

按事件时间聚合合成样本

下面用相对秒数代替真实时钟，四条输入里有一条完全重复记录。字典按合成事件 ID 去重，再按一分钟窗口计算均值。窗口 0 包含 0 秒和 30 秒的两个样本，窗口 1 包含 60 秒的一个样本。

samples = [("S-1", 0, 10), ("S-1", 0, 10), ("S-2", 30, 20), ("S-3", 60, 30)]
unique = {sample_id: (time, value) for sample_id, time, value in samples}
windows = {}
for time, value in unique.values():
    windows.setdefault(time//60, []).append(value)
means = {window: sum(values)/len(values) for window, values in windows.items()}
assert len(unique) == 3
assert means == {0: 15.0, 1: 30.0}
print(means)

输出为 {0: 15.0, 1: 30.0}，唯一事件数为三。示例按输入顺序保留同一 ID 的最后一条；它没有判断修订时间，也没有解决相同 ID 不同内容的冲突。实际数据先执行身份和冲突政策，再进入聚合。

代码计算的是样本的算术平均，各样本权重相同。如果采样间隔不均匀，它不自动等于一段时间内的时间加权平均。没有样本的窗口不会出现在字典中；前端必须知道它缺失，不能用零补齐后声称设备停止活动。这个模型不验证设备校准、流式性能或任何真实观测结论。

迟到、缺失和过期分别处理

窗口采用采样时间还是接收时间应成为接口契约。选择采样时间时，迟到样本可能修订历史窗口。规定允许修订的期限、窗口版本和刷新策略；选择接收时间时，则明确面板展示的是到达趋势。两个用途不同，不应在同一图里悄悄切换。

存储统一时间基准，展示时按用户时区格式化，保留原始时间供核查。先排序再连线，避免乱序事件使折线折返。设备上报未来时间、重启序号或长时间断网后批量补传，都应在验收样本里出现。

新鲜度由最后一个符合政策的样本与当前时间的差值决定。只有一个旧数据点时，页面应显示“数据已过期”，而不是持续显示一个看似实时的数值。未知、坏质量、缺失和测得的零值分别呈现；这些状态影响读者是否能依赖图表作决定。

图表与服务监控使用不同的数据路径

聚合接口返回窗口起点、样本数、最小值、最大值、均值及质量信息。Vega-Lite 可以声明时间轴、数值轴和图形编码，具体字段类型与单位仍由项目提供。读取面板的人需要看到时间范围、单位、刷新时间与缺口，也需要一个能核对数值的表格或文本视图。

设备样本属于业务数据。Prometheus 更适合观察接收服务的请求量、错误和处理延迟等运行指标；它以指标名和标签组合识别时间序列，随意把每条事件 ID 或大量动态设备 ID 加为标签会扩大序列数量。不要为了少建一层存储，就把业务原始事件无差别塞进服务监控。

告警规则另外定义。练习可以要求连续多个有效窗口超过阈值才触发，并区分数据异常告警和数据断流告警。阈值与持续时间是教学政策，不能宣称适用于真实安全设备。恢复通知、重复通知与无人确认时的处理也要写清。

设备更换单位或采样协议时，为记录加入模式版本，避免同名数值被聚合到同一序列。单位转换保留原值与规则，不能只在图表标签上改名字。把不兼容版本隔离展示或拒绝接收，重放历史数据时使用当时的转换约定。

从固定数据重放到接口验收

先生成一份固定样本，完成去重、窗口结果和静态图表，再连接 Go 接收端和查询接口。记录数据版本，前端请求更新时只展示当前范围对应的响应，避免旧范围的慢请求覆盖新图表。大范围查询设置聚合粒度和结果数量上限。

测试完整重复、身份冲突、乱序、跨窗口边界、零值、缺失窗口、无穷大或非法数值、时区切换、过期样本与批量补传。分别核对原始事件数、唯一有效事件数和窗口计数；这三个数不同可能是正常处理，也可能暴露去重错误，需要依据政策判断。

验收时既检查图表，也检查表格和空状态。重新启动服务后仍应读取已确认写入的样本；接收失败应给出可恢复状态。只有完成实际接口、数据库和浏览器检查，才能评价整条数据路径，本篇离线代码只证明合成输入上的聚合结果。