156 lines
5.4 KiB
Markdown
156 lines
5.4 KiB
Markdown
# OneOS 车辆里程接口需求
|
||
|
||
当前协议选源联调阻塞项和 OneOS 修改清单见：
|
||
[OneOS 车辆里程数据源协议改造清单](./oneos-mileage-source-protocol-gaps.md)。
|
||
|
||
## 开发原则
|
||
|
||
1. 新增区间查询接口；车辆里程汇总能力在现有
|
||
`POST /api/v1/vehicles/mileage/query` 上兼容扩展。
|
||
2. 现有接口的路径、鉴权、已有请求参数、已有响应字段、字段语义和默认行为必须完全兼容。
|
||
3. 公网 `https://open.d.lnoneos.com` 与 ECS 内网 `http://172.17.111.55:20310` 使用相同路径、鉴权和数据口径。
|
||
4. 鉴权继续使用 `Authorization: Bearer APP_KEY`。
|
||
5. 日期采用 `YYYY-MM-DD`，时区统一为 `Asia/Shanghai`，里程单位统一为 km。
|
||
|
||
## 1. 车辆区间日里程批量查询
|
||
|
||
```http
|
||
POST /api/v1/vehicles/mileage/range/query
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"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`。
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"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. 兼容扩展现有单日车辆里程接口
|
||
|
||
用于一次获取指定日期每辆车的日里程、累计里程和数据时间。
|
||
|
||
```http
|
||
POST /api/v1/vehicles/mileage/query
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"date": "2026-07-23",
|
||
"plateNumbers": ["沪A00001", "沪A00002"],
|
||
"protocolPriority": ["GB32960", "MQTT", "JT808"]
|
||
}
|
||
```
|
||
|
||
规则：
|
||
|
||
- `date` 和 `plateNumbers` 沿用现有接口规则；
|
||
- `protocolPriority` 的枚举、顺序和禁用规则与区间接口完全一致；
|
||
- `plateNumbers` 省略时返回授权范围内全部车辆；
|
||
- 接口默认在现有车辆结果中返回 `totalMileageKm`、`dataTime` 和 `updatedAt`；
|
||
- 只增加响应字段，不删除或修改任何现有字段及其语义；
|
||
- 历史日期返回该自然日最终有效结果；
|
||
- 查询当天返回当前最新结果；
|
||
- `dataTime` 必须是本次统计实际采用的最后一条车辆源数据时间，不能使用接口请求时间或响应时间代替；
|
||
- 无数据时相关里程字段返回 `null`，不能使用 0 代替；
|
||
- 接口应支持当前应用授权范围内的全部车辆。
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"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 时，授权范围和查询结果保持一致；
|
||
- 区间接口及现有接口的汇总扩展不得影响现有调用方和默认行为。
|
||
|
||
## 验收
|
||
|
||
1. 现有 `/api/v1/vehicles/mileage/query` 请求方式保持不变，回归测试全部通过。
|
||
2. 区间接口不传车牌可完整查询全部授权车辆，分页无重复、无漏行。
|
||
3. 现有接口不传车牌时，默认返回全部授权车辆的日里程、累计里程和数据时间。
|
||
4. 正确区分无数据与真实零里程。
|
||
5. `dataTime` 能反映每辆车实际数据的新鲜度。
|
||
6. 四种 `protocolPriority` 组合均能按顺序选源，且响应中的
|
||
`sourceProtocol` 与实际采用协议一致。
|
||
7. 禁用某类协议后，响应不得回退到该协议。
|