测量值语义：Raw、工程量、阈值与日志

内容类型：专项方法难度：进阶适合：处理示波器、电源、传感器、采集卡和试验参数的上位机工程师阅读时间：约 8 分钟

测量类 Bug 很多并不是“公式不会写”，而是同一个变量在不同层代表的东西不一样：设备原始量、换算后的工程量、界面显示值、判定阈值和日志记录值被混在一起。

V10 对这类任务使用一个很小的 Measurement Semantics 检查表。

六个必须分清的概念

RawValue
EngineeringValue
Conversion
ThresholdBasis
Aggregation
LoggedUnit

字段	要回答的问题
RawValue	设备/协议最初给出的是什么？单位是什么？
EngineeringValue	业务真正使用的物理量是什么？
Conversion	Raw 到工程量怎样换算？方向是否正确？
ThresholdBasis	阈值比较的是 Raw 还是工程量？
Aggregation	单帧、最大值、平均值、连续 N 次还是窗口统计？
LoggedUnit	日志到底保存哪一层值，单位写什么？

一个典型例子

假设示波器 CH2 峰值返回：

RawValue = 0.45 V
Sensitivity = 0.005 V/A

那么工程电流是：

EngineeringValue = 0.45 / 0.005 = 90 A

这时下面几句话代表完全不同的需求：

• “日志保存原始值” → 应记录 0.45 V；
• “日志保存电流值” → 应记录 90 A；
• “阈值 90 A” → 判定前必须确认比较的是工程电流；
• “保存未经 0.005 换算的原始电流” → 这句话本身有量纲歧义，应先确认用户真正想要 Raw CH2 电压还是工程电流。

修改测量逻辑时的最短检查

设备/协议原始数据在哪里产生？
→ 换算在哪里发生？
→ 判定使用哪一层值？
→ UI 显示哪一层值？
→ 日志/CSV/MES 保存哪一层值？
→ 单位是否一致？

不需要为了这六项扫描整个仓库。找到数据 owner 和主要消费者后就停止扩搜。

Aggregation 也属于测量语义

下面这些行为不能当成同一种判断：

单次 >= 90 A
连续 5 次 >= 90 A
5 次平均 >= 90 A
一个窗口最大值 >= 90 A
连续 5 次 >= 本轮峰值的 90%

涉及“连续 N 次”时还要确认：

• 中间一次正常是否清零；
• 无效帧是否清零；
• 一个窗口是否只触发一次；
• 下一窗口何时复位；
• 日志记录触发帧还是整个连续序列。

这些内容通常应和 行为与告警语义 一起检查。

常见错误

错误	后果
变量名叫 Current，但实际保存的是 V	后续开发者误用
阈值按 A 配置，代码拿 V 直接比较	判定完全错误
已换算一次又再次除灵敏度	数值放大
UI 显示平均值，日志却写瞬时值但不标注	现场无法复盘
Raw 日志没有单位	数据看似完整但不可解释
MES 与本地使用不同换算路径	同一试验出现两套结果

推荐命名

尽量让变量和字段表达层级，例如：

rawChannel2PeakVolts
currentAmps
averageCurrentAmps
thresholdAmps
loggedRawPeakVolts

不一定要照这个英文命名，但不要让同一个 value 在不同方法里不断改变物理意义。

验证建议

测量值修改通常至少是 V2：

• 用固定 Raw 输入验证换算结果；
• 用边界值验证阈值；
• 连续判断要覆盖“刚好 N 次”“中间一次恢复”“窗口重置”；
• 日志/CSV 断言数值和单位；
• 真实设备验证与模拟验证分开记录。

和 V10 Skill 的关系

当任务涉及示波器、电源、传感器、采集卡、ADC、校准系数或“原始值/换算值”时，host-computer-dev 会按需启用 Measurement Semantics，而不会对所有普通 UI 修改加载这套规则。

相关页面：

• 功能修改最小流程
• 行为与告警语义
• 回归测试与验收

一句话原则

先确定这个数字在物理上到底是什么，再讨论怎么显示、怎么比较、怎么记录。