ln-bi/docs/oneos-mileage-api-requirements.md

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. 车辆区间日里程批量查询

POST /api/v1/vehicles/mileage/range/query

请求：

{
  "startDate": "2026-07-01",
  "endDate": "2026-07-23",
  "plateNumbers": ["沪A00001", "沪A00002"],
  "cursor": null,
  "pageSize": 5000
}

规则：

• startDate、endDate 必填，最长支持 366 天；
• plateNumbers 可省略，省略时返回授权范围内全部车辆；
• 数据量过大时使用 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,
      "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"]
}

规则：

• date 和 plateNumbers 沿用现有接口规则；
• 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,
      "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 格式；
• 每个响应返回 traceId；
• 接口返回值保留原始精度；
• 负里程不得作为正常数据返回；
• 公网和 ECS 内网使用同一 AppKey 时，授权范围和查询结果保持一致；
• 区间接口及现有接口的汇总扩展不得影响现有调用方和默认行为。

验收

1. 现有 /api/v1/vehicles/mileage/query 请求方式保持不变，回归测试全部通过。
2. 区间接口不传车牌可完整查询全部授权车辆，分页无重复、无漏行。
3. 现有接口不传车牌时，默认返回全部授权车辆的日里程、累计里程和数据时间。
4. 正确区分无数据与真实零里程。
5. dataTime 能反映每辆车实际数据的新鲜度。