4.2 KiB
里程监控结果复用（2026-10-27）
本文为第二阶段历史记录。当前主列表已改用上游区间汇总；最新行为、权限趋势处理及实测见 区间汇总接入与验证。下文的明细缓存和首次耗时描述不代表当前实现。
行为
同一服务进程内，按规范化起止日期和有序协议优先级缓存 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 性能优化反馈。