feat: 按35MPa满充模型提供剩余氢量估算与百分比
This commit is contained in:
lingniu
@@ -1,6 +1,6 @@
|
||||
# OneOS 氢能车辆实况接口交付契约
|
||||
|
||||
契约修订日期：2026-09-08。对应 `/api/v1/vehicles/realtime/query`、`/mileage/query`、`/hydrogen-consumption/query` 的增量交付。实际发布版本、上线时间及脱敏联调证据由发布验收记录提供，本文不将开发完成等同于线上验收完成。
|
||||
契约版本：1.9.0；修订日期：2026-09-08。对应 `/api/v1/vehicles/realtime/query`、`/mileage/query`、`/hydrogen-consumption/query` 的增量交付。实际发布版本、上线时间及脱敏联调证据由发布验收记录提供，本文不将开发完成等同于线上验收完成。
|
||||
|
||||
## 兼容性与授权
|
||||
|
||||
@@ -12,26 +12,58 @@
|
||||
|
||||
| 字段 | 类型/单位 | 本次口径 |
|
||||
| --- | --- | --- |
|
||||
| remainingHydrogenKg | number/null，kg | GB32960 广东燃料电池扩展 0x34 终端全车氢质量直接上报；保留真实零，不汇总单瓶、不由压力推算 |
|
||||
| remainingHydrogenPercent | number/null，% | 当前缺少可信质量容量分母，固定 null，字段级 UNSUPPORTED；不使用 SOC 或当日消耗替代 |
|
||||
| remainingHydrogenKg | number/null，kg | 优先 GB32960 广东扩展 0x34 终端上报；缺质量时同帧最大氢压/氢温与 VIN 全车水容积作实气估算；保留真实零 |
|
||||
| remainingHydrogenPercent | number/null，% | 剩余质量 / 35 MPa、15°C 满充模型质量 × 100；缺容量 null/MISSING，超过100 null/INVALID，不以SOC替代 |
|
||||
| hydrogenRecordTime | RFC 3339/null | 精确匹配 raw_frames 原始同帧采集时间，非合并快照更新时间 |
|
||||
| hydrogenDataStatus | enum | NORMAL/PARTIAL/STALE/MISSING/UNSUPPORTED/INVALID；当前 kg 有效但百分比不支持为 PARTIAL |
|
||||
| hydrogenDataStatus | enum | NORMAL/PARTIAL/STALE/MISSING/UNSUPPORTED/INVALID；两项有效为 NORMAL（估算由来源区别）；仅一项有效为 PARTIAL |
|
||||
| remainingHydrogenKgStatus / remainingHydrogenPercentStatus | enum | 分别为 NORMAL/STALE/MISSING/UNSUPPORTED/INVALID，客户端独立判断 |
|
||||
| hydrogenValueSource / hydrogenSourceProtocol | string/null | REPORTED 仅表示终端上报，无法确认终端内部采用测量还是估算；储氢协议独立于位置 protocol |
|
||||
| hydrogenValueSource / hydrogenSourceProtocol | string/null | kg 来源 REPORTED 仅确认终端上报，ESTIMATED 为平台模型估算；储氢协议独立于位置 protocol |
|
||||
| hydrogenStaleAfterSeconds | integer/null，秒 | GB32960 服务陈旧阈值 300；并非协议规定更新频率 |
|
||||
| hydrogenExpectedIntervalSeconds | integer/null，秒 | 各协议未确认上报周期，当前为 null |
|
||||
| gpsFixStatus | FIXED/NO_FIX/UNKNOWN | 来源为实际位置报文定位位，不根据在线、运动或记录年龄推断 |
|
||||
| locationRecordTime | RFC 3339/null | 位置实际采集时间，可与主记录 recordTime 不同 |
|
||||
| coordinateSystem | WGS84/GCJ02/UNKNOWN | 仅 GB2025 显式坐标类型 1/2 对应 WGS84/GCJ02；GB2016/JT808/MQTT 暂无确证为 UNKNOWN |
|
||||
|
||||
平台接受 0–200 kg，超出范围、非有限值或采集时间超过请求时刻 1 分钟标为 INVALID 并返回 null。超过 300 秒的有效质量保留数值并标 STALE，客户端需提示陈旧；PARTIAL 仍需逐字段判断。聚合 NORMAL 保留供未来两字段均有效，目前不会输出。原始帧未找到返回 MISSING；补充历史查询共享 3 秒预算，查询异常或超时降级为 MISSING/UNKNOWN 并保留旧实时字段，不以合并快照伪造采集时间。因此 MISSING 既可能暂无记录，也可能本次未取得可信证据，不能据此断言设备不支持。
|
||||
终端上报接受 0–200 kg，平台估算接受 0–500 kg；非有限值、超出范围或采集时间超过请求时刻 1 分钟标 INVALID/null。估算压力需为0–70 MPa、温度为−40–726.85°C（沿用模型输入域，不是车辆安全阈值），且必须来自同一原始帧；压力0有效，缺温度不填默认值。超过 300 秒的有效质量保留数值并标 STALE，客户端需提示陈旧；PARTIAL 仍需逐字段判断。两字段有效时聚合为 NORMAL；估算与否查看来源。百分比超过100拒绝该百分比，kg仍独立可用，聚合 PARTIAL（陈旧时 STALE）；EXCEEDS_NOMINAL_FULL_CAPACITY 表示超出本次模型参考，不是车辆安全判定。原始帧未找到返回 MISSING；补充历史查询共享 3 秒预算，查询异常或超时降级为 MISSING/UNKNOWN 并保留旧实时字段，不以合并快照伪造采集时间。因此 MISSING 既可能暂无记录，也可能本次未取得可信证据，不能据此断言设备不支持。
|
||||
|
||||
有界回补仅针对具有 GB 最新快照原始帧引用、且精确帧氢量为 MISSING 的车辆：查询该快照 `received_at` 向前 5 分钟内含氢量键的原始帧，按 `event_time DESC, ts DESC` 取最新候选。窗口以快照接收时间为基准，不是 API 当前时间；离线车辆可返回真实的 STALE。显式 null 或异常候选不被过滤成旧正常值；已有 INVALID/PARTIAL/STALE 不回补，不能掩盖最新异常。回补所得氢量及 hydrogenRecordTime 始终来自同一原始帧，仍共享 3 秒预算；超时或无记录维持 MISSING。该策略不会扫描全部历史，也不承诺找到窗口外最近一条氢量。
|
||||
有界回补仅针对具有 GB 最新快照原始帧引用、且精确帧氢量为 MISSING 的车辆：查询该快照 `received_at` 向前 5 分钟内含氢量、氢压或氢温键的原始帧，按 `event_time DESC, ts DESC` 检查最近5条候选；最新仅有不完整温压时可取次新完整原始帧，最新显式异常仍阻止回补。窗口以快照接收时间为基准，不是 API 当前时间；离线车辆可返回真实的 STALE。显式 null 或异常候选不被过滤成旧正常值；已有 NORMAL/INVALID/PARTIAL/STALE 不回补，不能掩盖最新异常。回补所得氢量及 hydrogenRecordTime 始终来自同一原始帧，仍共享 3 秒预算；超时或无记录维持 MISSING。该策略不会扫描全部历史，也不承诺找到窗口外最近一条氢量。
|
||||
|
||||
储氢覆盖以收到扩展字段的 GB32960 车辆为限，不代表所有 GB32960 车型支持；MQTT/JT808 当前不支持储氢。平台不提供凭容量未知的百分比换算，因而本次不保证 Seeker 所有车辆两列均有值。多瓶完整性由终端全车上报负责，接口没有逐瓶完整性检测能力。
|
||||
储氢覆盖 GB32960 终端质量上报，以及具备有效同帧压力/温度和已配置 VIN 全车容积的车辆；MQTT/JT808 当前不支持储氢。GB32960 或尚无协议记录的车辆，完全没有储氢字段时两字段状态为 MISSING；有容量但无读数原因 MISSING_HYDROGEN_MEASUREMENT。收到压力/温度或终端质量但缺容积时比例 MISSING。没有容积时可保留终端上报 kg，百分比 null/MISSING；没有终端质量时无法估算 kg，两个数值均可为空。最大氢压与最大氢温不保证来自同一瓶，以全车容积计算属于近似估算，不是逐瓶质量求和，也没有逐瓶完整性检测能力。
|
||||
|
||||
定位使用位置行的 event_id 对应原始报文：GB 定位状态 bit0=0 表示 FIXED；JT808 bit1=1 表示 FIXED；缺少可信定位位为 UNKNOWN。NO_FIX 时位置不可用、经纬度 null。历史 FIXED 可与 offline 同时存在；显示历史位置需提示位置时间，UNKNOWN 坐标系不得擅自作为 GCJ02 上图。现有 `protocol` 是实时唯一协议字段，枚举 GB32960/MQTT/JT808；`sourceProtocol` 属于里程接口。`online=false` 时 motionStatus=offline；在线且所选速度>3 km/h 为 driving，否则 idle。
|
||||
|
||||
## 实时估算追溯字段
|
||||
|
||||
以下新增字段始终序列化，无法生成时为 null。`hydrogenValueSource` 描述 kg 来源，`remainingHydrogenPercentSource` 独立描述比例来源；即使 kg 是 REPORTED，比例也是 ESTIMATED。质量 NORMAL 只表示通过当前规则，不代表直接测量。
|
||||
|
||||
| 字段 | 口径 |
|
||||
| --- | --- |
|
||||
| remainingHydrogenPercentSource | ESTIMATED；缺计算条件为 null |
|
||||
| hydrogenFullCapacityKg | 未舍入的实际满充质量分母，kg |
|
||||
| hydrogenTankCapacityL | 已启用 VIN 配置全车水容积，L，0＜V≤10000，无默认车型值 |
|
||||
| hydrogenFullPressureMPa / hydrogenReferenceTemperatureC | 35 MPa / 15°C |
|
||||
| hydrogenEstimatePressureMPa / hydrogenEstimateTemperatureC | 仅平台估算 kg 时采用的同帧原始压力/温度 |
|
||||
| hydrogenPressureTemperatureSource | MAX_SENSOR_AGGREGATE：最大传感值聚合，不保证同瓶 |
|
||||
| hydrogenCalculationVersion | REAL_GAS_35MPA_15C_V1 |
|
||||
| hydrogenCapacitySource | vehicle_hydrogen_tank_capacity |
|
||||
| hydrogenPercentReason | MISSING_HYDROGEN_MEASUREMENT、INVALID_MASS_READING、INVALID_PRESSURE_TEMPERATURE、INCOMPLETE_PRESSURE_TEMPERATURE、MISSING_TANK_CAPACITY、MASS_CALCULATION_FAILED 或 EXCEEDS_NOMINAL_FULL_CAPACITY；无原因时 null |
|
||||
|
||||
显式无效质量不改用压力估算掩盖异常；有效终端上报优先。百分比使用舍入前的质量与满充分母计算，输出质量及比例保留3位小数，因此显示值复算可能出现舍入差异。两个字段独立可空，不将超过100的百分比悄悄截断为100，不用质量状态NORMAL掩盖比例异常。
|
||||
|
||||
## 实时估算参考条件
|
||||
|
||||
本次按业务确认的 **35 MPa、15°C** 作为满充参考。UNECE 文件对 NWP 的定义采用 15°C 均温满充后稳定压力，并用当前氢密度与 NWP、15°C 参考密度的比值定义储氢 SOC。35 MPa 是本次明确选用的业务参数，不表示接口自动验证了每辆车的铭牌额定压力；这也不是动力电池 SOC。[定义来源：ECE/TRANS/WP.29/2023/110](https://unece.org/sites/default/files/2024-07/ECE_TRANS_WP.29_2023_110E.pdf)
|
||||
|
||||
估算复用 `PressureHydrogenMassKg` 的现有 NIST 实气模型与 VIN 储氢水容积：
|
||||
|
||||
```text
|
||||
满充质量 = PressureHydrogenMassKg(35 MPa, 15°C, VIN 储氢容积 L)
|
||||
估算剩余质量 = PressureHydrogenMassKg(同帧氢压 MPa, 同帧氢温 °C, VIN 储氢容积 L)
|
||||
储氢百分比 = 剩余质量 / 满充质量 × 100
|
||||
```
|
||||
|
||||
分母是上述参考条件下的全车氢质量，不是扣除不可用余量后的可用容量，也不是压力除以 35 MPa。模型不代表传感器实测或法规认证；逐瓶缺失及温压分布无法仅由总容积和单组遥测识别。接口保留估算来源与参数供追溯。此变化仅作用于实时储氢展示，不修改当日用氢量计算。
|
||||
|
||||
## 日统计身份与时间
|
||||
|
||||
两个接口均以 Asia/Shanghai 自然日请求，新增时间为 RFC 3339 带时区，不改变原 dataTime / updatedAt 的含义。
|
||||
|
||||
Reference in New Issue
Block a user