feat: 按35MPa满充模型提供剩余氢量估算与百分比

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

@@ -1,7 +1,7 @@
 openapi: 3.0.3
 info:
   title: 车辆数据开放平台 API
-  version: 1.8.0
+  version: 1.9.0
   license:
     name: Proprietary
   description: |
@@ -211,8 +211,9 @@ paths:
         socPercent 仅在所选来源采集到有效 SOC（0–100，单位 %）时返回；无值或无效值时该字段省略。
         activeToday 表示任一采集协议在当前自然日（Asia/Shanghai）内曾上报，用于日上线车辆统计，不改变 online 的实时口径。
         离线时 motionStatus=offline；在线且所选来源速度大于3km/h为 driving，否则为 idle。
-        储氢使用可追溯原始帧；最新帧缺少氢量时可有界回补，当前百分比无可信容量分母为 null/UNSUPPORTED；不得用 SOC 替代。
-        仅 GB 最新快照有引用且精确帧氢量 MISSING 时，回查该快照 received_at 向前 5 分钟的含氢量字段原始帧，按采集时间优先、接收时间次序取最新；不回退覆盖 INVALID，离线回补保留真实 STALE。
+        满充容量采用 PressureHydrogenMassKg(35,15,VIN水容积)；35 MPa 是本次业务基准，15°C 密度比参考来自 https://unece.org/sites/default/files/2024-07/ECE_TRANS_WP.29_2023_110E.pdf，不代表车型额定压力自动认证。
+        储氢优先终端上报质量 REPORTED；无质量时以同帧最大氢压/最大氢温与 VIN 全车水容积估算 ESTIMATED。百分比按 35 MPa、15°C 满充参考质量计算，不以 SOC 替代。
+        仅 GB 最新快照有引用且精确帧氢量 MISSING 时有界回补，按采集时间优先、接收时间次序检查最近5条候选；不完整温压可取次新完整帧，不回退覆盖 INVALID，离线回补保留真实 STALE。
         GPS 定位状态独立于在线与陈旧；坐标系可能 UNKNOWN，不能假定统一 GCJ02。
         补充历史查询共享 3 秒预算，失败或超时降级为 MISSING/UNKNOWN 并保留旧实时字段；MISSING 不等于设备不支持。
       operationId: queryRealtimeVehicles
@@ -878,7 +879,7 @@ components:
                 $ref: '#/components/schemas/StationaryVehicleResult'
     RealtimeVehicleResult:
       type: object
-      required: [vin, plateNumber, online, motionStatus, locationAvailable, status, remainingHydrogenKg, remainingHydrogenPercent, hydrogenRecordTime, hydrogenDataStatus, remainingHydrogenKgStatus, remainingHydrogenPercentStatus, hydrogenValueSource, hydrogenSourceProtocol, hydrogenStaleAfterSeconds, hydrogenExpectedIntervalSeconds, gpsFixStatus, locationRecordTime, coordinateSystem]
+      required: [vin, plateNumber, online, motionStatus, locationAvailable, status, remainingHydrogenKg, remainingHydrogenPercent, hydrogenRecordTime, hydrogenDataStatus, remainingHydrogenKgStatus, remainingHydrogenPercentStatus, hydrogenValueSource, hydrogenSourceProtocol, hydrogenStaleAfterSeconds, hydrogenExpectedIntervalSeconds, remainingHydrogenPercentSource, hydrogenFullCapacityKg, hydrogenTankCapacityL, hydrogenFullPressureMPa, hydrogenReferenceTemperatureC, hydrogenEstimatePressureMPa, hydrogenEstimateTemperatureC, hydrogenPressureTemperatureSource, hydrogenCalculationVersion, hydrogenCapacitySource, hydrogenPercentReason, gpsFixStatus, locationRecordTime, coordinateSystem]
       properties:
         vin: { type: string }
         plateNumber: { type: string }
@@ -886,14 +887,14 @@ components:
           type: number
           nullable: true
           minimum: 0
-          maximum: 200
-          description: GB32960 广东燃料电池扩展 0x34 全车上报氢质量，kg；真实零保留。无值、不支持或无效为 null；陈旧值保留并标 STALE，不以单瓶压力或当日消耗推算
+          maximum: 500
+          description: 全车氢质量 kg；优先 GB32960 广东扩展终端上报（0–200 kg），缺质量时以同帧最大氢压/氢温和 VIN 全车水容积作实气估算（0–500 kg）。真实零保留，缺失/异常为 null，陈旧值保留并标 STALE
         remainingHydrogenPercent:
           type: number
           nullable: true
           minimum: 0
           maximum: 100
-          description: 当前无可信额定或可用质量容量分母，固定 null，字段状态 UNSUPPORTED；不以 SOC 替代
+          description: 剩余质量除以 VIN 水容积在 35 MPa、15°C 的实气模型满充质量乘100，属于 ESTIMATED；缺容量为 null/MISSING。超过100返回 null/INVALID，不截断为100，kg独立保留；不以动力电池SOC替代
         hydrogenRecordTime:
           type: string
           format: date-time
@@ -902,19 +903,70 @@ components:
         hydrogenDataStatus:
           type: string
           enum: [NORMAL, PARTIAL, STALE, MISSING, UNSUPPORTED, INVALID]
-          description: NORMAL 保留供未来全部字段有效；当前不会输出 NORMAL；PARTIAL 部分支持（当前质量有效但百分比不支持）；STALE 数据陈旧；MISSING 无记录；UNSUPPORTED 不支持；INVALID 异常。分别检查字段级状态
+          description: 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
+          description: 独立于 kg 状态；容量缺失 MISSING，比例超100 INVALID；有值时继承 kg 的 NORMAL 或 STALE
         hydrogenValueSource:
           type: string
           nullable: true
-          enum: [REPORTED]
-          description: REPORTED 仅表示终端上报质量，无法确认终端内部采用测量还是估算；本接口不作压力推算
+          enum: [REPORTED, ESTIMATED]
+          description: kg 来源；REPORTED 仅确认终端上报，无法判断终端内部测量或估算；ESTIMATED 为平台压力/温度/容积实气模型估算
+        remainingHydrogenPercentSource:
+          type: string
+          nullable: true
+          enum: [ESTIMATED]
+          description: 百分比始终为模型满充容量推算；与 kg 来源独立，计算前缺条件时为 null
+        hydrogenFullCapacityKg:
+          type: number
+          nullable: true
+          description: 实际用于比例分母的未舍入满充质量，kg；PressureHydrogenMassKg(35,15,VIN水容积)，不是扣除残余后的可用容量
+        hydrogenTankCapacityL:
+          type: number
+          nullable: true
+          description: VIN 配置的全车储氢水容积，L；必须 active 且大于0、不超过10000，不根据车型臆造默认值
+        hydrogenFullPressureMPa:
+          type: number
+          nullable: true
+          enum: [35]
+          description: 本次业务确认的满充参考压力，MPa；不代表自动核验每辆车铭牌额定压力
+        hydrogenReferenceTemperatureC:
+          type: number
+          nullable: true
+          enum: [15]
+          description: 满充参考温度，摄氏度
+        hydrogenEstimatePressureMPa:
+          type: number
+          nullable: true
+          description: 仅平台估算 kg 时使用的同帧最大氢压，MPa；支持0，不补默认值
+        hydrogenEstimateTemperatureC:
+          type: number
+          nullable: true
+          description: 仅平台估算 kg 时使用的同帧最大氢温，摄氏度；模型输入范围−40–726.85°C，不是车辆安全温度阈值；缺失不补默认温度
+        hydrogenPressureTemperatureSource:
+          type: string
+          nullable: true
+          enum: [MAX_SENSOR_AGGREGATE]
+          description: 最大氢压/最大氢温聚合读数近似；两者不保证来自同一瓶，不是逐瓶质量求和或全瓶完整性证明
+        hydrogenCalculationVersion:
+          type: string
+          nullable: true
+          enum: [REAL_GAS_35MPA_15C_V1]
+          description: 实时储氢模型版本；不修改日用氢算法
+        hydrogenCapacitySource:
+          type: string
+          nullable: true
+          enum: [vehicle_hydrogen_tank_capacity]
+          description: 满充容量采用的 VIN 配置数据表
+        hydrogenPercentReason:
+          type: string
+          nullable: true
+          enum: [MISSING_HYDROGEN_MEASUREMENT, INVALID_MASS_READING, INVALID_PRESSURE_TEMPERATURE, INCOMPLETE_PRESSURE_TEMPERATURE, MISSING_TANK_CAPACITY, MASS_CALCULATION_FAILED, EXCEEDS_NOMINAL_FULL_CAPACITY]
+          description: 缺少或拒绝百分比的原因；超出业务满充参考仅拒绝百分比，不伪装为100，也不据此判断车辆安全状态
         hydrogenSourceProtocol:
           type: string
           nullable: true