ln-bi/docs/oneos-mileage-reconciliation-investigation-2026-09-16.md

# OneOS 日里程与累计里程差额排查报告

- 排查日期：2026-09-16（Asia/Shanghai）
- 涉及数据日期：2026-09-11 至 2026-09-15
- 接收方：OneOS 开放平台及里程计算服务维护人员
- 状态：已复现；待上游核查计算基准、跨日缺报及协议选源逻辑

## 1. 问题概述

BI 用户发现：昨日累计总里程减去前日累计总里程，不等于昨日的区间里程；继续向前检查，多日均存在差额。

本次在相同车辆范围、相同协议优先级下复现，并绕过 BI 直接请求 OneOS 单日接口核对异常车辆。上游返回本身就存在相邻日期累计差与日里程不一致的情况，不能仅用 BI 显示取整解释。

已确认的现象：

1. 某查询日返回的累计里程对应更早日期的报文；后续更新后的累计差跨越多天，与当日日里程不一致。
2. 同一车辆相邻日期切换 MQTT / GB32960，累计读数发生跳变，且切换后可能选中很早的读数。

尚未确认：日里程的内部计算公式、有效数据判定、跨日补算规则及异常过滤规则。本文不将差额直接认定为漏算里程，也不将累计差直接认定为真实日行驶里程。

## 2. 查询范围与 BI 计算口径

本次 BI 查询未附加客户、部门、车牌或里程筛选条件，每天返回 916 台车辆。

```text
GET /api/mileage/monitoring
    ?startDate=2026-09-15
    &endDate=2026-09-15
    &sourcePriority=instrument
    &limit=2000
```

`instrument` 对应上游协议优先级：

```json
["GB32960", "MQTT"]
```

BI 当前计算方式：

| 指标 | 计算方式 |
| --- | --- |
| 单车累计里程 | OneOS `totalMileageKm`，不以日里程反推 |
| 单车单日里程 | OneOS `dailyMileageKm` |
| 单车区间里程 | 区间内每日 `dailyMileageKm` 求和 |
| 累计总里程 | 查询范围内车辆的累计里程求和；空值按 0 参与汇总 |
| 当日总里程 | 查询范围内车辆的日里程求和；汇总接口对结果取整 |

以下对账表使用逐车日里程原始数值求和，保留三位小数，避免整数显示带来的误差。

## 3. 汇总对账结果

单位：km。定义 `差额 = 当天累计总里程 - 前一天累计总里程 - 当天日里程合计`。

| 日期 | 累计总里程 | 相邻日累计差 | 当日日里程合计 | 差额 |
| --- | ---: | ---: | ---: | ---: |
| 2026-09-11 | 48,448,486.800 | — | 98,182.208 | — |
| 2026-09-12 | 48,546,128.300 | 97,641.500 | 97,321.774 | +319.726 |
| 2026-09-13 | 48,619,784.800 | 73,656.500 | 82,322.847 | −8,666.347 |
| 2026-09-14 | 48,721,190.600 | 101,405.800 | 94,242.687 | +7,163.113 |
| 2026-09-15 | 48,824,917.800 | 103,727.200 | 103,554.604 | +172.596 |

按车牌匹配相邻日期，差额来源分解如下：

| 日期 | 两日累计非空且协议相同的车辆数 / 净差额 | 两日累计非空且协议变化的车辆数 / 净差额 | 至少一日累计为空的车辆数 / 净差额 |
| --- | --- | --- | --- |
| 09-12 | 759 / +319.726 | 0 / 0 | 157 / 0 |
| 09-13 | 758 / +674.653 | 1 / −9,341.000 | 157 / 0 |
| 09-14 | 759 / +7,163.113 | 0 / 0 | 157 / 0 |
| 09-15 | 759 / +172.596 | 0 / 0 | 157 / 0 |

本次样本中，空累计值组对差额净贡献为 0；同协议数据也存在明显不一致，不能只修复协议切换问题。

## 4. 异常样本一：累计读数跨日，日里程未与累计差对齐

以下记录已通过 OneOS 单日接口直接复核，响应均为 HTTP 200、`code=SUCCESS`，记录状态均为 `NORMAL`。

### 4.1 粤AGQ8377：9 月 15 日差额 +70.2 km

| 查询日期 | sourceProtocol | totalMileageKm | dailyMileageKm | dataTime（+08:00） |
| --- | --- | ---: | ---: | --- |
| 2026-09-13 | GB32960 | 14,366.0 | 6.1 | 2026-09-13 07:17:27 |
| 2026-09-14 | GB32960 | 14,366.0 | 0 | 2026-09-13 07:17:27 |
| 2026-09-15 | GB32960 | 14,467.4 | 31.2 | 2026-09-15 20:57:04 |

```text
累计差 = 14,467.4 - 14,366.0 = 101.4
差额   = 101.4 - 31.2 = 70.2 km
```

查询 9 月 14 日时，累计读数仍来自 9 月 13 日。请核查 9 月 15 日日里程的起点读数及其时间，并解释 70.2 km 在日统计中的归属或过滤原因。

### 4.2 粤AGR6839：9 月 15 日差额 +38.0 km

| 查询日期 | sourceProtocol | totalMileageKm | dailyMileageKm | dataTime（+08:00） |
| --- | --- | ---: | ---: | --- |
| 2026-09-14 | GB32960 | 45,122.2 | 0 | 2026-09-11 11:10:53 |
| 2026-09-15 | GB32960 | 45,162.8 | 2.6 | 2026-09-15 10:34:02 |

累计差为 40.6 km，日里程为 2.6 km，差额为 38.0 km。请核查跨多日无新读数后的统计基准及补算策略。

### 4.3 粤AGP3609：9 月 14 日差额 +808.7 km

| 查询日期 | sourceProtocol | totalMileageKm | dailyMileageKm | dataTime（+08:00） |
| --- | --- | ---: | ---: | --- |
| 2026-09-12 | GB32960 | 48,102.9 | 1,293.6 | 2026-09-12 15:08:47 |
| 2026-09-13 | GB32960 | 48,102.9 | 0 | 2026-09-12 15:08:47 |
| 2026-09-14 | GB32960 | 48,981.7 | 70.1 | 2026-09-14 23:59:51 |
| 2026-09-15 | GB32960 | 50,349.1 | 1,367.4 | 2026-09-15 23:59:50 |

9 月 14 日累计差为 878.8 km，日里程为 70.1 km，差额为 808.7 km；9 月 15 日累计差与日里程则同为 1,367.4 km。该车适合对比正常日期与跨日缺报日期的计算路径。

## 5. 异常样本二：协议切换导致累计值倒退

车辆：沪A60591F。以下记录也已直接请求上游复核，均返回 `NORMAL`。

| 查询日期 | sourceProtocol | totalMileageKm | dailyMileageKm | dataTime（+08:00） |
| --- | --- | ---: | ---: | --- |
| 2026-09-12 | MQTT | 51,416 | 0 | 2026-09-12 04:53:49 |
| 2026-09-13 | GB32960 | 42,075 | 0 | 2026-07-16 23:59:59 |
| 2026-09-14 | GB32960 | 42,075 | 0 | 2026-07-16 23:59:59 |
| 2026-09-15 | GB32960 | 42,075 | 0 | 2026-07-16 23:59:59 |

```text
9 月 13 日累计差 = 42,075 - 51,416 = -9,341 km
9 月 13 日日里程 = 0 km
```

该车单独贡献 −9,341 km，叠加其他同协议车辆 +674.653 km 的差额后，形成当日全量净差额 −8,666.347 km。

请重点核查：

1. 同一请求优先级下，9 月 12 日采用 MQTT，9 月 13 日为何改用 7 月 16 日的 GB32960 读数？
2. 协议“有效数据”的定义是否包含数据时间、新鲜度和查询日期边界？
3. `NORMAL` 是否仅表示读数数值有效，而不表示查询当日存在有效报文？
4. 两协议累计读数是否具有同一基准？切换时是否应提供不连续标识？
5. 请核查该车协议记录对应的 VIN、设备及绑定历史，排除历史绑定变化造成的读数混用。

## 6. 上游直接复现方法

接口：`POST https://open.d.lnoneos.com/api/v1/vehicles/mileage/query`。

使用已授权的 API Key，通过环境变量注入，不将真实凭证写入报告或日志。

```bash
curl --fail-with-body --silent --show-error \
  'https://open.d.lnoneos.com/api/v1/vehicles/mileage/query' \
  -H "Authorization: Bearer ${ONEOS_MILEAGE_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{
    "date": "2026-09-15",
    "plateNumbers": ["粤AGQ8377", "粤AGR6839", "粤AGP3609", "沪A60591F"],
    "protocolPriority": ["GB32960", "MQTT"]
  }'
```

依次将 `date` 替换为 `2026-09-12`、`2026-09-13`、`2026-09-14`、`2026-09-15`。

逐车对比字段：`date`、`plateNumber`、`vin`、`status`、`dailyMileageKm`、`totalMileageKm`、`sourceProtocol`、`dataTime`、`calculatedAt`、`updatedAt`。

本次直接复核保留了报告中的关键字段，未记录响应 `traceId`；上游重放时请保存完整响应及 `traceId`。历史数据如已重算或补报，当前返回值可能与本报告不同，请同时提供重算时间和修改前后结果。

## 7. 请上游提供的定位结果

### 7.1 明确字段契约

- `dailyMileageKm`：是当天首尾读数差、前日末值到当日末值的差，还是逐报文有效增量之和？是否丢弃跨日增量、异常跳变或负增量？
- `totalMileageKm`：是查询日最后读数、截至查询日最近读数，还是其他快照？无当日报文时是否延用历史值？
- `dataTime`：具体对应累计读数、日里程终点还是其他时间？
- 两个里程字段是否保证来自同一协议、同一设备、同一计算快照？
- 自然日边界是否统一为 Asia/Shanghai 的 00:00:00 至次日 00:00:00？
- 是否承诺相邻日累计差等于日里程；若不承诺，请明确哪些场景不成立及差额如何解释。

### 7.2 提供样本计算明细

对上述四辆车，请返回：

1. 各协议参与选源的候选记录、时间及未选中原因。
2. 日里程计算起止报文的时间、累计读数、设备/VIN 标识。
3. 有效增量、被过滤增量及过滤原因。
4. 缺报、补报、跨日增量归属，以及历史重算记录。
5. 对每个差额给出可核对的数值分解，不能只解释为“统计口径不同”。

## 8. 修复或口径确认后的验收建议

1. 使用同一车辆集合和协议配置，重放 9 月 11 至 15 日数据，逐车核对后再核对汇总。
2. 对连续上报且同协议的正常车辆，若契约约定可对账，应满足累计差与日里程一致；容差按上游实际数值精度明确。
3. 对跨日缺报车辆，明确跨日增量是否补算、归属哪天，并能解释全部差额。
4. 对协议切换车辆，避免将不同基准的累计值视为连续可减的序列；提供明确的协议切换和不连续信息。
5. 对陈旧读数，区分“历史累计值仍有效”和“当日有有效报文”，避免用单一 `NORMAL` 混淆两者。
6. 验证单日接口与区间接口对同一车、同一天的日里程、累计值和选源结果一致。
7. 如修复涉及历史重算，提供重算范围及完成时间；BI 历史接口缓存最长 6 小时，应在刷新后复核。

## 9. 本次排查边界

- 已检查 BI 里程映射、日/区间聚合和汇总逻辑，并对异常样本直接调用上游单日接口复核。
- 尚未访问 OneOS 原始报文、计算服务源码或内部存储，不能确定其内部算法根因。
- 本次未修改业务代码、未变更里程口径、未触发历史数据重算。