88 lines
8.7 KiB
Markdown
88 lines
8.7 KiB
Markdown
# 历史剩余氢量接口契约
|
||
|
||
契约版本：1.10.0；修订日期：2026-09-09。此文档定义实现与使用边界，不代替上线记录或真实历史覆盖验收报告。
|
||
|
||
## 用途与业务边界
|
||
|
||
`POST /api/v1/vehicles/hydrogen-remaining/history/query` 批量查询指定历史时刻的全车剩余氢质量。认证继续使用 `Authorization: Bearer <appKey>`，外层继续返回 `code / message / data / traceId`。实时剩余氢量和日用氢量接口保持原口径。
|
||
|
||
Seeker 负责保存和计算：
|
||
|
||
```text
|
||
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 维护。
|