5.4 KiB
5.4 KiB
OneOS 车辆里程接口需求
当前协议选源联调阻塞项和 OneOS 修改清单见： OneOS 车辆里程数据源协议改造清单。
开发原则
- 新增区间查询接口；车辆里程汇总能力在现有
POST /api/v1/vehicles/mileage/query上兼容扩展。 - 现有接口的路径、鉴权、已有请求参数、已有响应字段、字段语义和默认行为必须完全兼容。
- 公网
https://open.d.lnoneos.com与 ECS 内网http://172.17.111.55:20310使用相同路径、鉴权和数据口径。 - 鉴权继续使用
Authorization: Bearer APP_KEY。 - 日期采用
YYYY-MM-DD，时区统一为Asia/Shanghai，里程单位统一为 km。
1. 车辆区间日里程批量查询
POST /api/v1/vehicles/mileage/range/query
请求：
{
"startDate": "2026-07-01",
"endDate": "2026-07-23",
"plateNumbers": ["沪A00001", "沪A00002"],
"protocolPriority": ["GB32960", "MQTT", "JT808"],
"cursor": null,
"pageSize": 5000
}
规则：
startDate、endDate必填，最长支持 366 天；plateNumbers可省略，省略时返回授权范围内全部车辆；protocolPriority可省略；提供时只允许GB32960、MQTT、JT808， 数组顺序表示逐车逐日的数据源优先级，未列出的协议视为禁用；- BI 只会使用以下四种组合：
- 仪表数据优先：
["GB32960", "MQTT", "JT808"]； - GPS 数据优先：
["JT808", "GB32960", "MQTT"]； - 仅仪表数据：
["GB32960", "MQTT"]； - 仅 GPS 数据：
["JT808"]；
- 仪表数据优先：
- BI 页面默认只启用“仪表数据”，即默认发送
["GB32960", "MQTT"]；用户主动启用 GPS 后才发送包含JT808的组合； - 仪表数据内部优先级固定为
GB32960 > MQTT，不提供反向切换； - 数据量过大时使用
cursor分页，同一次查询使用相同snapshotId； - 每辆车每天返回一条记录；
- 无数据返回
status: "NO_DATA"且dailyMileageKm: null，真实零里程返回status: "NORMAL"且dailyMileageKm: 0。
响应：
{
"code": "SUCCESS",
"message": "success",
"data": [
{
"vin": "LMRK...",
"plateNumber": "沪A00001",
"date": "2026-07-01",
"dailyMileageKm": 182.437,
"sourceProtocol": "GB32960",
"dataTime": "2026-07-01T23:58:45+08:00",
"updatedAt": "2026-07-02T05:10:00+08:00",
"status": "NORMAL"
}
],
"snapshotId": "mileage-20260723-001",
"nextCursor": null,
"traceId": "..."
}
2. 兼容扩展现有单日车辆里程接口
用于一次获取指定日期每辆车的日里程、累计里程和数据时间。
POST /api/v1/vehicles/mileage/query
请求：
{
"date": "2026-07-23",
"plateNumbers": ["沪A00001", "沪A00002"],
"protocolPriority": ["GB32960", "MQTT", "JT808"]
}
规则：
date和plateNumbers沿用现有接口规则；protocolPriority的枚举、顺序和禁用规则与区间接口完全一致；plateNumbers省略时返回授权范围内全部车辆；- 接口默认在现有车辆结果中返回
totalMileageKm、dataTime和updatedAt； - 只增加响应字段，不删除或修改任何现有字段及其语义；
- 历史日期返回该自然日最终有效结果；
- 查询当天返回当前最新结果；
dataTime必须是本次统计实际采用的最后一条车辆源数据时间，不能使用接口请求时间或响应时间代替；- 无数据时相关里程字段返回
null，不能使用 0 代替； - 接口应支持当前应用授权范围内的全部车辆。
响应：
{
"code": "SUCCESS",
"message": "success",
"data": [
{
"vin": "LMRK...",
"plateNumber": "沪A00001",
"date": "2026-07-23",
"dailyMileageKm": 182.437,
"totalMileageKm": 12345.678,
"sourceProtocol": "GB32960",
"dataTime": "2026-07-23T10:35:42+08:00",
"updatedAt": "2026-07-23T10:35:46+08:00",
"status": "NORMAL"
}
],
"traceId": "..."
}
现有响应外层结构及已有字段保持不变，调用方无需增加任何请求参数。
通用要求
dataTime、updatedAt使用带+08:00的 ISO 8601 格式；sourceProtocol必须返回本条结果实际采用的协议：GB32960、MQTT或JT808；无数据时返回null；- OneOS 必须按
protocolPriority选择第一份有效数据，不得返回已禁用协议的数据； sourceProtocol=GB32960/MQTT在 BI 显示为“仪表数据”，sourceProtocol=JT808显示为“GPS数据”；- 每个响应返回
traceId； - 接口返回值保留原始精度；
- 负里程不得作为正常数据返回；
- 公网和 ECS 内网使用同一 AppKey 时，授权范围和查询结果保持一致；
- 区间接口及现有接口的汇总扩展不得影响现有调用方和默认行为。
验收
- 现有
/api/v1/vehicles/mileage/query请求方式保持不变，回归测试全部通过。 - 区间接口不传车牌可完整查询全部授权车辆，分页无重复、无漏行。
- 现有接口不传车牌时，默认返回全部授权车辆的日里程、累计里程和数据时间。
- 正确区分无数据与真实零里程。
dataTime能反映每辆车实际数据的新鲜度。- 四种
protocolPriority组合均能按顺序选源，且响应中的sourceProtocol与实际采用协议一致。 - 禁用某类协议后，响应不得回退到该协议。