feat: expose vehicle map data APIs

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

@@ -1,11 +1,11 @@
 openapi: 3.0.3
 info:
   title: 车辆数据开放平台 API
-  version: 1.5.0
+  version: 1.6.0
   license:
     name: Proprietary
   description: |
-    向授权合作方开放车辆单日用氢量、单日里程、区间日里程和指定时刻总里程。
+    向授权合作方开放车辆单日用氢量、单日里程、区间日里程、指定时刻总里程、实时位置状态及加氢站地图点位。
     appKey 和逐车授权必须完整覆盖查询自然日。
 servers:
   - url: /
@@ -160,6 +160,67 @@ paths:
           $ref: '#/components/responses/Forbidden'
         '500':
           $ref: '#/components/responses/InternalError'
+  /api/v1/vehicles/realtime/query:
+    post:
+      tags: [合作方数据接口]
+      summary: 查询授权车辆实时位置与状态
+      description: |
+        plateNumbers 省略或传空数组时返回应用当前有效授权的全部车辆。
+        实时来源优先级为 GB32960 > YUTONG_MQTT > JT808；所有来源超过10分钟时改按最新记录选择。
+        记录时间距当前不超过60秒视为在线；在线且速度大于3km/h为行驶中，否则为静止中。
+      operationId: queryRealtimeVehicles
+      security:
+        - AppKeyAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RealtimeVehicleQuery'
+            example: {}
+      responses:
+        '200':
+          description: 查询成功；没有实时记录的授权车辆以 NO_DATA 返回
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/RealtimeVehicleQueryResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '403':
+          $ref: '#/components/responses/Forbidden'
+        '500':
+          $ref: '#/components/responses/InternalError'
+  /api/v1/hydrogen-stations/query:
+    post:
+      tags: [合作方数据接口]
+      summary: 查询加氢站地图点位
+      description: 只读返回资产管理数据库内具有有效经纬度的加氢站，可按省、市和合作状态筛选；无需车辆授权但要求有效 appKey。
+      operationId: queryHydrogenStations
+      security:
+        - AppKeyAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/HydrogenStationQuery'
+            example: {}
+      responses:
+        '200':
+          description: 查询成功
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HydrogenStationQueryResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '500':
+          $ref: '#/components/responses/InternalError'
   /api/v2/open-platform/apps:
     get:
       tags: [开放平台管理]
@@ -430,6 +491,32 @@ components:
           type: string
           enum: [GB32960, YUTONG_MQTT, JT808]
           description: 可选；只接受平台统一协议标识；不传时按 GB32960 > YUTONG_MQTT > JT808
+    RealtimeVehicleQuery:
+      type: object
+      additionalProperties: false
+      properties:
+        plateNumbers:
+          type: array
+          maxItems: 2000
+          uniqueItems: true
+          items:
+            type: string
+            minLength: 1
+            maxLength: 32
+          description: 可选；省略或传空数组时查询当前有效授权的全部车辆
+    HydrogenStationQuery:
+      type: object
+      additionalProperties: false
+      properties:
+        province:
+          type: string
+          maxLength: 32
+        city:
+          type: string
+          maxLength: 32
+        cooperateOnly:
+          type: boolean
+          description: true仅合作站，false仅外部站，省略则返回全部
     HydrogenResult:
       type: object
       required: [plateNumber, date, hydrogenConsumptionKg, status]
@@ -614,6 +701,55 @@ components:
           properties:
             data:
               $ref: '#/components/schemas/TotalMileageResult'
+    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 }
+        online: { type: boolean }
+        motionStatus: { type: string, enum: [driving, idle, offline] }
+        locationAvailable: { type: boolean }
+        status: { $ref: '#/components/schemas/DataStatus' }
+    RealtimeVehicleQueryResponse:
+      allOf:
+        - $ref: '#/components/schemas/SuccessEnvelope'
+        - type: object
+          required: [data]
+          properties:
+            data:
+              type: array
+              items: { $ref: '#/components/schemas/RealtimeVehicleResult' }
+    HydrogenStation:
+      type: object
+      required: [id, name, longitude, latitude, cooperative]
+      properties:
+        id: { type: string, description: 站点ID使用字符串避免JavaScript整数精度损失 }
+        name: { type: string }
+        shortName: { type: string }
+        address: { type: string }
+        longitude: { type: number, format: double }
+        latitude: { type: number, format: double }
+        province: { type: string }
+        city: { type: string }
+        district: { type: string }
+        cooperative: { type: boolean }
+    HydrogenStationQueryResponse:
+      allOf:
+        - $ref: '#/components/schemas/SuccessEnvelope'
+        - type: object
+          required: [data]
+          properties:
+            data:
+              type: array
+              items: { $ref: '#/components/schemas/HydrogenStation' }
     SuccessEnvelope:
       type: object
       required: [code, message, traceId]