openapi: 3.0.3
info:
  title: 车辆数据开放平台 API
  version: 1.1.0
  license:
    name: Proprietary
  description: |
    向授权合作方开放车辆单日用氢量、单日里程和指定时刻总里程。
    appKey 和逐车授权必须完整覆盖查询自然日。
servers:
  - url: /
    description: 当前服务
tags:
  - name: 合作方数据接口
    description: 使用 appKey 查询已授权车辆的日统计数据
  - name: 开放平台管理
    description: 仅车辆数据平台管理员可调用的应用和车辆授权管理接口
paths:
  /api/v1/vehicles/hydrogen-consumption/query:
    post:
      tags: [合作方数据接口]
      summary: 查询车辆单日用氢量
      operationId: queryDailyHydrogenConsumption
      security:
        - AppKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VehicleDailyQuery'
            example:
              plateNumbers: [粤A12345, 粤B67890]
              date: '2026-07-01'
      responses:
        '200':
          description: 查询成功；无数据车辆仍保留在结果中
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HydrogenQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/vehicles/mileage/query:
    post:
      tags: [合作方数据接口]
      summary: 查询车辆单日里程
      operationId: queryDailyMileage
      security:
        - AppKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VehicleDailyQuery'
            example:
              plateNumbers: [粤A12345]
              date: '2026-07-01'
      responses:
        '200':
          description: 查询成功；无数据车辆仍保留在结果中
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MileageQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v1/vehicles/total-mileage/query:
    post:
      tags: [合作方数据接口]
      summary: 查询指定时刻的车辆总里程
      description: |
        返回不晚于请求时间的最近一条有效总里程记录、实际记录时间和时间差秒数。
        protocol 不传时严格按 GB32960 > YUTONG_MQTT > JT808 选择首个有数据的协议。
        GB32960 和 YUTONG_MQTT 为车辆仪表盘或车端累计里程；JT808 为定位终端/GPS侧累计里程。
      operationId: queryTotalMileageAtTime
      security:
        - AppKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TotalMileageQuery'
            example:
              vin: LA9GG68L2PBAF4790
              time: '2026-07-21 09:30:00'
              protocol: '32960'
      responses:
        '200':
          description: 查询成功；没有可用记录时返回 NO_DATA
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TotalMileageQueryResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalError'
  /api/v2/open-platform/apps:
    get:
      tags: [开放平台管理]
      summary: 查询开放平台应用
      operationId: listOpenPlatformApps
      security:
        - AdminBearer: []
      responses:
        '200':
          description: 应用列表
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAppListResponse'
        '401':
          description: 未登录
        '403':
          description: 非管理员
    post:
      tags: [开放平台管理]
      summary: 创建应用和 appKey
      description: appKey 明文仅在本次响应中返回。
      operationId: createOpenPlatformApp
      security:
        - AdminBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppInput'
      responses:
        '200':
          description: 创建成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAppCreatedResponse'
        '400':
          description: 参数错误
        '401':
          description: 未登录
        '403':
          description: 非管理员
  /api/v2/open-platform/apps/{id}:
    put:
      tags: [开放平台管理]
      summary: 更新应用状态和有效期
      operationId: updateOpenPlatformApp
      security:
        - AdminBearer: []
      parameters:
        - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppInput'
      responses:
        '200':
          description: 更新成功
        '400':
          description: 参数错误
        '404':
          description: 应用不存在
  /api/v2/open-platform/apps/{id}/rotate-key:
    post:
      tags: [开放平台管理]
      summary: 轮换 appKey
      description: 旧 Key 立即失效，新 Key 明文仅在本次响应中返回。
      operationId: rotateOpenPlatformAppKey
      security:
        - AdminBearer: []
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: 轮换成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminAppCreatedResponse'
        '404':
          description: 应用不存在
  /api/v2/open-platform/apps/{id}/vehicles:
    get:
      tags: [开放平台管理]
      summary: 查询应用的车辆授权
      operationId: listOpenPlatformVehicleGrants
      security:
        - AdminBearer: []
      parameters:
        - $ref: '#/components/parameters/AppId'
      responses:
        '200':
          description: 授权列表
        '404':
          description: 应用不存在
    put:
      tags: [开放平台管理]
      summary: 完整替换车辆授权
      operationId: replaceOpenPlatformVehicleGrants
      security:
        - AdminBearer: []
      parameters:
        - $ref: '#/components/parameters/AppId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VehicleGrantRequest'
      responses:
        '200':
          description: 替换成功
        '400':
          description: VIN 或有效期不正确
        '404':
          description: 应用不存在
components:
  securitySchemes:
    AppKeyAuth:
      type: http
      scheme: bearer
      bearerFormat: 32-character appKey
      description: 32 位无连字符 UUID appKey
    AdminBearer:
      type: http
      scheme: bearer
      bearerFormat: Platform session token
      description: 车辆数据平台管理员令牌
  parameters:
    AppId:
      name: id
      in: path
      required: true
      schema:
        type: integer
        format: int64
        minimum: 1
  responses:
    BadRequest:
      description: 请求参数不正确
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            invalidDate:
              value:
                code: INVALID_DATE_FORMAT
                message: date格式必须为yyyy-MM-dd
                traceId: 4ccf63c4e51d4d4ab9107d931783a53e
    Unauthorized:
      description: appKey 不存在、停用或过期
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Key 或车辆授权未完整覆盖查询自然日
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: 服务内部异常
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    VehicleDailyQuery:
      type: object
      additionalProperties: false
      required: [plateNumbers, date]
      properties:
        plateNumbers:
          type: array
          minItems: 1
          maxItems: 200
          uniqueItems: true
          items:
            type: string
            minLength: 1
            maxLength: 32
          description: 需要查询的车牌号
        date:
          type: string
          format: date
          description: 查询自然日，yyyy-MM-dd
    TotalMileageQuery:
      type: object
      additionalProperties: false
      required: [vin, time]
      properties:
        vin:
          type: string
          pattern: '^[A-HJ-NPR-Z0-9]{17}$'
          description: 已授权车辆 VIN
        time:
          type: string
          pattern: '^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}$'
          description: 请求时刻，北京时间，固定格式 yyyy-MM-dd HH:mm:ss
        protocol:
          type: string
          enum: ['32960', mqtt, '808', GB32960, YUTONG_MQTT, JT808]
          description: 可选；不传时按 GB32960 > YUTONG_MQTT > JT808
    HydrogenResult:
      type: object
      required: [plateNumber, date, hydrogenConsumptionKg, status]
      properties:
        plateNumber:
          type: string
        date:
          type: string
          format: date
        hydrogenConsumptionKg:
          type: number
          format: double
          nullable: true
          description: 单日用氢量，kg；无数据时为 null
        status:
          $ref: '#/components/schemas/DataStatus'
    MileageResult:
      type: object
      required: [plateNumber, date, dailyMileageKm, status]
      properties:
        plateNumber:
          type: string
        date:
          type: string
          format: date
        dailyMileageKm:
          type: number
          format: double
          nullable: true
          description: 单日里程，km；无数据时为 null
        status:
          $ref: '#/components/schemas/DataStatus'
    DataStatus:
      type: string
      enum: [NORMAL, NO_DATA]
    HydrogenQueryResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/HydrogenResult'
    MileageQueryResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/MileageResult'
    TotalMileageResult:
      type: object
      required: [vin, queryTime, totalMileageKm, selectionPolicy, status]
      properties:
        vin:
          type: string
        queryTime:
          type: string
          description: 请求时刻，北京时间
        totalMileageKm:
          type: number
          format: double
          nullable: true
          description: 总里程，km；无数据时为 null
        protocol:
          type: string
          enum: [GB32960, YUTONG_MQTT, JT808]
          description: 实际采用的采集协议
        protocolInput:
          type: string
          description: 请求中指定的协议原值；未指定时省略
        mileageMeaning:
          type: string
          description: 当前协议总里程的业务含义
        recordTime:
          type: string
          description: 命中的实际采集记录时间，北京时间
        timeDifferenceSeconds:
          type: integer
          format: int64
          minimum: 0
          description: 请求时间减实际记录时间，单位秒
        selectionPolicy:
          type: string
          example: GB32960 > YUTONG_MQTT > JT808
        status:
          $ref: '#/components/schemas/DataStatus'
    TotalMileageQueryResponse:
      allOf:
        - $ref: '#/components/schemas/SuccessEnvelope'
        - type: object
          required: [data]
          properties:
            data:
              $ref: '#/components/schemas/TotalMileageResult'
    SuccessEnvelope:
      type: object
      required: [code, message, traceId]
      properties:
        code:
          type: string
          enum: [SUCCESS]
        message:
          type: string
          example: success
        traceId:
          type: string
          example: 4ccf63c4e51d4d4ab9107d931783a53e
    ErrorResponse:
      type: object
      required: [code, message, traceId]
      properties:
        code:
          type: string
          enum:
            - INVALID_REQUEST
            - PLATE_NUMBERS_EMPTY
            - INVALID_DATE_FORMAT
            - UNAUTHORIZED
            - FORBIDDEN
            - INTERNAL_ERROR
        message:
          type: string
        traceId:
          type: string
    AppInput:
      type: object
      additionalProperties: false
      required: [name, status, validFrom]
      properties:
        name:
          type: string
          maxLength: 96
          example: 示例合作方
        status:
          type: string
          enum: [enabled, disabled]
        validFrom:
          type: string
          format: date-time
          example: '2026-07-01T00:00:00+08:00'
        validTo:
          type: string
          format: date-time
          nullable: true
          example: '2027-07-01T00:00:00+08:00'
    App:
      type: object
      required: [id, name, appKeyPrefix, status, validFrom]
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
        appKeyPrefix:
          type: string
          minLength: 8
          maxLength: 8
        status:
          type: string
          enum: [enabled, disabled]
        validFrom:
          type: string
          format: date-time
        validTo:
          type: string
          format: date-time
          nullable: true
    AppCreated:
      allOf:
        - $ref: '#/components/schemas/App'
        - type: object
          required: [appKey]
          properties:
            appKey:
              type: string
              minLength: 32
              maxLength: 32
              pattern: '^[0-9a-f]{32}$'
              description: 仅本次响应返回
    VehicleGrantRequest:
      type: object
      additionalProperties: false
      required: [vehicles]
      properties:
        vehicles:
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/VehicleGrantInput'
    VehicleGrantInput:
      type: object
      additionalProperties: false
      required: [vin, validFrom]
      properties:
        vin:
          type: string
          minLength: 17
          maxLength: 17
        validFrom:
          type: string
          format: date-time
        validTo:
          type: string
          format: date-time
          nullable: true
    AdminAppListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/App'
        traceId:
          type: string
    AdminAppCreatedResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/AppCreated'
        traceId:
          type: string