feat: 上线历史剩余氢质量批量查询接口
This commit is contained in:
lingniu
@@ -1,7 +1,7 @@
|
||||
openapi: 3.0.3
|
||||
info:
|
||||
title: 车辆数据开放平台 API
|
||||
version: 1.9.0
|
||||
version: 1.10.0
|
||||
license:
|
||||
name: Proprietary
|
||||
description: |
|
||||
@@ -16,6 +16,55 @@ tags:
|
||||
- name: 开放平台管理
|
||||
description: 仅车辆数据平台管理员可调用的应用和车辆授权管理接口
|
||||
paths:
|
||||
/api/v1/vehicles/hydrogen-remaining/history/query:
|
||||
post:
|
||||
tags: [合作方数据接口]
|
||||
summary: 批量查询历史时刻剩余氢质量
|
||||
description: |
|
||||
按真实 event_time 查询不晚于指定时刻的最近氢相关帧，不跳过最新异常记录，不使用实时值或日用氢量填补。
|
||||
历史支持从 2026-08-01 起；实际车辆/时间覆盖以保留的原始帧为准，日期可请求不代表每个时点均有有效氢量。
|
||||
历史容量必须具有适用于历史时点的证据；不能用当前配置回套历史。当前缺少历史容量版本，只输出有证据的REPORTED质量，温压有效但无容量版本时 MISSING。
|
||||
同批按规范化VIN+time+protocol去重，同一点共享一次查询/授权结果与来源版本，各requestId仍独立回显；不同点为非原子快照，不以同批证明两端可比。
|
||||
200项仅为结构上限，不保证200个不同点能在9秒完成。建议先用20个不同点，ERROR超时时缩小批量并退避重试。
|
||||
有效采样超容差为STALE，最新帧INVALID/MISSING优先保留原原因；分块原始帧重组失败或候选预算耗尽为ERROR，不伪装NO_DATA。
|
||||
每项均返回 requestId；FORBIDDEN、ERROR 等失败不丢项，非 NORMAL 质量为 null。
|
||||
appKey须当前有效，并逐项校验请求时刻与采样时刻授权（结束时间不含端点）；FORBIDDEN不返回采样元数据。
|
||||
每app每服务实例30批/60秒，最多2个并发批；429包含Retry-After。整批9秒预算、最多4个工作协程，超时项ERROR，可重试。
|
||||
operationId: queryHistoricalHydrogenRemaining
|
||||
security:
|
||||
- AppKeyAuth: []
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/HistoricalHydrogenQuery'
|
||||
example:
|
||||
queries:
|
||||
- requestId: job-start
|
||||
vin: LA9GG68L2PBAF4773
|
||||
time: '2026-08-03 16:02:43'
|
||||
protocol: GB32960
|
||||
maxTimeDifferenceSeconds: 300
|
||||
responses:
|
||||
'200':
|
||||
description: 批量处理完成；每项状态独立判断，包括 FORBIDDEN 或 ERROR
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: '#/components/schemas/HistoricalHydrogenQueryResponse'
|
||||
'400':
|
||||
$ref: '#/components/responses/BadRequest'
|
||||
'401':
|
||||
$ref: '#/components/responses/Unauthorized'
|
||||
'429':
|
||||
description: 超出历史查询限流；读取 Retry-After 秒数后重试
|
||||
headers:
|
||||
Retry-After:
|
||||
schema: { type: integer, minimum: 1 }
|
||||
description: 建议等待秒数
|
||||
'500':
|
||||
$ref: '#/components/responses/InternalError'
|
||||
/api/v1/vehicles/hydrogen-consumption/query:
|
||||
post:
|
||||
tags: [合作方数据接口]
|
||||
@@ -529,7 +578,7 @@ components:
|
||||
properties:
|
||||
vin:
|
||||
type: string
|
||||
pattern: '^[A-HJ-NPR-Z0-9]{17}$'
|
||||
pattern: '^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$'
|
||||
description: 已授权车辆 VIN
|
||||
time:
|
||||
type: string
|
||||
@@ -598,6 +647,67 @@ components:
|
||||
minLength: 1
|
||||
maxLength: 32
|
||||
description: 可选；省略或传空数组时查询当前有效授权的全部车辆
|
||||
HistoricalHydrogenQuery:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required: [queries]
|
||||
properties:
|
||||
queries:
|
||||
type: array
|
||||
minItems: 1
|
||||
maxItems: 200
|
||||
items:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
required: [requestId, vin, time]
|
||||
properties:
|
||||
requestId: { type: string, minLength: 1, maxLength: 128, description: 本批唯一非空关联标识，最多128字节，原样返回 }
|
||||
vin: { type: string, minLength: 17, maxLength: 17, pattern: '^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$', description: 查询VIN按大写规范化，禁止I/O/Q }
|
||||
time: { type: string, description: '北京时间 yyyy-MM-dd HH:mm:ss；不得早于2026-08-01或晚于请求时刻' }
|
||||
protocol: { type: string, enum: [GB32960, YUTONG_MQTT, JT808], default: GB32960, description: 省略固定GB32960；显式协议不切换，YUTONG_MQTT/JT808当前UNSUPPORTED }
|
||||
maxTimeDifferenceSeconds:
|
||||
type: integer
|
||||
minimum: 0
|
||||
maximum: 300
|
||||
default: 300
|
||||
description: 允许采样早于查询的最大秒数；0要求精确命中，不静默放宽
|
||||
HistoricalHydrogenQueryResponse:
|
||||
allOf:
|
||||
- $ref: '#/components/schemas/SuccessEnvelope'
|
||||
- type: object
|
||||
required: [data]
|
||||
properties:
|
||||
data:
|
||||
type: array
|
||||
items: { $ref: '#/components/schemas/HistoricalHydrogenResult' }
|
||||
HistoricalHydrogenResult:
|
||||
type: object
|
||||
required: [requestId, vin, plateNumber, queryTime, remainingHydrogenKg, hydrogenRecordTime, timeDifferenceSeconds, remainingHydrogenKgStatus, hydrogenValueSource, hydrogenSourceProtocol, sourceRecordId, sourceDataVersion, hydrogenEstimatePressureMPa, hydrogenEstimateTemperatureC, hydrogenTankCapacityL, hydrogenPressureTemperatureSource, hydrogenCalculationVersion, hydrogenCapacityVersion, updatedAt, reasonCode, message]
|
||||
properties:
|
||||
requestId: { type: string, description: 本批对应请求标识 }
|
||||
vin: { type: string }
|
||||
plateNumber: { type: string, nullable: true, description: 无可证明历史车牌时为 null，不冒用当前车牌 }
|
||||
queryTime: { type: string, description: 请求北京时间 }
|
||||
remainingHydrogenKg: { type: number, nullable: true, minimum: 0, description: '全车剩余氢质量kg，保留源/模型计算精度；仅NORMAL可用，其他状态null。不得用缺值补0' }
|
||||
hydrogenRecordTime: { type: string, format: date-time, nullable: true, description: 真实原始帧 event_time，RFC3339带时区 }
|
||||
timeDifferenceSeconds: { type: number, nullable: true, minimum: 0, description: queryTime减真实采集时间的秒数 }
|
||||
remainingHydrogenKgStatus:
|
||||
type: string
|
||||
enum: [NORMAL, NO_DATA, MISSING, STALE, UNSUPPORTED, INVALID, FORBIDDEN, ERROR]
|
||||
description: 仅NORMAL参与业务计算；ERROR明确为处理失败，可按原因重试；FORBIDDEN不泄露采样
|
||||
hydrogenValueSource: { type: string, nullable: true, enum: [REPORTED, ESTIMATED], description: 终端上报不等同于直接测量；估算需历史温压/容积证据 }
|
||||
hydrogenSourceProtocol: { type: string, nullable: true, enum: [GB32960, YUTONG_MQTT, JT808] }
|
||||
sourceRecordId: { type: string, nullable: true, description: raw-sha256采样身份指纹；两端相同需识别采样分辨率不足，内容修订另看sourceDataVersion }
|
||||
sourceDataVersion: { type: string, nullable: true, description: 'sha256原始JSON和解析状态内容指纹；同采样被修订时变化，不是两端必须相等的口径版本' }
|
||||
hydrogenEstimatePressureMPa: { type: number, nullable: true, description: 有效同帧最大氢压MPa证据，缺历史容量仍可诊断返回 }
|
||||
hydrogenEstimateTemperatureC: { type: number, nullable: true, description: 有效同帧最大氢温摄氏度证据 }
|
||||
hydrogenTankCapacityL: { type: number, nullable: true, description: 当前缺历史容量版本始终null，不能回套当前容积 }
|
||||
hydrogenPressureTemperatureSource: { type: string, nullable: true, enum: [MAX_SENSOR_AGGREGATE], description: 最大温压聚合不保证同瓶 }
|
||||
hydrogenCalculationVersion: { type: string, nullable: true, description: 当前REPORTED_HYDROGEN_KG_V1，质量不额外舍入；ESTIMATED预留但当前缺历史容积版本不输出估算值 }
|
||||
hydrogenCapacityVersion: { type: string, nullable: true, description: 历史时点适用容积版本；估算必需，无证据不估算 }
|
||||
updatedAt: { type: string, format: date-time, nullable: true, description: 原始记录received_at，RFC3339带时区；不代替采集时间，同时间戳修订通过sourceDataVersion识别 }
|
||||
reasonCode: { type: string, nullable: true, description: 可程序识别的状态原因 }
|
||||
message: { type: string, nullable: true, description: 中文状态说明 }
|
||||
HydrogenStationQuery:
|
||||
type: object
|
||||
additionalProperties: false
|
||||
|
||||
Reference in New Issue
Block a user