feat: integrate OneOS mileage APIs and release v1.1.10

2026-07-23 12:19:11 +08:00
parent 4d523cbce0
commit 3f29bed5fa
14 changed files with 863 additions and 325 deletions
--- a/docs/oneos-mileage-api-requirements.md
+++ b/docs/oneos-mileage-api-requirements.md
@@ -0,0 +1,129 @@
+# 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"],
+  "cursor": null,
+  "pageSize": 5000
+}
+```
+
+规则：
+
+- `startDate`、`endDate` 必填，最长支持 366 天；
+- `plateNumbers` 可省略，省略时返回授权范围内全部车辆；
+- 数据量过大时使用 `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,
+      "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"]
+}
+```
+
+规则：
+
+- `date` 和 `plateNumbers` 沿用现有接口规则；
+- `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,
+      "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` 能反映每辆车实际数据的新鲜度。