feat(mileage): 接入区间汇总并复用查询结果

docs/mileage-query-cache-2026-10-27.md

@@ -0,0 +1,56 @@
+# 里程监控结果复用（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)。

docs/mileage-query-performance-2026-10-27.md

@@ -0,0 +1,56 @@
+# 里程监控查询交互与性能分析（2026-10-27）
+
+当前已完成第三阶段 [区间汇总接入与验证](mileage-summary-integration-2026-10-27.md)，首次查询不再拉取全量逐日明细。
+
+本文保留第一阶段诊断与修改记录。后续已实现 OneOS 查询复用，见 [第二阶段实现与验证](mileage-query-cache-2026-10-27.md)；可转交上游的独立建议见 [OneOS 性能优化反馈](oneos-mileage-performance-feedback-2026-10-27.md)。
+
+## 本次修改
+
+实时监控页将编辑中的筛选条件与已提交条件分开。日期输入、快捷日期、搜索选择、筛选标签清理、重置与排序修改只更新草稿，点击「查询」才提交。首次进入仍加载默认日期；主动刷新与确认后的滚动分页继续保留。移除页面每分钟自动刷新，避免编辑过程中产生后台查询。
+
+高级筛选和全屏均提供查询按钮。草稿未提交时禁用刷新和导出，并暂停加载更多，避免使用未确认条件。日期不完整或起止倒置时不可提交。接口失败显示重试提示；数据统计使用返回结果的日期范围。保留原有权限过滤、数据来源规则及全屏参数差异。
+
+范围：本次修改实时监控页；统计报表、每日汇报和单车详情的日期交互未改动。后端数据缓存、上游分页及实时性策略未修改。
+
+## 测量方式
+
+在本地开发环境中，使用已有配置调用 `queryRangeMileage`，仅执行数据读取。临时探针包裹 `fetch`（统计至 JSON 读取完毕）及数据库 `execute`，不记录凭据和车辆明细。来源为仪表数据，测量日期均为已结束的上海自然日。
+
+这些是单次样本，不代表 P95 或高并发表现；总耗时为服务端查询函数耗时，包含网络、解析、数据库及合并计算，不包含浏览器渲染。同一进程重复查询可复用已有单日缓存。
+
+| 区间 | 总耗时 | 区间上游记录数 | 区间分页请求数 |
+| --- | ---: | ---: | ---: |
+| 10 月 26 日 | 1,644 ms | 1,024 | 1 |
+| 10 月 20–26 日，首次 | 3,100 ms | 7,168 | 2 |
+| 10 月 20–26 日，重复 | 2,994 ms | 7,168 | 2 |
+| 10 月 1–26 日，首次 | 11,123 ms | 26,624 | 6 |
+| 10 月 1–26 日，重复 | 9,510 ms | 26,624 | 6 |
+
+单日样本同时另发结束日和前一日的两个单日请求，各约 1.6 秒。26 天首次查询的 6 个游标分页分别约 2,283 / 2,114 / 1,775 / 1,762 / 1,682 / 1,466 ms，串行耗时合计约 11.08 秒，几乎占满总耗时。
+
+车辆关联 SQL 返回 765 行，耗时 58–168 ms；考核目标关联 SQL 返回 512 行，耗时 25–125 ms。它们与上游查询并行执行。本次样本不支持把主要瓶颈归因于数据库或浏览器渲染。
+
+## 原因与代码依据
+
+1. **每次改条件就发请求。** `MonitoringView.tsx` 原本直接以全部输入状态构建 `monitoringQuery`，依赖它的 `loadFirstPage` 改变后由 Effect 自动调用；另有 60 秒轮询。本次已经改为显式提交。
+2. **页面分页发生在全量查询之后。** `src/server/routes/mileage/monitoring.ts` 先调用 `queryRangeMileage`，然后执行权限过滤、业务筛选、排序和 `slice`。请求第 2 页或只选一辆车仍先执行全量区间查询。
+3. **区间查询没有结果缓存。** `src/server/routes/mileage/oneos-api.ts` 中的 `fetchOneOsMileageDates` 只有 `rangeInflight`，完成后删除；单日查询的历史 6 小时缓存不覆盖此路径。重复查询同一个月仍发 6 次分页请求，与实测吻合。
+4. **游标必须串行。** `requestRange` 每页 5,000 条，拿到 `nextCursor` 才能发下一页。不能直接并行发后续页。前端固定传 `startDate/endDate`，即使只选一天也会走区间接口，再额外取结束日单日数据。
+5. **重试可能进一步拉长等待。** 本地配置每次上游调用超时 20 秒，最多尝试 3 次，中间等待 1 秒、2 秒。某一页连续超时即可约 63 秒；这是代码推导，实测样本没有出现超时。接口没有整个区间请求的总时限。
+6. **开发环境首次请求有两次。** `src/main.tsx` 启用 React StrictMode，浏览器测试观察到首次挂载两次请求；用户点击查询只产生一次请求。上游相同在途请求可合并，但数据库工作仍重复。这与生产环境行为需区分，不能为消除开发重复而移除 StrictMode。
+
+## 后续优化顺序
+
+1. **优先让分页、排序、导出复用一次已完成查询的结果。** 采用明确的查询快照或按日期范围与数据来源缓存原始结果，再按当前用户权限过滤。需要定义刷新失效方式及允许的数据延迟；不能缓存某个用户过滤后的结果再跨用户共享。这样能去掉重复查询的主要等待，但不会缩短首次上游查询。
+2. **对单日范围复用单日数据。** 避免区间与结束日两个接口重复查询同一天，验证缺失值、累计里程、来源优先级和前一日统计口径后再替换。
+3. **减少首次查询传输量。** 上游若提供区间聚合结果，可直接获取每车汇总及每日总量；明确车牌查询可考虑传入车牌限制，但必须保留现有权限检查和筛选候选项语义。若继续只提供明细游标分页，长区间首次查询仍受串行页数限制。
+
+未通过缩短超时、隐藏等待动画或并发重试来声称已解决单次查询耗时。
+
+## 验证
+
+- TypeScript 检查通过。
+- 监控查询模型、日期范围及里程显示相关 12 项测试通过。
+- Vite 生产构建通过，保留已有的大资源包提示。
+- 浏览器真实接口检查：修改两个日期没有监控请求，点击查询后发送一条包含两个最终日期的请求。
+- 浏览器自动化使用模拟数据验证 1440px 和 390px 两种宽度，各 11 项交互检查通过，均无页面运行时错误；运行脚本与结果位于工作区上级 `outputs/mileage-query-20261027/`。模拟测试用于验证请求触发条件，不用于性能结论。

docs/mileage-summary-integration-2026-10-27.md

@@ -0,0 +1,59 @@
+# 区间里程汇总接入与验证（2026-10-27）
+
+本地里程监控页已接入 `POST /api/v1/vehicles/mileage/summary/query`。依据用户提供的《BI 区间里程汇总接口对接说明》及 [OpenAPI 契约](https://open.d.lnoneos.com/open-api/openapi.yaml)；沿用现有服务地址和 appKey，不新增凭据配置。
+
+## 查询与展示
+
+- 首次进入加载默认日期；修改日期、来源及业务筛选后点击「查询」才请求。保留手动刷新，取消定时轮询。
+- 主列表每辆车使用一条区间汇总，不再先拉全部逐日明细。分页、排序、全屏及区间汇总导出复用服务器结果。
+- 默认仪表来源仍为有序的 `GB32960, MQTT`；不因文档示例包含 `JT808` 而扩大来源。保留现有来源选择、366 天 BI 区间限制和上海自然日口径。
+- 区间里程取 `periodMileageKm`，只合计有效日；真实零显示 0，无有效数据显示横杠。异常车辆保留其余有效日期的合计，并展示有效、缺失、异常天数及原因提示。
+- 结束日累计里程取 `endDateTotalMileageKm`，独立于区间日里程质量。无读数时不回填历史累计。采集时间、源更新时间与查询时间保持区分。
+- `CARRIED_FORWARD` 明细计为缺失，不冒充有效零。日趋势的 `null` 保留缺口。
+- 单车详情按当前区间和来源按需取明细。导出菜单分为「导出区间汇总」和「导出逐日明细」；前者复用汇总，后者明确拉取所选车辆逐日数据，仍可能较慢。
+
+## 权限与缓存
+
+每次 BI 请求重新读取车辆归属和考核关系，再执行现有部门、个人等权限及业务筛选、客户名称脱敏。上游原始结果可复用，用户授权结果不跨用户缓存。单车详情也校验当前 BI 车辆权限。
+
+上游全量授权车辆与 BI 当前可见车辆并不相同，因此不能直接把全量趋势展示给用户。当筛选范围缩小时，使用已授权且可见的车牌集合请求范围内趋势；空集合直接返回无数据趋势，不向上游传空数组（空数组在契约中代表全部）。分页、排序、全屏和导出使用 `includeDailyTrend=0`，无需重复获取趋势。
+
+缓存键包含起止日期、有序来源及规范化车牌范围；同一在途请求合并，成功结果最多缓存 5 分钟且不超过上游快照到期时间，最多 4 项。显式刷新绕过已完成缓存；失败不回退成空数据或成功零值。401、403、429、504 等上游错误转为明确提示，保留错误码、traceId 和适用的 Retry-After。
+
+缓存为进程内机制，过期、淘汰、重启或跨实例都会重新请求。BI 归属变化立即按最新数据库结果过滤；上游授权变化需要下次上游请求才能获知。列表与按权限重查的趋势可能来自两个生成时点，当前日或历史补报期间不保证原子一致；上游首次汇总本身也不是数据库原子快照。
+
+## 真实数据对账
+
+条件：2026-10-01 至 2026-10-26，仪表来源。仅执行读取，不修改上游或业务数据库。
+
+- 旧明细接口：6 页、26,624 条记录；新汇总：1,024 辆、26 天趋势。
+- 逐车对比有效里程合计、有效/缺失/异常天数：差异 0。
+- 旧明细中 6,910 条 `NORMAL/CARRIED_FORWARD` 按契约计为缺失，真实正常记录 11,150 条，无数据 8,559 条，异常 5 条。
+- BI 列表 765 辆，其中 761 辆匹配上游汇总，4 辆不在返回集合内，保持无可用里程。匹配车辆的区间里程、质量天数、结束日累计里程：差异 0。
+- 按 BI 车辆集合重新计算的 26 天趋势与返回趋势逐日对比：差异 0。
+
+## 性能实测
+
+同一本地开发环境、同一日期和来源；单次样本，非 P95。HTTP 指标包含响应及 JSON 读取，不包含浏览器绘图或 XLSX 生成。
+
+| 路径 | 耗时 |
+| --- | ---: |
+| 旧上游逐日明细，完整 6 页 | 10,250 ms |
+| 新上游区间汇总，单次请求 | 1,869 ms |
+| 新 BI 首次完整查询，缓存 miss | 3,862 ms |
+| 第 2 页，缓存 hit | 68 ms |
+| 升序查询，缓存 hit | 35 ms |
+| 区间汇总导出数据，765 辆，缓存 hit | 39 ms |
+| 主动刷新 | 3,572 ms |
+| 刷新后再次导出数据，缓存 hit | 67 ms |
+
+首次 BI 请求仍包含全量汇总、原有对比日读数、数据库查询，以及 BI 范围的趋势汇总，因此不能把上游单次 1.9 秒宣称为完整页面耗时。此前旧 BI 冷查询实测 10,723 ms，本次 3,862 ms，单样本约缩短 64%。
+
+## 验证记录
+
+- 38 项里程相关测试通过：覆盖契约解析、快照分页、真实零与缺失、部分异常有效合计、缓存与过期、部门/个人/空权限、归属变化、错误响应和按需明细。
+- `npm run lint` 和 `npm run build` 通过；构建仍提示已有的大资源包。
+- 真实浏览器 1440px / 390px：日期编辑不请求、确认后查询、765 辆和 26 天趋势、质量天数、手机查询按钮可见，均通过，无页面脚本异常。
+- 实际下载并解析区间汇总 XLSX：1 张表、765 辆、质量列齐全；单车逐日 XLSX：2 张表、26 个日期列。单车详情请求日期与来源与列表一致。
+
+本机验证脚本、脱离 Git 的原始结果及截图位于工作区父目录 `outputs/mileage-summary-20261027/`：`timings.json`、`reconciliation.json`、`browser-results.json`。原始响应含业务数据，不应直接发布到公共仓库或转发。

docs/oneos-mileage-performance-feedback-2026-10-27.md

@@ -0,0 +1,103 @@
+# 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、快照当前实现与复用能力、聚合接口可行性，以及可交付的第一阶段范围与排期。