# OneOS 车辆里程接口需求

## 开发原则

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"]`；
- 仪表数据内部优先级固定为 `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. 禁用某类协议后，响应不得回退到该协议。