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

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`。原始响应含业务数据，不应直接发布到公共仓库或转发。