# 里程监控结果复用（2026-10-27）

本文为第二阶段历史记录。当前主列表已改用上游区间汇总；最新行为、权限趋势处理及实测见 [区间汇总接入与验证](mileage-summary-integration-2026-10-27.md)。下文的明细缓存和首次耗时描述不代表当前实现。

## 行为

同一服务进程内，按规范化起止日期和有序协议优先级缓存 OneOS 区间明细、结束日数据及对比日数据。有效期为成功获取后 5 分钟，最多保留 4 组，新增超限时淘汰最早写入项；相同在途查询合并。只在成功完成后写入缓存，失败可重试。

分页、排序、筛选、全屏和导出复用这组上游数据。车辆归属及考核关系每次从数据库读取，然后重新合并并按当前用户权限过滤。用户身份不需要进入原始里程缓存键；授权结果绝不跨用户缓存。车辆改派经理、变更部门后，下一次请求读取最新归属。

区间日趋势始终根据已授权且符合筛选条件的车辆重新计算，修正此前权限过滤后仍可能使用全量日趋势合计的问题。

点击「查询」可命中缓存；点击普通视图或全屏的刷新按钮发送 `refresh=1`，跳过已完成缓存，包括历史单日缓存。已有相同在途请求仍可共享。刷新失败时不回退旧的区间缓存。日期和搜索仍需确认后请求。

## 接口可观察性

`GET /api/mileage/monitoring?startDate=...&endDate=...`：

- 响应头 `X-Mileage-Cache`：`miss` / `hit` / `shared` / `refresh`。
- 响应字段 `queriedAt`：这组 OneOS 数据成功获取的时间。缓存命中时保持不变；前端使用它展示获取时间，避免将缓存读取误显示为重新采集。
- `refresh=1`：显式刷新。普通分页、排序和导出不附带该参数。

旧的 `date=` 单日兼容分支和不带日期的后台缓存分支保持原有机制；当前监控前端使用起止日期参数，走本次新增的复用路径。

## 限制与取舍

这是 5 分钟的进程内数据复用，不是持久化会话快照。过期、淘汰、进程重启或请求落到另一实例时会重新取数；跨过这些边界时数据可能变化，不能保证整场会话固定在同一快照。前端可随时主动刷新。没有新增 Redis、数据库表或后台清理任务。

缓存仅减少 OneOS 的重复拉取。数据库读取、权限过滤、汇总和排序仍按请求执行，保证归属及时变化；首次长区间仍受上游串行分页限制。导出接口耗时不包含浏览器生成 XLSX 文件的时间。

## 本地真实接口实测

条件：2026-10-01 至 2026-10-26，仪表来源，765 辆 BI 车辆；同一进程连续请求，包含 HTTP 传输和 JSON 读取。

| 操作 | 耗时 | 缓存状态 |
| --- | ---: | --- |
| 首次查询 50 条 | 10,723 ms | miss |
| 第 2 页 | 92 ms | hit |
| 改为升序 | 48 ms | hit |
| 导出接口返回全部 765 条 | 64 ms | hit |
| 主动刷新 | 9,869 ms | refresh |
| 刷新后再次导出 | 96 ms | hit |

前 4 次响应使用相同的 `queriedAt`；主动刷新更新该时间，再次导出复用新的结果。以上为单次样本，不是 P95。命中路径仍包含最新车辆信息 SQL 和重新聚合；首次/主动刷新仍受上游耗时影响。

## 验证

TypeScript 检查、30 项里程相关测试及生产构建通过；构建仍有已有的大资源包提示。

- 查询缓存单测覆盖命中、5 分钟过期、容量淘汰、来源顺序隔离、在途合并、刷新和失败重试。
- 路由集成测试以模拟 OneOS/SQL 验证：首页拉取 3 次上游数据，后续分页、排序、导出、筛选及权限变更均不新增上游请求；刷新再新增 3 次。归属变更后权限立即按新的数据库结果生效。
- 验证部门/个人范围的列表、筛选车牌、日趋势及空权限结果；缓存不会被某一用户的筛选污染。
- 浏览器模拟测试覆盖桌面 1440px 和手机 390px，各 15 项交互检查通过，包括刷新传参、刷新后恢复复用、未确认条件不请求。
- 实测脚本与结果保存在工作区上级 `outputs/mileage-query-cache-20261027/`。

上游首次查询建议见 [OneOS 性能优化反馈](oneos-mileage-performance-feedback-2026-10-27.md)。