+
+
+ 认证
+ Authorization: Bearer <32位appKey>
+Content-Type: application/json
+ appKey 由平台管理员创建并授权车辆。Key 和逐车授权都必须完整覆盖所查询的自然日。
+
+ 开放接口
+ POST/api/v1/vehicles/hydrogen-consumption/query
+ 查询指定车辆的单日用氢量，单位 kg。
+ POST/api/v1/vehicles/mileage/query
+ 查询指定车辆的单日行驶里程、累计总里程、实际来源协议、车辆源数据时间和投影更新时间，单位 km。
+ 以上两个按日接口的 plateNumbers 可选；省略或传空数组时，返回该应用在查询自然日有效授权的全部车辆。
+ POST/api/v1/vehicles/mileage/range/query
+ 按最长 366 天区间分页查询逐车逐日里程。首次请求固化授权车辆清单，后续使用 nextCursor 翻页。
+ 两个里程接口均可传 protocolPriority，唯一外部值为 GB32960、MQTT、JT808。逐车逐日按数组顺序选择第一个有效协议；未列出的协议完全禁用。省略字段时保持现有默认选源行为。
+ 查询日没有有效里程但此前存在有效累计里程时，日里程补 0，累计总里程、来源协议和数据时间沿用最近有效统计；updatedAt 显示上一个统计周期的计算时间。
+ POST/api/v1/vehicles/total-mileage/query
+ 按 VIN 和北京时间查询不晚于指定时刻的最近一条总里程，返回实际采集协议、记录时间和时间差秒数。
+
+ 总里程协议口径
+
+ | protocol 唯一规范值 | 总里程含义 |
|---|
+
+ | GB32960 | 车辆仪表盘累计总里程，对应 GB/T 32960 整车数据累计里程 |
+ | YUTONG_MQTT | 车辆仪表盘或车端控制器累计总里程，由 MQTT 平台上报 |
+ | JT808 | 定位终端累计里程，由 GPS/终端侧计算，不等同于车辆仪表盘里程 |
+
+
+ protocol 不传时严格按 GB32960 > YUTONG_MQTT > JT808 选择首个有数据的协议。接口取不晚于请求时间的最近记录，不跨协议拼接里程。
+
+ 请求示例
+ curl -X POST 'https://your-host/api/v1/vehicles/hydrogen-consumption/query' \
+ -H 'Authorization: Bearer YOUR_32_CHARACTER_APP_KEY' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "plateNumbers": ["粤A12345", "粤B67890"],
+ "date": "2026-07-01"
+ }'
+
+ 查询全部授权车辆的单日数据
+ {
+ "date": "2026-07-01"
+}
+
+ 按自定义协议优先级查询单日里程
+ {
+ "plateNumbers": ["粤A12345"],
+ "date": "2026-07-01",
+ "protocolPriority": ["JT808", "GB32960", "MQTT"]
+}
+
+ 指定时刻总里程
+ curl -X POST 'https://your-host/api/v1/vehicles/total-mileage/query' \
+ -H 'Authorization: Bearer YOUR_32_CHARACTER_APP_KEY' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "vin": "LA9GG68L2PBAF4790",
+ "time": "2026-07-21 09:30:00",
+ "protocol": "GB32960"
+ }'
+
+ 车辆区间日里程
+ curl -X POST 'https://your-host/api/v1/vehicles/mileage/range/query' \
+ -H 'Authorization: Bearer YOUR_32_CHARACTER_APP_KEY' \
+ -H 'Content-Type: application/json' \
+ -d '{
+ "startDate": "2026-07-01",
+ "endDate": "2026-07-23",
+ "protocolPriority": ["GB32960", "MQTT"],
+ "pageSize": 5000
+ }'
+ 下一页保持原请求参数不变，并传入上一页 nextCursor；同一次分页查询的 snapshotId 保持不变。
+
+ 响应示例
+ 车辆单日里程
+ {
+ "code": "SUCCESS",
+ "message": "success",
+ "data": [{
+ "vin": "LNB00000000000001",
+ "plateNumber": "粤A12345",
+ "date": "2026-07-01",
+ "dailyMileageKm": 182.437,
+ "totalMileageKm": 12345.679,
+ "dataTime": "2026-07-01T23:58:45+08:00",
+ "updatedAt": "2026-07-02T05:10:00+08:00",
+ "sourceProtocol": "GB32960",
+ "status": "NORMAL"
+ }],
+ "traceId": "b7ff5582ab1a4e13bfb4f10943685599"
+}
+ 里程状态为 NORMAL 时，dailyMileageKm、totalMileageKm、dataTime 与 updatedAt 均有值；NO_DATA 时相关数据字段为 null，真实零里程仍为 NORMAL。
+ 车辆区间日里程响应
+ {
+ "code": "SUCCESS",
+ "message": "success",
+ "data": [{
+ "vin": "LNB00000000000001",
+ "plateNumber": "粤A12345",
+ "date": "2026-07-01",
+ "dailyMileageKm": 182.437,
+ "dataTime": "2026-07-01T23:58:45+08:00",
+ "updatedAt": "2026-07-02T05:10:00+08:00",
+ "status": "NORMAL"
+ }],
+ "snapshotId": "9f8a74efbf9846349ae5676f3a5c0de8",
+ "nextCursor": null,
+ "traceId": "4ccf63c4e51d4d4ab9107d931783a53e"
+}
+ 车辆单日用氢量
+ {
+ "code": "SUCCESS",
+ "message": "success",
+ "data": [{
+ "plateNumber": "粤A12345",
+ "date": "2026-07-01",
+ "hydrogenConsumptionKg": 12.315,
+ "status": "NORMAL"
+ }],
+ "traceId": "4ccf63c4e51d4d4ab9107d931783a53e"
+}
+
+ 指定时刻总里程响应
+ {
+ "code": "SUCCESS",
+ "message": "success",
+ "data": {
+ "vin": "LA9GG68L2PBAF4790",
+ "queryTime": "2026-07-21 09:30:00",
+ "totalMileageKm": 12345.678,
+ "protocol": "GB32960",
+ "protocolInput": "GB32960",
+ "mileageMeaning": "车辆仪表盘累计总里程（GB/T 32960整车数据累计里程）",
+ "recordTime": "2026-07-21 09:29:45",
+ "timeDifferenceSeconds": 15,
+ "selectionPolicy": "GB32960 > YUTONG_MQTT > JT808",
+ "status": "NORMAL"
+ },
+ "traceId": "95bddca78133474fa2bf56ecdf758e22"
+}
+
+ 状态与错误码
+
+ | HTTP | code | 说明 |
|---|
+
+ | 200 | SUCCESS | 查询成功；无统计数据的车辆以 NO_DATA 返回 |
+ | 400 | INVALID_REQUEST | 请求格式、车牌或数量不正确 |
+ | 400 | INVALID_DATE_FORMAT | 日期不是 yyyy-MM-dd |
+ | 400 | INVALID_DATETIME_FORMAT | 时间不是 yyyy-MM-dd HH:mm:ss |
+ | 401 | UNAUTHORIZED | appKey 不存在、停用或过期 |
+ | 403 | FORBIDDEN | Key 或车辆授权未覆盖查询自然日 |
+ | 500 | INTERNAL_ERROR | 服务内部异常 |
+
+
+
+
+
diff --git a/vehicle-data-platform/apps/api/internal/openplatform/assets/openapi.yaml b/vehicle-data-platform/apps/api/internal/openplatform/assets/openapi.yaml
new file mode 100644
index 00000000..da20ba74
--- /dev/null
+++ b/vehicle-data-platform/apps/api/internal/openplatform/assets/openapi.yaml
@@ -0,0 +1,743 @@
+openapi: 3.0.3
+info:
+ title: 车辆数据开放平台 API
+ version: 1.5.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: 查询车辆单日用氢量
+ description: plateNumbers 省略或传空数组时，返回该应用在查询自然日有效授权的全部车辆。
+ operationId: queryDailyHydrogenConsumption
+ security:
+ - AppKeyAuth: []
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/VehicleDailyQuery'
+ example:
+ 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: 查询车辆单日里程
+ description: |
+ plateNumbers 省略或传空数组时，返回该应用在查询自然日有效授权的全部车辆。
+ protocolPriority 传入时，逐车按数组顺序选择第一个有效协议，未列出的协议完全禁用且不会兜底；省略时保持平台默认选源行为。
+ NORMAL 结果同时包含日里程、累计总里程、实际来源协议、源数据时间和投影更新时间。
+ 当日无有效里程时，日里程补 0，累计总里程、来源协议、dataTime 和 updatedAt 沿用此前最近的有效统计；updatedAt 仍为上一统计周期的计算时间。
+ operationId: queryDailyMileage
+ security:
+ - AppKeyAuth: []
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MileageDailyQuery'
+ example:
+ date: '2026-07-01'
+ protocolPriority: [GB32960, MQTT, JT808]
+ 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/mileage/range/query:
+ post:
+ tags: [合作方数据接口]
+ summary: 分页查询车辆区间日里程
+ description: |
+ 最长支持 366 天。plateNumbers 省略或传空数组时固化应用在整个查询区间有效授权的全部车辆。
+ 首次请求返回 snapshotId 和 nextCursor；后续请求保持原参数并传回 nextCursor。
+ 快照仅固化授权车辆清单，逐页读取已建立索引的日统计投影，不扫描原始时序明细。
+ protocolPriority 对区间内每辆车、每个自然日独立生效；未列出的协议完全禁用。
+ 某日无有效里程时，dailyMileageKm 补 0，其余里程证据沿用此前最近的有效统计。
+ operationId: queryDailyMileageRange
+ security:
+ - AppKeyAuth: []
+ requestBody:
+ required: true
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MileageRangeQuery'
+ example:
+ startDate: '2026-07-01'
+ endDate: '2026-07-23'
+ plateNumbers: [沪A00001, 沪A00002]
+ protocolPriority: [JT808, GB32960, MQTT]
+ cursor: null
+ pageSize: 5000
+ responses:
+ '200':
+ description: 查询成功；每辆授权车辆每天均有一条 NORMAL 或 NO_DATA 记录
+ content:
+ application/json:
+ schema:
+ $ref: '#/components/schemas/MileageRangeQueryResponse'
+ '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: GB32960
+ 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: [date]
+ properties:
+ plateNumbers:
+ type: array
+ maxItems: 200
+ uniqueItems: true
+ items:
+ type: string
+ minLength: 1
+ maxLength: 32
+ description: 可选；指定时查询这些已授权车牌，省略或传空数组时查询该自然日有效授权的全部车辆
+ date:
+ type: string
+ format: date
+ description: 查询自然日，yyyy-MM-dd
+ MileageDailyQuery:
+ type: object
+ additionalProperties: false
+ required: [date]
+ properties:
+ plateNumbers:
+ type: array
+ maxItems: 200
+ uniqueItems: true
+ items:
+ type: string
+ minLength: 1
+ maxLength: 32
+ description: 可选；指定时查询这些已授权车牌，省略或传空数组时查询该自然日有效授权的全部车辆
+ date:
+ type: string
+ format: date
+ description: 查询自然日，yyyy-MM-dd
+ protocolPriority:
+ $ref: '#/components/schemas/ProtocolPriority'
+ MileageRangeQuery:
+ type: object
+ additionalProperties: false
+ required: [startDate, endDate]
+ properties:
+ startDate:
+ type: string
+ format: date
+ description: 区间开始自然日，Asia/Shanghai
+ endDate:
+ type: string
+ format: date
+ description: 区间结束自然日，含当日；与 startDate 最多相隔 365 天
+ plateNumbers:
+ type: array
+ maxItems: 5000
+ uniqueItems: true
+ items:
+ type: string
+ minLength: 1
+ maxLength: 32
+ description: 可选；省略或传空数组时查询整个区间均有效授权的全部车辆
+ protocolPriority:
+ $ref: '#/components/schemas/ProtocolPriority'
+ cursor:
+ type: string
+ nullable: true
+ description: 首次查询传 null 或省略；翻页时原样传入上一页 nextCursor
+ pageSize:
+ type: integer
+ minimum: 1
+ maximum: 5000
+ default: 5000
+ ProtocolPriority:
+ type: array
+ minItems: 1
+ maxItems: 3
+ uniqueItems: true
+ items:
+ type: string
+ enum: [GB32960, MQTT, JT808]
+ description: 可选；按数组顺序逐车逐日选择第一个有效协议。未列出的协议被禁用且不会作为兜底；省略字段时保持平台默认选源行为
+ 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: [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: [vin, plateNumber, date, dailyMileageKm, totalMileageKm, dataTime, updatedAt, sourceProtocol, status]
+ properties:
+ vin:
+ type: string
+ plateNumber:
+ type: string
+ date:
+ type: string
+ format: date
+ dailyMileageKm:
+ type: number
+ format: double
+ nullable: true
+ description: 单日里程，km；当日无记录但存在历史累计里程时为 0
+ totalMileageKm:
+ type: number
+ format: double
+ nullable: true
+ description: 当日所选协议最后有效累计总里程，km；status=NORMAL 时必定有值，NO_DATA 时为 null
+ dataTime:
+ type: string
+ format: date-time
+ nullable: true
+ description: 本次统计实际采用的最后一条车辆源数据时间；status=NO_DATA 时为 null
+ updatedAt:
+ type: string
+ format: date-time
+ nullable: true
+ description: 本行所依据统计周期的计算时间；前向填充时为上一统计周期计算时间，status=NO_DATA 时为 null
+ sourceProtocol:
+ type: string
+ enum: [GB32960, MQTT, JT808]
+ nullable: true
+ description: 本行实际选中的来源协议；status=NO_DATA 时为 null
+ status:
+ $ref: '#/components/schemas/DataStatus'
+ MileageRangeResult:
+ type: object
+ required: [vin, plateNumber, date, dailyMileageKm, totalMileageKm, dataTime, updatedAt, sourceProtocol, status]
+ properties:
+ vin:
+ type: string
+ plateNumber:
+ type: string
+ date:
+ type: string
+ format: date
+ dailyMileageKm:
+ type: number
+ format: double
+ nullable: true
+ minimum: 0
+ description: 当日无记录但存在历史累计里程时为 0
+ totalMileageKm:
+ type: number
+ format: double
+ nullable: true
+ minimum: 0
+ description: 当日所选协议累计总里程；缺日时沿用此前最近有效值
+ dataTime:
+ type: string
+ format: date-time
+ nullable: true
+ updatedAt:
+ type: string
+ format: date-time
+ nullable: true
+ description: 本行所依据统计周期的计算时间；缺日补齐时为上一统计周期计算时间
+ sourceProtocol:
+ type: string
+ enum: [GB32960, MQTT, JT808]
+ nullable: true
+ description: 本行实际选中的来源协议；status=NO_DATA 时为 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'
+ MileageRangeQueryResponse:
+ type: object
+ required: [code, message, data, snapshotId, nextCursor, traceId]
+ properties:
+ code:
+ type: string
+ enum: [SUCCESS]
+ message:
+ type: string
+ example: success
+ data:
+ type: array
+ items:
+ $ref: '#/components/schemas/MileageRangeResult'
+ snapshotId:
+ type: string
+ description: 同一次分页查询保持不变的授权车辆快照标识
+ nextCursor:
+ type: string
+ nullable: true
+ description: 下一页游标；最后一页为 null
+ traceId:
+ type: string
+ 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
+ - 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
diff --git a/vehicle-data-platform/apps/api/internal/openplatform/assets/swagger-init.js b/vehicle-data-platform/apps/api/internal/openplatform/assets/swagger-init.js
new file mode 100644
index 00000000..6ccccca3
--- /dev/null
+++ b/vehicle-data-platform/apps/api/internal/openplatform/assets/swagger-init.js
@@ -0,0 +1,17 @@
+window.addEventListener("load", function () {
+ window.ui = SwaggerUIBundle({
+ url: "/open-api/openapi.yaml",
+ dom_id: "#swagger-ui",
+ deepLinking: true,
+ displayRequestDuration: true,
+ filter: true,
+ persistAuthorization: false,
+ tryItOutEnabled: false,
+ validatorUrl: null,
+ presets: [
+ SwaggerUIBundle.presets.apis,
+ SwaggerUIStandalonePreset
+ ],
+ layout: "StandaloneLayout"
+ });
+});
diff --git a/vehicle-data-platform/apps/api/internal/openplatform/assets/swagger.html b/vehicle-data-platform/apps/api/internal/openplatform/assets/swagger.html
new file mode 100644
index 00000000..612ae0d7
--- /dev/null
+++ b/vehicle-data-platform/apps/api/internal/openplatform/assets/swagger.html
@@ -0,0 +1,15 @@
+
+
+
+