5.8 KiB
历史剩余氢量接口发布验收
发布结果
- 生产版本：
open-platform-historical-hydrogen-202609090100；北京时间2026-09-09 00:57:48确认就绪。 - 正式服务：开放平台，服务
lingniu-vehicle-open-platform，端口20310。 - 新接口：
POST /api/v1/vehicles/hydrogen-remaining/history/query；在线文档及OpenAPI 1.10.0同步生效。 - 最终候选与生产二进制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/。不含密钥；私有原始样本仅为服务器临时验收文件，验收后移除。