历史剩余氢量接口契约

契约版本：1.10.0；修订日期：2026-09-09。此文档定义实现与使用边界，不代替上线记录或真实历史覆盖验收报告。

用途与业务边界

POST /api/v1/vehicles/hydrogen-remaining/history/query 批量查询指定历史时刻的全车剩余氢质量。认证继续使用 Authorization: Bearer <appKey>，外层继续返回 code / message / data / traceId。实时剩余氢量和日用氢量接口保持原口径。

Seeker 负责保存和计算：

rawHydrogenDeltaKg = 起点剩余氢质量 − 终点剩余氢质量
hydrogenConsumptionKg = max(rawHydrogenDeltaKg, 0)
negativeDeltaClamped = rawHydrogenDeltaKg < 0

两端均 NORMAL 且来源、协议、转换版本、容量版本可比时才计算，使用 API 返回的未额外舍入质量值，最后按展示需要舍入。任一端缺失、未授权、异常或不可比较则结果 null。真实两端质量相同、或负差值归零，可以产生0；负的剩余质量本身属于 INVALID。此公式是业务约定的两端储氢净减少量，不代表区间内加氢修正后的实际燃料电池消耗量；不能用日用氢量替代或按时长/里程分摊。

请求与授权

参数	约束
queries	必填，1–200项，单点也使用数组
queries[].requestId	必填、非空、批内唯一、最多128字节，原样回显
queries[].vin	规范化大写17位VIN，不含I/O/Q
queries[].time	严格北京时间 `yyyy-MM-dd HH:mm:ss`；从2026-08-01 00:00:00起，不允许未来时刻，更早或非法为400
queries[].protocol	GB32960/YUTONG_MQTT/JT808；省略固定GB32960，不跨协议回退，后两者当前UNSUPPORTED
maxTimeDifferenceSeconds	整数0–300，默认300；0要求精确采样，不静默放宽

appKey当前无效、停用或过期返回401。合法批量返回HTTP200/SUCCESS，各项以 remainingHydrogenKgStatus 判定；查询时刻及实际采样时刻都必须落在应用和逐车授权范围内，授权结束时间为不含端点。单项FORBIDDEN仍回显requestId/vin/queryTime，采样时间、记录标识、来源、版本等均不泄露。整个请求结构非法返回400，不提交部分查询。

每个app、每个服务实例限制30批/60秒，最多2个并发批；429的 Retry-After 为等待秒数。整个批次9秒预算，最多4个并发工作协程；失败/超时明确为单项ERROR，其他已完成项仍可用。客户端按Retry-After或有限退避重试，不将错误作为无数据缓存；建议按VIN+time+protocol+容差去重，并将作业起终点放同批核对。此限制不是全服务集群共享令牌桶。200项是请求结构上限，不是200个不同点在9秒完成的性能保证；建议首次使用20个不同点，出现超时后缩小批量并退避重试。重复点较多的200项测试不能证明200个不同点的吞吐能力，具体候选性能证据见发布验收记录。

历史证据要求

匹配使用真实 event_time，只能采用不晚于查询时刻的历史氢相关采样。最新氢相关帧异常或字段不全时显式返回异常/缺失，不能跳过它拿更旧正常值掩盖。请求时间、接收时间、数据库更新时间和当前实时快照均不能冒充采集时间；不插值、不把日统计还原成瞬时质量。

有终端质量上报时 hydrogenValueSource=REPORTED 仅确认终端上报，不能保证终端内部直接测量。平台估算 ESTIMATED 必须使用历史同帧温压及适用于该历史时点、有可追溯版本的 VIN 全车水容积。当前容积表的现值不是历史有效性证明，缺少历史适用证据时返回 MISSING，不把修改后的当前容积套回8月记录。最大温压聚合也不保证来自同一瓶，仍需披露选取方法。

两端可能命中同一原始帧，调用方必须保留 sourceRecordId 与实际采集时间识别采样分辨率不足。同批按规范化VIN+time+protocol去重，同一点共享一次查询/授权结果与来源版本，每个requestId仍各有独立结果；不同点不保证原子数据快照，同批不等于所有点同一修订版本。保存每项数据版本、算法/配置版本、更新时间及 traceId，结果发生变化时重新核对两端。

返回字段与状态

所有字段存在，无法提供时为null；requestId、vin、queryTime和remainingHydrogenKgStatus为非空基本字段。

字段	当前实现
plateNumber	无历史车牌证据，null，不用当前车牌冒充
remainingHydrogenKg	仅NORMAL返回终端上报有效0–200kg；不额外round3，保留解析后数值精度
hydrogenRecordTime / timeDifferenceSeconds	真实event_time（RFC3339带时区）及与查询时刻的秒差，可含小数
hydrogenValueSource / hydrogenSourceProtocol	当前有效结果REPORTED / GB32960；ESTIMATED为契约预留，目前缺历史容量版本不输出估算值
sourceRecordId	raw-sha256采样身份指纹，不包含底层连接配置
sourceDataVersion	sha256原始JSON及parseStatus指纹；同一采样原地修订即使received_at不变也能识别
hydrogenCalculationVersion	当前REPORTED_HYDROGEN_KG_V1；算法口径版本不同默认不混算
hydrogenCapacityVersion / hydrogenTankCapacityL	当前无历史适用容积版本，两者null，不读取当前表假装历史有效
updatedAt	原始记录received_at，非API当前时间，也不是采集时间
hydrogenEstimatePressureMPa / hydrogenEstimateTemperatureC / hydrogenPressureTemperatureSource	有效历史同帧温压可供诊断返回，方法MAX_SENSOR_AGGREGATE；缺历史容量仍MISSING
reasonCode / message	机器原因与中文说明；非正常情况可解释，不暴露底层凭证

sourceDataVersion是单条内容修订证据，起终点本来就是不同内容，不要求两端指纹相等。可比性由VIN、数据来源、协议、算法及适用容量版本共同判断；更新时重新核对并留存两端证据。

状态	使用边界
NORMAL	有效质量且采样在容差内，才可参与已核实可比的差值计算
NO_DATA	支持的历史查询范围内没有氢相关帧；不代表更早数据不存在
MISSING	最近氢相关帧缺量、温压不全或缺历史容量版本；不跳过最新缺失帧
STALE	有效质量命中超容差，数值null，可返回采样诊断信息
UNSUPPORTED	显式请求当前不支持氢量的协议
INVALID	最新负质量、无效读数、温压异常或原始解析异常，数值null
FORBIDDEN	查询时刻或采样时刻授权不满足，采样元数据全部null
ERROR	超时、上游失败、分块重组失败或候选预算耗尽；可以重试，不当查无数据

状态优先保留最新原始帧的INVALID/MISSING；只有原始质量有效时才因超容差变为STALE，不能用陈旧状态掩盖异常。分块报文会重组后确认是否氢相关；采集时间与入库时间均相同的候选发生冲突时返回ERROR，不任意择值；不完整分块处理失败为ERROR，最多检查32个候选的预算耗尽也为ERROR。

常见原因：NO_HISTORICAL_SAMPLE、SAMPLE_OUTSIDE_TOLERANCE、HISTORY_FORBIDDEN、PROTOCOL_UNSUPPORTED、UPSTREAM_TIMEOUT、UPSTREAM_FAILURE、INVALID_MASS_READING、INVALID_PRESSURE_TEMPERATURE、INCOMPLETE_PRESSURE_TEMPERATURE、MISSING_HISTORICAL_CAPACITY_VERSION、RAW_FRAME_PARSE_FAILED、INVALID_RAW_JSON。原因可随新增诊断扩展，客户端优先按状态处理未知原因。

覆盖与交付证据

接口仅支持2026-08-01北京时间起的请求与原始采样，较早请求400。这是接口能力边界，不表示此前所有原始数据不存在；更早保留范围不在本版承诺。日期可查询、授权覆盖、存在原始帧、存在有效氢量是四件不同的事，应逐车逐时点核对。生产原始历史采样测试、至少3车2段区间验证及缺失样本见本次发布验收报告；没有海港真实作业节点时，只能称历史采样区间验证，不宣称已通过海港作业联调。

Seeker 接入检查

VIN、requestId、queryTime 与请求逐项核对，不能以数组位置或当前车牌作为唯一关联依据。
仅 NORMAL 进入差值计算；STALE、NO_DATA、MISSING、UNSUPPORTED、INVALID、FORBIDDEN、ERROR 均保持待数据/待核对，不补零。
两端协议、REPORTED/ESTIMATED、转换版本及估算容量版本不同时默认不混算，须先核实可比性。
原始质量、原始差值、归零标记、采样偏差、原始帧标识和版本均留存；展示舍入不回写覆盖计算证据。
保留跨日作业两个时点，不切换为日报相减。集装箱分摊与碳排因子继续由 Seeker 维护。

8.7 KiB Raw Blame History Unescape Escape