chore: curate monthly assessment evidence and scripts

openapi.yaml

@@ -0,0 +1,553 @@
+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