104 lines
6.5 KiB
Markdown
104 lines
6.5 KiB
Markdown
# OneOS 里程接口性能优化反馈
|
||
|
||
后续进展：上游已提供区间汇总接口，本地 BI 已接入并完成对账，见 [接入与验证记录](mileage-summary-integration-2026-10-27.md)。下文保留最初反馈背景。
|
||
|
||
日期：2026-10-27。本文供 BI 与 OneOS 团队对接，建议项尚未代表上游已实现或已承诺。
|
||
|
||
## 当前问题与业务影响
|
||
|
||
BI 查询一段日期的车辆里程时，先获取全部车辆逐日明细，完成后才能汇总、排序及展示首页。长区间查询的主要等待发生在 OneOS 游标分页：首次进入或主动刷新一个月的数据仍需约 10 秒。
|
||
|
||
相关现有接口：
|
||
|
||
- `POST /api/v1/vehicles/mileage/range/query`：日期范围、可选车牌、来源优先级、游标分页。
|
||
- `POST /api/v1/vehicles/mileage/query`：单日里程及累计里程。
|
||
|
||
## 可复现样本
|
||
|
||
请求条件如下，不包含任何访问凭据：
|
||
|
||
```json
|
||
{
|
||
"startDate": "2026-10-01",
|
||
"endDate": "2026-10-26",
|
||
"pageSize": 5000,
|
||
"protocolPriority": ["GB32960", "MQTT"]
|
||
}
|
||
```
|
||
|
||
后续请求携带上一页返回的 `nextCursor` 作为 `cursor`；BI 检查返回 `snapshotId` 的一致性。
|
||
|
||
在当前应用授权范围内，共返回 26,624 条逐日记录，需 6 次串行分页请求。2026-10-27 的一组测量结果如下（客户端计时至 JSON 读取完毕）：
|
||
|
||
| 页 | 返回条数 | 耗时 |
|
||
| --- | ---: | ---: |
|
||
| 1 | 5,000 | 2,283 ms |
|
||
| 2 | 5,000 | 2,114 ms |
|
||
| 3 | 5,000 | 1,775 ms |
|
||
| 4 | 5,000 | 1,762 ms |
|
||
| 5 | 5,000 | 1,682 ms |
|
||
| 6 | 1,624 | 1,466 ms |
|
||
|
||
区间分页合计约 11.08 秒，BI 查询函数整体约 11.12 秒。同一进程重复查询约 9.51 秒，仍需请求 6 页。另一组 7 天查询约 3.10 秒，重复约 2.99 秒。
|
||
|
||
车辆归属 SQL 约 58–168 ms，与上游调用并行；合并后 BI 范围为 765 辆车，上游返回范围大于 BI 的有效车辆集合。
|
||
|
||
以上是单次本地实测，包含网络与 JSON 处理，不是服务端执行时间或 P95。尚无 OneOS 内部 trace，不能据此断言某条 SQL 缺索引或每个游标页都重复计算。
|
||
|
||
## BI 已做的优化
|
||
|
||
- 日期、筛选和搜索修改后，点击查询才发请求。
|
||
- 相同日期范围与来源优先级的 OneOS 结果在本地服务进程中复用 5 分钟，最多保留 4 组。
|
||
- 分页、排序、筛选和导出复用 OneOS 数据；主动刷新绕过该缓存，并重新获取相关单日数据。
|
||
- 车辆归属与考核关系仍每次读取，权限检查、筛选和汇总仍按当前用户执行，不缓存用户权限结果。
|
||
|
||
这解决重复查询，不能消除首次长区间查询的 6 次串行等待。上游优化的目标是首次查询、主动刷新及跨应用复用，而不是让 BI 延长缓存来掩盖延迟。
|
||
|
||
## 建议优先级
|
||
|
||
### P0：诊断每页耗时，并复用已生成快照
|
||
|
||
请提供一次上述查询的 `traceId` 与各页阶段耗时，至少区分：数据库读取、里程计算/协议选择、快照生成或读取、序列化、排队等待。
|
||
|
||
请确认：
|
||
|
||
1. 后续游标页是否只读取已有快照，还是重新扫描、计算整个区间？若存在重复计算，优先改为计算一次后分页读取。
|
||
2. 相同应用授权范围、日期范围、协议优先级和车牌集合，能否在短期内复用已完成快照？
|
||
3. 当前 `snapshotId` 的有效期及数据更新时间是什么？能否通过新增参数重用指定快照，而不是重新创建？
|
||
|
||
快照复用必须包含应用权限范围和有序协议优先级，车牌集合需规范化；不能仅按起止日期跨应用共享授权后的结果。需要返回有效期/数据时间，明确实时日更新、历史补数与主动刷新的失效规则。
|
||
|
||
### P1：提供按车辆的区间聚合，减少传输与调用次数
|
||
|
||
建议新增“区间汇总”能力（接口名称由 OneOS 确定，非现有协议）：每辆车返回一条汇总，而非默认返回每辆车每天一条完整记录。BI 列表所需字段包括：
|
||
|
||
| 字段能力 | 用途及口径 |
|
||
| --- | --- |
|
||
| 车牌、VIN | 与 BI 车辆信息关联 |
|
||
| 区间有效日里程合计 | 不能用末日累计里程减首日累计里程替代 |
|
||
| 有效天数、缺失天数、异常状态 | 区分真实零里程和整段无数据 |
|
||
| 结束日累计里程 | 当前 BI 为它额外调用单日接口 |
|
||
| 区间开始日前一天的日里程 | 当前对比口径，若可一并提供可再减少一次调用 |
|
||
| 实际来源/混合来源、数据时间 | 保持来源优先级与数据质量可解释性 |
|
||
| 快照标识、计算/生成时间 | 后续查询与数据时间展示 |
|
||
|
||
这能将主列表传输量从约“车辆数 × 天数”降至“车辆数”。日报趋势/单车逐日明细按需读取，或通过字段投影仅返回必要的逐日值。
|
||
|
||
BI 的每日趋势必须遵循当前筛选与权限范围：不能直接采用全应用车辆的日合计。建议日趋势聚合支持同一快照和明确车牌集合，或在汇总结果中可选返回每车的精简逐日值，再由 BI 汇总。
|
||
|
||
### P2：减少单页耗时并提供稳定的调用预算
|
||
|
||
- 基于 trace 和实际执行计划，优化日期范围、车牌集合、来源优先级条件的读取路径；目前数据不足以指定具体索引。
|
||
- 核实响应压缩、连接复用及明细字段投影是否生效。调大 `pageSize` 可作为对照实验，但应同时评估响应大小、内存与单页超时；不能只靠加大页数掩盖重复计算。
|
||
- 目前 BI 每页超时 20 秒、最多尝试 3 次，退避 1 秒与 2 秒。单页连续超时可导致约 63 秒等待，这是配置推导，非本次实测异常。建议约定整个查询的期限、可重试错误码和可恢复快照，避免失效后从第一页重做。
|
||
|
||
## 建议验收方式
|
||
|
||
双方使用相同应用权限、同一车牌集合及协议优先级，对 1 / 7 / 31 天、冷查询与快照复用分别测量。记录首屏耗时、完整结果耗时、请求数、响应字节数和上游阶段耗时；有足够重复样本后再报告 P50/P95。
|
||
|
||
可讨论的目标：约 1,000 辆 × 31 天汇总首次完整返回在 3 秒内，快照复用在 300 ms 内。以上是待双方评估确认的目标，不是当前测量结果或已承诺 SLA。
|
||
|
||
结果正确性需与现有接口逐车核对：来源优先级、缺失值与零值、异常里程、累计里程、上海自然日起止边界、跨月区间及权限范围。缓存命中不能改变这些口径。
|
||
|
||
请上游反馈：阶段 trace、快照当前实现与复用能力、聚合接口可行性，以及可交付的第一阶段范围与排期。
|