feat: 补齐开放平台车辆实况与统计时间字段

vehicle-data-platform/apps/api/internal/openplatform/assets/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: 车辆数据开放平台 API
-  version: 1.7.0
+  version: 1.8.0
   license:
     name: Proprietary
   description: |
@@ -210,7 +210,11 @@ paths:
         任一采集协议在最近60秒内上报即视为在线；protocol、位置、速度、SOC 和记录时间仍按上述来源优先级选择。
         socPercent 仅在所选来源采集到有效 SOC（0–100，单位 %）时返回；无值或无效值时该字段省略。
         activeToday 表示任一采集协议在当前自然日（Asia/Shanghai）内曾上报，用于日上线车辆统计，不改变 online 的实时口径。
-        在线且所选来源速度大于3km/h为行驶中，否则为静止中。
+        离线时 motionStatus=offline；在线且所选来源速度大于3km/h为 driving，否则为 idle。
+        储氢使用可追溯原始帧；最新帧缺少氢量时可有界回补，当前百分比无可信容量分母为 null/UNSUPPORTED；不得用 SOC 替代。
+        仅 GB 最新快照有引用且精确帧氢量 MISSING 时，回查该快照 received_at 向前 5 分钟的含氢量字段原始帧，按采集时间优先、接收时间次序取最新；不回退覆盖 INVALID，离线回补保留真实 STALE。
+        GPS 定位状态独立于在线与陈旧；坐标系可能 UNKNOWN，不能假定统一 GCJ02。
+        补充历史查询共享 3 秒预算，失败或超时降级为 MISSING/UNKNOWN 并保留旧实时字段；MISSING 不等于设备不支持。
       operationId: queryRealtimeVehicles
       security:
         - AppKeyAuth: []
@@ -608,8 +612,11 @@ components:
           description: true仅合作站，false仅外部站，省略则返回全部
     HydrogenResult:
       type: object
-      required: [plateNumber, date, hydrogenConsumptionKg, status]
+      required: [vin, plateNumber, date, hydrogenConsumptionKg, statisticsStartTime, statisticsEndTime, updatedAt, status]
       properties:
+        vin:
+          type: string
+          description: 授权车辆 VIN，供跨接口身份校验
         plateNumber:
           type: string
         date:
@@ -620,17 +627,32 @@ components:
           format: double
           nullable: true
           description: 单日用氢量，kg；OK 和 SUSPECT 计算结果均返回数值，无数据时为 null
+        statisticsStartTime:
+          type: string
+          format: date-time
+          nullable: true
+          description: FINAL 证据区间最早开始时间；PRELIMINARY 仅有结束水位故为 null；缺失或异常证据为 null。边界是证据包络，不承诺连续覆盖
+        statisticsEndTime:
+          type: string
+          format: date-time
+          nullable: true
+          description: FINAL 证据区间最晚结束时间，PRELIMINARY 为真实 lastEventTime 水位；缺失或异常证据为 null；不是 API 查询时间
+        updatedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: 同一用氢统计行的数据库更新时间，RFC 3339 带时区；无统计行时为 null
         calculationPhase:
           type: string
           enum: [PRELIMINARY, FINAL]
-          description: 当天流式结果为 PRELIMINARY，日终重算结果为 FINAL
+          description: PRELIMINARY 仅供标注为初步的日内监控；FINAL 表示批量重算已完成，补传或算法调整仍可能再次重算，不保证固定结算时刻
         algorithmVersion:
           type: string
           description: 氢耗计算算法版本
         qualityStatus:
           type: string
           enum: [OK, SUSPECT, NO_DATA]
-          description: 氢耗计算质量状态
+          description: OK 对应 NORMAL；SUSPECT 对应 DATA_ANOMALY 并保留数值供审计，不得用于正常百公里氢耗；NO_DATA 对应无可用统计
         qualityReason:
           type: string
           description: 质量判定原因；SUSPECT 或 NO_DATA 时供调用方解释和审计
@@ -638,7 +660,7 @@ components:
           $ref: '#/components/schemas/DataStatus'
     MileageResult:
       type: object
-      required: [vin, plateNumber, date, dailyMileageKm, totalMileageKm, dataTime, updatedAt, sourceProtocol, status]
+      required: [vin, plateNumber, date, dailyMileageKm, totalMileageKm, dataTime, updatedAt, sourceProtocol, statisticsStartTime, statisticsEndTime, status]
       properties:
         vin:
           type: string
@@ -657,6 +679,16 @@ components:
           format: double
           nullable: true
           description: 当日所选协议最后有效终端累计总里程，km；GPS 日里程估算不会作为累计总里程。status=NORMAL 时必定有值，NO_DATA 时为 null
+        statisticsStartTime:
+          type: string
+          format: date-time
+          nullable: true
+          description: 当日统计所选来源的最早 first_event_time，跨日基线可早于当日零点，不是自然日起始；历史结转补零或无数据时为 null
+        statisticsEndTime:
+          type: string
+          format: date-time
+          nullable: true
+          description: 当日所选来源最晚 latest_event_time，等于 dataTime；历史结转补零或无数据时为 null。与用氢接口无共同快照保证
         dataTime:
           type: string
           format: date-time
@@ -846,10 +878,69 @@ components:
                 $ref: '#/components/schemas/StationaryVehicleResult'
     RealtimeVehicleResult:
       type: object
-      required: [vin, plateNumber, online, motionStatus, locationAvailable, status]
+      required: [vin, plateNumber, online, motionStatus, locationAvailable, status, remainingHydrogenKg, remainingHydrogenPercent, hydrogenRecordTime, hydrogenDataStatus, remainingHydrogenKgStatus, remainingHydrogenPercentStatus, hydrogenValueSource, hydrogenSourceProtocol, hydrogenStaleAfterSeconds, hydrogenExpectedIntervalSeconds, gpsFixStatus, locationRecordTime, coordinateSystem]
       properties:
         vin: { type: string }
         plateNumber: { type: string }
+        remainingHydrogenKg:
+          type: number
+          nullable: true
+          minimum: 0
+          maximum: 200
+          description: GB32960 广东燃料电池扩展 0x34 全车上报氢质量，kg；真实零保留。无值、不支持或无效为 null；陈旧值保留并标 STALE，不以单瓶压力或当日消耗推算
+        remainingHydrogenPercent:
+          type: number
+          nullable: true
+          minimum: 0
+          maximum: 100
+          description: 当前无可信额定或可用质量容量分母，固定 null，字段状态 UNSUPPORTED；不以 SOC 替代
+        hydrogenRecordTime:
+          type: string
+          format: date-time
+          nullable: true
+          description: 氢质量对应原始同帧实际采集时间，RFC 3339 带时区；不是请求时间或缓存更新时间
+        hydrogenDataStatus:
+          type: string
+          enum: [NORMAL, PARTIAL, STALE, MISSING, UNSUPPORTED, INVALID]
+          description: NORMAL 保留供未来全部字段有效；当前不会输出 NORMAL；PARTIAL 部分支持（当前质量有效但百分比不支持）；STALE 数据陈旧；MISSING 无记录；UNSUPPORTED 不支持；INVALID 异常。分别检查字段级状态
+        remainingHydrogenKgStatus:
+          type: string
+          enum: [NORMAL, STALE, MISSING, UNSUPPORTED, INVALID]
+        remainingHydrogenPercentStatus:
+          type: string
+          enum: [NORMAL, STALE, MISSING, UNSUPPORTED, INVALID]
+          description: 当前固定 UNSUPPORTED
+        hydrogenValueSource:
+          type: string
+          nullable: true
+          enum: [REPORTED]
+          description: REPORTED 仅表示终端上报质量，无法确认终端内部采用测量还是估算；本接口不作压力推算
+        hydrogenSourceProtocol:
+          type: string
+          nullable: true
+          enum: [GB32960, MQTT, JT808]
+          description: 储氢数据采用的协议，独立于位置的 protocol
+        hydrogenStaleAfterSeconds:
+          type: integer
+          nullable: true
+          description: GB32960 服务时效策略为 300 秒；不是协议采样周期承诺
+        hydrogenExpectedIntervalSeconds:
+          type: integer
+          nullable: true
+          description: 当前无已确认上报周期，固定 null
+        gpsFixStatus:
+          type: string
+          enum: [FIXED, NO_FIX, UNKNOWN]
+          description: 实际位置报文定位位；GB32960 bit0=0、JT808 bit1=1 表示 FIXED；MQTT 或缺少可信定位位为 UNKNOWN。不以在线或数据年龄推断
+        locationRecordTime:
+          type: string
+          format: date-time
+          nullable: true
+          description: 位置行对应实际采集时间，独立于主记录 recordTime；历史 FIXED 不因车辆离线改变
+        coordinateSystem:
+          type: string
+          enum: [WGS84, GCJ02, UNKNOWN]
+          description: 仅 GB2025 显式坐标类型 1=WGS84、2=GCJ02，其余 UNKNOWN；GB2016/JT808/MQTT 当前无确证为 UNKNOWN，未知坐标系不得直接当高德坐标使用
         protocol:
           type: string
           enum: [GB32960, MQTT, JT808]