shishengliang/lingniu-vehicle-ingest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 上线历史剩余氢质量批量查询接口

Browse Source
This commit is contained in:
lingniu
2026-09-09 01:00:29 +08:00
parent 4ab654e1c1
commit 1849bc1870
12 changed files with 1457 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
vehicle-data-platform/docs/oneos-historical-hydrogen-api-contract.md
+87
View File
@@ -0,0 +1,87 @@
# 历史剩余氢量接口契约
契约版本：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 维护。
vehicle-data-platform/docs/oneos-historical-hydrogen-api-release-20260909.md
+51
View File
@@ -0,0 +1,51 @@
# 历史剩余氢量接口发布验收
## 发布结果
- 生产版本：`open-platform-historical-hydrogen-202609090100`；北京时间2026-09-09 00:57:48确认就绪。
- 正式服务：[开放平台](https://open.d.lnoneos.com)，服务`lingniu-vehicle-open-platform`，端口20310。
- 新接口：`POST /api/v1/vehicles/hydrogen-remaining/history/query`；[在线文档](https://open.d.lnoneos.com/open-api/docs/)及[OpenAPI 1.10.0](https://open.d.lnoneos.com/open-api/openapi.yaml)同步生效。
- 最终候选与生产二进制SHA-256一致：`6bb05405b2dd126dd3a8fe13d226fd128a577154e00c2505bcba57f0aca5870b`。
- 上一版`open-platform-hydrogen-estimate-202609082311`及原静态门户资源保留；无数据库迁移。发布脚本含失败自动回滚。
## 实现与边界
历史查询从北京时间2026-08-01起，按实际event_time匹配最近且不晚于请求时刻的氢相关原始帧，支持延迟上传；不会使用实时快照、日统计、插值或当前容积回套历史。缺历史容量版本的温压记录MISSING，当前有效历史质量仅REPORTED。真实零有效，负质量及显式无效值INVALID；非NORMAL质量null。最新异常不会被旧正常值掩盖。分块帧须完整重组，候选时间冲突或重组失败返回ERROR。
原始上报质量不额外舍入。返回采样时间、协议、稳定采样指纹sourceRecordId、独立内容版本sourceDataVersion、转换版本和接收时间updatedAt；内容修订即使保留接收时间也可通过指纹识别。历史车牌没有证据时null。采样与查询两个时刻均须满足应用和车辆授权，越权项不泄露采样元数据。
每批1–200项；requestId唯一并逐项回显。同批按VIN+time+protocol去重，相同点共享单次查询版本；不同点不保证原子快照。默认容差300秒，0要求精确命中。每应用每实例30批/60秒、2并发批；429附Retry-After。批次9秒、4工作协程，超时逐项ERROR。建议从20个不同点开始；200是结构上限，不能将重复点压测解读为200个不同历史点的性能保证。
完整契约见 `oneos-historical-hydrogen-api-contract.md`。作业净用氢量仍由Seeker按两端可比NORMAL值计算，不在平台新增日用氢量分摊。
## 验证证据
- `go test ./...`、`go test -race ./internal/openplatform`、`go vet ./internal/openplatform`、文档YAML校验、发布脚本自测与diff-check通过。
- 单元/SQL测试覆盖真实零、原始精度、负数/null、非法及未来时间、容差边界、延迟上传、分块重组失败、同时间冲突、历史容量缺失、修订指纹、跨午夜、协议限制、查询/采样双重授权、混合错误、超时不丢项、200项去重映射、429并发/时间窗限制。
- 生产只读覆盖调查确认8月1日已有氢质量原始帧，1024个VIN的既有应用及逐车授权覆盖8月1日至调查时刻；这不代表每台车每个时点有有效氢量。
- 在生产机器的隔离候选进程127.0.0.1:20311测试后停止候选；未建立永久对外测试域名。
- 选3台既有授权车辆，每车8月3日和15日各一个历史采样区间，每区间3条原始帧，共18帧。接口逐项比对原始质量、真实采集时间、VIN、requestId、来源及版本；全部NORMAL。
- 最终候选18点2.989秒；200项含18个不同点2.997秒。正式HTTPS复测分别3.066秒和3.133秒，均全部NORMAL。
- 正式HTTPS确认偏移1秒且容差0为STALE/null，默认容差命中同一sourceRecordId；部分FORBIDDEN和UNSUPPORTED不影响正常项；401、非法批次400、429及Retry-After通过。
- 真实缺数样本：SAMPLE_VIN_1查询2026-08-01 00:00:00，返回NO_DATA、NO_HISTORICAL_SAMPLE，质量和采样信息为null，没有补零。
- 候选与正式均回归100台实时、里程、日用氢量接口。正式耗时184/16/6毫秒；实时包含20条ESTIMATED kg与2个真实零，质量/满充百分比公式验证通过。日用氢量的NO_DATA/DATA_ANOMALY为数据状态，未把它们算作有效氢耗。
- 正式健康、文档、OpenAPI和目录均200，systemd active；启动后日志未见新增服务异常。所有临时测试凭证及其授权已删除，未修改合作方既有密钥或授权。
## 脱敏历史样本
下表为真实历史遥测采样区间，**不是已取得海港作业节点证明的真实作业区间**。每区间中间一帧也已核验，完整脱敏返回保存在证据目录。两个端点相同质量是有效记录，不能据此推断全天或整次作业用氢为零。
| 车辆代号 | 采集时间（北京时间） | 剩余kg起点 → 终点 | 状态 |
| --- | --- | --- | --- |
| SAMPLE_VIN_1 | 2026-08-03T08:50:09+08:00 → 2026-08-03T08:50:29+08:00 | 2.9 → 2.9 | NORMAL |
| SAMPLE_VIN_1 | 2026-08-15T00:09:57+08:00 → 2026-08-15T00:10:19+08:00 | 5.5 → 5.5 | NORMAL |
| SAMPLE_VIN_2 | 2026-08-03T00:00:00+08:00 → 2026-08-03T00:00:20+08:00 | 3.3 → 3.3 | NORMAL |
| SAMPLE_VIN_2 | 2026-08-15T06:40:02+08:00 → 2026-08-15T06:40:21+08:00 | 1.9 → 1.9 | NORMAL |
| SAMPLE_VIN_3 | 2026-08-03T00:00:06+08:00 → 2026-08-03T00:00:26+08:00 | 5.7 → 5.7 | NORMAL |
| SAMPLE_VIN_3 | 2026-08-15T00:00:04+08:00 → 2026-08-15T00:00:24+08:00 | 4.4 → 4.4 | NORMAL |
## 未覆盖的业务验收
海港真实作业开始/结束节点未提供，因此还未完成“3台车、每台2段真实海港作业”的端到端Seeker联调。本次完成历史接口与原始采样验收及部署。较早于2026-08-01的查询不在本版开放范围；当前容量历史版本证据不足，历史估算不输出数值。这些限制已同步在线契约，未伪造历史配置或作业记录。
脱敏响应、探针源码、候选与正式验收输出、发布SHA等位于工作区`outputs/historical-hydrogen-release-20260909/`。不含密钥；私有原始样本仅为服务器临时验收文件，验收后移除。