功能：扩展开放平台氢耗溯源与合作站数据

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

@@ -5,7 +5,7 @@ info:
   license:
     name: Proprietary
   description: |
-    向授权合作方开放车辆单日用氢量、单日里程、区间日里程、指定时刻总里程、实时位置状态及加氢站地图点位。
+    向授权合作方开放车辆单日用氢量、单日里程、区间日里程、指定时刻总里程、加氢站停留核验、实时位置状态及加氢站地图点位。
     appKey 和逐车授权必须完整覆盖查询自然日。
 servers:
   - url: /
@@ -54,7 +54,7 @@ paths:
       description: |
         plateNumbers 省略或传空数组时，返回该应用在查询自然日有效授权的全部车辆。
         protocolPriority 传入时，逐车按数组顺序选择第一个有效协议，未列出的协议完全禁用且不会兜底；省略时保持平台默认选源行为。
-        NORMAL 结果同时包含日里程、累计总里程、实际来源协议、源数据时间和投影更新时间。
+        NORMAL 结果同时包含日里程、日末累计总里程、实际来源协议、源数据时间和投影更新时间。日里程可由 GPS 轨迹估算；累计总里程读取每日统计中的 day_end_total_mileage_km，始终优先采用同协议终端上报的累计里程，不会使用 GPS 日里程估算值冒充累计里程。
         当日无有效里程时，日里程补 0，累计总里程、来源协议、dataTime 和 updatedAt 沿用此前最近的有效统计；updatedAt 仍为上一统计周期的计算时间。
       operationId: queryDailyMileage
       security:
@@ -92,7 +92,7 @@ paths:
         首次请求返回 snapshotId 和 nextCursor；后续请求保持原参数并传回 nextCursor。
         快照仅固化授权车辆清单，逐页读取已建立索引的日统计投影，不扫描原始时序明细。
         protocolPriority 对区间内每辆车、每个自然日独立生效；未列出的协议完全禁用。
-        某日无有效里程时，dailyMileageKm 补 0，其余里程证据沿用此前最近的有效统计。
+        某日无有效里程时，dailyMileageKm 补 0，其余里程证据沿用此前最近的有效统计。若终端累计里程回退，返回 DATA_ANOMALY 与 dataQuality=TOTAL_MILEAGE_ROLLBACK，绝不沿用历史值伪装为正常数据。日里程与日末累计总里程独立统计：GPS 轨迹估算仅用于日里程，累计总里程读取每日统计字段 day_end_total_mileage_km。
       operationId: queryDailyMileageRange
       security:
         - AppKeyAuth: []
@@ -160,6 +160,46 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '500':
           $ref: '#/components/responses/InternalError'
+  /api/v1/vehicles/stationary/query:
+    post:
+      tags: [合作方数据接口]
+      summary: 加氢站车辆停留核验
+      description: |
+        用于加氢车牌核验。传入加氢站经度、纬度、坐标系、半径和北京时间区间，返回范围内速度不大于 3 km/h 的授权车辆停留区间。
+        coordinateSystem 支持 WGS84（默认）和 GCJ02（高德坐标）；服务端会将 GCJ02 转换为 WGS84 后进行核验。
+        同一车辆相邻静止点间隔超过 10 分钟会拆分为不同停留；仅返回至少 2 个定位样本且持续不少于 60 秒的停留。
+        最大查询区间为 24 小时。结果按 matchScore 从高到低排序；分数综合平均距离、最高速度、停留时长和采样数量，供人工核验使用，不等同于加氢交易凭证。
+      operationId: queryStationaryVehicles
+      security:
+        - AppKeyAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StationaryVehicleQuery'
+            example:
+              startTime: '2026-08-06 10:00:00'
+              endTime: '2026-08-06 12:00:00'
+              longitude: 120.752312
+              latitude: 30.746281
+              coordinateSystem: GCJ02
+              radiusMeters: 5
+      responses:
+        '200':
+          description: 查询成功；无匹配车辆时 data 为空数组
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StationaryVehicleQueryResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalError'
   /api/v1/vehicles/realtime/query:
     post:
       tags: [合作方数据接口]
@@ -167,7 +207,9 @@ paths:
       description: |
         plateNumbers 省略或传空数组时返回应用当前有效授权的全部车辆。
         实时来源优先级为 GB32960 > YUTONG_MQTT > JT808；所有来源超过10分钟时改按最新记录选择。
-        任一采集协议在最近60秒内上报即视为在线；protocol、位置、速度和记录时间仍按上述来源优先级选择。
+        任一采集协议在最近60秒内上报即视为在线；protocol、位置、速度、SOC 和记录时间仍按上述来源优先级选择。
+        socPercent 仅在所选来源采集到有效 SOC（0–100，单位 %）时返回；无值或无效值时该字段省略。
+        activeToday 表示任一采集协议在当前自然日（Asia/Shanghai）内曾上报，用于日上线车辆统计，不改变 online 的实时口径。
         在线且所选来源速度大于3km/h为行驶中，否则为静止中。
       operationId: queryRealtimeVehicles
       security:
@@ -492,6 +534,52 @@ components:
           type: string
           enum: [GB32960, YUTONG_MQTT, JT808]
           description: 可选；只接受平台统一协议标识；不传时按 GB32960 > YUTONG_MQTT > JT808
+    StationaryVehicleQuery:
+      type: object
+      additionalProperties: false
+      required: [startTime, endTime, longitude, latitude]
+      properties:
+        startTime:
+          type: string
+          pattern: '^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$'
+          description: 开始时间，北京时间，yyyy-MM-dd HH:mm:ss
+        endTime:
+          type: string
+          pattern: '^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$'
+          description: 结束时间，北京时间；须晚于开始时间，最长 24 小时
+        longitude:
+          type: number
+          format: double
+          minimum: -180
+          maximum: 180
+          description: 加氢站经度；坐标系由 coordinateSystem 指定
+        latitude:
+          type: number
+          format: double
+          minimum: -90
+          maximum: 90
+          description: 加氢站纬度；坐标系由 coordinateSystem 指定
+        coordinateSystem:
+          type: string
+          enum: [WGS84, GCJ02]
+          default: WGS84
+          description: 坐标系；WGS84 为默认值，GCJ02 为高德地图坐标。GCJ02 会在服务端转换为 WGS84 后核验
+        radiusMeters:
+          type: number
+          format: double
+          minimum: 1
+          maximum: 100
+          default: 5
+          description: 核验半径，单位米；省略时为 5 米
+        plateNumbers:
+          type: array
+          maxItems: 2000
+          uniqueItems: true
+          items:
+            type: string
+            minLength: 1
+            maxLength: 32
+          description: 可选；省略或传空数组时核验整个时间区间均有效授权的全部车辆
     RealtimeVehicleQuery:
       type: object
       additionalProperties: false
@@ -554,7 +642,7 @@ components:
           type: number
           format: double
           nullable: true
-          description: 当日所选协议最后有效累计总里程，km；status=NORMAL 时必定有值，NO_DATA 时为 null
+          description: 当日所选协议最后有效终端累计总里程，km；GPS 日里程估算不会作为累计总里程。status=NORMAL 时必定有值，NO_DATA 时为 null
         dataTime:
           type: string
           format: date-time
@@ -570,6 +658,11 @@ components:
           enum: [GB32960, MQTT, JT808]
           nullable: true
           description: 本行实际选中的来源协议；status=NO_DATA 时为 null
+        dataQuality:
+          type: string
+          nullable: true
+          enum: [TOTAL_MILEAGE_ROLLBACK]
+          description: status=DATA_ANOMALY 时的异常原因；累计里程回退时为 TOTAL_MILEAGE_ROLLBACK
         status:
           $ref: '#/components/schemas/DataStatus'
     MileageRangeResult:
@@ -594,7 +687,7 @@ components:
           format: double
           nullable: true
           minimum: 0
-          description: 当日所选协议累计总里程；缺日时沿用此前最近有效值
+          description: 当日所选协议终端累计总里程；GPS 日里程估算不会作为累计总里程，缺日时沿用此前最近有效值
         dataTime:
           type: string
           format: date-time
@@ -609,11 +702,17 @@ components:
           enum: [GB32960, MQTT, JT808]
           nullable: true
           description: 本行实际选中的来源协议；status=NO_DATA 时为 null
+        dataQuality:
+          type: string
+          nullable: true
+          enum: [TOTAL_MILEAGE_ROLLBACK]
+          description: status=DATA_ANOMALY 时的异常原因；累计里程回退时为 TOTAL_MILEAGE_ROLLBACK
         status:
           $ref: '#/components/schemas/DataStatus'
     DataStatus:
       type: string
-      enum: [NORMAL, NO_DATA]
+      enum: [NORMAL, NO_DATA, DATA_ANOMALY]
+      description: NORMAL=存在可用数据；NO_DATA=授权范围内无可用数据；DATA_ANOMALY=检测到数据异常，详情见 dataQuality
     HydrogenQueryResponse:
       allOf:
         - $ref: '#/components/schemas/SuccessEnvelope'
@@ -694,6 +793,25 @@ components:
           example: GB32960 > YUTONG_MQTT > JT808
         status:
           $ref: '#/components/schemas/DataStatus'
+    StationaryVehicleResult:
+      type: object
+      required: [vin, plateNumber, stayStartTime, stayEndTime, stayDurationSeconds, stayDurationMinutes, matchScore, averageDistanceMeters, maxDistanceMeters, averageSpeedKmh, maxSpeedKmh, matchedSamples, sourceProtocols]
+      properties:
+        vin: { type: string, description: 车辆唯一 VIN }
+        plateNumber: { type: string, description: 车辆车牌号 }
+        stayStartTime: { type: string, description: 停留开始定位时间，北京时间 }
+        stayEndTime: { type: string, description: 停留结束定位时间，北京时间 }
+        stayDurationSeconds: { type: integer, description: 停留长度，秒 }
+        stayDurationMinutes: { type: number, format: double, description: 停留长度，分钟 }
+        matchScore: { type: number, format: double, minimum: 0, maximum: 100, description: 匹配度，越高表示位置更接近、速度更低、停留更久且样本更充分 }
+        averageDistanceMeters: { type: number, format: double }
+        maxDistanceMeters: { type: number, format: double }
+        averageSpeedKmh: { type: number, format: double }
+        maxSpeedKmh: { type: number, format: double, maximum: 3 }
+        matchedSamples: { type: integer, minimum: 2 }
+        sourceProtocols:
+          type: array
+          items: { type: string, enum: [GB32960, MQTT, JT808] }
     TotalMileageQueryResponse:
       allOf:
         - $ref: '#/components/schemas/SuccessEnvelope'
@@ -702,22 +820,37 @@ components:
           properties:
             data:
               $ref: '#/components/schemas/TotalMileageResult'
+    StationaryVehicleQueryResponse:
+      allOf:
+        - $ref: '#/components/schemas/SuccessEnvelope'
+        - type: object
+          required: [data]
+          properties:
+            data:
+              type: array
+              items:
+                $ref: '#/components/schemas/StationaryVehicleResult'
     RealtimeVehicleResult:
       type: object
       required: [vin, plateNumber, online, motionStatus, locationAvailable, status]
       properties:
         vin: { type: string }
         plateNumber: { type: string }
-        protocol: { type: string, enum: [GB32960, YUTONG_MQTT, JT808] }
-        longitude: { type: number, format: double, nullable: true }
-        latitude: { type: number, format: double, nullable: true }
-        speedKmh: { type: number, format: double, nullable: true }
-        totalMileageKm: { type: number, format: double, nullable: true }
-        recordTime: { type: string }
-        timeDifferenceSeconds: { type: integer, format: int64, minimum: 0 }
+        protocol:
+          type: string
+          enum: [GB32960, MQTT, JT808]
+          description: 本条实时位置、速度、里程及记录时间实际采用的采集协议；GB32960=车辆协议，MQTT=MQTT车端来源，JT808=定位终端来源
+        longitude: { type: number, format: double, nullable: true, description: 所选来源的最新有效经度；无位置时为 null }
+        latitude: { type: number, format: double, nullable: true, description: 所选来源的最新有效纬度；无位置时为 null }
+        speedKmh: { type: number, format: double, nullable: true, description: 所选来源瞬时速度，单位 km/h }
+        socPercent: { type: number, format: double, minimum: 0, maximum: 100, description: 所选来源的动力电池荷电状态，单位 %；无有效采集值时字段省略 }
+        totalMileageKm: { type: number, format: double, nullable: true, description: 所选来源累计总里程，单位 km }
+        recordTime: { type: string, description: 所选来源实际记录时间，北京时间 }
+        timeDifferenceSeconds: { type: integer, format: int64, minimum: 0, description: 当前查询时间减 recordTime，单位秒 }
         online: { type: boolean, description: 任一采集协议是否在最近60秒内上报 }
-        motionStatus: { type: string, enum: [driving, idle, offline] }
-        locationAvailable: { type: boolean }
+        activeToday: { type: boolean, description: 任一采集协议在当前自然日（Asia/Shanghai）内上报过 }
+        motionStatus: { type: string, enum: [driving, idle, offline], description: driving=在线且速度大于3km/h；idle=在线且速度不大于3km/h；offline=当前不在线或无实时记录 }
+        locationAvailable: { type: boolean, description: true=longitude/latitude 有效；false=当前无有效位置 }
         status: { $ref: '#/components/schemas/DataStatus' }
     RealtimeVehicleQueryResponse:
       allOf: