feat: 补齐开放平台车辆实况与统计时间字段
This commit is contained in:
lingniu
@@ -0,0 +1,77 @@
|
||||
# OneOS 氢能车辆实况接口交付契约
|
||||
|
||||
契约修订日期：2026-09-08。对应 `/api/v1/vehicles/realtime/query`、`/mileage/query`、`/hydrogen-consumption/query` 的增量交付。实际发布版本、上线时间及脱敏联调证据由发布验收记录提供，本文不将开发完成等同于线上验收完成。
|
||||
|
||||
## 兼容性与授权
|
||||
|
||||
认证继续使用 `Authorization: Bearer <appKey>`；成功响应继续包含 `code / message / data / traceId`。原请求参数不变；新字段增量添加。`plateNumbers` 省略或空数组表示全部有效授权车辆，指定名单时按授权校验后查询，消费者必须核对 VIN、车牌和日期，不能只按车牌串接不同车辆。报警、违章、企业名称、Seeker 本地车辆编号均不在本次新增范围。
|
||||
|
||||
完整机器契约见服务 `/open-api/openapi.yaml`（路径以服务文档入口为准），内嵌 HTML 同步说明新增字段。
|
||||
|
||||
## 实时储氢与定位
|
||||
|
||||
| 字段 | 类型/单位 | 本次口径 |
|
||||
| --- | --- | --- |
|
||||
| remainingHydrogenKg | number/null，kg | GB32960 广东燃料电池扩展 0x34 终端全车氢质量直接上报；保留真实零，不汇总单瓶、不由压力推算 |
|
||||
| remainingHydrogenPercent | number/null，% | 当前缺少可信质量容量分母，固定 null，字段级 UNSUPPORTED；不使用 SOC 或当日消耗替代 |
|
||||
| hydrogenRecordTime | RFC 3339/null | 精确匹配 raw_frames 原始同帧采集时间，非合并快照更新时间 |
|
||||
| hydrogenDataStatus | enum | NORMAL/PARTIAL/STALE/MISSING/UNSUPPORTED/INVALID；当前 kg 有效但百分比不支持为 PARTIAL |
|
||||
| remainingHydrogenKgStatus / remainingHydrogenPercentStatus | enum | 分别为 NORMAL/STALE/MISSING/UNSUPPORTED/INVALID，客户端独立判断 |
|
||||
| hydrogenValueSource / hydrogenSourceProtocol | string/null | REPORTED 仅表示终端上报，无法确认终端内部采用测量还是估算；储氢协议独立于位置 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 既可能暂无记录，也可能本次未取得可信证据，不能据此断言设备不支持。
|
||||
|
||||
有界回补仅针对具有 GB 最新快照原始帧引用、且精确帧氢量为 MISSING 的车辆：查询该快照 `received_at` 向前 5 分钟内含氢量键的原始帧，按 `event_time DESC, ts DESC` 取最新候选。窗口以快照接收时间为基准，不是 API 当前时间；离线车辆可返回真实的 STALE。显式 null 或异常候选不被过滤成旧正常值；已有 INVALID/PARTIAL/STALE 不回补，不能掩盖最新异常。回补所得氢量及 hydrogenRecordTime 始终来自同一原始帧，仍共享 3 秒预算；超时或无记录维持 MISSING。该策略不会扫描全部历史，也不承诺找到窗口外最近一条氢量。
|
||||
|
||||
储氢覆盖以收到扩展字段的 GB32960 车辆为限，不代表所有 GB32960 车型支持；MQTT/JT808 当前不支持储氢。平台不提供凭容量未知的百分比换算，因而本次不保证 Seeker 所有车辆两列均有值。多瓶完整性由终端全车上报负责，接口没有逐瓶完整性检测能力。
|
||||
|
||||
定位使用位置行的 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。
|
||||
|
||||
## 日统计身份与时间
|
||||
|
||||
两个接口均以 Asia/Shanghai 自然日请求，新增时间为 RFC 3339 带时区，不改变原 dataTime / updatedAt 的含义。
|
||||
|
||||
| 接口 | 字段 | 来源及空值 |
|
||||
| --- | --- | --- |
|
||||
| 用氢 | vin | 授权车辆 VIN，与实时和里程核对 |
|
||||
| 用氢 | statisticsStartTime / statisticsEndTime | FINAL 为 evidence 区间 min(startTime) / max(endTime)；这是证据包络，不保证连续覆盖。PRELIMINARY 只有 lastEventTime 水位，start=null；证据缺失或异常为 null |
|
||||
| 用氢 | updatedAt | 同一 daily_energy 行的 updated_at，无统计行为 null |
|
||||
| 里程 | statisticsStartTime / statisticsEndTime | 同一所选来源 MIN(first_event_time) / MAX(latest_event_time)，start 可为前一日跨日基线采样，不能夹到 00:00 伪造自然日起始；end 等于 dataTime；历史结转的当日 0 里程、无记录或异常缺少有效边界时为 null |
|
||||
|
||||
两个接口独立读取投影，**没有共同快照或严格同步统计保证**。同日、NORMAL、相近 updatedAt 均不足以证明可以相除。客户端至少需边界非空且一致，并核查证据覆盖/来源口径；边界仅为包络，相等也不是完整连续同区间的证明。无法证明可比时百公里氢耗为空，保留各自指标展示。里程沿用历史累计值时日里程补 0，是既有兼容规则，不证明当天真实测得零里程。
|
||||
|
||||
## 日用氢量算法与质量
|
||||
|
||||
当前算法标识为 `PRESSURE_NIST_VALID_BOUNDARY_CHARGE_CYCLE_V3_5`；客户端应展示实际 `algorithmVersion`，不能据名称自行推定公式或锁定未来版本。
|
||||
|
||||
数据基础是 GB32960 氢气压力（MPa）、温度（摄氏度）与车型配置的储氢系统水容积，经 NIST 实气压缩因子换算质量（kg）：
|
||||
|
||||
```text
|
||||
Tk = 温度 + 273.15
|
||||
m = P × 1000 × 0.00201588 × V / (8.314472 × Tk × Z)
|
||||
```
|
||||
|
||||
V 为储氢容积升数，Z 为代码实现的 NIST 压缩因子。算法筛选有效运行分界点，识别日内加氢后分段计算首末质量下降；不直接拿两次 API 响应相减。加氢识别包含持续压力回升与净质量增加补充规则；纯电异常压降、工作状态、运行边界与仪表里程异常参与质量判定。缺少足够有效边界为 `NO_DATA`。此输入不包含逐瓶完整性证明，不能将部分瓶数据包装成已测量全车总量。
|
||||
|
||||
压力边界无法产生有效正耗氢且满足混动里程等条件时，可用燃料电池电压电流积分折算氢量兜底；此时质量降为 `SUSPECT` 并在 `qualityReason` 说明。`hydrogenConsumptionKg` 返回物理用氢结果，不是 SOC、剩余氢量或 SOC 平衡校正量。压力法本身也是模型估算，不应对外宣称为质量流量计直接测量。
|
||||
|
||||
| qualityStatus | status | 数值与使用要求 |
|
||||
| --- | --- | --- |
|
||||
| OK | NORMAL | 可用于日内监控；还需校验计算阶段和可比区间 |
|
||||
| SUSPECT | DATA_ANOMALY | 保留数值供审计，禁止作为正常百公里氢耗输入 |
|
||||
| NO_DATA | NO_DATA | 用氢量为 null；没有统计行时质量/阶段等旧可选字段可能省略 |
|
||||
|
||||
`calculationPhase` 为 `PRELIMINARY` 或 `FINAL`。流式初步结果可变化，`NORMAL + PRELIMINARY + OK` 仅适用于明确标注“初步”的日内监控；不能当成最终日报。`FINAL` 表示已执行批量重算，仍可因补传、参数或算法修订再次重算，并非不可变账单。实际完成时间读取 `updatedAt`；接口不承诺每日固定时刻已经完成 FINAL。正式报表应同时要求 FINAL、OK、NORMAL、有效时间区间，并留存版本和查询快照。
|
||||
|
||||
## Seeker 必须同步适配
|
||||
|
||||
1. Go 上游模型增加储氢、GPS、质量及时间字段，映射 `remainingHydrogenKg → leftHydrogen`、`remainingHydrogenPercent → originalLeftHydrogen`；前端分别判断两个字段，保留真实 0，null 显示“—”并提示原因。
|
||||
2. `socPercent` 仍为动力电池 SOC，不得替代储氢百分比。`timeDifferenceSeconds / 3600` 是记录年龄（小时），不是实际离线持续时间；移除“72 小时即 GPS 正常”的判断。
|
||||
3. 按 VIN、规范化车牌及 date 合并三个接口；本地 truckNum、筛选、排序保持原口径。新字段不会自动接入不在本仓库的 Seeker 代码。
|
||||
4. 百公里氢耗由 Seeker 计算 `hydrogenConsumptionKg / dailyMileageKm × 100`，单位 kg/100km。必须保证分子分母有效、里程大于 0、两行 NORMAL、氢量质量 OK，且统计区间可比较；否则返回 null。真实用氢量 0 与正里程可产生 0。历史字段 `dayHydrogenPercent` 并非百分比。
|
||||
5. 联调需覆盖真实零、部分字段支持、陈旧、无记录、未支持协议、异常、离线历史位置、无定位、零里程及统计重算。页面验收须在 Seeker 完成上述接入后单独进行。
|
||||
@@ -0,0 +1,49 @@
|
||||
# 车辆实况接口补充：发布与验收记录
|
||||
|
||||
需求依据：2026-09-08《OneOS 氢能车辆实况接口补充需求》。交付范围是本仓库 OneOS 开放平台，Seeker 客户端代码不在本仓库，未将接口上线等同于客户端页面已完成适配。
|
||||
|
||||
## 交付范围
|
||||
|
||||
- 实时查询：储氢 kg、百分比接口字段、字段级状态、真实采集时间、来源和陈旧阈值；GPS 定位位、位置采集时间和可确认的坐标系。
|
||||
- 日用氢量：VIN、来自同一统计记录的可空证据起止时间、更新时间。
|
||||
- 日里程：所选来源真实证据起止时间，历史累计结转不伪造当日区间。
|
||||
- 认证、原请求体、响应外壳和旧数值口径兼容；加强请求车牌与授权映射成员校验。
|
||||
- 内嵌 OpenAPI 1.8.0、HTML 文档以及 `oneos-vehicle-live-api-contract.md`。
|
||||
|
||||
## 验收方法
|
||||
|
||||
1. 执行 API 模块 `go test ./...`、开放平台 `go test -race ./internal/openplatform`、`go vet ./internal/openplatform`，以及发布脚本自测与 diff-check。
|
||||
2. 在生产机器仅监听 127.0.0.1:20311 的候选进程读取真实数据；以已有授权车辆为样本，创建临时测试凭证，调用三个正式 HTTP 接口，测试完删除临时凭证与授权，保留接口审计记录。凭证没有写入交付文件。
|
||||
3. 每轮批量 100 台，检查结果数量、车牌白名单、VIN 一致性、必备新增字段、真实零、百分比空值、NO_FIX 坐标为空、401 未认证、403 未授权名单。覆盖当日及前一日统计。
|
||||
4. 对实时快照与原始帧进行脱敏核对，确认合并快照会保留旧字段、最新帧可能没有储氢单元；回补须使用真正含储氢字段的原始帧及原采集时间。
|
||||
5. 原始回查以每 VIN 五分钟接收时间窗、四并发、共享三秒预算限制成本；测试缺数据、显式异常、未来时间、陈旧、历史离线定位、故障降级、错 VIN、跨日结转及证据重算变化。
|
||||
|
||||
候选联调中发现并修复了两个仅靠 SQL mock 无法充分覆盖的问题：DATE_FORMAT 秒标记与 IN 参数模板冲突；TDengine 的排序分区查询 LIMIT 实际限制全局行数，回补最终改为每 VIN 单独查询。上线前进一步通过真实 SQL 核对。
|
||||
|
||||
## 交付限制
|
||||
|
||||
- 百分比目前 `null / UNSUPPORTED`：没有可信全车容量分母，不能使用电池 SOC、单瓶值或猜测容量替代。
|
||||
- `REPORTED` 仅确认终端上报质量；无法确认终端内部采用测量还是估算。全车口径依赖已识别的 GB32960 广东扩展，不代表全部车型和协议均支持。
|
||||
- 坐标系没有明确原始编码时为 UNKNOWN，不能宣称统一 GCJ02；真实定位状态与在线、新旧独立。
|
||||
- 两个日统计接口没有共同快照保证；PRELIMINARY 氢耗开始时间通常未知，不能仅凭同日就作为严格同步百公里氢耗依据。
|
||||
- 回补有明确时间窗；原始记录不可用、没有相关字段或查询超时仍可能 MISSING，不伪造数值或采集时间。
|
||||
- Seeker 须自行增加字段映射、状态展示和 VIN/统计区间核验，接口添加不会自动改变其页面。
|
||||
|
||||
## 发布证据
|
||||
|
||||
发布结果、二进制 SHA-256、正式接口烟测和脱敏样本保存在工作区 `outputs/live-api-release-20260908/`。最终发布与验收结果如下：
|
||||
|
||||
|
||||
- 正式版本：`open-platform-live-fields-202609082146`，北京时间 2026-09-08 21:46:08 切换，21:46:09 健康检查就绪。
|
||||
- 服务：`lingniu-vehicle-open-platform`，端口 20310。无数据库迁移；沿用原门户静态资源，更新开放平台 API 及其内嵌接口文档。
|
||||
- 正式二进制 SHA-256：`724491000e1010dc20960e0abb7db9aceac0dd99dc9867cd993f339da00ac97c`，与验收候选一致。
|
||||
- 原版本 `open-platform-suspect-20260904162007` 和本次首版 `open-platform-live-fields-202609082130` 均保留。安装器保留失败时恢复旧版本的逻辑；本次正式切换成功，未执行生产回滚演练。
|
||||
- 最终全量 Go 测试、race、vet、文档测试、YAML 校验、发布脚本测试和 diff-check 均通过。
|
||||
- 最终候选四轮：实时接口 244–275 ms，100 台样本中 74–77 台有 kg，0 台 MISSING；其余为不支持协议。包括当日及前一日统计。各轮重新选择活跃授权样本，不是固定车辆群组，不应把不同轮覆盖率当作同一群组趋势。
|
||||
- 正式接口三轮（每轮 100 台）：实时 446/335/295 ms；里程 15/15/18 ms；用氢 6/6/6 ms。三接口均 SUCCESS，结果数量及车牌/VIN 核验通过，401/403 负向用例通过。
|
||||
- 正式样本 kg 非空 59/69/71 台，包含 3/4/4 个真实零；MISSING 33/22/19 台；UNSUPPORTED 8/9/10 台。未把缺失样本认定为已有有效储氢量，也不承诺全量车辆覆盖。无 enrichment 错误日志，仍应按真实来源和回查窗口判断可用性。
|
||||
- 正式 GPS 样本识别 NO_FIX 4/5/5 台，经纬度及 locationAvailable 验证一致；所有样本坐标系为 UNKNOWN，未伪报统一坐标系。
|
||||
- `http://115.29.187.205:20310/healthz`、`/open-api/openapi.yaml`、`/open-api/docs/` 公网检查 200 且版本/字段匹配；门户 catalog 正常，systemd active，无异常退出。
|
||||
- 本轮所有临时测试应用与授权均删除，测试用凭证未输出。没有修改既有合作方密钥和授权。
|
||||
|
||||
结论：开放平台本次增量接口及其兼容、权限、真实来源、空值和发布行为验收通过；储氢百分比数据接入、未知坐标系的供应方确认、统一统计快照和 Seeker 页面适配仍属于上述明确限制，不宣称这些数据/客户端工作已经完成。
|
||||
Reference in New Issue
Block a user