perf: reuse historical mileage range snapshots

- '车辆汇总' sheet now includes per-day mileage columns for date ranges
- Daily columns shown as 'MM-DD里程(km)' between base info and summary cols
- Freeze pane fixed at 7 base columns for horizontal scrolling
- '每日明细' sheet retained as detailed backup
- Bump version to 1.1.9

.dockerignore

@@ -0,0 +1,9 @@
+node_modules
+dist
+.env
+.git
+.codex
+outputs
+reports
+data/geo
+data/vehicle-heatmap/source.csv

.env.example

@@ -0,0 +1,51 @@
+# Core asset database
+DB_HOST=
+DB_PORT=3306
+DB_USER=
+DB_PASSWORD=
+DB_NAME=
+
+# Hydrogen ledger database
+HYDROGEN_DB_HOST=
+HYDROGEN_DB_PORT=3306
+HYDROGEN_DB_USER=
+HYDROGEN_DB_PASSWORD=
+HYDROGEN_DB_NAME=
+
+# Mileage reference database
+MILEAGE_DB_HOST=
+MILEAGE_DB_PORT=3306
+MILEAGE_DB_USER=
+MILEAGE_DB_PASSWORD=
+MILEAGE_DB_NAME=
+
+# OneOS mileage API
+ONEOS_MILEAGE_API_BASE_URL=http://172.17.111.55:20310
+ONEOS_MILEAGE_API_KEY=
+ONEOS_MILEAGE_API_TIMEOUT_MS=20000
+
+# Authentication and external API
+EXTERNAL_API_BASE=https://lnh2e.com
+JWT_SECRET=
+DEV_BYPASS_AUTH=0
+
+# Vehicle heatmap database and map SDK
+HEATMAP_DB_HOST=
+HEATMAP_DB_PORT=36453
+HEATMAP_DB_USER=
+HEATMAP_DB_PASSWORD=
+HEATMAP_DB_NAME=lingniu_vehicle_data
+HEATMAP_DB_SSL=false
+AMAP_WEB_KEY=
+AMAP_SECURITY_JS_CODE=
+
+# Feedback attachment object storage
+OSS_ENDPOINT=
+OSS_REGION=oss-cn-shanghai
+OSS_ACCESS_KEY_ID=
+OSS_ACCESS_KEY_SECRET=
+OSS_BUCKET=
+OSS_BASE_DIR=/dos
+OSS_HOST=
+
+SERVER_PORT=3001

docker-compose.yml

@@ -5,24 +5,42 @@ services:
     image: harbor.lnh2e.com/lingniu-v1/ln-bi:main-1.0.0
     network_mode: host
     environment:
-      DB_HOST: "rm-bp179zbv481rnw3e2no.mysql.rds.aliyuncs.com"
-      DB_PORT: "3306"
-      DB_USER: "oneos_db_prod"
-      DB_PASSWORD: "adASHJcviqwjkbn23ngt1"
-      DB_NAME: "ln_asset_management"
-      HYDROGEN_DB_HOST: "47.99.185.173"
-      HYDROGEN_DB_PORT: "3306"
-      HYDROGEN_DB_USER: "root"
-      HYDROGEN_DB_PASSWORD: "lnMysql."
-      HYDROGEN_DB_NAME: "ln_asset_management"
-      MILEAGE_DB_HOST: "101.133.130.65"
-      MILEAGE_DB_PORT: "3306"
-      MILEAGE_DB_USER: "bi_reader_02"
-      MILEAGE_DB_PASSWORD: "bi_reader_02_Pass"
-      MILEAGE_DB_NAME: "hydrogen_energy"
-      SERVER_PORT: "8111"
-      EXTERNAL_API_BASE: "https://lnh2e.com"
-      JWT_SECRET: "ln-bi-jwt-prod-k8s9m2x7"
+      DB_HOST: "${DB_HOST:?Set DB_HOST in the deployment environment}"
+      DB_PORT: "${DB_PORT:-3306}"
+      DB_USER: "${DB_USER:?Set DB_USER in the deployment environment}"
+      DB_PASSWORD: "${DB_PASSWORD:?Set DB_PASSWORD in the deployment environment}"
+      DB_NAME: "${DB_NAME:?Set DB_NAME in the deployment environment}"
+      HYDROGEN_DB_HOST: "${HYDROGEN_DB_HOST:?Set HYDROGEN_DB_HOST in the deployment environment}"
+      HYDROGEN_DB_PORT: "${HYDROGEN_DB_PORT:-3306}"
+      HYDROGEN_DB_USER: "${HYDROGEN_DB_USER:?Set HYDROGEN_DB_USER in the deployment environment}"
+      HYDROGEN_DB_PASSWORD: "${HYDROGEN_DB_PASSWORD:?Set HYDROGEN_DB_PASSWORD in the deployment environment}"
+      HYDROGEN_DB_NAME: "${HYDROGEN_DB_NAME:?Set HYDROGEN_DB_NAME in the deployment environment}"
+      MILEAGE_DB_HOST: "${MILEAGE_DB_HOST:?Set MILEAGE_DB_HOST in the deployment environment}"
+      MILEAGE_DB_PORT: "${MILEAGE_DB_PORT:-3306}"
+      MILEAGE_DB_USER: "${MILEAGE_DB_USER:?Set MILEAGE_DB_USER in the deployment environment}"
+      MILEAGE_DB_PASSWORD: "${MILEAGE_DB_PASSWORD:?Set MILEAGE_DB_PASSWORD in the deployment environment}"
+      MILEAGE_DB_NAME: "${MILEAGE_DB_NAME:?Set MILEAGE_DB_NAME in the deployment environment}"
+      ONEOS_MILEAGE_API_BASE_URL: "${ONEOS_MILEAGE_API_BASE_URL:-http://172.17.111.55:20310}"
+      ONEOS_MILEAGE_API_KEY: "${ONEOS_MILEAGE_API_KEY:?Set ONEOS_MILEAGE_API_KEY in the deployment environment}"
+      ONEOS_MILEAGE_API_TIMEOUT_MS: "${ONEOS_MILEAGE_API_TIMEOUT_MS:-20000}"
+      SERVER_PORT: "${SERVER_PORT:-8111}"
+      EXTERNAL_API_BASE: "${EXTERNAL_API_BASE:-https://lnh2e.com}"
+      JWT_SECRET: "${JWT_SECRET:?Set JWT_SECRET in the deployment environment}"
+      AMAP_WEB_KEY: "${AMAP_WEB_KEY:?Set AMAP_WEB_KEY in the deployment environment}"
+      AMAP_SECURITY_JS_CODE: "${AMAP_SECURITY_JS_CODE:?Set AMAP_SECURITY_JS_CODE in the deployment environment}"
+      OSS_ENDPOINT: "${OSS_ENDPOINT:?Set OSS_ENDPOINT in the deployment environment}"
+      OSS_REGION: "${OSS_REGION:-oss-cn-shanghai}"
+      OSS_ACCESS_KEY_ID: "${OSS_ACCESS_KEY_ID:?Set OSS_ACCESS_KEY_ID in the deployment environment}"
+      OSS_ACCESS_KEY_SECRET: "${OSS_ACCESS_KEY_SECRET:?Set OSS_ACCESS_KEY_SECRET in the deployment environment}"
+      OSS_BUCKET: "${OSS_BUCKET:?Set OSS_BUCKET in the deployment environment}"
+      OSS_BASE_DIR: "${OSS_BASE_DIR:-/dos}"
+      OSS_HOST: "${OSS_HOST:-}"
+      HEATMAP_DB_HOST: "${HEATMAP_DB_HOST:?Set HEATMAP_DB_HOST in the deployment environment}"
+      HEATMAP_DB_PORT: "${HEATMAP_DB_PORT:-36453}"
+      HEATMAP_DB_USER: "${HEATMAP_DB_USER:?Set HEATMAP_DB_USER in the deployment environment}"
+      HEATMAP_DB_PASSWORD: "${HEATMAP_DB_PASSWORD:?Set HEATMAP_DB_PASSWORD in the deployment environment}"
+      HEATMAP_DB_NAME: "${HEATMAP_DB_NAME:-lingniu_vehicle_data}"
+      HEATMAP_DB_SSL: "${HEATMAP_DB_SSL:-false}"
     deploy:
       replicas: 1
       restart_policy:

docs/bi-refactor-roadmap.md

@@ -0,0 +1,216 @@
+# BI 渐进式重构方案
+
+更新日期：2026-08-07
+
+## 1. 目标
+
+本次重构不重做整套系统，采用可回滚的小批次交付，逐步解决三个核心问题：
+
+1. UI/UX：统一信息层级、筛选方式、状态反馈和移动端行为。
+2. 下钻：任何汇总指标都能沿同一统计口径进入可核对的明细。
+3. 统计逻辑：指标公式、时间语义、数据来源和数据截至时间均可查询、可测试。
+
+不在当前阶段引入新的 BI 引擎或替换现有 React、Hono、MySQL 技术栈。
+
+## 2. 设计原则
+
+- 先口径，后图表：没有明确公式和数据源的指标不得进入主看板。
+- 父子一致：下钻前后的时间、车辆范围、组织范围和数据源必须一致。
+- URL 即分析状态：日期、范围、实体和数据源写入 URL，支持刷新、返回和分享。
+- 空值不等于零值：接口失败、尚未接入、没有权限和真实零业务使用不同状态。
+- 汇总可对账：页面汇总应等于明细全量聚合，明细截断不能影响顶部合计。
+- 数据新鲜度显式展示：业务时间与页面刷新时间分开表达。
+- 渐进发布：每批只修改一个口径或一条下钻链路，通过测试和真实数据核对后提交。
+
+## 3. 目标信息架构
+
+每个 BI 模块统一为三级信息结构：
+
+| 层级 | 用途 | 页面内容 |
+| --- | --- | --- |
+| 总览 | 判断经营状态 | 核心 KPI、趋势、结构、异常、数据截至时间 |
+| 分析 | 定位变化来源 | 时间筛选、组织/车辆范围、分组排行、归因 |
+| 明细 | 核对原始业务 | 车辆、订单、站点、账单或通行记录 |
+
+页面头部统一提供模块名称、简短业务说明和“指标口径”入口。筛选条件位于内容上方，实体下钻状态紧邻筛选区展示，避免用户忘记当前分析范围。
+
+## 4. 模块与下钻矩阵
+
+### 4.1 里程
+
+| 父级 | 下钻目标 | 必须继承的上下文 | 当前状态 |
+| --- | --- | --- | --- |
+| 实时监控汇总 | 车辆详情 | 日期区间、协议优先级、车牌 | 已完成 |
+| 考核目标 | 部门/客户归因 | 考核年份、目标、归因维度 | 已完成 |
+| 归因分组 | 车辆清单 | 目标、部门或客户值 | 已完成 |
+| 每日汇报 | 实时监控/考核目标 | 汇报日期、目标或车牌 | 已完成 |
+
+考核完成率使用目标里程加权：
+
+```text
+SUM(completed_mileage_km) / NULLIF(SUM(target_mileage_km), 0) * 100
+```
+
+禁止直接平均车辆完成率或考核组完成率。
+
+### 4.2 氢能
+
+| 父级 | 下钻目标 | 必须继承的上下文 | 当前状态 |
+| --- | --- | --- | --- |
+| 站点排行 | 站点每日明细 | 年份、站点、日期区间、车辆范围 | 已完成 |
+| 客户排行 | 客户每日明细 | 年份、客户、日期区间、车辆范围 | 已完成 |
+| 每日趋势 | 加氢订单 | 日期、车辆范围、站点或客户 | 下钻代码已完成，待数据源恢复后验收 |
+
+成本、收入和毛利必须分开：
+
+```text
+成本 = SUM(cost_total)
+客户收入 = SUM(fee_total)
+客户单毛利 = 客户收入 - 客户单对应成本
+```
+
+数据库不可用时返回可识别的 503 状态，页面不得显示派生零值。
+
+### 4.3 电能
+
+| 父级 | 下钻目标 | 必须继承的上下文 | 当前状态 |
+| --- | --- | --- | --- |
+| 总览日柱 | 当日订单 | 日期、全部车辆范围 | 已完成 |
+| 月份 | 日期 | 车辆范围、日期区间 | 已完成 |
+| 日期 | 充电订单 | 日期、车辆范围 | 已完成 |
+
+电能范围包括“全部车辆、羚牛车辆、外部车辆”。总览使用全部车辆口径，因此总览下钻必须进入 `all`，不能默认切换为羚牛车辆。
+
+综合费用强度使用加权公式：
+
+```text
+SUM(fee) / NULLIF(SUM(kwh), 0)
+```
+
+零费用订单参与电量和订单数统计。当前月无数据时可以展示最近数据月，但所有月度标签必须显示实际月份，并展示 `MAX(start_time)` 数据截至时间。
+
+### 4.4 ETC
+
+| 父级 | 下钻目标 | 必须继承的上下文 | 当前状态 |
+| --- | --- | --- | --- |
+| 通行费用 | 通行记录 | 日期、车牌、客户、费用承担类型 | 下钻代码已完成，待首次真实同步验收 |
+| 账单应收 | ETC 账单 | 账期、客户、支付状态 | 下钻代码已完成，待首次真实同步验收 |
+
+供应商未配置或从未同步时展示接入状态，不使用模拟业务数据填充图表。
+
+## 5. 指标治理
+
+指标目录由 `/api/analytics/metrics` 发布，当前采用版本化合同。每个指标必须包含：
+
+- 唯一且带领域前缀的指标 ID。
+- 中文名称和业务解释。
+- 单位、聚合方式和时间语义。
+- 可审计公式与真实数据源。
+- 支持的筛选维度和下钻实体。
+
+指标变更规则：
+
+1. 修改公式、来源或时间语义时提升目录版本。
+2. 后端查询、指标目录、页面标签和测试在同一批次修改。
+3. 比率类指标必须由分子、分母汇总后计算，禁止平均子级比率。
+4. 金额同时标明成本、收入、应收、实收或总费用，不使用模糊的“费用”。
+5. 快照、区间流量和数据新鲜度不得混在同一时间标签下。
+
+## 6. URL 与交互约定
+
+- 模块和子页使用 hash，例如 `#electric/overview`。
+- 分析上下文使用领域前缀查询参数，例如 `electricDate`、`hydrogenStationId`、`mileagePlate`。
+- 不删除其他领域的查询参数。
+- 总览进入明细使用 `pushState`，同页筛选调整使用 `replaceState`。
+- 浏览器返回、前进和刷新必须恢复筛选与展开状态。
+- 图表下钻同时支持鼠标和键盘，交互图形提供可读名称。
+
+## 7. 接口与性能边界
+
+| 类型 | 目标 |
+| --- | --- |
+| 热缓存汇总接口 | P95 小于 500 ms |
+| 普通数据库聚合 | P95 小于 1.5 s |
+| 明细查询 | 首屏小于 2 s，超过上限时分页或截断 |
+| 并发同参 GET | 前端和服务端均只执行一次 |
+| 外部数据源失败 | 返回结构化 503，不返回连接信息 |
+
+查询要求：
+
+- 日期条件使用范围比较，避免对索引列套 `DATE()` 或 `DATE_FORMAT()` 后再过滤。
+- 汇总与明细可以并行查询，但必须使用相同过滤条件。
+- 明细展示上限与全量汇总分离，截断时明确提示。
+- 缓存键必须包含所有影响统计结果的筛选维度。
+- 失败请求不得驻留在并发请求缓存中。
+
+## 8. 分阶段路线
+
+### 阶段 A：口径与导航基线
+
+- 已完成版本化指标目录和四模块入口。
+- 已完成里程、电能、氢能主要 URL 状态。
+- 已完成 ETC 记录/账单视图、日期、搜索和分页 URL 状态，以及超范围页码自动纠正。
+- 已统一共享加载、空数据和故障组件的顶层卡片与明细内联边界，消除能源明细中的嵌套状态卡片。
+- 已统一电能、氢能和 ETC 日期范围输入；电能与氢能共用快捷区间算法和单一输入事件路径。
+- 电能与氢能可根据 URL 日期恢复快捷区间选中态；过期区间自动归为自定义，避免标签与统计日期不一致。
+- 已统一电能和氢能车辆范围 segmented control，并区分前端车辆归属状态与后端 `customer` 查询参数语义。
+- 已完成并发同参 GET 去重。
+
+### 阶段 B：核心下钻闭环
+
+- 已完成里程考核归因、车辆详情和每日汇报跳转。
+- 里程考核年度已纳入 `mileageYear` URL 状态；目标、部门/客户归因和车辆清单下钻继承同一年度，无效年度会按目标真实年度归一。
+- 车辆级里程详情继承 `mileageStart`、`mileageEnd` 和数据源优先级；显式下钻日期严格展示所选日，预设区间继续排除尚未完整的当天数据，请求故障显示为不可用并支持重试。
+- 里程实时监控的日期、来源、批次、区域、车牌、归属、高级筛选和排序已纳入独立 URL 状态；分享或刷新链接可恢复完整查询，车辆详情前进后退保留列表上下文且不把下钻车牌误写为筛选车牌。
+- 已完成氢能站点、客户下钻代码。
+- 已完成氢能每日趋势到加氢订单的 URL 下钻、分页和结构化故障状态；待数据源恢复后验收真实明细。
+- 已为电能总览与氢能每日趋势柱图统一 Enter/Space 键盘下钻；氢能有效日期柱提供可读名称、焦点和选中反馈。
+- 已完成电能全部车辆、日期和订单下钻。
+- 电能每日列表打开新日期订单使用浏览器历史 `pushState`，返回/前进可恢复进入前后的分析状态；筛选调整仍使用 `replaceState`。
+- 已完成 ETC 通行记录与结算账单下钻代码、筛选、分页和未同步空状态；待首次真实同步后验收真实数据。
+
+### 阶段 C：数据可信度
+
+- 里程年度归因使用考核台账 `current_mileage` 快照，按车辆目标封顶后加总完成量与缺口，并自动核对归因合计和目标汇总；带日期的 OneOS 里程只用于车辆实时明细。
+- 里程考核目标接口发布车辆台账 `MAX(update_time)`，统计页使用真实日期和时间展示数据截至点，不再用页面访问日或考核结束日代替快照时间。
+- 里程考核接口区分目标声明台数与当前有效车辆数；两者不一致时页面明确标注缺少或超配数量，并说明完成率、缺口和归因的实际计算范围。
+- 里程考核统计主数据已区分加载、真实空数据、首次请求故障和保留旧数据的刷新故障，并提供统一重试入口，接口失败不再显示为零值或空页面。
+- 里程考核归因车辆与 7 天趋势已提供独立加载、故障、空数据和重试状态；子请求失败时停止展示“0 台未达标”和“最新日变化 +0”等伪业务结果。
+- 里程考核车辆日期侧栏仅展示带目标和日期标识的成功快照；切换日期失败时保留并标注上一成功日期，首次失败不再回退为当前日数据或伪造“0 辆”。
+- 里程实时监控的首页、分页、全屏和导出已共用同一组筛选参数；全屏首次故障不再显示零值，刷新故障会保留并标注上一成功快照，导出成功或失败均提供可见结果和重试入口。
+- 里程实时监控主列表快照已绑定完整筛选与排序口径；新口径请求失败时隐藏旧 KPI、趋势和车辆，原口径刷新失败时保留并标注旧快照，快速筛选与分页的过期响应不会覆盖当前结果。
+- 里程实时监控已将排序维度与 KPI 公式解耦：主值和平均单车始终使用当日/区间流量里程，累计仪表合计保持独立快照语义；平均单车里程已纳入版本 7 指标目录。
+- 里程历史区间监控已复用权限过滤前的分钟级基础快照；筛选、排序、分页和并发同参请求不再重复拉取 OneOS 区间数据及车辆元数据，强制刷新仍可绕过已完成快照，失败请求不进入缓存。
+- 已完成电能数据截至时间和实际趋势月展示。
+- 电能日期下钻自动核对日汇总与订单全量合计的日期、车辆范围、电量和费用，并显式展示通过或差异状态。
+- 已完成氢能结构化故障状态与重试体验。
+- 已完成里程今日仪表快照复用：监控查询和考核车辆当前日明细命中同一分钟级快照，手动刷新生成一致的分页快照；历史日仍使用独立日期缓存。
+- 已在各 BI 模块头部提供当前数据源的真实请求状态、失败率和最后成功/失败时间。
+- 待恢复氢能数据库后进行总览、站点、客户三层对账。
+- 待 ETC 同步后进行通行记录、账单和收款三层对账。
+
+### 阶段 D：部署与安全
+
+- 已将部署清单、氢能和里程连接中的数据库敏感值迁移为必填环境变量。
+- 轮换已经进入版本历史的氢能数据库凭据。
+- 已提供无敏感值的 `.env.example`；测试、生产值由各环境密钥管理。
+- 已拆分进程存活检查与无敏感值的配置就绪检查。
+- 已增加基于真实业务请求的数据源最后结果、最后成功时间和滚动失败率监控。
+
+## 9. 每批验收门槛
+
+每次提交至少满足：
+
+1. TypeScript 检查通过。
+2. 受影响的口径、URL 或查询测试通过。
+3. 生产前端构建通过，服务端入口可加载。
+4. `git diff --check` 通过。
+5. 桌面和移动端检查无溢出、遮挡或不可操作控件。
+6. 使用真实接口核对至少一个父级汇总与子级明细。
+7. 不提交本地数据、临时脚本、凭据或无关工作区修改。
+
+## 10. 当前外部依赖
+
+- 氢能数据库连接尚未恢复，真实数据对账未完成。
+- ETC 供应商未配置、未执行首次同步；记录与账单下钻代码已完成，但真实数据仍不可验收。
+- 氢能连接信息已从当前版本迁出，但历史凭据仍必须在数据库侧轮换；文档不记录任何连接值。

docs/oneos-mileage-api-requirements.md

@@ -0,0 +1,155 @@
+# OneOS 车辆里程接口需求
+
+当前协议选源联调阻塞项和 OneOS 修改清单见：
+[OneOS 车辆里程数据源协议改造清单](./oneos-mileage-source-protocol-gaps.md)。
+
+## 开发原则
+
+1. 新增区间查询接口；车辆里程汇总能力在现有
+   `POST /api/v1/vehicles/mileage/query` 上兼容扩展。
+2. 现有接口的路径、鉴权、已有请求参数、已有响应字段、字段语义和默认行为必须完全兼容。
+3. 公网 `https://open.d.lnoneos.com` 与 ECS 内网 `http://172.17.111.55:20310` 使用相同路径、鉴权和数据口径。
+4. 鉴权继续使用 `Authorization: Bearer APP_KEY`。
+5. 日期采用 `YYYY-MM-DD`，时区统一为 `Asia/Shanghai`，里程单位统一为 km。
+
+## 1. 车辆区间日里程批量查询
+
+```http
+POST /api/v1/vehicles/mileage/range/query
+```
+
+请求：
+
+```json
+{
+  "startDate": "2026-07-01",
+  "endDate": "2026-07-23",
+  "plateNumbers": ["沪A00001", "沪A00002"],
+  "protocolPriority": ["GB32960", "MQTT", "JT808"],
+  "cursor": null,
+  "pageSize": 5000
+}
+```
+
+规则：
+
+- `startDate`、`endDate` 必填，最长支持 366 天；
+- `plateNumbers` 可省略，省略时返回授权范围内全部车辆；
+- `protocolPriority` 可省略；提供时只允许 `GB32960`、`MQTT`、`JT808`，
+  数组顺序表示逐车逐日的数据源优先级，未列出的协议视为禁用；
+- BI 只会使用以下四种组合：
+  - 仪表数据优先：`["GB32960", "MQTT", "JT808"]`；
+  - GPS 数据优先：`["JT808", "GB32960", "MQTT"]`；
+  - 仅仪表数据：`["GB32960", "MQTT"]`；
+  - 仅 GPS 数据：`["JT808"]`；
+- BI 页面默认只启用“仪表数据”，即默认发送
+  `["GB32960", "MQTT"]`；用户主动启用 GPS 后才发送包含 `JT808` 的组合；
+- 仪表数据内部优先级固定为 `GB32960 > MQTT`，不提供反向切换；
+- 数据量过大时使用 `cursor` 分页，同一次查询使用相同 `snapshotId`；
+- 每辆车每天返回一条记录；
+- 无数据返回 `status: "NO_DATA"` 且 `dailyMileageKm: null`，真实零里程返回 `status: "NORMAL"` 且 `dailyMileageKm: 0`。
+
+响应：
+
+```json
+{
+  "code": "SUCCESS",
+  "message": "success",
+  "data": [
+    {
+      "vin": "LMRK...",
+      "plateNumber": "沪A00001",
+      "date": "2026-07-01",
+      "dailyMileageKm": 182.437,
+      "sourceProtocol": "GB32960",
+      "dataTime": "2026-07-01T23:58:45+08:00",
+      "updatedAt": "2026-07-02T05:10:00+08:00",
+      "status": "NORMAL"
+    }
+  ],
+  "snapshotId": "mileage-20260723-001",
+  "nextCursor": null,
+  "traceId": "..."
+}
+```
+
+## 2. 兼容扩展现有单日车辆里程接口
+
+用于一次获取指定日期每辆车的日里程、累计里程和数据时间。
+
+```http
+POST /api/v1/vehicles/mileage/query
+```
+
+请求：
+
+```json
+{
+  "date": "2026-07-23",
+  "plateNumbers": ["沪A00001", "沪A00002"],
+  "protocolPriority": ["GB32960", "MQTT", "JT808"]
+}
+```
+
+规则：
+
+- `date` 和 `plateNumbers` 沿用现有接口规则；
+- `protocolPriority` 的枚举、顺序和禁用规则与区间接口完全一致；
+- `plateNumbers` 省略时返回授权范围内全部车辆；
+- 接口默认在现有车辆结果中返回 `totalMileageKm`、`dataTime` 和 `updatedAt`；
+- 只增加响应字段，不删除或修改任何现有字段及其语义；
+- 历史日期返回该自然日最终有效结果；
+- 查询当天返回当前最新结果；
+- `dataTime` 必须是本次统计实际采用的最后一条车辆源数据时间，不能使用接口请求时间或响应时间代替；
+- 无数据时相关里程字段返回 `null`，不能使用 0 代替；
+- 接口应支持当前应用授权范围内的全部车辆。
+
+响应：
+
+```json
+{
+  "code": "SUCCESS",
+  "message": "success",
+  "data": [
+    {
+      "vin": "LMRK...",
+      "plateNumber": "沪A00001",
+      "date": "2026-07-23",
+      "dailyMileageKm": 182.437,
+      "totalMileageKm": 12345.678,
+      "sourceProtocol": "GB32960",
+      "dataTime": "2026-07-23T10:35:42+08:00",
+      "updatedAt": "2026-07-23T10:35:46+08:00",
+      "status": "NORMAL"
+    }
+  ],
+  "traceId": "..."
+}
+```
+
+现有响应外层结构及已有字段保持不变，调用方无需增加任何请求参数。
+
+## 通用要求
+
+- `dataTime`、`updatedAt` 使用带 `+08:00` 的 ISO 8601 格式；
+- `sourceProtocol` 必须返回本条结果实际采用的协议：
+  `GB32960`、`MQTT` 或 `JT808`；无数据时返回 `null`；
+- OneOS 必须按 `protocolPriority` 选择第一份有效数据，不得返回已禁用协议的数据；
+- `sourceProtocol=GB32960/MQTT` 在 BI 显示为“仪表数据”，
+  `sourceProtocol=JT808` 显示为“GPS数据”；
+- 每个响应返回 `traceId`；
+- 接口返回值保留原始精度；
+- 负里程不得作为正常数据返回；
+- 公网和 ECS 内网使用同一 AppKey 时，授权范围和查询结果保持一致；
+- 区间接口及现有接口的汇总扩展不得影响现有调用方和默认行为。
+
+## 验收
+
+1. 现有 `/api/v1/vehicles/mileage/query` 请求方式保持不变，回归测试全部通过。
+2. 区间接口不传车牌可完整查询全部授权车辆，分页无重复、无漏行。
+3. 现有接口不传车牌时，默认返回全部授权车辆的日里程、累计里程和数据时间。
+4. 正确区分无数据与真实零里程。
+5. `dataTime` 能反映每辆车实际数据的新鲜度。
+6. 四种 `protocolPriority` 组合均能按顺序选源，且响应中的
+   `sourceProtocol` 与实际采用协议一致。
+7. 禁用某类协议后，响应不得回退到该协议。

docs/oneos-mileage-source-protocol-gaps.md

@@ -0,0 +1,183 @@
+# OneOS 车辆里程数据源协议改造清单
+
+## 0. 发布后复测结论
+
+复测日期：2026-07-23
+
+开放平台发布后，BI 已重新连接 `https://open.d.lnoneos.com` 并完成复测：
+
+- 单日接口和区间接口均接受 `protocolPriority`，不再返回
+  `INVALID_REQUEST`；
+- 成功响应已返回实际使用的 `sourceProtocol`；
+- 仪表优先、GPS 优先、仅仪表、仅 GPS 四种模式均返回 HTTP 200；
+- “仅仪表数据”结果未出现 `JT808`；
+- “仅 GPS 数据”结果未出现 `GB32960` 或 `MQTT`；
+- 同一车辆四天区间查询能够随优先级在 `GB32960` 和 `JT808`
+  之间正确切换；
+- BI 页面已显示真实“仪表数据”或“GPS数据”，不再显示“来源待接口”。
+
+复测时的单日协议分布如下，数据量会随当天车辆上报变化：
+
+| BI 模式 | GB32960 | MQTT | JT808 | 无数据 | 禁用协议混入 |
+| --- | ---: | ---: | ---: | ---: | --- |
+| 仪表数据优先 | 387 | 49 | 134 | 454 | 无 |
+| GPS 数据优先 | 69 | 30 | 471 | 454 | 无 |
+| 仅仪表数据 | 387 | 49 | 0 | 588 | 无 |
+| 仅 GPS 数据 | 0 | 0 | 471 | 553 | 无 |
+
+结论：本清单中的协议选源阻塞项已关闭，当前接口满足 BI 对接要求。
+以下内容保留为接口契约和后续回归验收依据。
+
+## 1. 历史联调结论（发布前）
+
+联调地址：`https://open.d.lnoneos.com`
+
+涉及接口：
+
+- `POST /api/v1/vehicles/mileage/query`
+- `POST /api/v1/vehicles/mileage/range/query`
+
+发布前接口不满足 BI 对车辆里程数据源切换和来源标注的要求，阻塞项如下：
+
+| 序号 | 当前表现 | 期望表现 | 影响 |
+| --- | --- | --- | --- |
+| 1 | 请求增加 `protocolPriority` 后返回 HTTP 400，业务码为 `INVALID_REQUEST` | 两个里程接口均接受可选字段 `protocolPriority` | BI 无法切换仪表数据和 GPS 数据的优先级，也无法单独禁用某类数据 |
+| 2 | 成功响应中没有 `sourceProtocol` | 每辆车、每天的结果返回实际采用的协议 | BI 无法准确标注“仪表数据”或“GPS数据” |
+| 3 | 无法验证接口是否排除了已禁用协议 | 未列入 `protocolPriority` 的协议不得参与选源 | “仅仪表数据”和“仅 GPS 数据”无法生效 |
+| 4 | 无法验证仪表数据内部的降级顺序 | 仪表数据固定按 `GB32960 > MQTT` 选源 | 32960 缺失时无法确认是否正确降级到 MQTT |
+
+BI 保留旧请求格式的兼容回退，用于开放平台异常或版本回滚时保证现有里程查询可用。回退结果不会伪造数据来源，页面会显示“来源待接口”。正常情况下新接口已不触发该回退。
+
+## 2. OneOS 必须修改的请求字段
+
+两个接口都需要增加以下可选字段：
+
+```json
+{
+  "protocolPriority": ["GB32960", "MQTT", "JT808"]
+}
+```
+
+字段规则：
+
+1. 类型为非空字符串数组。
+2. 仅允许 `GB32960`、`MQTT`、`JT808`，协议名区分以此处定义为准。
+3. 数组顺序表示逐车、逐自然日的数据源优先级。
+4. 未出现在数组中的协议视为禁用，不得参与选源或作为兜底数据返回。
+5. `protocolPriority` 省略时保持现有接口的默认行为，确保旧调用方兼容。
+6. 非法枚举、空数组或重复协议应返回 HTTP 400，并在响应中给出明确的错误信息和 `traceId`。
+
+BI 只会发送以下四种组合：
+
+| BI 模式 | `protocolPriority` | 选源规则 |
+| --- | --- | --- |
+| 仪表数据优先 | `["GB32960", "MQTT", "JT808"]` | 先查 32960，再查 MQTT，最后查 JT808 |
+| GPS 数据优先 | `["JT808", "GB32960", "MQTT"]` | 先查 JT808，再查 32960，最后查 MQTT |
+| 仅仪表数据 | `["GB32960", "MQTT"]` | 只允许 32960 和 MQTT，禁止使用 JT808 |
+| 仅 GPS 数据 | `["JT808"]` | 只允许 JT808，禁止使用 32960 和 MQTT |
+
+BI 页面默认只启用“仪表数据”，即默认使用
+`["GB32960", "MQTT"]`；GPS 数据需要用户主动启用。
+
+仪表数据内部优先级固定为 `GB32960 > MQTT`，BI 不会发送 `MQTT > GB32960`。
+
+## 3. OneOS 必须增加的响应字段
+
+两个接口的每条车辆日里程结果都需要增加：
+
+```json
+{
+  "sourceProtocol": "GB32960"
+}
+```
+
+字段规则：
+
+1. 有有效里程数据时，只能返回 `GB32960`、`MQTT` 或 `JT808`。
+2. 返回值必须是本条结果实际采用的协议，不能返回车辆支持的协议列表，也不能返回请求中的第一项作为固定值。
+3. 无有效数据、`status="NO_DATA"` 时返回 `null`。
+4. `sourceProtocol` 对应关系：
+   - `GB32960`、`MQTT`：BI 显示为“仪表数据”；
+   - `JT808`：BI 显示为“GPS数据”。
+5. 如果 `sourceProtocol` 不在本次请求的 `protocolPriority` 中，应视为接口错误。
+
+响应示例：
+
+```json
+{
+  "code": "SUCCESS",
+  "message": "success",
+  "data": [
+    {
+      "vin": "LMRK...",
+      "plateNumber": "粤A00001F",
+      "date": "2026-07-23",
+      "dailyMileageKm": 182.437,
+      "totalMileageKm": 12345.678,
+      "sourceProtocol": "GB32960",
+      "dataTime": "2026-07-23T10:35:42+08:00",
+      "updatedAt": "2026-07-23T10:35:46+08:00",
+      "status": "NORMAL"
+    }
+  ],
+  "traceId": "..."
+}
+```
+
+## 4. 逐车逐日选源规则
+
+OneOS 需要针对每辆车、每个自然日独立执行以下逻辑：
+
+1. 按 `protocolPriority` 从前到后检查数据源。
+2. 找到第一份有效数据后立即使用，不再混用低优先级协议的数据。
+3. 有效数据必须满足现有里程质量规则，包括里程非空、非负且数据状态有效。
+4. 高优先级协议无有效数据时，才能降级到下一个已启用协议。
+5. 所有已启用协议均无有效数据时，返回：
+
+```json
+{
+  "dailyMileageKm": null,
+  "sourceProtocol": null,
+  "status": "NO_DATA"
+}
+```
+
+6. 真实零里程必须返回：
+
+```json
+{
+  "dailyMileageKm": 0,
+  "sourceProtocol": "实际采用的协议",
+  "status": "NORMAL"
+}
+```
+
+区间查询必须逐日选源，不能先按一个协议汇总整个区间后再切换协议。
+
+## 5. 验收用例
+
+OneOS 修改完成后，至少提供一辆在同一天同时存在 32960、MQTT、JT808 数据的测试车辆，以及一辆只有 MQTT 数据的测试车辆。
+
+| 用例 | 请求优先级 | 必须满足的结果 |
+| --- | --- | --- |
+| 仪表优先 | `GB32960, MQTT, JT808` | 同时有三种数据时采用 GB32960，`sourceProtocol="GB32960"` |
+| GPS 优先 | `JT808, GB32960, MQTT` | 同时有三种数据时采用 JT808，`sourceProtocol="JT808"` |
+| 仅仪表 | `GB32960, MQTT` | 不得返回 JT808；32960 缺失时允许降级到 MQTT |
+| 仅 GPS | `JT808` | 不得返回 GB32960 或 MQTT |
+| 32960 降级 | `GB32960, MQTT` | 只有 MQTT 有效时返回 MQTT，`sourceProtocol="MQTT"` |
+| 禁用验证 | `JT808` | 即使仪表数据存在，也不能回退到仪表数据 |
+| 无数据 | 任一合法组合 | 返回 `dailyMileageKm=null`、`sourceProtocol=null`、`status="NO_DATA"` |
+| 真实零里程 | 任一合法组合 | 返回 `dailyMileageKm=0`、实际 `sourceProtocol`、`status="NORMAL"` |
+| 单日接口 | 四种组合分别测试 | 请求成功且选源、来源字段符合规则 |
+| 区间接口 | 四种组合分别测试 | 每辆车每天独立选源，分页无重复、无漏行 |
+| 兼容性 | 不传 `protocolPriority` | 原有调用方式和响应语义保持不变 |
+
+## 6. 交付和联调要求
+
+1. 公网 `https://open.d.lnoneos.com` 和 ECS 内网地址同时发布相同能力。
+2. 发布后提供接口版本或发布日期、测试车辆、测试日期及对应协议数据情况。
+3. 提供四种合法组合的请求和响应样例。
+4. 提供一组禁用协议的验证结果，证明未启用协议不会被回退使用。
+5. 每个成功和失败响应均返回 `traceId`，便于双方定位问题。
+
+完成标准：两个接口均支持 `protocolPriority`，每条结果准确返回 `sourceProtocol`，四种 BI 模式全部通过上述验收用例。

package-lock.json

@@ -1,13 +1,14 @@
 {
   "name": "ln-bi",
-  "version": "1.1.6",
+  "version": "1.1.13",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "ln-bi",
-      "version": "1.1.6",
+      "version": "1.1.13",
       "dependencies": {
+        "@amap/amap-jsapi-loader": "^1.0.1",
         "@hono/node-server": "^1.13.0",
         "@types/jsonwebtoken": "^9.0.10",
         "ali-oss": "^6.23.0",
@@ -17,6 +18,7 @@
         "lucide-react": "^0.546.0",
         "motion": "^12.23.24",
         "mysql2": "^3.11.0",
+        "pg": "^8.22.0",
         "react": "^19.0.0",
         "react-dom": "^19.0.0",
         "recharts": "^3.8.1",
@@ -27,6 +29,7 @@
         "@tailwindcss/vite": "^4.1.14",
         "@types/ali-oss": "^6.23.3",
         "@types/node": "^22.14.0",
+        "@types/pg": "^8.20.0",
         "@types/react": "^19.0.0",
         "@types/react-dom": "^19.0.0",
         "@vitejs/plugin-react": "^5.0.4",
@@ -36,6 +39,12 @@
         "vite": "^6.2.0"
       }
     },
+    "node_modules/@amap/amap-jsapi-loader": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/@amap/amap-jsapi-loader/-/amap-jsapi-loader-1.0.1.tgz",
+      "integrity": "sha512-nPyLKt7Ow/ThHLkSvn2etQlUzqxmTVgK7bIgwdBRTg2HK5668oN7xVxkaiRe3YZEzGzfV2XgH5Jmu2T73ljejw==",
+      "license": "MIT"
+    },
     "node_modules/@babel/code-frame": {
       "version": "7.29.0",
       "resolved": "https://registry.npmjs.org/@babel/code-frame/-/code-frame-7.29.0.tgz",
@@ -1620,6 +1629,18 @@
         "undici-types": "~6.21.0"
       }
     },
+    "node_modules/@types/pg": {
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/@types/pg/-/pg-8.20.0.tgz",
+      "integrity": "sha512-bEPFOaMAHTEP1EzpvHTbmwR8UsFyHSKsRisLIHVMXnpNefSbGA1bD6CVy+qKjGSqmZqNqBDV2azOBo8TgkcVow==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@types/node": "*",
+        "pg-protocol": "*",
+        "pg-types": "^2.2.0"
+      }
+    },
     "node_modules/@types/react": {
       "version": "19.2.14",
       "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.14.tgz",
@@ -3521,6 +3542,95 @@
         "through": "~2.3"
       }
     },
+    "node_modules/pg": {
+      "version": "8.22.0",
+      "resolved": "https://registry.npmjs.org/pg/-/pg-8.22.0.tgz",
+      "integrity": "sha512-8wih1vVIBMxoUM2oB4soJsD9tDnDpLv4OXBJ+EJzFsvycD+lfyIreC2gGHq78f8jbLLt+bvlPTFdFZfJkOuzAA==",
+      "license": "MIT",
+      "dependencies": {
+        "pg-connection-string": "^2.14.0",
+        "pg-pool": "^3.14.0",
+        "pg-protocol": "^1.15.0",
+        "pg-types": "2.2.0",
+        "pgpass": "1.0.5"
+      },
+      "engines": {
+        "node": ">= 16.0.0"
+      },
+      "optionalDependencies": {
+        "pg-cloudflare": "^1.4.0"
+      },
+      "peerDependencies": {
+        "pg-native": ">=3.0.1"
+      },
+      "peerDependenciesMeta": {
+        "pg-native": {
+          "optional": true
+        }
+      }
+    },
+    "node_modules/pg-cloudflare": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/pg-cloudflare/-/pg-cloudflare-1.4.0.tgz",
+      "integrity": "sha512-Vo7z/6rrQYxpNRylp4Tlob2elzbh+N/MOQbxFVWCxS7oEx6jF53GTJFxK2WWpKuBRkmiin4Mt+xofFDjx09R0A==",
+      "license": "MIT",
+      "optional": true
+    },
+    "node_modules/pg-connection-string": {
+      "version": "2.14.0",
+      "resolved": "https://registry.npmjs.org/pg-connection-string/-/pg-connection-string-2.14.0.tgz",
+      "integrity": "sha512-XwWDGcLRGCXAR8F/AM5bG7Q+A3Wm2s6QeEjlOKZLlH3UYcguiqCWKyWXVag5TLTIjR7oOJUY8kcADaZgWPyLeg==",
+      "license": "MIT"
+    },
+    "node_modules/pg-int8": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/pg-int8/-/pg-int8-1.0.1.tgz",
+      "integrity": "sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw==",
+      "license": "ISC",
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/pg-pool": {
+      "version": "3.14.0",
+      "resolved": "https://registry.npmjs.org/pg-pool/-/pg-pool-3.14.0.tgz",
+      "integrity": "sha512-gKtPkFdQPU3DksooVLi9LsjZxrsBUZIpa+7aVx+LV5pNh0KzP4Zleud2po+ConrxbuXGBJ6Hfer6hdgpIBpBaw==",
+      "license": "MIT",
+      "peerDependencies": {
+        "pg": ">=8.0"
+      }
+    },
+    "node_modules/pg-protocol": {
+      "version": "1.15.0",
+      "resolved": "https://registry.npmjs.org/pg-protocol/-/pg-protocol-1.15.0.tgz",
+      "integrity": "sha512-cq9sECI5s0+uPUXjbz8ioyPJni6RzsRib0US67i5IoTZKw8fNeYlVE7u8F4dG7vEJJtc5wdD1K189lCCUwqWTQ==",
+      "license": "MIT"
+    },
+    "node_modules/pg-types": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/pg-types/-/pg-types-2.2.0.tgz",
+      "integrity": "sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==",
+      "license": "MIT",
+      "dependencies": {
+        "pg-int8": "1.0.1",
+        "postgres-array": "~2.0.0",
+        "postgres-bytea": "~1.0.0",
+        "postgres-date": "~1.0.4",
+        "postgres-interval": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/pgpass": {
+      "version": "1.0.5",
+      "resolved": "https://registry.npmjs.org/pgpass/-/pgpass-1.0.5.tgz",
+      "integrity": "sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug==",
+      "license": "MIT",
+      "dependencies": {
+        "split2": "^4.1.0"
+      }
+    },
     "node_modules/picocolors": {
       "version": "1.1.1",
       "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
@@ -3576,6 +3686,45 @@
         "node": "^10 || ^12 || >=14"
       }
     },
+    "node_modules/postgres-array": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/postgres-array/-/postgres-array-2.0.0.tgz",
+      "integrity": "sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4"
+      }
+    },
+    "node_modules/postgres-bytea": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/postgres-bytea/-/postgres-bytea-1.0.1.tgz",
+      "integrity": "sha512-5+5HqXnsZPE65IJZSMkZtURARZelel2oXUEO8rH83VS/hxH5vv1uHquPg5wZs8yMAfdv971IU+kcPUczi7NVBQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/postgres-date": {
+      "version": "1.0.7",
+      "resolved": "https://registry.npmjs.org/postgres-date/-/postgres-date-1.0.7.tgz",
+      "integrity": "sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/postgres-interval": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/postgres-interval/-/postgres-interval-1.2.0.tgz",
+      "integrity": "sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==",
+      "license": "MIT",
+      "dependencies": {
+        "xtend": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/process-nextick-args": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
@@ -3969,6 +4118,15 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/split2": {
+      "version": "4.2.0",
+      "resolved": "https://registry.npmjs.org/split2/-/split2-4.2.0.tgz",
+      "integrity": "sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==",
+      "license": "ISC",
+      "engines": {
+        "node": ">= 10.x"
+      }
+    },
     "node_modules/sql-escaper": {
       "version": "1.3.3",
       "resolved": "https://registry.npmjs.org/sql-escaper/-/sql-escaper-1.3.3.tgz",

package.json

@@ -1,7 +1,7 @@
 {
   "name": "ln-bi",
   "private": true,
-  "version": "1.1.6",
+  "version": "1.1.13",
   "type": "module",
   "scripts": {
     "dev": "concurrently -n server,client -c blue,green \"npm run dev:server\" \"npm run dev:client\"",
@@ -12,6 +12,7 @@
     "lint": "tsc --noEmit"
   },
   "dependencies": {
+    "@amap/amap-jsapi-loader": "^1.0.1",
     "@hono/node-server": "^1.13.0",
     "@types/jsonwebtoken": "^9.0.10",
     "ali-oss": "^6.23.0",
@@ -21,6 +22,7 @@
     "lucide-react": "^0.546.0",
     "motion": "^12.23.24",
     "mysql2": "^3.11.0",
+    "pg": "^8.22.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "recharts": "^3.8.1",
@@ -31,6 +33,7 @@
     "@tailwindcss/vite": "^4.1.14",
     "@types/ali-oss": "^6.23.3",
     "@types/node": "^22.14.0",
+    "@types/pg": "^8.20.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^5.0.4",

src/App.tsx

@@ -1,5 +1,5 @@
 import { lazy, Suspense, useEffect, useMemo, useState } from "react";
-import { Truck, Route, Activity, Fuel, BatteryCharging, Receipt } from "lucide-react";
+import { Truck, Route, Activity, Fuel, BatteryCharging, Receipt, MapPinned } from "lucide-react";
 import { Shell, type ModuleConfig } from "./components/Shell";
 import AuthProvider from "./auth/AuthProvider";
 import { useAuth } from "./auth/useAuth";
@@ -15,6 +15,8 @@ const ElectricModule = lazy(() => import("./modules/energy/ElectricModule"));
 const EtcModule = lazy(() => import("./modules/energy/EtcModule"));
 const EleImportPage = lazy(() => import("./modules/ele/EleImportPage"));
 const FeedbackAdminPage = lazy(() => import("./modules/admin/FeedbackAdminPage"));
+const VehicleHeatmapModule = lazy(() => import("./modules/vehicle-heatmap/VehicleHeatmapModule"));
+const HydrogenHeatmapModule = lazy(() => import("./modules/hydrogen-heatmap/HydrogenHeatmapModule"));
 
 const ASSETS_MODULE: ModuleConfig = {
   id: "assets",
@@ -30,6 +32,13 @@ const MILEAGE_MODULE: ModuleConfig = {
   component: MileageModule,
 };
 
+const VEHICLE_HEATMAP_MODULE: ModuleConfig = {
+  id: "vehicle-heatmap",
+  label: "车辆",
+  icon: MapPinned,
+  component: VehicleHeatmapModule,
+};
+
 const SCHEDULING_MODULE: ModuleConfig = {
   id: "scheduling",
   label: "智能调度",
@@ -44,6 +53,13 @@ const HYDROGEN_MODULE: ModuleConfig = {
   component: HydrogenModule,
 };
 
+const HYDROGEN_HEATMAP_MODULE: ModuleConfig = {
+  id: "hydrogen-heatmap",
+  label: "加氢",
+  icon: MapPinned,
+  component: HydrogenHeatmapModule,
+};
+
 const ELECTRIC_MODULE: ModuleConfig = {
   id: "electric",
   label: "电能",
@@ -138,7 +154,16 @@ function AuthGate() {
     if (pathSet === "energy") {
       return [HYDROGEN_MODULE, ELECTRIC_MODULE, ETC_MODULE];
     }
-    const result: ModuleConfig[] = [ASSETS_MODULE, MILEAGE_MODULE];
+    const heatmapChildren = canAccessEnergy(user?.roles)
+      ? [HYDROGEN_HEATMAP_MODULE, VEHICLE_HEATMAP_MODULE]
+      : [VEHICLE_HEATMAP_MODULE];
+    const heatmapModule: ModuleConfig = {
+      id: "heatmap",
+      label: "热力图",
+      icon: MapPinned,
+      children: heatmapChildren,
+    };
+    const result: ModuleConfig[] = [ASSETS_MODULE, MILEAGE_MODULE, heatmapModule];
     if (canAccessScheduling(user?.roles)) result.push(SCHEDULING_MODULE);
     return result;
   }, [pathSet, user?.roles]);

src/auth/api-client.test.ts

@@ -0,0 +1,99 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  ApiRequestError,
+  _clearApiClientInflightForTests,
+  fetchJson,
+  setTokenGetter,
+} from './api-client.js';
+
+function jsonResponse(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+test('deduplicates concurrent GET requests for the same URL and token', async () => {
+  const originalFetch = globalThis.fetch;
+  let calls = 0;
+  let resolveFetch: ((response: Response) => void) | undefined;
+  globalThis.fetch = ((_: string | URL | Request, init?: RequestInit) => {
+    calls += 1;
+    assert.equal(new Headers(init?.headers).get('authorization'), 'Bearer test-token');
+    return new Promise<Response>(resolve => { resolveFetch = resolve; });
+  }) as typeof fetch;
+  setTokenGetter(() => 'test-token');
+  _clearApiClientInflightForTests();
+
+  try {
+    const first = fetchJson<{ value: number }>('/api/test');
+    const second = fetchJson<{ value: number }>('/api/test');
+    assert.equal(calls, 1);
+    resolveFetch?.(jsonResponse({ value: 42 }));
+    assert.deepEqual(await first, { value: 42 });
+    assert.deepEqual(await second, { value: 42 });
+  } finally {
+    globalThis.fetch = originalFetch;
+    setTokenGetter(() => null);
+    _clearApiClientInflightForTests();
+  }
+});
+
+test('does not retain a failed GET request', async () => {
+  const originalFetch = globalThis.fetch;
+  let calls = 0;
+  globalThis.fetch = (async () => {
+    calls += 1;
+    if (calls === 1) throw new Error('network down');
+    return jsonResponse({ ok: true });
+  }) as typeof fetch;
+  setTokenGetter(() => null);
+  _clearApiClientInflightForTests();
+
+  try {
+    await assert.rejects(fetchJson('/api/retry'), /network down/);
+    assert.deepEqual(await fetchJson('/api/retry'), { ok: true });
+    assert.equal(calls, 2);
+  } finally {
+    globalThis.fetch = originalFetch;
+    _clearApiClientInflightForTests();
+  }
+});
+
+test('surfaces structured API errors without retaining the failed request', async () => {
+  const originalFetch = globalThis.fetch;
+  let calls = 0;
+  globalThis.fetch = (async () => {
+    calls += 1;
+    if (calls > 1) return jsonResponse({ ok: true });
+    return new Response(JSON.stringify({
+      error: '当前无法读取氢能业务数据，请稍后重试',
+      code: 'HYDROGEN_SOURCE_UNAVAILABLE',
+      retryable: true,
+    }), {
+      status: 503,
+      headers: { 'content-type': 'application/json' },
+    });
+  }) as typeof fetch;
+  _clearApiClientInflightForTests();
+
+  try {
+    await assert.rejects(
+      fetchJson('/api/energy/hydrogen/overview'),
+      (error: unknown) => {
+        assert.ok(error instanceof ApiRequestError);
+        assert.equal(error.message, '当前无法读取氢能业务数据，请稍后重试');
+        assert.equal(error.status, 503);
+        assert.equal(error.code, 'HYDROGEN_SOURCE_UNAVAILABLE');
+        assert.equal(error.retryable, true);
+        return true;
+      },
+    );
+    assert.deepEqual(await fetchJson('/api/energy/hydrogen/overview'), { ok: true });
+    assert.equal(calls, 2);
+  } finally {
+    globalThis.fetch = originalFetch;
+    _clearApiClientInflightForTests();
+  }
+});

src/auth/api-client.ts

@@ -1,13 +1,34 @@
 /** 全局认证 fetch 客户端 */
 
 let tokenGetter: () => string | null = () => null;
+const inflightGetRequests = new Map<string, Promise<unknown>>();
+
+export class ApiRequestError extends Error {
+  readonly status: number;
+  readonly code: string | null;
+  readonly retryable: boolean;
+
+  constructor(message: string, status: number, code: string | null, retryable: boolean) {
+    super(message);
+    this.name = 'ApiRequestError';
+    this.status = status;
+    this.code = code;
+    this.retryable = retryable;
+  }
+}
+
+interface ApiErrorPayload {
+  error?: unknown;
+  message?: unknown;
+  code?: unknown;
+  retryable?: unknown;
+}
 
 export function setTokenGetter(fn: () => string | null) {
   tokenGetter = fn;
 }
 
-export async function fetchJson<T>(url: string, options?: RequestInit): Promise<T> {
-  const token = tokenGetter();
+async function executeJsonRequest<T>(url: string, options: RequestInit | undefined, token: string | null): Promise<T> {
   const res = await fetch(url, {
     ...options,
     headers: {
@@ -19,6 +40,44 @@ export async function fetchJson<T>(url: string, options?: RequestInit): Promise<
     window.dispatchEvent(new CustomEvent('auth:unauthorized'));
     throw new Error('Unauthorized');
   }
-  if (!res.ok) throw new Error(`API error: ${res.status} ${res.statusText}`);
+  if (!res.ok) {
+    let payload: ApiErrorPayload = {};
+    try {
+      const parsed: unknown = await res.json();
+      if (typeof parsed === 'object' && parsed !== null) payload = parsed as ApiErrorPayload;
+    } catch {
+      payload = {};
+    }
+    const message = typeof payload?.error === 'string'
+      ? payload.error
+      : typeof payload?.message === 'string'
+        ? payload.message
+        : `请求失败（${res.status}）`;
+    const code = typeof payload?.code === 'string' ? payload.code : null;
+    const retryable = typeof payload?.retryable === 'boolean' ? payload.retryable : res.status >= 500;
+    throw new ApiRequestError(message, res.status, code, retryable);
+  }
   return res.json();
 }
+
+export async function fetchJson<T>(url: string, options?: RequestInit): Promise<T> {
+  const token = tokenGetter();
+  const method = (options?.method || 'GET').toUpperCase();
+  const canDedupe = method === 'GET' && options?.body == null && options?.signal == null;
+  if (!canDedupe) return executeJsonRequest<T>(url, options, token);
+
+  const key = `${token || 'anonymous'}:${url}`;
+  const existing = inflightGetRequests.get(key) as Promise<T> | undefined;
+  if (existing) return existing;
+
+  const request = executeJsonRequest<T>(url, options, token)
+    .finally(() => {
+      if (inflightGetRequests.get(key) === request) inflightGetRequests.delete(key);
+    });
+  inflightGetRequests.set(key, request);
+  return request;
+}
+
+export function _clearApiClientInflightForTests(): void {
+  inflightGetRequests.clear();
+}

src/components/BiHeaderActions.tsx

@@ -0,0 +1,12 @@
+import type { MetricDomain } from '../shared/analytics/catalog';
+import DataSourceStatusButton from './DataSourceStatusButton';
+import MetricCatalogButton from './MetricCatalogButton';
+
+export default function BiHeaderActions({ domain }: { domain: MetricDomain }) {
+  return (
+    <>
+      <DataSourceStatusButton domain={domain} />
+      <MetricCatalogButton domain={domain} />
+    </>
+  );
+}

src/components/DataSourceStatusButton.tsx

@@ -0,0 +1,228 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { Activity, AlertTriangle, CheckCircle2, Clock3, Loader2, RefreshCw, X } from 'lucide-react';
+import { AnimatePresence, motion } from 'motion/react';
+import { fetchJson } from '../auth/api-client';
+import type { MetricDomain } from '../shared/analytics/catalog';
+import {
+  BI_SOURCE_BY_DOMAIN,
+  type DataSourceId,
+  type DataSourceState,
+} from '../shared/analytics/source-status';
+
+interface SourceTelemetry {
+  source: DataSourceId;
+  state: DataSourceState;
+  attempts: number;
+  failures: number;
+  failureRate: number | null;
+  lastSuccessAt: string | null;
+  lastFailureAt: string | null;
+}
+
+interface SourceTelemetryResponse {
+  semantics: 'observed-requests';
+  windowSize: number;
+  processStartedAt: string;
+  checkedAt: string;
+  sources: SourceTelemetry[];
+}
+
+const STATE_META = {
+  available: {
+    label: '最近请求成功',
+    icon: CheckCircle2,
+    className: 'border-emerald-200 bg-emerald-50 text-emerald-700',
+  },
+  failing: {
+    label: '最近请求失败',
+    icon: AlertTriangle,
+    className: 'border-rose-200 bg-rose-50 text-rose-700',
+  },
+  unobserved: {
+    label: '启动后尚无真实请求',
+    icon: Clock3,
+    className: 'border-slate-200 bg-slate-50 text-slate-600',
+  },
+} as const;
+
+function formatObservedAt(value: string | null): string {
+  if (!value) return '暂无';
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return new Intl.DateTimeFormat('zh-CN', {
+    timeZone: 'Asia/Shanghai',
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+  }).format(date);
+}
+
+export default function DataSourceStatusButton({ domain }: { domain: MetricDomain }) {
+  const [open, setOpen] = useState(false);
+  const [data, setData] = useState<SourceTelemetryResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const focusCloseButton = useCallback((node: HTMLButtonElement | null) => node?.focus(), []);
+  const sourceMeta = BI_SOURCE_BY_DOMAIN[domain];
+  const source = useMemo(
+    () => data?.sources.find(item => item.source === sourceMeta.source) || null,
+    [data, sourceMeta.source],
+  );
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      setData(await fetchJson<SourceTelemetryResponse>('/api/analytics/data-sources'));
+    } catch (loadError) {
+      setError(loadError instanceof Error ? loadError.message : String(loadError));
+    } finally {
+      setLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    if (open) void load();
+  }, [load, open]);
+
+  useEffect(() => {
+    if (!open) return undefined;
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setOpen(false);
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.body.style.overflow = previousOverflow;
+      document.removeEventListener('keydown', handleKeyDown);
+      triggerRef.current?.focus();
+    };
+  }, [open]);
+
+  const stateMeta = source ? STATE_META[source.state] : STATE_META.unobserved;
+  const StateIcon = stateMeta.icon;
+  const triggerTone = source?.state === 'failing'
+    ? 'border-rose-200 bg-rose-50 text-rose-600'
+    : source?.state === 'available'
+      ? 'border-emerald-200 bg-emerald-50 text-emerald-600'
+      : 'border-slate-200 bg-white text-slate-500';
+
+  return (
+    <>
+      <button
+        ref={triggerRef}
+        type="button"
+        onClick={() => setOpen(true)}
+        className={`inline-flex h-9 w-9 items-center justify-center rounded-xl border shadow-sm transition-colors hover:border-blue-200 hover:bg-blue-50 hover:text-blue-600 ${triggerTone}`}
+        aria-label="查看数据源运行状态"
+        title="数据源运行状态"
+      >
+        <Activity size={16} />
+      </button>
+
+      {createPortal(<AnimatePresence>
+        {open ? (
+          <div className="fixed inset-0 z-[10020]">
+            <motion.button
+              type="button"
+              aria-label="点击遮罩关闭数据源状态"
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+              onClick={() => setOpen(false)}
+              className="absolute inset-0 h-full w-full bg-slate-950/35 backdrop-blur-[2px]"
+            />
+            <motion.section
+              role="dialog"
+              aria-modal="true"
+              aria-labelledby={`${domain}-source-status-title`}
+              initial={{ opacity: 0, x: 32 }}
+              animate={{ opacity: 1, x: 0 }}
+              exit={{ opacity: 0, x: 32 }}
+              transition={{ duration: 0.2, ease: 'easeOut' }}
+              className="absolute inset-y-0 right-0 flex w-full max-w-sm flex-col bg-white shadow-2xl"
+            >
+              <header className="flex shrink-0 items-center gap-3 border-b border-slate-100 px-4 py-4">
+                <span className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-blue-50 text-blue-600 ring-1 ring-blue-100">
+                  <Activity size={17} />
+                </span>
+                <div className="min-w-0 flex-1">
+                  <h2 id={`${domain}-source-status-title`} className="text-sm font-black text-slate-900">数据源运行状态</h2>
+                  <p className="mt-0.5 truncate text-[10px] font-bold text-slate-400">{sourceMeta.label}</p>
+                </div>
+                <button
+                  type="button"
+                  onClick={() => void load()}
+                  disabled={loading}
+                  className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border border-slate-200 text-slate-500 hover:bg-slate-50 disabled:opacity-50"
+                  aria-label="刷新数据源状态"
+                  title="刷新"
+                >
+                  <RefreshCw size={15} className={loading ? 'animate-spin' : ''} />
+                </button>
+                <button
+                  ref={focusCloseButton}
+                  type="button"
+                  onClick={() => setOpen(false)}
+                  className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border border-slate-200 text-slate-500 hover:bg-slate-50"
+                  aria-label="关闭数据源状态"
+                  title="关闭"
+                >
+                  <X size={16} />
+                </button>
+              </header>
+
+              <div className="min-h-0 flex-1 overflow-y-auto px-4 py-5">
+                {error ? (
+                  <div className="rounded-lg border border-rose-100 bg-rose-50 p-3 text-xs font-bold text-rose-700">{error}</div>
+                ) : loading && !data ? (
+                  <div className="flex items-center justify-center gap-2 py-16 text-xs font-bold text-slate-400">
+                    <Loader2 size={16} className="animate-spin" />正在读取运行状态
+                  </div>
+                ) : source ? (
+                  <>
+                    <div className={`flex items-center gap-2 rounded-lg border px-3 py-3 ${stateMeta.className}`}>
+                      <StateIcon size={18} />
+                      <span className="text-sm font-black">{stateMeta.label}</span>
+                    </div>
+                    <dl className="mt-5 divide-y divide-slate-100 border-y border-slate-100 text-xs">
+                      <div className="flex items-center justify-between gap-4 py-3">
+                        <dt className="font-bold text-slate-400">观察窗口</dt>
+                        <dd className="font-black text-slate-700">最近 {data?.windowSize ?? 100} 次真实读取</dd>
+                      </div>
+                      <div className="flex items-center justify-between gap-4 py-3">
+                        <dt className="font-bold text-slate-400">请求 / 失败</dt>
+                        <dd className="font-black tabular-nums text-slate-700">{source.attempts} / {source.failures}</dd>
+                      </div>
+                      <div className="flex items-center justify-between gap-4 py-3">
+                        <dt className="font-bold text-slate-400">滚动失败率</dt>
+                        <dd className="font-black tabular-nums text-slate-700">{source.failureRate == null ? '暂无' : `${(source.failureRate * 100).toFixed(1)}%`}</dd>
+                      </div>
+                      <div className="flex items-center justify-between gap-4 py-3">
+                        <dt className="font-bold text-slate-400">最后成功</dt>
+                        <dd className="font-black tabular-nums text-slate-700">{formatObservedAt(source.lastSuccessAt)}</dd>
+                      </div>
+                      <div className="flex items-center justify-between gap-4 py-3">
+                        <dt className="font-bold text-slate-400">最后失败</dt>
+                        <dd className="font-black tabular-nums text-slate-700">{formatObservedAt(source.lastFailureAt)}</dd>
+                      </div>
+                    </dl>
+                    <p className="mt-5 text-[10px] font-bold leading-relaxed text-slate-400">
+                      状态来自本进程真实数据读取；缓存命中不计入，最近成功不代表持续可达。
+                    </p>
+                  </>
+                ) : null}
+              </div>
+            </motion.section>
+          </div>
+        ) : null}
+      </AnimatePresence>, document.body)}
+    </>
+  );
+}

src/components/MetricCatalogButton.tsx

@@ -0,0 +1,166 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+import { BookOpen, Database, Loader2, X } from 'lucide-react';
+import { AnimatePresence, motion } from 'motion/react';
+import { fetchJson } from '../auth/api-client';
+import type { MetricDefinition, MetricDomain } from '../shared/analytics/catalog';
+
+interface MetricCatalogResponse {
+  catalogVersion: number;
+  domains: MetricDomain[];
+  metrics: MetricDefinition[];
+}
+
+const AGGREGATION_LABEL: Record<MetricDefinition['aggregation'], string> = {
+  sum: '求和',
+  count: '计数',
+  derived: '派生计算',
+  'weighted-ratio': '加权比率',
+  'distinct-count': '去重计数',
+  latest: '取最新值',
+};
+
+const TIME_LABEL: Record<MetricDefinition['timeSemantics'], string> = {
+  flow: '区间流量',
+  snapshot: '时点快照',
+  freshness: '数据新鲜度',
+};
+
+export default function MetricCatalogButton({ domain }: { domain: MetricDomain }) {
+  const [open, setOpen] = useState(false);
+  const [data, setData] = useState<MetricCatalogResponse | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const triggerRef = useRef<HTMLButtonElement>(null);
+  const closeRef = useRef<HTMLButtonElement>(null);
+  const setCloseRef = useCallback((node: HTMLButtonElement | null) => {
+    closeRef.current = node;
+    node?.focus();
+  }, []);
+
+  useEffect(() => {
+    if (!open || data) return undefined;
+    let cancelled = false;
+    setError(null);
+    fetchJson<MetricCatalogResponse>(`/api/analytics/metrics?domain=${domain}`)
+      .then(result => { if (!cancelled) setData(result); })
+      .catch(e => { if (!cancelled) setError(e instanceof Error ? e.message : String(e)); });
+    return () => { cancelled = true; };
+  }, [open, data, domain]);
+
+  useEffect(() => {
+    if (!open) return undefined;
+    const previousOverflow = document.body.style.overflow;
+    document.body.style.overflow = 'hidden';
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setOpen(false);
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.body.style.overflow = previousOverflow;
+      document.removeEventListener('keydown', handleKeyDown);
+      triggerRef.current?.focus();
+    };
+  }, [open]);
+
+  return (
+    <>
+      <button
+        ref={triggerRef}
+        type="button"
+        onClick={() => setOpen(true)}
+        className="inline-flex h-9 w-9 items-center justify-center rounded-xl border border-slate-200 bg-white text-slate-500 shadow-sm transition-colors hover:border-blue-200 hover:bg-blue-50 hover:text-blue-600"
+        aria-label="查看指标口径"
+        title="指标口径"
+      >
+        <BookOpen size={16} />
+      </button>
+
+      {createPortal(<AnimatePresence>
+        {open && (
+          <div className="fixed inset-0 z-[10020]">
+            <motion.button
+              type="button"
+              aria-label="点击遮罩关闭指标口径"
+              initial={{ opacity: 0 }}
+              animate={{ opacity: 1 }}
+              exit={{ opacity: 0 }}
+              onClick={() => setOpen(false)}
+              className="absolute inset-0 h-full w-full bg-slate-950/35 backdrop-blur-[2px]"
+            />
+            <motion.section
+              role="dialog"
+              aria-modal="true"
+              aria-labelledby={`${domain}-metric-catalog-title`}
+              initial={{ opacity: 0, x: 32 }}
+              animate={{ opacity: 1, x: 0 }}
+              exit={{ opacity: 0, x: 32 }}
+              transition={{ duration: 0.2, ease: 'easeOut' }}
+              className="absolute inset-y-0 right-0 flex w-full max-w-lg flex-col bg-white shadow-2xl"
+            >
+              <header className="flex shrink-0 items-center gap-3 border-b border-slate-100 px-4 py-4 md:px-5">
+                <span className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg bg-blue-50 text-blue-600 ring-1 ring-blue-100">
+                  <BookOpen size={17} />
+                </span>
+                <div className="min-w-0 flex-1">
+                  <h2 id={`${domain}-metric-catalog-title`} className="text-sm font-black text-slate-900">指标口径</h2>
+                  <p className="mt-0.5 text-[10px] font-bold text-slate-400">
+                    {data ? `目录版本 v${data.catalogVersion} · ${data.metrics.length} 项指标` : '读取已发布指标目录'}
+                  </p>
+                </div>
+                <button
+                  ref={setCloseRef}
+                  type="button"
+                  onClick={() => setOpen(false)}
+                  className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border border-slate-200 text-slate-500 hover:bg-slate-50 hover:text-slate-800"
+                  aria-label="关闭指标口径"
+                  title="关闭"
+                >
+                  <X size={16} />
+                </button>
+              </header>
+
+              <div className="min-h-0 flex-1 overflow-y-auto px-4 py-2 md:px-5">
+                {error ? (
+                  <div className="my-4 rounded-lg border border-rose-100 bg-rose-50 p-3 text-xs font-bold text-rose-700">{error}</div>
+                ) : !data ? (
+                  <div className="flex items-center justify-center gap-2 py-16 text-xs font-bold text-slate-400">
+                    <Loader2 size={16} className="animate-spin" />正在加载指标口径
+                  </div>
+                ) : (
+                  data.metrics.map(metric => (
+                    <article key={metric.id} className="border-b border-slate-100 py-4 last:border-b-0">
+                      <div className="flex flex-wrap items-start justify-between gap-2">
+                        <div>
+                          <h3 className="text-sm font-black text-slate-900">{metric.label}</h3>
+                          <div className="mt-1 font-mono text-[9px] font-bold text-slate-400">{metric.id}</div>
+                        </div>
+                        <div className="flex flex-wrap gap-1 text-[9px] font-black">
+                          <span className="rounded bg-blue-50 px-1.5 py-1 text-blue-600">{AGGREGATION_LABEL[metric.aggregation]}</span>
+                          <span className="rounded bg-slate-100 px-1.5 py-1 text-slate-600">{TIME_LABEL[metric.timeSemantics]}</span>
+                          <span className="rounded bg-emerald-50 px-1.5 py-1 text-emerald-700">{metric.unit}</span>
+                        </div>
+                      </div>
+                      <p className="mt-3 text-[11px] font-bold leading-relaxed text-slate-600">{metric.description}</p>
+                      <div className="mt-3 rounded-lg bg-slate-950 px-3 py-2 font-mono text-[10px] leading-relaxed text-slate-200 break-words">
+                        {metric.formula}
+                      </div>
+                      <div className="mt-3 flex items-start gap-2 text-[10px] font-bold text-slate-500">
+                        <Database size={12} className="mt-0.5 shrink-0 text-slate-400" />
+                        <span className="break-words">{metric.sources.join(' · ')}</span>
+                      </div>
+                      <div className="mt-2 flex flex-wrap gap-1">
+                        {metric.dimensions.map(dimension => (
+                          <span key={dimension} className="rounded border border-slate-200 px-1.5 py-0.5 text-[9px] font-bold text-slate-500">{dimension}</span>
+                        ))}
+                      </div>
+                    </article>
+                  ))
+                )}
+              </div>
+            </motion.section>
+          </div>
+        )}
+      </AnimatePresence>, document.body)}
+    </>
+  );
+}

src/components/Shell.tsx

@@ -1,6 +1,6 @@
 import { useState, useEffect, useMemo, type ComponentType, type ElementType, Suspense } from 'react';
 import { motion } from 'motion/react';
-import { Building2, ShieldCheck } from 'lucide-react';
+import { Building2, ChevronRight, ShieldCheck } from 'lucide-react';
 import { useAuth } from '../auth/useAuth';
 import { DemoModeProvider } from './Blur';
 import FeedbackFab from './FeedbackFab';
@@ -11,7 +11,12 @@ export interface ModuleConfig {
   id: string;
   label: string;
   icon: ComponentType<{ size?: number; className?: string }>;
-  component: ElementType;
+  component?: ElementType;
+  children?: ModuleConfig[];
+}
+
+function flattenModules(modules: ModuleConfig[]): ModuleConfig[] {
+  return modules.flatMap((module) => module.children ?? [module]);
 }
 
 /** hash 一级段（`#<id>` 或 `#<id>/<sub>` 都只取 id） */
@@ -31,16 +36,27 @@ function getHashModule(modules: ModuleConfig[]): string {
 }
 
 export function Shell({ modules }: { modules: ModuleConfig[] }) {
-  const [activeModule, setActiveModule] = useState(() => getInitialModule(modules));
+  const flatModules = useMemo(() => flattenModules(modules), [modules]);
+  const [activeModule, setActiveModule] = useState(() => getInitialModule(flattenModules(modules)));
+  const [openGroupId, setOpenGroupId] = useState<string | null>(null);
 
   useEffect(() => {
     const onHashChange = () => {
-      const h = getHashModule(modules);
+      const h = getHashModule(flatModules);
       if (h) setActiveModule(h);
     };
     window.addEventListener('hashchange', onHashChange);
     return () => window.removeEventListener('hashchange', onHashChange);
-  }, [modules]);
+  }, [flatModules]);
+
+  useEffect(() => {
+    if (!openGroupId) return undefined;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setOpenGroupId(null);
+    };
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [openGroupId]);
 
   useEffect(() => {
     // 同步 hash 一段到当前模块：使用 replaceState 避免产生多余的 history 记录，
@@ -53,16 +69,20 @@ export function Shell({ modules }: { modules: ModuleConfig[] }) {
   }, [activeModule]);
 
   const switchModule = (id: string) => {
-    if (getHashHead() === id) return;
+    setOpenGroupId(null);
+    if (getHashHead() === id) {
+      setActiveModule(id);
+      return;
+    }
     const { pathname, search } = window.location;
     window.history.replaceState(null, '', `${pathname}${search}#${id}`);
     setActiveModule(id);
   };
 
-  const ActiveComponent = modules.find((m) => m.id === activeModule)?.component ?? modules[0]?.component;
+  const ActiveComponent = flatModules.find((module) => module.id === activeModule)?.component ?? flatModules[0]?.component;
 
   const { user } = useAuth();
-  const activeLabel = modules.find((m) => m.id === activeModule)?.label ?? '业务看板';
+  const activeLabel = flatModules.find((module) => module.id === activeModule)?.label ?? '业务看板';
   const watermarkText = useMemo(() => {
     const name = user?.userName || '未登录';
     const time = new Date().toLocaleString('zh-CN', { year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit', hour12: false }).replace(/\//g, '-');
@@ -87,29 +107,43 @@ export function Shell({ modules }: { modules: ModuleConfig[] }) {
         <div className="flex w-full flex-1 flex-col items-center gap-2">
           {modules.map((m) => {
             const Icon = m.icon;
-            const isActive = m.id === activeModule;
+            const isGroup = Boolean(m.children?.length);
+            const isActive = m.id === activeModule || Boolean(m.children?.some((child) => child.id === activeModule));
+            const isOpen = openGroupId === m.id;
             return (
-              <button
-                key={m.id}
-                onClick={() => switchModule(m.id)}
-                className={cn(
-                  'group relative flex h-16 w-16 flex-col items-center justify-center rounded-2xl text-[10px] font-black transition-all',
-                  isActive
-                    ? 'text-white'
-                    : 'text-slate-400 hover:bg-white/8 hover:text-white',
-                )}
-                title={m.label}
-              >
-                {isActive ? (
-                  <motion.span
-                    layoutId="desktop-shell-active"
-                    className="absolute inset-0 rounded-2xl bg-blue-600 shadow-lg shadow-blue-950/30"
-                    transition={{ type: 'spring', stiffness: 430, damping: 34 }}
-                  />
+              <div key={m.id} className="relative">
+                <button
+                  type="button"
+                  onClick={() => isGroup ? setOpenGroupId((current) => current === m.id ? null : m.id) : switchModule(m.id)}
+                  aria-expanded={isGroup ? isOpen : undefined}
+                  aria-haspopup={isGroup ? 'menu' : undefined}
+                  className={cn(
+                    'group relative flex h-16 w-16 flex-col items-center justify-center rounded-2xl text-[10px] font-black transition-all',
+                    isActive ? 'text-white' : 'text-slate-400 hover:bg-white/8 hover:text-white',
+                  )}
+                  title={m.label}
+                >
+                  {isActive ? (
+                    <motion.span layoutId="desktop-shell-active" className="absolute inset-0 rounded-2xl bg-blue-600 shadow-lg shadow-blue-950/30" transition={{ type: 'spring', stiffness: 430, damping: 34 }} />
+                  ) : null}
+                  <Icon size={21} className="relative mb-1" />
+                  <span className="relative leading-tight">{m.label}</span>
+                  {isGroup ? <ChevronRight size={11} className={cn('absolute right-1 top-1/2 -translate-y-1/2 transition-transform', isOpen && 'rotate-180')} /> : null}
+                </button>
+                {isGroup && isOpen ? (
+                  <div role="menu" aria-label={`${m.label}二级菜单`} className="absolute left-[calc(100%+12px)] top-1/2 w-36 -translate-y-1/2 rounded-2xl border border-slate-700 bg-slate-900 p-2 shadow-2xl shadow-slate-950/30">
+                    {m.children!.map((child) => {
+                      const ChildIcon = child.icon;
+                      const childActive = child.id === activeModule;
+                      return (
+                        <button key={child.id} type="button" role="menuitem" onClick={() => switchModule(child.id)} className={cn('flex h-11 w-full items-center gap-2 rounded-xl px-3 text-xs font-black transition-colors', childActive ? 'bg-blue-600 text-white' : 'text-slate-300 hover:bg-white/8 hover:text-white')}>
+                          <ChildIcon size={16} />{child.label}
+                        </button>
+                      );
+                    })}
+                  </div>
                 ) : null}
-                <Icon size={21} className="relative mb-1" />
-                <span className="relative leading-tight">{m.label}</span>
-              </button>
+              </div>
             );
           })}
         </div>
@@ -139,26 +173,38 @@ export function Shell({ modules }: { modules: ModuleConfig[] }) {
         <div className="grid gap-1" style={{ gridTemplateColumns: `repeat(${modules.length}, minmax(0, 1fr))` }}>
         {modules.map((m) => {
           const Icon = m.icon;
-          const isActive = m.id === activeModule;
+          const isGroup = Boolean(m.children?.length);
+          const isActive = m.id === activeModule || Boolean(m.children?.some((child) => child.id === activeModule));
+          const isOpen = openGroupId === m.id;
           return (
-            <button
-              key={m.id}
-              onClick={() => switchModule(m.id)}
-              className={cn(
-                'relative flex min-h-12 flex-col items-center justify-center gap-0.5 rounded-2xl text-[10px] font-black transition-colors',
-                isActive ? 'text-blue-700' : 'text-slate-400',
-              )}
-            >
-              {isActive ? (
-                <motion.span
-                  layoutId="mobile-shell-active"
-                  className="absolute inset-0 rounded-2xl bg-blue-50 ring-1 ring-blue-100"
-                  transition={{ type: 'spring', stiffness: 430, damping: 34 }}
-                />
+            <div key={m.id} className="relative flex justify-center">
+              <button
+                type="button"
+                onClick={() => isGroup ? setOpenGroupId((current) => current === m.id ? null : m.id) : switchModule(m.id)}
+                aria-expanded={isGroup ? isOpen : undefined}
+                aria-haspopup={isGroup ? 'menu' : undefined}
+                className={cn('relative flex min-h-12 w-full flex-col items-center justify-center gap-0.5 rounded-2xl text-[10px] font-medium transition-colors', isActive ? 'text-blue-700' : 'text-slate-400')}
+              >
+                {isActive ? (
+                  <motion.span layoutId="mobile-shell-active" className="absolute inset-0 rounded-2xl bg-blue-50 ring-1 ring-blue-100" transition={{ type: 'spring', stiffness: 430, damping: 34 }} />
+                ) : null}
+                <Icon size={20} className="relative" />
+                <span className="relative">{m.label}</span>
+              </button>
+              {isGroup && isOpen ? (
+                <div role="menu" aria-label={`${m.label}二级菜单`} className="absolute bottom-[calc(100%+14px)] left-1/2 w-36 -translate-x-1/2 rounded-2xl border border-slate-200 bg-white p-2 shadow-2xl shadow-slate-900/15">
+                  {m.children!.map((child) => {
+                    const ChildIcon = child.icon;
+                    const childActive = child.id === activeModule;
+                    return (
+                      <button key={child.id} type="button" role="menuitem" onClick={() => switchModule(child.id)} className={cn('flex h-11 w-full items-center gap-2 rounded-xl px-3 text-xs font-medium transition-colors', childActive ? 'bg-blue-50 text-blue-700' : 'text-slate-600 hover:bg-slate-50')}>
+                        <ChildIcon size={16} />{child.label}
+                      </button>
+                    );
+                  })}
+                </div>
               ) : null}
-              <Icon size={20} className="relative" />
-              <span className="relative">{m.label}</span>
-            </button>
+            </div>
           );
         })}
         </div>

src/components/ui/surface.tsx

@@ -1,5 +1,5 @@
 import { useState, type ComponentType, type ReactNode } from 'react';
-import { AlertCircle, Info, Loader2, SearchX, X } from 'lucide-react';
+import { AlertCircle, Info, Loader2, RefreshCw, SearchX, X } from 'lucide-react';
 import { AnimatePresence, motion } from 'motion/react';
 import { cn } from '../../lib/cn';
 
@@ -56,7 +56,7 @@ export function PageFrame({
                   </div>
                   <h1 className="mt-0.5 truncate text-base font-black tracking-tight text-slate-950 md:text-lg">{title}</h1>
                 </div>
-                {actions ? <div className="hidden shrink-0 items-center gap-2 md:flex">{actions}</div> : null}
+                {actions ? <div className="flex shrink-0 items-center gap-2">{actions}</div> : null}
                 {subtitle ? (
                   <button
                     type="button"
@@ -190,23 +190,51 @@ export function SegmentedNav<T extends string>({
   tabs,
   active,
   onChange,
+  idPrefix,
+  ariaLabel,
   className,
 }: {
   tabs: readonly { id: T; label: string; icon?: SurfaceIcon }[];
   active: T;
   onChange: (id: T) => void;
+  idPrefix: string;
+  ariaLabel: string;
   className?: string;
 }) {
+  const activateFromKeyboard = (event: React.KeyboardEvent<HTMLButtonElement>, currentIndex: number) => {
+    let nextIndex: number | null = null;
+    if (event.key === 'ArrowRight') nextIndex = (currentIndex + 1) % tabs.length;
+    if (event.key === 'ArrowLeft') nextIndex = (currentIndex - 1 + tabs.length) % tabs.length;
+    if (event.key === 'Home') nextIndex = 0;
+    if (event.key === 'End') nextIndex = tabs.length - 1;
+    if (nextIndex === null) return;
+    event.preventDefault();
+    const next = tabs[nextIndex];
+    onChange(next.id);
+    window.requestAnimationFrame(() => document.getElementById(`${idPrefix}-tab-${next.id}`)?.focus());
+  };
+
   return (
     <div className={cn('rounded-2xl border border-white/70 bg-white/90 p-1 shadow-sm backdrop-blur-xl', className)}>
-      <div className="grid gap-1" style={{ gridTemplateColumns: `repeat(${tabs.length}, minmax(0, 1fr))` }}>
-        {tabs.map(({ id, label, icon: Icon }) => {
+      <div
+        role="tablist"
+        aria-label={ariaLabel}
+        className="grid gap-1"
+        style={{ gridTemplateColumns: `repeat(${tabs.length}, minmax(0, 1fr))` }}
+      >
+        {tabs.map(({ id, label, icon: Icon }, index) => {
           const isActive = active === id;
           return (
             <button
               key={id}
+              id={`${idPrefix}-tab-${id}`}
               type="button"
+              role="tab"
+              aria-selected={isActive}
+              aria-controls={`${idPrefix}-panel-${id}`}
+              tabIndex={isActive ? 0 : -1}
               onClick={() => onChange(id)}
+              onKeyDown={event => activateFromKeyboard(event, index)}
               className={cn(
                 'relative flex min-h-10 items-center justify-center gap-1.5 rounded-xl px-2 text-[12px] font-black transition-colors',
                 isActive ? 'text-blue-700' : 'text-slate-400 hover:bg-slate-50 hover:text-slate-600',
@@ -233,9 +261,20 @@ export function SkeletonBlock({ className }: { className?: string }) {
   return <div className={cn('overflow-hidden rounded-xl bg-slate-100 shimmer', className)} />;
 }
 
-export function LoadingState({ label = '数据加载中' }: { label?: string }) {
+type StateVariant = 'card' | 'inline';
+
+export function LoadingState({
+  label = '数据加载中',
+  variant = 'card',
+}: {
+  label?: string;
+  variant?: StateVariant;
+}) {
   return (
-    <div className="rounded-2xl border border-slate-100 bg-white p-8 text-center shadow-sm">
+    <div className={cn(
+      'p-8 text-center',
+      variant === 'card' && 'rounded-2xl border border-slate-100 bg-white shadow-sm',
+    )}>
       <Loader2 className="mx-auto mb-3 animate-spin text-blue-500" size={22} />
       <div className="text-xs font-black text-slate-500">{label}</div>
     </div>
@@ -245,12 +284,17 @@ export function LoadingState({ label = '数据加载中' }: { label?: string })
 export function EmptyState({
   title = '暂无数据',
   description = '换个筛选条件或稍后再试',
+  variant = 'card',
 }: {
   title?: string;
   description?: string;
+  variant?: StateVariant;
 }) {
   return (
-    <div className="rounded-2xl border border-slate-100 bg-white p-8 text-center shadow-sm">
+    <div className={cn(
+      'p-8 text-center',
+      variant === 'card' && 'rounded-2xl border border-slate-100 bg-white shadow-sm',
+    )}>
       <SearchX className="mx-auto mb-3 text-slate-300" size={26} />
       <div className="text-sm font-black text-slate-700">{title}</div>
       <div className="mt-1 text-xs font-bold text-slate-400">{description}</div>
@@ -258,14 +302,40 @@ export function EmptyState({
   );
 }
 
-export function ErrorState({ message }: { message: string }) {
+export function ErrorState({
+  message,
+  title = '加载失败',
+  onRetry,
+  retrying = false,
+  variant = 'card',
+}: {
+  message: string;
+  title?: string;
+  onRetry?: () => void;
+  retrying?: boolean;
+  variant?: StateVariant;
+}) {
   return (
-    <div className="rounded-2xl border border-rose-100 bg-rose-50 p-4 text-rose-700 shadow-sm">
+    <div className={cn(
+      'bg-rose-50 p-4 text-rose-700',
+      variant === 'card' && 'rounded-2xl border border-rose-100 shadow-sm',
+    )}>
       <div className="flex items-start gap-2">
         <AlertCircle size={18} className="mt-0.5 shrink-0" />
-        <div>
-          <div className="text-sm font-black">加载失败</div>
+        <div className="min-w-0 flex-1">
+          <div className="text-sm font-black">{title}</div>
           <div className="mt-1 text-xs font-bold leading-relaxed">{message}</div>
+          {onRetry ? (
+            <button
+              type="button"
+              onClick={onRetry}
+              disabled={retrying}
+              className="mt-3 inline-flex h-8 items-center gap-1.5 rounded-lg border border-rose-200 bg-white px-3 text-xs font-black text-rose-700 transition-colors hover:bg-rose-100 disabled:cursor-not-allowed disabled:opacity-60"
+            >
+              <RefreshCw size={13} className={retrying ? 'animate-spin' : ''} />
+              重试
+            </button>
+          ) : null}
         </div>
       </div>
     </div>

src/index.css

@@ -20,6 +20,32 @@ html {
 body {
   overflow: auto;
   height: 100%;
+  color: #0f172a;
+  background: #fff;
+  font-family: Inter, "PingFang SC", "Microsoft YaHei", system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+button, input, select {
+  font-family: inherit;
+}
+
+.amap-logo,
+.amap-copyright {
+  opacity: 0.82;
+}
+
+.amap-toolbar {
+  border: 1px solid #e2e8f0 !important;
+  border-radius: 10px !important;
+  box-shadow: 0 8px 24px rgb(15 23 42 / 10%) !important;
+  overflow: hidden;
+}
+
+@media (max-width: 767px) {
+  .amap-logo,
+  .amap-copyright {
+    bottom: 60px !important;
+  }
 }
 
 @keyframes marquee {

src/modules/energy/AnalysisDateFilters.tsx

@@ -0,0 +1,110 @@
+import { cn } from '../../lib/cn';
+import type { DateQuickPick } from './types';
+import { QUICK_DATE_OPTIONS, type DateRangeMode } from './date-range';
+
+export function DateRangeInputs({
+  idPrefix,
+  startDate,
+  endDate,
+  onChange,
+  ariaPrefix = '',
+  className,
+}: {
+  idPrefix: string;
+  startDate: string;
+  endDate: string;
+  onChange: (field: 'start' | 'end', value: string) => void;
+  ariaPrefix?: string;
+  className?: string;
+}) {
+  const prefix = ariaPrefix ? `${ariaPrefix} ` : '';
+  return (
+    <div className={cn('grid grid-cols-2 gap-2', className)}>
+      <label className="min-w-0 rounded-lg border border-slate-100 bg-slate-50 px-3 py-2">
+        <span className="block text-[10px] font-black text-slate-400">开始日期</span>
+        <input
+          id={`${idPrefix}-start-date`}
+          name={`${idPrefix}StartDate`}
+          type="date"
+          aria-label={`${prefix}开始日期`}
+          value={startDate}
+          onInput={event => onChange('start', event.currentTarget.value)}
+          className="mt-1 h-6 w-full bg-transparent text-[12px] font-black text-slate-800 outline-none"
+        />
+      </label>
+      <label className="min-w-0 rounded-lg border border-slate-100 bg-slate-50 px-3 py-2">
+        <span className="block text-[10px] font-black text-slate-400">结束日期</span>
+        <input
+          id={`${idPrefix}-end-date`}
+          name={`${idPrefix}EndDate`}
+          type="date"
+          aria-label={`${prefix}结束日期`}
+          value={endDate}
+          onInput={event => onChange('end', event.currentTarget.value)}
+          className="mt-1 h-6 w-full bg-transparent text-[12px] font-black text-slate-800 outline-none"
+        />
+      </label>
+    </div>
+  );
+}
+
+export default function AnalysisDateFilters({
+  idPrefix,
+  mode,
+  startDate,
+  endDate,
+  onQuickPick,
+  onCustom,
+  onDateChange,
+}: {
+  idPrefix: string;
+  mode: DateRangeMode;
+  startDate: string;
+  endDate: string;
+  onQuickPick: (pick: DateQuickPick) => void;
+  onCustom: () => void;
+  onDateChange: (field: 'start' | 'end', value: string) => void;
+}) {
+  return (
+    <>
+      <div className="flex items-center gap-2 overflow-x-auto pb-1">
+        {QUICK_DATE_OPTIONS.map(option => (
+          <button
+            key={option.id}
+            type="button"
+            onClick={() => onQuickPick(option.id)}
+            aria-pressed={mode === option.id}
+            className={cn(
+              'min-h-9 shrink-0 rounded-lg border px-3 text-[12px] font-black transition-colors',
+              mode === option.id
+                ? 'border-blue-200 bg-blue-50 text-blue-600 shadow-sm'
+                : 'border-slate-100 bg-white text-slate-500 hover:bg-slate-50',
+            )}
+          >
+            {option.label}
+          </button>
+        ))}
+        <button
+          type="button"
+          onClick={onCustom}
+          aria-pressed={mode === 'custom'}
+          className={cn(
+            'min-h-9 shrink-0 rounded-lg border px-3 text-[12px] font-black transition-colors',
+            mode === 'custom'
+              ? 'border-blue-200 bg-blue-50 text-blue-600 shadow-sm'
+              : 'border-slate-100 bg-white text-slate-500 hover:bg-slate-50',
+          )}
+        >
+          自定义
+        </button>
+      </div>
+      <DateRangeInputs
+        idPrefix={idPrefix}
+        startDate={startDate}
+        endDate={endDate}
+        onChange={onDateChange}
+        className="mt-2"
+      />
+    </>
+  );
+}

src/modules/energy/AnalysisScopeSwitch.tsx

@@ -0,0 +1,50 @@
+import type { ComponentType } from 'react';
+import { cn } from '../../lib/cn';
+
+export interface AnalysisScopeOption<T extends string> {
+  id: T;
+  label: string;
+}
+
+export default function AnalysisScopeSwitch<T extends string>({
+  ariaLabel,
+  value,
+  options,
+  onChange,
+  icon: Icon,
+  className,
+}: {
+  ariaLabel: string;
+  value: T;
+  options: readonly AnalysisScopeOption<T>[];
+  onChange: (value: T) => void;
+  icon?: ComponentType<{ size?: number; className?: string }>;
+  className?: string;
+}) {
+  return (
+    <div
+      role="group"
+      aria-label={ariaLabel}
+      className={cn('grid gap-1 rounded-lg bg-slate-100 p-1', className)}
+      style={{ gridTemplateColumns: `repeat(${options.length}, minmax(0, 1fr))` }}
+    >
+      {options.map(option => (
+        <button
+          key={option.id}
+          type="button"
+          onClick={() => onChange(option.id)}
+          aria-pressed={value === option.id}
+          className={cn(
+            'flex min-h-9 min-w-0 items-center justify-center gap-1.5 rounded-lg px-2 text-[12px] font-black transition-colors',
+            value === option.id
+              ? 'bg-white text-slate-900 shadow-sm'
+              : 'text-slate-500 hover:text-slate-700',
+          )}
+        >
+          {Icon ? <Icon size={14} className="shrink-0" /> : null}
+          <span className="min-w-0 truncate">{option.label}</span>
+        </button>
+      ))}
+    </div>
+  );
+}

src/modules/energy/ETCDetails.tsx

@@ -0,0 +1,315 @@
+import { useEffect, useState } from 'react';
+import { CheckCircle2, ChevronLeft, ChevronRight, ReceiptText, Route, Search, TriangleAlert } from 'lucide-react';
+import Blur from '../../components/Blur';
+import { ErrorState, LoadingState } from '../../components/ui/surface';
+import { fetchEtcBills, fetchEtcRecords } from './api';
+import type { EtcBillResponse, EtcOverviewResponse, EtcTollRecordResponse } from './types';
+import type { EtcDetailView, EtcDrillContext } from './etc-drill-context';
+import { DateRangeInputs } from './AnalysisDateFilters';
+import { reconcileEtcBills, reconcileEtcRecords } from './etc-reconciliation';
+
+function fmtMoney(value: number): string {
+  return `¥${value.toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+function formatSigned(value: number, fractionDigits = 0): string {
+  const formatted = Math.abs(value).toLocaleString('zh-CN', {
+    minimumFractionDigits: fractionDigits,
+    maximumFractionDigits: fractionDigits,
+  });
+  return `${value >= 0 ? '+' : '-'}${formatted}`;
+}
+
+function costTypeLabel(value: number): string {
+  if (value === 1) return '客户承担';
+  if (value === 2) return '我方承担';
+  return '承担方待确认';
+}
+
+function paymentLabel(receivable: number, paid: number): string {
+  if (receivable > 0 && paid >= receivable) return '已收';
+  if (paid > 0) return '部分收款';
+  return '未收';
+}
+
+export default function ETCDetails({
+  context,
+  overviewKpi,
+  onContextChange,
+}: {
+  context: EtcDrillContext;
+  overviewKpi: EtcOverviewResponse['kpi'];
+  onContextChange: (context: EtcDrillContext, mode: 'push' | 'replace') => void;
+}) {
+  const { view, startDate, endDate, search, page } = context;
+  const [draftSearch, setDraftSearch] = useState(search);
+  const [records, setRecords] = useState<EtcTollRecordResponse | null>(null);
+  const [bills, setBills] = useState<EtcBillResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => setDraftSearch(search), [search]);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    if (view === 'records') setRecords(null);
+    else setBills(null);
+    const query = {
+      page,
+      limit: 20,
+      startDate: startDate || undefined,
+      endDate: endDate || undefined,
+      search: search || undefined,
+    };
+    const request = view === 'records' ? fetchEtcRecords(query) : fetchEtcBills(query);
+    request
+      .then(result => {
+        if (cancelled) return;
+        if (page > result.totalPages) {
+          onContextChange({ ...context, page: result.totalPages }, 'replace');
+          return;
+        }
+        if (view === 'records') setRecords(result as EtcTollRecordResponse);
+        else setBills(result as EtcBillResponse);
+      })
+      .catch(loadError => {
+        if (!cancelled) setError(loadError instanceof Error ? loadError.message : String(loadError));
+      })
+      .finally(() => { if (!cancelled) setLoading(false); });
+    return () => { cancelled = true; };
+  }, [context, endDate, onContextChange, page, search, startDate, view]);
+
+  const activeData = view === 'records' ? records : bills;
+  const totalPages = activeData?.totalPages || 1;
+  const isFullDataset = !startDate && !endDate && !search;
+  const reconciliation = isFullDataset
+    ? view === 'records' && records
+      ? reconcileEtcRecords(overviewKpi, records)
+      : view === 'bills' && bills
+        ? reconcileEtcBills(overviewKpi, bills)
+        : null
+    : null;
+  const reconciliationDifferences = reconciliation && !reconciliation.matches
+    ? 'passageCountDifference' in reconciliation
+      ? [
+          reconciliation.passageCountDifference !== 0 && `通行次数 ${formatSigned(reconciliation.passageCountDifference)}`,
+          reconciliation.vehicleCountDifference !== 0 && `车辆数 ${formatSigned(reconciliation.vehicleCountDifference)}`,
+          reconciliation.tollAmountDifference !== 0 && `通行费 ${formatSigned(reconciliation.tollAmountDifference, 2)} 元`,
+          reconciliation.serviceFeeDifference !== 0 && `服务费 ${formatSigned(reconciliation.serviceFeeDifference, 2)} 元`,
+          reconciliation.totalAmountDifference !== 0 && `总费用 ${formatSigned(reconciliation.totalAmountDifference, 2)} 元`,
+        ].filter(Boolean).join(' · ')
+      : [
+          reconciliation.billCountDifference !== 0 && `账单数 ${formatSigned(reconciliation.billCountDifference)}`,
+          reconciliation.receivableAmountDifference !== 0 && `应收 ${formatSigned(reconciliation.receivableAmountDifference, 2)} 元`,
+          reconciliation.paidAmountDifference !== 0 && `已收 ${formatSigned(reconciliation.paidAmountDifference, 2)} 元`,
+        ].filter(Boolean).join(' · ')
+    : '';
+  const applySearch = () => {
+    onContextChange({ ...context, search: draftSearch.trim(), page: 1 }, 'replace');
+  };
+  const changeView = (next: EtcDetailView) => {
+    onContextChange(
+      { ...context, view: next, page: 1 },
+      next === view ? 'replace' : 'push',
+    );
+  };
+  const updateDate = (field: 'start' | 'end', value: string) => {
+    let nextStart = field === 'start' ? value : startDate;
+    let nextEnd = field === 'end' ? value : endDate;
+    if (nextStart && nextEnd && nextStart > nextEnd) [nextStart, nextEnd] = [nextEnd, nextStart];
+    onContextChange({ ...context, startDate: nextStart, endDate: nextEnd, page: 1 }, 'replace');
+  };
+
+  return (
+    <section
+      id="etc-details"
+      tabIndex={-1}
+      className="scroll-mt-3 overflow-hidden rounded-lg border border-slate-100 bg-white shadow-sm outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
+    >
+      <header className="flex flex-col gap-3 border-b border-slate-100 px-3 py-3 md:px-4">
+        <div className="flex items-center justify-between gap-3">
+          <div>
+            <h2 className="text-sm font-black text-slate-900">ETC 明细下钻</h2>
+            <p className="mt-1 text-[10px] font-bold text-slate-400">
+              {view === 'records' ? '通行流水与费用承担' : '客户账期、应收与收款'}
+            </p>
+          </div>
+          <div className="flex rounded-lg bg-slate-100 p-1">
+            <button
+              type="button"
+              onClick={() => changeView('records')}
+              aria-pressed={view === 'records'}
+              className={`inline-flex h-8 items-center gap-1.5 rounded-md px-3 text-[10px] font-black ${view === 'records' ? 'bg-white text-blue-600 shadow-sm' : 'text-slate-500'}`}
+            >
+              <Route size={13} />通行记录
+            </button>
+            <button
+              type="button"
+              onClick={() => changeView('bills')}
+              aria-pressed={view === 'bills'}
+              className={`inline-flex h-8 items-center gap-1.5 rounded-md px-3 text-[10px] font-black ${view === 'bills' ? 'bg-white text-blue-600 shadow-sm' : 'text-slate-500'}`}
+            >
+              <ReceiptText size={13} />结算账单
+            </button>
+          </div>
+        </div>
+
+        <div className="grid grid-cols-[minmax(0,1fr)_40px] gap-2 sm:grid-cols-[minmax(280px,1fr)_minmax(0,1fr)_40px]">
+          <DateRangeInputs
+            idPrefix="etc"
+            ariaPrefix="ETC"
+            startDate={startDate}
+            endDate={endDate}
+            onChange={updateDate}
+            className="col-span-2 sm:col-span-1"
+          />
+          <label className="min-w-0 rounded-lg border border-slate-100 bg-slate-50 px-3 py-2">
+            <span className="block text-[10px] font-black text-slate-400">搜索</span>
+            <input
+              type="search"
+              aria-label={view === 'records' ? '搜索车牌、客户或流水号' : '搜索客户或账单号'}
+              placeholder={view === 'records' ? '车牌 / 客户 / 流水号' : '客户 / 账单号'}
+              value={draftSearch}
+              maxLength={128}
+              onChange={event => setDraftSearch(event.target.value)}
+              onKeyDown={event => { if (event.key === 'Enter') applySearch(); }}
+              className="mt-1 h-6 w-full min-w-0 bg-transparent text-[11px] font-bold text-slate-700 outline-none placeholder:text-slate-300"
+            />
+          </label>
+          <button
+            type="button"
+            onClick={applySearch}
+            className="flex h-full min-h-[58px] w-10 items-center justify-center rounded-lg bg-slate-900 text-white hover:bg-blue-600"
+            aria-label="应用 ETC 明细搜索"
+            title="搜索"
+          >
+            <Search size={14} />
+          </button>
+        </div>
+      </header>
+
+      {activeData ? (
+        <div className="flex flex-wrap items-center justify-between gap-2 border-b border-slate-100 bg-slate-50/70 px-3 py-2 text-[10px] font-bold text-slate-500 md:px-4">
+          <span>{activeData.total} 条结果</span>
+          {view === 'records' && records ? (
+            <span>通行费 {fmtMoney(records.summary.tollAmount)} · 服务费 {fmtMoney(records.summary.serviceFee)} · 合计 {fmtMoney(records.summary.totalAmount)}</span>
+          ) : view === 'bills' && bills ? (
+            <span>应收 {fmtMoney(bills.summary.receivableAmount)} · 已收 {fmtMoney(bills.summary.paidAmount)}</span>
+          ) : null}
+        </div>
+      ) : null}
+
+      {reconciliation && (
+        <div
+          role={reconciliation.matches ? 'status' : 'alert'}
+          className={`flex items-start gap-2 border-b px-3 py-2 text-[10px] font-bold md:px-4 ${
+            reconciliation.matches
+              ? 'border-emerald-100 bg-emerald-50 text-emerald-700'
+              : 'border-amber-200 bg-amber-50 text-amber-800'
+          }`}
+        >
+          {reconciliation.matches
+            ? <CheckCircle2 size={14} className="mt-0.5 shrink-0" />
+            : <TriangleAlert size={14} className="mt-0.5 shrink-0" />}
+          <span>
+            {reconciliation.matches
+              ? `口径核对通过：总览与 ${activeData?.total ?? 0} 条${view === 'records' ? '通行记录' : '结算账单'}全量汇总一致`
+              : `口径存在差异：${reconciliationDifferences}`}
+          </span>
+        </div>
+      )}
+
+      {error ? (
+        <ErrorState message={error} variant="inline" />
+      ) : loading && !activeData ? (
+        <LoadingState label="正在加载 ETC 明细" variant="inline" />
+      ) : view === 'records' && records ? (
+        records.items.length === 0 ? (
+          <div className="py-14 text-center">
+            <Route size={22} className="mx-auto text-slate-300" />
+            <div className="mt-3 text-xs font-black text-slate-500">暂无匹配的通行记录</div>
+            <div className="mt-1 text-[10px] font-bold text-slate-300">首次同步后将按通行时间倒序展示</div>
+          </div>
+        ) : (
+          <>
+            <div className="hidden overflow-x-auto md:block">
+              <table className="w-full min-w-[820px] text-left text-[11px]">
+                <thead className="bg-white text-[10px] font-black text-slate-400">
+                  <tr><th className="px-4 py-2">通行时间</th><th className="px-3 py-2">车牌 / 客户</th><th className="px-3 py-2">入口 → 出口</th><th className="px-3 py-2">承担</th><th className="px-4 py-2 text-right">费用</th></tr>
+                </thead>
+                <tbody className="divide-y divide-slate-100">
+                  {records.items.map(item => (
+                    <tr key={item.id}>
+                      <td className="px-4 py-3 font-bold text-slate-600">{item.transTime}</td>
+                      <td className="px-3 py-3"><div className="font-black text-slate-800"><Blur>{item.plate}</Blur></div><div className="mt-1 text-[9px] font-bold text-slate-400"><Blur>{item.customerName || '未关联客户'}</Blur></div></td>
+                      <td className="px-3 py-3 font-bold text-slate-600">{item.entryStation || '-'} → {item.exitStation || '-'}</td>
+                      <td className="px-3 py-3 font-bold text-slate-600">{costTypeLabel(item.costType)}</td>
+                      <td className="px-4 py-3 text-right"><div className="font-black text-slate-800">{fmtMoney(item.totalAmount)}</div><div className="mt-1 text-[9px] font-bold text-slate-400">通行 {fmtMoney(item.tollAmount)} · 服务 {fmtMoney(item.serviceFee)}</div></td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+            <div className="divide-y divide-slate-100 md:hidden">
+              {records.items.map(item => (
+                <article key={item.id} className="px-3 py-3">
+                  <div className="flex items-start justify-between gap-3"><div><div className="font-mono text-xs font-black text-slate-800"><Blur>{item.plate}</Blur></div><div className="mt-1 text-[9px] font-bold text-slate-400">{item.transTime}</div></div><div className="text-right text-sm font-black text-slate-800">{fmtMoney(item.totalAmount)}</div></div>
+                  <div className="mt-2 text-[10px] font-bold text-slate-500">{item.entryStation || '-'} → {item.exitStation || '-'}</div>
+                  <div className="mt-1 flex justify-between gap-2 text-[9px] font-bold text-slate-400"><Blur>{item.customerName || '未关联客户'}</Blur><span>{costTypeLabel(item.costType)}</span></div>
+                </article>
+              ))}
+            </div>
+          </>
+        )
+      ) : view === 'bills' && bills ? (
+        bills.items.length === 0 ? (
+          <div className="py-14 text-center">
+            <ReceiptText size={22} className="mx-auto text-slate-300" />
+            <div className="mt-3 text-xs font-black text-slate-500">暂无匹配的结算账单</div>
+            <div className="mt-1 text-[10px] font-bold text-slate-300">生成账单后将按账期结束日倒序展示</div>
+          </div>
+        ) : (
+          <>
+            <div className="hidden overflow-x-auto md:block">
+              <table className="w-full min-w-[760px] text-left text-[11px]">
+                <thead className="text-[10px] font-black text-slate-400"><tr><th className="px-4 py-2">账单 / 客户</th><th className="px-3 py-2">账期</th><th className="px-3 py-2">通行</th><th className="px-3 py-2">收款状态</th><th className="px-4 py-2 text-right">应收 / 已收</th></tr></thead>
+                <tbody className="divide-y divide-slate-100">
+                  {bills.items.map(item => (
+                    <tr key={item.id}>
+                      <td className="px-4 py-3"><div className="font-black text-slate-800">{item.billCode}</div><div className="mt-1 text-[9px] font-bold text-slate-400"><Blur>{item.customerName || '未指定客户'}</Blur></div></td>
+                      <td className="px-3 py-3 font-bold text-slate-600">{item.periodStart} → {item.periodEnd}</td>
+                      <td className="px-3 py-3 font-bold text-slate-600">{item.tollCount} 次 · {fmtMoney(item.tollAmount)}</td>
+                      <td className="px-3 py-3 font-bold text-slate-600">{paymentLabel(item.receivableAmount, item.paidAmount)}</td>
+                      <td className="px-4 py-3 text-right"><div className="font-black text-slate-800">{fmtMoney(item.receivableAmount)}</div><div className="mt-1 text-[9px] font-bold text-slate-400">已收 {fmtMoney(item.paidAmount)}</div></td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+            <div className="divide-y divide-slate-100 md:hidden">
+              {bills.items.map(item => (
+                <article key={item.id} className="px-3 py-3">
+                  <div className="flex items-start justify-between gap-3"><div><div className="text-xs font-black text-slate-800">{item.billCode}</div><div className="mt-1 text-[9px] font-bold text-slate-400"><Blur>{item.customerName || '未指定客户'}</Blur></div></div><div className="text-right"><div className="text-sm font-black text-slate-800">{fmtMoney(item.receivableAmount)}</div><div className="mt-1 text-[9px] font-bold text-slate-400">已收 {fmtMoney(item.paidAmount)}</div></div></div>
+                  <div className="mt-2 text-[10px] font-bold text-slate-500">{item.periodStart} → {item.periodEnd}</div>
+                  <div className="mt-1 flex justify-between text-[9px] font-bold text-slate-400"><span>{item.tollCount} 次通行</span><span>{paymentLabel(item.receivableAmount, item.paidAmount)}</span></div>
+                </article>
+              ))}
+            </div>
+          </>
+        )
+      ) : null}
+
+      {activeData ? (
+        <footer className="flex items-center justify-between border-t border-slate-100 px-3 py-3 md:px-4">
+          <span className="text-[10px] font-bold text-slate-400">第 {page} / {totalPages} 页</span>
+          <div className="flex gap-2">
+            <button type="button" onClick={() => onContextChange({ ...context, page: Math.max(1, page - 1) }, 'push')} disabled={page <= 1 || loading} className="flex h-8 w-8 items-center justify-center rounded-lg border border-slate-200 text-slate-500 disabled:opacity-30" aria-label="上一页" title="上一页"><ChevronLeft size={14} /></button>
+            <button type="button" onClick={() => onContextChange({ ...context, page: Math.min(totalPages, page + 1) }, 'push')} disabled={page >= totalPages || loading} className="flex h-8 w-8 items-center justify-center rounded-lg border border-slate-200 text-slate-500 disabled:opacity-30" aria-label="下一页" title="下一页"><ChevronRight size={14} /></button>
+          </div>
+        </footer>
+      ) : null}
+    </section>
+  );
+}

src/modules/energy/ETCView.tsx

@@ -1,79 +1,184 @@
-import { motion } from 'motion/react';
-import { Construction, Hammer } from 'lucide-react';
-import RotatingFooterHint from '../../components/RotatingFooterHint';
+import { useCallback, useEffect, useState } from 'react';
+import type { ReactNode } from 'react';
+import { CircleCheck, CircleX, Clock3, Database, ReceiptText, RefreshCw, Route, Truck } from 'lucide-react';
+import { fetchEtcOverview } from './api';
+import type { EtcOverviewResponse } from './types';
+import { ErrorState, LoadingState, MetricTile, SurfaceCard } from '../../components/ui/surface';
+import ETCDetails from './ETCDetails';
+import {
+  buildEtcDrillUrl,
+  parseEtcDrillContext,
+  type EtcDetailView,
+  type EtcDrillContext,
+} from './etc-drill-context';
 
-const ETC_HINTS = [
-  'ETC 通行费数据正在与发卡方系统打通…',
-  '工人 GG 正在搭脚手架，敬请期待 ~',
-  '马上能看到每月通行费明细啦',
-  '想看哪个维度的 ETC？反馈一下嘛',
-  '上线时机：等数据接通的那一天',
-];
+function fmtMoney(value: number): string {
+  return `¥${value.toLocaleString('zh-CN', { maximumFractionDigits: 2 })}`;
+}
+
+function syncStatusLabel(status: EtcOverviewResponse['integration']['lastSyncStatus']): string {
+  if (status === 'success') return '同步成功';
+  if (status === 'failed') return '同步失败';
+  if (status === 'partial') return '部分成功';
+  if (status === 'never') return '尚未同步';
+  return '状态未知';
+}
+
+function DrilldownMetricButton({
+  label,
+  title,
+  onClick,
+  children,
+}: {
+  label: string;
+  title: string;
+  onClick: () => void;
+  children: ReactNode;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onClick}
+      aria-controls="etc-details"
+      aria-label={label}
+      className="min-w-0 rounded-2xl text-left outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
+      title={title}
+    >
+      {children}
+    </button>
+  );
+}
 
 export default function ETCView() {
+  const [data, setData] = useState<EtcOverviewResponse | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [refreshing, setRefreshing] = useState(false);
+  const [detailContext, setDetailContext] = useState<EtcDrillContext>(() => (
+    parseEtcDrillContext(window.location.search)
+  ));
+
+  const commitDetailContext = useCallback((next: EtcDrillContext, mode: 'push' | 'replace') => {
+    window.history[mode === 'push' ? 'pushState' : 'replaceState'](
+      null,
+      '',
+      buildEtcDrillUrl(window.location, next),
+    );
+    setDetailContext(next);
+  }, []);
+
+  const selectDetailView = useCallback((next: EtcDetailView) => {
+    commitDetailContext(
+      { ...detailContext, view: next, page: 1 },
+      next === detailContext.view ? 'replace' : 'push',
+    );
+  }, [commitDetailContext, detailContext]);
+
+  const openDetailView = useCallback((next: EtcDetailView) => {
+    selectDetailView(next);
+    window.requestAnimationFrame(() => {
+      const details = document.getElementById('etc-details');
+      details?.focus({ preventScroll: true });
+      details?.scrollIntoView({
+        behavior: window.matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth',
+        block: 'start',
+      });
+    });
+  }, [selectDetailView]);
+
+  useEffect(() => {
+    const handlePopState = () => setDetailContext(parseEtcDrillContext(window.location.search));
+    window.addEventListener('popstate', handlePopState);
+    return () => window.removeEventListener('popstate', handlePopState);
+  }, []);
+
+  const load = async (force = false) => {
+    if (force) setRefreshing(true);
+    setError(null);
+    try {
+      setData(await fetchEtcOverview(force));
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setRefreshing(false);
+    }
+  };
+
+  useEffect(() => {
+    void load();
+  }, []);
+
+  if (error && !data) return <ErrorState message={error} />;
+  if (!data) return <LoadingState label="正在检查 ETC 接入状态" />;
+
+  const { integration, kpi } = data;
+  const collectionRate = kpi.receivableAmount > 0 ? kpi.paidAmount / kpi.receivableAmount * 100 : 0;
+
   return (
-    <div className="flex flex-col gap-4">
-      <motion.div
-        initial={{ opacity: 0, y: 12 }}
-        animate={{ opacity: 1, y: 0 }}
-        transition={{ duration: 0.3 }}
-        className="bg-white rounded-2xl border border-slate-100 shadow-sm px-6 py-14 flex flex-col items-center text-center"
-      >
-        <div className="relative w-20 h-20 mb-4">
-          <motion.div
-            animate={{ rotate: [0, -8, 8, -4, 4, 0] }}
-            transition={{ duration: 2.4, repeat: Infinity, ease: 'easeInOut' }}
-            className="absolute inset-0 rounded-3xl bg-gradient-to-br from-amber-50 to-orange-50 flex items-center justify-center"
-          >
-            <Construction size={36} className="text-amber-500" strokeWidth={2.2} />
-          </motion.div>
-          <motion.div
-            animate={{ rotate: [0, 18, -10, 0], y: [0, -2, 1, 0] }}
-            transition={{ duration: 1.6, repeat: Infinity, ease: 'easeInOut' }}
-            className="absolute -top-1 -right-1 w-9 h-9 rounded-2xl bg-white border border-amber-100 shadow-sm flex items-center justify-center"
-          >
-            <Hammer size={16} className="text-amber-500" strokeWidth={2.2} />
-          </motion.div>
+    <div className="flex flex-col gap-3">
+      <SurfaceCard className="flex items-center gap-3 p-3">
+        <span className={`flex h-9 w-9 shrink-0 items-center justify-center rounded-lg ${integration.providerConfigured ? 'bg-emerald-50 text-emerald-600' : 'bg-amber-50 text-amber-600'}`}>
+          {integration.providerConfigured ? <CircleCheck size={18} /> : <CircleX size={18} />}
+        </span>
+        <div className="min-w-0 flex-1">
+          <div className="text-xs font-black text-slate-800">
+            {integration.providerConfigured ? 'ETC 数据提供方已配置' : 'ETC 数据提供方尚未配置'}
+          </div>
+          <div className="mt-1 truncate text-[10px] font-bold text-slate-400">
+            {integration.providerConfigured
+              ? `${integration.providerType || '已配置提供方'} · ${syncStatusLabel(integration.lastSyncStatus)}`
+              : '数据库结构已准备，等待配置同步账户并完成首次同步'}
+          </div>
         </div>
+        <button
+          type="button"
+          onClick={() => void load(true)}
+          disabled={refreshing}
+          className="flex h-9 w-9 shrink-0 items-center justify-center rounded-lg border border-slate-200 bg-white text-slate-500 hover:text-blue-600 disabled:opacity-50"
+          aria-label="刷新 ETC 状态"
+          title="刷新 ETC 状态"
+        >
+          <RefreshCw size={15} className={refreshing ? 'animate-spin' : ''} />
+        </button>
+      </SurfaceCard>
 
-        <div className="text-base font-black text-slate-800 mb-1.5">ETC 模块建设中</div>
-        <div className="text-[12px] text-slate-500 font-bold leading-relaxed max-w-[280px]">
-          通行费明细、按车按月统计、运营成本拆分
-          <br />
-          这些数据都在路上啦
-        </div>
+      <div className="grid grid-cols-2 gap-3 md:grid-cols-4">
+        <DrilldownMetricButton label={`查看 ETC 通行记录，总费用 ${fmtMoney(kpi.totalAmount)}`} title="查看通行记录" onClick={() => openDetailView('records')}>
+          <MetricTile icon={ReceiptText} label="ETC 总费用" value={fmtMoney(kpi.totalAmount)} helper={`通行费 ${fmtMoney(kpi.tollAmount)} · 服务费 ${fmtMoney(kpi.serviceFee)}`} />
+        </DrilldownMetricButton>
+        <DrilldownMetricButton label={`查看 ETC 通行记录，共 ${kpi.passageCount} 次`} title="查看通行记录" onClick={() => openDetailView('records')}>
+          <MetricTile icon={Route} label="通行次数" value={kpi.passageCount} unit="次" helper={kpi.latestTransactionTime ? `最新 ${kpi.latestTransactionTime}` : '暂无通行记录'} tone="emerald" />
+        </DrilldownMetricButton>
+        <DrilldownMetricButton label={`查看 ETC 通行记录，共 ${kpi.vehicleCount} 辆车`} title="查看通行记录" onClick={() => openDetailView('records')}>
+          <MetricTile icon={Truck} label="通行车辆" value={kpi.vehicleCount} unit="辆" helper="按车牌去重" tone="amber" />
+        </DrilldownMetricButton>
+        <DrilldownMetricButton label={`查看 ETC 结算账单，应收 ${fmtMoney(kpi.receivableAmount)}`} title="查看结算账单" onClick={() => openDetailView('bills')}>
+          <MetricTile icon={Database} label="账单应收" value={fmtMoney(kpi.receivableAmount)} helper={`${kpi.billCount} 账单 · 已收 ${fmtMoney(kpi.paidAmount)} · ${collectionRate.toFixed(1)}%`} tone="slate" />
+        </DrilldownMetricButton>
+      </div>
 
-        {/* 简单的里程碑进度感 */}
-        <div className="mt-6 w-full max-w-xs space-y-2">
-          {[
-            { label: '需求评审', done: true },
-            { label: '数据对接', done: true },
-            { label: '页面开发', done: false, current: true },
-            { label: '正式上线', done: false },
-          ].map((m, i) => (
-            <motion.div
-              key={i}
-              initial={{ opacity: 0, x: -8 }}
-              animate={{ opacity: 1, x: 0 }}
-              transition={{ delay: 0.1 + i * 0.08, duration: 0.3 }}
-              className="flex items-center gap-2.5 text-[11px]"
-            >
-              <span className={`w-3 h-3 rounded-full flex-shrink-0 ${
-                m.done ? 'bg-emerald-400'
-                : m.current ? 'bg-amber-400 ring-4 ring-amber-100 animate-pulse'
-                : 'bg-slate-200'
-              }`} />
-              <span className={`font-bold ${m.done ? 'text-slate-500' : m.current ? 'text-amber-600' : 'text-slate-300'}`}>
-                {m.label}
-              </span>
-              {m.done && <span className="text-[10px] text-emerald-500 font-bold ml-auto">已完成</span>}
-              {m.current && <span className="text-[10px] text-amber-500 font-bold ml-auto">进行中</span>}
-            </motion.div>
-          ))}
-        </div>
-      </motion.div>
+      <div className="grid gap-3 md:grid-cols-3">
+        <SurfaceCard className="p-3">
+          <div className="text-[10px] font-black text-slate-400">提供方配置</div>
+          <div className={`mt-1 text-sm font-black ${integration.providerConfigured ? 'text-emerald-600' : 'text-amber-600'}`}>
+            {integration.providerConfigured ? '已配置' : '未配置'}
+          </div>
+        </SurfaceCard>
+        <SurfaceCard className="p-3">
+          <div className="text-[10px] font-black text-slate-400">自动同步</div>
+          <div className={`mt-1 text-sm font-black ${integration.syncEnabled ? 'text-emerald-600' : 'text-slate-500'}`}>
+            {integration.syncEnabled ? '已启用' : '未启用'}
+          </div>
+        </SurfaceCard>
+        <SurfaceCard className="p-3">
+          <div className="flex items-center gap-1 text-[10px] font-black text-slate-400"><Clock3 size={11} />最近同步</div>
+          <div className="mt-1 text-sm font-black text-slate-700">{syncStatusLabel(integration.lastSyncStatus)}</div>
+          <div className="mt-1 text-[10px] font-bold text-slate-400">{integration.lastSyncAt || '无同步记录'}</div>
+        </SurfaceCard>
+      </div>
 
-      <RotatingFooterHint hints={ETC_HINTS} />
+      <ETCDetails context={detailContext} overviewKpi={kpi} onContextChange={commitDetailContext} />
+
+      {error && <ErrorState message={error} />}
     </div>
   );
 }

src/modules/energy/ElectricDaily.tsx

@@ -1,56 +1,70 @@
-import { useEffect, useMemo, useState } from 'react';
-import { BatteryCharging, CalendarDays, ChevronRight, Plug, TrendingUp, Truck, Wallet } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { BatteryCharging, CalendarDays, CheckCircle2, ChevronRight, MapPin, Plug, TrendingUp, TriangleAlert, Truck, Wallet, X } from 'lucide-react';
 import { motion, AnimatePresence } from 'motion/react';
 import TrendBadge from './TrendBadge';
-import { fetchElectricMonthly } from './api';
-import type { CustomerType, DateQuickPick, ElectricMonthGroup } from './types';
+import { fetchElectricMonthly, fetchElectricOrders } from './api';
+import type { DateQuickPick, ElectricChargeOrderResponse, ElectricMonthGroup, ElectricVehicleScope } from './types';
 import RotatingFooterHint from '../../components/RotatingFooterHint';
 import { EmptyState, ErrorState, LoadingState, MetricTile, SurfaceCard } from '../../components/ui/surface';
+import {
+  buildElectricDrillUrl,
+  parseElectricDrillContext,
+  type ElectricDrillContext,
+} from './electric-drill-context';
+import AnalysisDateFilters from './AnalysisDateFilters';
+import AnalysisScopeSwitch, { type AnalysisScopeOption } from './AnalysisScopeSwitch';
+import {
+  dateRangeModeLabel,
+  getQuickDateRange,
+  inferDateRangeMode,
+  normalizeDateRange,
+  type DateRangeMode,
+} from './date-range';
+import { reconcileElectricDaily } from './electric-reconciliation';
 
-const QUICK_PICK_OPTIONS: Array<{ id: DateQuickPick; label: string }> = [
-  { id: 'thisWeek',  label: '本周'    },
-  { id: 'thisMonth', label: '本月'    },
-  { id: 'last15',    label: '近 15 天' },
+const VEHICLE_SCOPE_OPTIONS: readonly AnalysisScopeOption<ElectricVehicleScope>[] = [
+  { id: 'all', label: '全部车辆' },
+  { id: 'lingniu', label: '羚牛车辆' },
+  { id: 'external', label: '外部车辆' },
 ];
 
-type RangeMode = DateQuickPick | 'custom';
-
-function fmtYmd(d: Date): string {
-  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
-}
-
-function addDays(d: Date, days: number): Date {
-  const next = new Date(d);
-  next.setDate(next.getDate() + days);
-  return next;
-}
-
-function getQuickRange(pick: DateQuickPick): { start: string; end: string } {
-  const today = new Date();
-  today.setHours(0, 0, 0, 0);
-  if (pick === 'thisWeek') {
-    const day = today.getDay() || 7;
-    return { start: fmtYmd(addDays(today, -(day - 1))), end: fmtYmd(today) };
-  }
-  if (pick === 'thisMonth') {
-    return { start: fmtYmd(new Date(today.getFullYear(), today.getMonth(), 1)), end: fmtYmd(today) };
-  }
-  return { start: fmtYmd(addDays(today, -14)), end: fmtYmd(today) };
-}
-
-function normalizeRange(start: string, end: string): { start: string; end: string } {
-  return start <= end ? { start, end } : { start: end, end: start };
-}
-
 export default function ElectricDaily() {
-  const [customer, setCustomer] = useState<CustomerType>('lingniu');
-  const [pick, setPick] = useState<RangeMode>('last15');
-  const [dateRange, setDateRange] = useState(() => getQuickRange('last15'));
+  const [drillContext, setDrillContext] = useState<ElectricDrillContext>(() => (
+    parseElectricDrillContext(window.location.search)
+  ));
+  const [vehicleScope, setVehicleScope] = useState<ElectricVehicleScope>(drillContext.vehicleScope);
+  const [pick, setPick] = useState<DateRangeMode>(() => {
+    if (drillContext.startDate && drillContext.endDate) {
+      return inferDateRangeMode(drillContext.startDate, drillContext.endDate);
+    }
+    return 'last15';
+  });
+  const [dateRange, setDateRange] = useState(() => {
+    if (drillContext.startDate && drillContext.endDate) {
+      return normalizeDateRange(drillContext.startDate, drillContext.endDate);
+    }
+    if (drillContext.selectedDate) {
+      return { start: drillContext.selectedDate, end: drillContext.selectedDate };
+    }
+    return getQuickDateRange('last15');
+  });
   const [months, setMonths] = useState<ElectricMonthGroup[] | null>(null);
   const [openMonths, setOpenMonths] = useState<Set<string>>(new Set());
   const [error, setError] = useState<string | null>(null);
+  const [orders, setOrders] = useState<ElectricChargeOrderResponse | null>(null);
+  const [ordersError, setOrdersError] = useState<string | null>(null);
+  const orderTriggerRef = useRef<HTMLButtonElement | null>(null);
 
-  const effectiveRange = useMemo(() => normalizeRange(dateRange.start, dateRange.end), [dateRange.start, dateRange.end]);
+  const effectiveRange = useMemo(() => normalizeDateRange(dateRange.start, dateRange.end), [dateRange.start, dateRange.end]);
+  const selectedDate = drillContext.selectedDate;
+  const selectedDateRef = useRef(selectedDate);
+  selectedDateRef.current = selectedDate;
+
+  const commitDrillContext = useCallback((next: ElectricDrillContext, mode: 'push' | 'replace' = 'replace') => {
+    const url = buildElectricDrillUrl(window.location, next);
+    window.history[mode === 'push' ? 'pushState' : 'replaceState'](null, '', url);
+    setDrillContext(next);
+  }, []);
 
   useEffect(() => {
     let cancelled = false;
@@ -58,16 +72,32 @@ export default function ElectricDaily() {
     const query = pick === 'custom'
       ? { startDate: effectiveRange.start, endDate: effectiveRange.end }
       : { range: pick };
-    fetchElectricMonthly(customer, query)
+    fetchElectricMonthly(vehicleScope, query)
       .then(m => {
         if (cancelled) return;
         setMonths(m);
-        // 默认展开最新一个月
-        if (m.length > 0) setOpenMonths(new Set([m[0].month]));
+        if (m.length > 0) {
+          setOpenMonths(new Set([selectedDateRef.current?.slice(0, 7) || m[0].month]));
+        }
       })
       .catch(e => { if (!cancelled) setError(e instanceof Error ? e.message : String(e)); });
     return () => { cancelled = true; };
-  }, [customer, pick, effectiveRange.start, effectiveRange.end]);
+  }, [vehicleScope, pick, effectiveRange.start, effectiveRange.end]);
+
+  useEffect(() => {
+    if (!selectedDate) {
+      setOrders(null);
+      setOrdersError(null);
+      return undefined;
+    }
+    let cancelled = false;
+    setOrders(null);
+    setOrdersError(null);
+    fetchElectricOrders(selectedDate, vehicleScope)
+      .then(result => { if (!cancelled) setOrders(result); })
+      .catch(e => { if (!cancelled) setOrdersError(e instanceof Error ? e.message : String(e)); });
+    return () => { cancelled = true; };
+  }, [selectedDate, vehicleScope]);
 
   const toggleMonth = (m: string) => setOpenMonths(prev => {
     const next = new Set(prev);
@@ -81,90 +111,110 @@ export default function ElectricDaily() {
   const abnormalDays = useMemo(() => (months ?? []).reduce((sum, m) => sum + m.rows.filter(r => Math.abs(r.chainPct) >= 0.3).length, 0), [months]);
   const avgKwh = activeDays > 0 ? totalKwh / activeDays : 0;
   const avgPrice = totalKwh > 0 ? totalFee / totalKwh : 0;
-  const scopeLabel = pick === 'custom'
-    ? '自定义区间'
-    : QUICK_PICK_OPTIONS.find(item => item.id === pick)?.label ?? '当前时段';
+  const scopeLabel = dateRangeModeLabel(pick);
   const rangeText = `${effectiveRange.start} 至 ${effectiveRange.end}`;
-  const hasFeeDetail = totalFee > 0;
-  const showExternalEmpty = customer === 'external' && months !== null && totalKwh === 0;
+  const showExternalEmpty = vehicleScope === 'external' && months !== null && totalKwh === 0;
 
   const applyQuickPick = (nextPick: DateQuickPick) => {
+    const nextRange = getQuickDateRange(nextPick);
     setPick(nextPick);
-    setDateRange(getQuickRange(nextPick));
+    setDateRange(nextRange);
+    commitDrillContext({
+      vehicleScope,
+      startDate: nextRange.start,
+      endDate: nextRange.end,
+    });
   };
 
   const updateDateRange = (field: 'start' | 'end', value: string) => {
     if (!value) return;
+    const nextRange = { ...dateRange, [field]: value };
+    const normalized = normalizeDateRange(nextRange.start, nextRange.end);
     setPick('custom');
-    setDateRange(prev => ({ ...prev, [field]: value }));
+    setDateRange(normalized);
+    commitDrillContext({
+      vehicleScope,
+      startDate: normalized.start,
+      endDate: normalized.end,
+    });
   };
 
+  const updateVehicleScope = (next: ElectricVehicleScope) => {
+    setVehicleScope(next);
+    commitDrillContext({
+      ...drillContext,
+      vehicleScope: next,
+      startDate: effectiveRange.start,
+      endDate: effectiveRange.end,
+    });
+  };
+
+  const toggleDate = (date: string) => {
+    const opening = selectedDate !== date;
+    if (opening && document.activeElement instanceof HTMLButtonElement) {
+      orderTriggerRef.current = document.activeElement;
+    }
+    commitDrillContext({
+      ...drillContext,
+      vehicleScope,
+      startDate: effectiveRange.start,
+      endDate: effectiveRange.end,
+      selectedDate: opening ? date : undefined,
+    }, opening ? 'push' : 'replace');
+    window.requestAnimationFrame(() => {
+      if (opening) {
+        const details = document.getElementById(`electric-orders-${date}`);
+        details?.focus({ preventScroll: true });
+        details?.scrollIntoView({
+          behavior: window.matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth',
+          block: 'start',
+        });
+      } else {
+        const trigger = orderTriggerRef.current ?? document.getElementById(`electric-date-trigger-${date}`);
+        if (trigger instanceof HTMLElement) trigger.focus();
+      }
+    });
+  };
+
+  useEffect(() => {
+    const handlePopState = () => {
+      const next = parseElectricDrillContext(window.location.search);
+      setDrillContext(next);
+      setVehicleScope(next.vehicleScope);
+      if (next.startDate && next.endDate) {
+        const normalized = normalizeDateRange(next.startDate, next.endDate);
+        setPick(inferDateRangeMode(normalized.start, normalized.end));
+        setDateRange(normalized);
+      } else if (next.selectedDate) {
+        setPick('custom');
+        setDateRange({ start: next.selectedDate, end: next.selectedDate });
+      }
+    };
+    window.addEventListener('popstate', handlePopState);
+    return () => window.removeEventListener('popstate', handlePopState);
+  }, []);
+
   return (
     <div className="flex flex-col gap-3">
       <SurfaceCard className="p-2 md:p-3">
-        <div className="flex items-center gap-2 overflow-x-auto pb-1">
-          {QUICK_PICK_OPTIONS.map(opt => (
-            <button
-              key={opt.id}
-              onClick={() => applyQuickPick(opt.id)}
-              className={`min-h-9 shrink-0 rounded-xl border px-3 text-[12px] font-black transition-colors ${
-                pick === opt.id
-                  ? 'border-blue-200 bg-blue-50 text-blue-600 shadow-sm'
-                  : 'border-slate-100 bg-white text-slate-500 hover:bg-slate-50'
-              }`}
-            >
-              {opt.label}
-            </button>
-          ))}
-          <button
-            onClick={() => setPick('custom')}
-            className={`min-h-9 shrink-0 rounded-xl border px-3 text-[12px] font-black transition-colors ${
-              pick === 'custom'
-                ? 'border-blue-200 bg-blue-50 text-blue-600 shadow-sm'
-                : 'border-slate-100 bg-white text-slate-500 hover:bg-slate-50'
-            }`}
-          >
-            自定义
-          </button>
-        </div>
+        <AnalysisDateFilters
+          idPrefix="electric"
+          mode={pick}
+          startDate={dateRange.start}
+          endDate={dateRange.end}
+          onQuickPick={applyQuickPick}
+          onCustom={() => setPick('custom')}
+          onDateChange={updateDateRange}
+        />
 
-        <div className="mt-2 grid grid-cols-2 gap-2">
-          <label className="min-w-0 rounded-xl border border-slate-100 bg-slate-50 px-3 py-2">
-            <span className="block text-[10px] font-black text-slate-400">开始日期</span>
-            <input
-              type="date"
-              value={dateRange.start}
-              onChange={e => updateDateRange('start', e.target.value)}
-              onInput={e => updateDateRange('start', e.currentTarget.value)}
-              className="mt-1 h-6 w-full bg-transparent text-[12px] font-black text-slate-800 outline-none"
-            />
-          </label>
-          <label className="min-w-0 rounded-xl border border-slate-100 bg-slate-50 px-3 py-2">
-            <span className="block text-[10px] font-black text-slate-400">结束日期</span>
-            <input
-              type="date"
-              value={dateRange.end}
-              onChange={e => updateDateRange('end', e.target.value)}
-              onInput={e => updateDateRange('end', e.currentTarget.value)}
-              className="mt-1 h-6 w-full bg-transparent text-[12px] font-black text-slate-800 outline-none"
-            />
-          </label>
-        </div>
-
-        <div className="mt-2 grid grid-cols-2 gap-1 rounded-xl bg-slate-100 p-1">
-          {(['lingniu', 'external'] as const).map(c => (
-            <button
-              key={c}
-              onClick={() => setCustomer(c)}
-              className={`flex min-h-9 items-center justify-center gap-1.5 rounded-lg text-[12px] font-black transition-all ${
-                customer === c ? 'bg-white text-slate-900 shadow-sm' : 'text-slate-500 hover:text-slate-700'
-              }`}
-            >
-              <Truck size={14} />
-              {c === 'external' ? '外部车辆' : '羚牛车辆'}
-            </button>
-          ))}
-        </div>
+        <AnalysisScopeSwitch
+          ariaLabel="电能车辆范围"
+          value={vehicleScope}
+          options={VEHICLE_SCOPE_OPTIONS}
+          onChange={updateVehicleScope}
+          icon={Truck}
+          className="mt-2"
+        />
       </SurfaceCard>
 
       <div className="grid grid-cols-2 gap-3 md:grid-cols-4">
@@ -172,9 +222,9 @@ export default function ElectricDaily() {
         <MetricTile
           icon={Wallet}
           label="充电费用"
-          value={hasFeeDetail ? `¥${totalFee.toLocaleString('zh-CN', { maximumFractionDigits: 0 })}` : '待同步'}
-          helper={hasFeeDetail ? `均价 ${avgPrice.toFixed(2)} 元/度` : '当前明细仅返回充电量'}
-          tone={hasFeeDetail ? 'emerald' : 'slate'}
+          value={`¥${totalFee.toLocaleString('zh-CN', { maximumFractionDigits: 0 })}`}
+          helper={`综合费用强度 ${avgPrice.toFixed(2)} 元/度`}
+          tone="emerald"
         />
         <MetricTile icon={CalendarDays} label="有效天数" value={`${activeDays}`} unit="天" helper={`日均 ${avgKwh.toLocaleString('zh-CN', { maximumFractionDigits: 1 })} 度`} tone="amber" />
         <MetricTile icon={TrendingUp} label="波动提醒" value={abnormalDays} unit="天" helper="环比超过 30% 标记" tone={abnormalDays > 0 ? 'rose' : 'slate'} />
@@ -210,20 +260,23 @@ export default function ElectricDaily() {
           <span className="text-right">环比</span>
         </div>
         {error ? (
-          <div className="p-3"><ErrorState message={error} /></div>
+          <ErrorState message={error} variant="inline" />
         ) : months === null ? (
-          <div className="p-3"><LoadingState label="正在加载充电明细" /></div>
+          <LoadingState label="正在加载充电明细" variant="inline" />
         ) : months.length === 0 ? (
-          <div className="p-3"><EmptyState title="暂无充电数据" description="请切换时间范围或车辆归属" /></div>
+          <EmptyState title="暂无充电数据" description="请切换时间范围或车辆归属" variant="inline" />
         ) : months.map(m => {
           const open = openMonths.has(m.month);
           return (
             <div key={m.month} className="border-t border-slate-100 first:border-t-0">
               <button
+                type="button"
                 onClick={() => toggleMonth(m.month)}
                 className={`w-full grid grid-cols-[minmax(0,1fr)_120px_88px] md:grid-cols-[minmax(0,1fr)_160px_120px] gap-3 px-3 py-2.5 text-left transition-colors ${
                   open ? 'bg-blue-50/30' : 'hover:bg-slate-50'
                 }`}
+                aria-expanded={open}
+                aria-controls={open ? `electric-month-${m.month}` : undefined}
               >
                 <span className="flex items-center gap-1 text-[12px] text-slate-700 font-bold">
                   <ChevronRight size={14} className={`transition-transform ${open ? 'rotate-90' : ''} text-slate-400`} />
@@ -237,6 +290,7 @@ export default function ElectricDaily() {
               <AnimatePresence initial={false}>
                 {open && (
                   <motion.div
+                    id={`electric-month-${m.month}`}
                     initial={{ height: 0, opacity: 0 }}
                     animate={{ height: 'auto', opacity: 1 }}
                     exit={{ height: 0, opacity: 0 }}
@@ -248,16 +302,121 @@ export default function ElectricDaily() {
                       const abnormalBg = isAbnormal
                         ? d.chainPct > 0 ? 'bg-emerald-50/40' : 'bg-red-50/40'
                         : 'bg-slate-50/50';
+                      const reconciliation = orders?.date === d.date
+                        ? reconcileElectricDaily(d, orders, vehicleScope)
+                        : null;
                       return (
-                        <div
-                          key={d.date}
-                          className={`grid grid-cols-[minmax(0,1fr)_120px_88px] md:grid-cols-[minmax(0,1fr)_160px_120px] gap-3 px-3 py-2 pl-9 border-t border-slate-100 ${abnormalBg}`}
-                        >
-                          <span className="text-[12px] text-slate-600">{d.date.slice(5)}</span>
-                          <span className="text-right text-[12px] text-slate-700 font-bold tabular-nums">
-                            {d.kwh.toLocaleString('zh-CN', { maximumFractionDigits: 2 })}
-                          </span>
-                          <span className="text-right"><TrendBadge value={d.chainPct} /></span>
+                        <div key={d.date} className="border-t border-slate-100">
+                          <button
+                            id={`electric-date-trigger-${d.date}`}
+                            type="button"
+                            onClick={() => toggleDate(d.date)}
+                            className={`grid w-full grid-cols-[minmax(0,1fr)_120px_88px] gap-3 px-3 py-2 pl-9 text-left md:grid-cols-[minmax(0,1fr)_160px_120px] ${abnormalBg}`}
+                            aria-expanded={selectedDate === d.date}
+                            aria-controls={`electric-orders-${d.date}`}
+                          >
+                            <span className="flex items-center gap-1 text-[12px] font-bold text-slate-600">
+                              <ChevronRight size={12} className={`text-slate-400 transition-transform ${selectedDate === d.date ? 'rotate-90' : ''}`} />
+                              {d.date.slice(5)}
+                            </span>
+                            <span className="text-right text-[12px] font-bold tabular-nums text-slate-700">
+                              {d.kwh.toLocaleString('zh-CN', { maximumFractionDigits: 2 })}
+                            </span>
+                            <span className="text-right"><TrendBadge value={d.chainPct} /></span>
+                          </button>
+                          {selectedDate === d.date && (
+                            <div
+                              id={`electric-orders-${d.date}`}
+                              tabIndex={-1}
+                              aria-label={`${d.date} 充电订单明细`}
+                              className="scroll-mt-3 border-t border-blue-100 bg-blue-50/40 px-3 py-3 outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-blue-500 md:pl-9"
+                            >
+                              <div className="mb-2 flex items-center justify-between gap-3">
+                                <div className="flex min-w-0 items-center gap-1.5 text-[11px] font-black text-blue-800">
+                                  <Plug size={13} className="shrink-0" />
+                                  <span className="truncate">{d.date} 充电订单</span>
+                                </div>
+                                <button
+                                  type="button"
+                                  onClick={() => toggleDate(d.date)}
+                                  className="flex h-7 w-7 shrink-0 items-center justify-center rounded-lg bg-white text-blue-500 ring-1 ring-blue-100 hover:text-blue-700"
+                                  aria-label={`关闭 ${d.date} 充电订单`}
+                                  title="关闭订单明细"
+                                >
+                                  <X size={13} />
+                                </button>
+                              </div>
+                              {orders && reconciliation && (
+                                <div
+                                  role={reconciliation.matches ? 'status' : 'alert'}
+                                  className={`mb-2 flex items-start gap-2 rounded-lg border px-3 py-2 text-[10px] font-bold ${
+                                  reconciliation.matches
+                                    ? 'border-emerald-100 bg-emerald-50 text-emerald-700'
+                                    : 'border-amber-200 bg-amber-50 text-amber-800'
+                                  }`}
+                                >
+                                  {reconciliation.matches
+                                    ? <CheckCircle2 size={14} className="mt-0.5 shrink-0" />
+                                    : <TriangleAlert size={14} className="mt-0.5 shrink-0" />}
+                                  <span>
+                                    {reconciliation.matches
+                                      ? `口径核对通过：日汇总与 ${orders.recordCount} 笔订单全量合计一致`
+                                      : `口径存在差异：电量 ${reconciliation.kwhDifference >= 0 ? '+' : ''}${reconciliation.kwhDifference.toFixed(2)} 度 · 费用 ${reconciliation.feeDifference >= 0 ? '+' : ''}${reconciliation.feeDifference.toFixed(2)} 元${!reconciliation.dateMatches || !reconciliation.scopeMatches ? ' · 日期或车辆范围不一致' : ''}`}
+                                  </span>
+                                </div>
+                              )}
+                              {ordersError ? (
+                                <ErrorState message={ordersError} variant="inline" />
+                              ) : !orders || orders.date !== d.date ? (
+                                <LoadingState label="正在加载充电订单" variant="inline" />
+                              ) : orders.items.length === 0 ? (
+                                <EmptyState title="当日无充电订单" description="当前车辆归属下没有订单明细" variant="inline" />
+                              ) : (
+                                <div className="overflow-hidden rounded-lg border border-blue-100 bg-white">
+                                  <div className="flex flex-wrap items-center justify-between gap-2 border-b border-blue-100 bg-blue-50 px-3 py-2 text-[10px] font-bold text-blue-700">
+                                    <span>{orders.recordCount} 笔 · {orders.totalKwh.toLocaleString('zh-CN')} 度</span>
+                                    <span>合计 ¥{orders.totalFee.toLocaleString('zh-CN', { maximumFractionDigits: 2 })}</span>
+                                  </div>
+                                  {orders.truncated && (
+                                    <div className="border-b border-amber-100 bg-amber-50 px-3 py-2 text-[10px] font-bold text-amber-700">
+                                      明细超过 500 笔，当前仅展示前 500 笔；顶部合计仍为全量口径。
+                                    </div>
+                                  )}
+                                  <div className="grid grid-cols-[minmax(0,1fr)_72px_82px] gap-2 border-b border-slate-100 bg-slate-50 px-3 py-1.5 text-[10px] font-bold text-slate-400 md:grid-cols-[minmax(0,1fr)_100px_120px]">
+                                    <span>时间 / 站点 / 车辆</span>
+                                    <span className="text-right">电量</span>
+                                    <span className="text-right">费用</span>
+                                  </div>
+                                  {orders.items.map(order => (
+                                    <div key={order.id} className="grid grid-cols-[minmax(0,1fr)_72px_82px] gap-2 border-b border-slate-100 px-3 py-2 last:border-b-0 md:grid-cols-[minmax(0,1fr)_100px_120px]">
+                                      <div className="min-w-0">
+                                        <div className="flex items-center gap-1 text-[11px] font-black text-slate-700">
+                                          <span>{order.startTime.slice(11, 16)}</span>
+                                          <span className="truncate text-blue-600">{order.plate}</span>
+                                          <span className="shrink-0 rounded bg-slate-100 px-1 py-0.5 text-[9px] text-slate-500">{order.orderStatus}</span>
+                                        </div>
+                                        <div className="mt-1 flex min-w-0 items-center gap-1 text-[10px] font-bold text-slate-400">
+                                          <MapPin size={10} className="shrink-0" />
+                                          <span className="truncate">{order.stationName}</span>
+                                          <span className="hidden shrink-0 md:inline">· {order.orderNo}</span>
+                                        </div>
+                                      </div>
+                                      <div className="text-right text-[11px] font-black tabular-nums text-slate-700">
+                                        {order.kwh.toLocaleString('zh-CN', { maximumFractionDigits: 2 })}
+                                        <div className="mt-1 text-[9px] font-bold text-slate-400">度</div>
+                                      </div>
+                                      <div className="text-right text-[11px] font-black tabular-nums text-emerald-600">
+                                        ¥{order.totalFee.toLocaleString('zh-CN', { maximumFractionDigits: 2 })}
+                                        <div className="mt-1 text-[9px] font-bold text-slate-400">
+                                          电 {order.electricityFee.toLocaleString('zh-CN')} · 服 {order.serviceFee.toLocaleString('zh-CN')}
+                                        </div>
+                                      </div>
+                                    </div>
+                                  ))}
+                                </div>
+                              )}
+                            </div>
+                          )}
                         </div>
                       );
                     })}

src/modules/energy/ElectricModule.tsx

@@ -4,6 +4,7 @@ import ElectricView, { type ElectricSubTab } from './ElectricView';
 import SubTabs from './SubTabs';
 import { useHashSubTab } from './useHashSubTab';
 import { FadeIn, PageFrame } from '../../components/ui/surface';
+import BiHeaderActions from '../../components/BiHeaderActions';
 
 const SUB_TABS = [
   { id: 'daily',    label: '每日', icon: CalendarDays },
@@ -21,11 +22,18 @@ export default function ElectricModule() {
       icon={CalendarDays}
       eyebrow="ELECTRIC BI"
       meta="时间单位清晰标注 · 支持日/总览切换"
+      actions={<BiHeaderActions domain="electric" />}
     >
-      <SubTabs tabs={SUB_TABS} active={sub} onChange={setSub} />
+      <SubTabs tabs={SUB_TABS} active={sub} onChange={setSub} idPrefix="electric-view" ariaLabel="电能分析视图" />
       <AnimatePresence mode="wait">
         <FadeIn key={sub}>
-          <ElectricView sub={sub} />
+          <div
+            id={`electric-view-panel-${sub}`}
+            role="tabpanel"
+            aria-labelledby={`electric-view-tab-${sub}`}
+          >
+            <ElectricView sub={sub} />
+          </div>
         </FadeIn>
       </AnimatePresence>
     </PageFrame>

src/modules/energy/ElectricOverview.tsx

@@ -4,6 +4,8 @@ import { BarChart, Bar, XAxis, YAxis, ResponsiveContainer, Cell, Tooltip, Refere
 import { fetchElectricOverview, type ElectricOverviewResponse } from './api';
 import RotatingFooterHint from '../../components/RotatingFooterHint';
 import { ErrorState, LoadingState, MetricTile, SurfaceCard } from '../../components/ui/surface';
+import { buildElectricDrillUrl } from './electric-drill-context';
+import { activateDrillOnKeyDown } from './drill-interaction';
 
 function fmtYuan(yuan: number) {
   return `¥${yuan.toLocaleString('zh-CN', { maximumFractionDigits: 2 })}`;
@@ -11,6 +13,11 @@ function fmtYuan(yuan: number) {
 function fmtKwh(kwh: number) {
   return `${kwh.toLocaleString('zh-CN', { maximumFractionDigits: 2 })} 度`;
 }
+function fmtMonth(month: string | undefined) {
+  if (!month) return '当前月';
+  const [year, monthNumber] = month.split('-');
+  return `${year}年${Number(monthNumber)}月`;
+}
 
 export default function ElectricOverview() {
   const [data, setData] = useState<ElectricOverviewResponse | null>(null);
@@ -34,33 +41,50 @@ export default function ElectricOverview() {
   const trendData = data.trend;
   // 当电能数据滞后（本月无数据走 fallback）时，柱图标题显示实际月份
   const trendMonthLabel = trendData[0]?.date.slice(0, 7);
-  const currentMonth = new Date().toISOString().slice(0, 7);
+  const trendMonthText = fmtMonth(trendMonthLabel);
+  const now = new Date();
+  const currentMonth = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}`;
   const chartTitle = trendMonthLabel && trendMonthLabel !== currentMonth
     ? `${trendMonthLabel} 每日充电`
     : '本月每日充电';
   const activeDays = trendData.filter(item => item.kwh > 0).length;
-  const avgDailyKwh = activeDays > 0 ? trendData.reduce((sum, item) => sum + item.kwh, 0) / activeDays : 0;
-  const avgDailyFee = activeDays > 0 ? trendData.reduce((sum, item) => sum + item.fee, 0) / activeDays : 0;
+  const trendKwh = trendData.reduce((sum, item) => sum + item.kwh, 0);
+  const trendFee = trendData.reduce((sum, item) => sum + item.fee, 0);
+  const avgDailyKwh = activeDays > 0 ? trendKwh / activeDays : 0;
+  const avgDailyFee = activeDays > 0 ? trendFee / activeDays : 0;
   const peakDay = trendData.reduce<typeof trendData[number] | null>((best, item) => (!best || item.kwh > best.kwh ? item : best), null);
   const avgPrice = k.totalKwh > 0 ? k.totalFee / k.totalKwh : 0;
-  const monthPrice = k.monthKwh > 0 ? k.monthFee / k.monthKwh : 0;
+  const trendPrice = trendKwh > 0 ? trendFee / trendKwh : 0;
+  const openDay = (date: string) => {
+    const url = buildElectricDrillUrl(
+      { pathname: window.location.pathname, search: window.location.search, hash: '#electric' },
+      {
+        vehicleScope: 'all',
+        startDate: date,
+        endDate: date,
+        selectedDate: date,
+      },
+    );
+    window.history.pushState(null, '', url);
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+  };
 
   return (
     <div className="flex flex-col gap-3">
       <div className="bg-white rounded-xl border border-slate-100 px-3 py-1.5 text-[11px] text-slate-400">
-        龙王路停车场充电站，期初 2025-01-01，手工导入每日更新
+        数据截至 {data.latestRecordAt ?? '暂无记录'} · 龙王路停车场充电站 · 手工导入
       </div>
       {/* 横向 mini KPI 头 */}
       <div className="grid grid-cols-2 gap-3 md:grid-cols-4">
         <MetricTile icon={Wallet} label="累计充电费" value={fmtYuan(k.totalFee)} helper={fmtKwh(k.totalKwh)} />
-        <MetricTile icon={CalendarClock} label="本月充电费" value={fmtYuan(k.monthFee)} helper={fmtKwh(k.monthKwh)} tone="emerald" />
-        <MetricTile icon={Gauge} label="累计均价" value={avgPrice.toFixed(2)} unit="元/度" helper={`本月 ${monthPrice.toFixed(2)} 元/度`} tone="amber" />
+        <MetricTile icon={CalendarClock} label={`${trendMonthText}充电费`} value={fmtYuan(trendFee)} helper={fmtKwh(trendKwh)} tone="emerald" />
+        <MetricTile icon={Gauge} label="综合费用强度" value={avgPrice.toFixed(2)} unit="元/度" helper={`${trendMonthText} ${trendPrice.toFixed(2)} 元/度 · 含零费用订单`} tone="amber" />
         <MetricTile icon={BatteryCharging} label="今日充电" value={k.todayKwh.toLocaleString('zh-CN', { maximumFractionDigits: 1 })} unit="度" helper={`${fmtYuan(k.todayFee)} · ${k.todayChainPct >= 0 ? '+' : ''}${(k.todayChainPct * 100).toFixed(1)}%`} tone={Math.abs(k.todayChainPct) >= 0.3 ? 'rose' : 'slate'} />
       </div>
 
       <div className="grid grid-cols-1 gap-3 md:grid-cols-3">
         <SurfaceCard className="p-3">
-          <div className="text-[11px] font-black text-slate-400">有效充电日</div>
+          <div className="text-[11px] font-black text-slate-400">{trendMonthText}有效充电日</div>
           <div className="mt-1 text-xl font-black text-slate-900">{activeDays}<span className="ml-1 text-[11px] text-slate-400">天</span></div>
           <div className="mt-1 text-[11px] font-bold text-slate-500">日均 {avgDailyKwh.toLocaleString('zh-CN', { maximumFractionDigits: 1 })} 度</div>
         </SurfaceCard>
@@ -71,12 +95,12 @@ export default function ElectricOverview() {
         </SurfaceCard>
         <SurfaceCard className="p-3">
           <div className="text-[11px] font-black text-slate-400">月度占比</div>
-          <div className="mt-1 text-xl font-black text-emerald-600">{k.totalFee > 0 ? (k.monthFee / k.totalFee * 100).toFixed(1) : '0.0'}%</div>
-          <div className="mt-1 text-[11px] font-bold text-slate-500">本月费用 / 累计费用</div>
+          <div className="mt-1 text-xl font-black text-emerald-600">{k.totalFee > 0 ? (trendFee / k.totalFee * 100).toFixed(1) : '0.0'}%</div>
+          <div className="mt-1 text-[11px] font-bold text-slate-500">{trendMonthText}费用 / 累计费用</div>
         </SurfaceCard>
       </div>
 
-      {/* 本月每日充电柱图 */}
+      {/* 当前月无数据时展示最近一个有数据的自然月 */}
       <SurfaceCard className="p-4">
         <div className="flex items-center justify-between mb-2">
           <span className="text-sm font-bold text-slate-700">{chartTitle}</span>
@@ -109,8 +133,17 @@ export default function ElectricOverview() {
               />
             )}
             <Bar dataKey="fee" radius={[4, 4, 0, 0]}>
-              {trendData.map((_, i) => (
-                <Cell key={i} fill="url(#electricBarGrad)" />
+              {trendData.map(item => (
+                <Cell
+                  key={item.date}
+                  fill="url(#electricBarGrad)"
+                  className="cursor-pointer outline-none focus:stroke-blue-700 focus:stroke-2"
+                  role="button"
+                  tabIndex={0}
+                  aria-label={`${item.date}，充电费用 ${fmtYuan(item.fee)}，查看全部车辆订单`}
+                  onClick={() => openDay(item.date)}
+                  onKeyDown={event => activateDrillOnKeyDown(event, () => openDay(item.date))}
+                />
               ))}
             </Bar>
             <defs>

src/modules/energy/EtcModule.tsx

@@ -1,15 +1,17 @@
 import { Receipt } from 'lucide-react';
 import ETCView from './ETCView';
 import { PageFrame } from '../../components/ui/surface';
+import BiHeaderActions from '../../components/BiHeaderActions';
 
 export default function EtcModule() {
   return (
     <PageFrame
       title="ETC 通行费看板"
-      subtitle="规划按车、按月、按线路拆分通行费，让车辆运营成本口径逐步完整。"
+      subtitle="区分通行记录与结算账单口径，展示通行费、服务费、车辆规模及数据同步状态。"
       icon={Receipt}
       eyebrow="ETC BI"
-      meta="数据对接中 · 页面能力预留"
+      meta="真实接入状态 · 指标口径已发布"
+      actions={<BiHeaderActions domain="etc" />}
     >
       <ETCView />
     </PageFrame>

src/modules/energy/HydrogenDaily.tsx

@@ -1,5 +1,5 @@
-import { useEffect, useMemo, useState } from 'react';
-import { ChevronRight, Fuel, Plug, TrendingUp, Truck } from 'lucide-react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { Building2, ChevronRight, Fuel, Plug, ReceiptText, TrendingUp, Truck, UserRound, X } from 'lucide-react';
 import { motion, AnimatePresence } from 'motion/react';
 import { BarChart, Bar, XAxis, YAxis, ResponsiveContainer, Cell, Tooltip, ReferenceLine } from 'recharts';
 import TrendBadge from './TrendBadge';
@@ -7,78 +7,97 @@ import { fetchHydrogenDaily } from './api';
 import type { CustomerType, DateQuickPick, HydrogenDailyRow } from './types';
 import RotatingFooterHint from '../../components/RotatingFooterHint';
 import { EmptyState, ErrorState, LoadingState, MetricTile, SurfaceCard } from '../../components/ui/surface';
+import {
+  buildHydrogenDrillUrl,
+  parseHydrogenDrillContext,
+  type HydrogenDrillContext,
+} from './hydrogen-drill-context';
+import HydrogenOrders from './HydrogenOrders';
+import AnalysisDateFilters from './AnalysisDateFilters';
+import AnalysisScopeSwitch, { type AnalysisScopeOption } from './AnalysisScopeSwitch';
+import { activateDrillOnKeyDown } from './drill-interaction';
+import {
+  dateRangeModeLabel,
+  getQuickDateRange,
+  inferDateRangeMode,
+  normalizeDateRange,
+  type DateRangeMode,
+} from './date-range';
 
-const QUICK_PICK_OPTIONS: Array<{ id: DateQuickPick; label: string }> = [
-  { id: 'thisWeek',  label: '本周'    },
-  { id: 'thisMonth', label: '本月'    },
-  { id: 'last15',    label: '近 15 天' },
+const VEHICLE_SCOPE_OPTIONS: readonly AnalysisScopeOption<CustomerType>[] = [
+  { id: 'lingniu', label: '羚牛车辆' },
+  { id: 'external', label: '外部车辆' },
 ];
 
-type RangeMode = DateQuickPick | 'custom';
-
-function fmtYmd(d: Date): string {
-  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, '0')}-${String(d.getDate()).padStart(2, '0')}`;
-}
-
-function addDays(d: Date, days: number): Date {
-  const next = new Date(d);
-  next.setDate(next.getDate() + days);
-  return next;
-}
-
-function getQuickRange(pick: DateQuickPick): { start: string; end: string } {
-  const today = new Date();
-  today.setHours(0, 0, 0, 0);
-  if (pick === 'thisWeek') {
-    const day = today.getDay() || 7;
-    return { start: fmtYmd(addDays(today, -(day - 1))), end: fmtYmd(today) };
-  }
-  if (pick === 'thisMonth') {
-    return { start: fmtYmd(new Date(today.getFullYear(), today.getMonth(), 1)), end: fmtYmd(today) };
-  }
-  return { start: fmtYmd(addDays(today, -14)), end: fmtYmd(today) };
-}
-
-function normalizeRange(start: string, end: string): { start: string; end: string } {
-  return start <= end ? { start, end } : { start: end, end: start };
-}
+const HYDROGEN_ORDERS_ID = 'hydrogen-orders';
 
 export default function HydrogenDaily() {
-  const [pick, setPick] = useState<RangeMode>('last15');
-  const [dateRange, setDateRange] = useState(() => getQuickRange('last15'));
-  const [customer, setCustomer] = useState<CustomerType>('lingniu');
+  const [drillContext, setDrillContext] = useState<HydrogenDrillContext>(() => (
+    parseHydrogenDrillContext(window.location.search)
+  ));
+  const [pick, setPick] = useState<DateRangeMode>(() => (
+    drillContext.startDate && drillContext.endDate
+      ? inferDateRangeMode(drillContext.startDate, drillContext.endDate)
+      : 'last15'
+  ));
+  const [dateRange, setDateRange] = useState(() => (
+    drillContext.startDate && drillContext.endDate
+      ? normalizeDateRange(drillContext.startDate, drillContext.endDate)
+      : getQuickDateRange('last15')
+  ));
+  const [vehicleScope, setVehicleScope] = useState<CustomerType>(drillContext.vehicleScope);
   const [expanded, setExpanded] = useState<Set<string>>(new Set());
   const [rows, setRows] = useState<HydrogenDailyRow[] | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const [retryKey, setRetryKey] = useState(0);
+  const orderTriggerRef = useRef<HTMLElement | SVGElement | null>(null);
 
-  const effectiveRange = useMemo(() => normalizeRange(dateRange.start, dateRange.end), [dateRange.start, dateRange.end]);
+  const effectiveRange = useMemo(() => normalizeDateRange(dateRange.start, dateRange.end), [dateRange.start, dateRange.end]);
+  const selectedStationId = drillContext.level === 'station' ? drillContext.stationId : undefined;
+  const selectedStationName = drillContext.level === 'station'
+    ? drillContext.stationName || `站点 #${drillContext.stationId}`
+    : undefined;
+  const selectedCustomerName = drillContext.level === 'customer'
+    ? drillContext.customerName
+    : undefined;
+  const selectedDate = drillContext.selectedDate;
+  const selectedDailyRow = rows?.find(row => row.date === selectedDate);
+
+  const commitDrillContext = useCallback((next: HydrogenDrillContext, mode: 'push' | 'replace') => {
+    const url = buildHydrogenDrillUrl(window.location, next);
+    window.history[mode === 'push' ? 'pushState' : 'replaceState'](null, '', url);
+    setDrillContext(next);
+  }, []);
 
   useEffect(() => {
     let cancelled = false;
     setError(null);
     const query = pick === 'custom'
-      ? { startDate: effectiveRange.start, endDate: effectiveRange.end }
-      : { range: pick };
-    fetchHydrogenDaily(query, customer)
+      ? { startDate: effectiveRange.start, endDate: effectiveRange.end, stationId: selectedStationId, customerName: selectedCustomerName }
+      : { range: pick, stationId: selectedStationId, customerName: selectedCustomerName };
+    fetchHydrogenDaily(query, vehicleScope)
       .then(r => { if (!cancelled) setRows(r); })
       .catch(e => { if (!cancelled) setError(e instanceof Error ? e.message : String(e)); });
     return () => { cancelled = true; };
-  }, [pick, customer, effectiveRange.start, effectiveRange.end]);
+  }, [pick, vehicleScope, effectiveRange.start, effectiveRange.end, selectedStationId, selectedCustomerName, retryKey]);
 
   // 柱图：按日期升序，用于"从左到右时间流"
   const trendData = useMemo(() => (rows ? [...rows].sort((a, b) => a.date.localeCompare(b.date)) : []), [rows]);
   const totalKg = (rows ?? []).reduce((a, r) => a + r.totalKg, 0);
   const activeDays = (rows ?? []).filter(r => r.totalKg > 0).length;
   const stationCount = useMemo(() => {
-    const names = new Set<string>();
-    (rows ?? []).forEach(r => r.stations.forEach(s => names.add(s.name)));
-    return names.size;
+    const ids = new Set<number>();
+    (rows ?? []).forEach(r => r.stations.forEach(s => ids.add(s.stationId)));
+    return ids.size;
   }, [rows]);
   const avgKg = activeDays > 0 ? totalKg / activeDays : 0;
-  const scopeLabel = pick === 'custom'
-    ? '自定义区间'
-    : QUICK_PICK_OPTIONS.find(item => item.id === pick)?.label ?? '当前时段';
+  const scopeLabel = dateRangeModeLabel(pick);
   const rangeText = `${effectiveRange.start} 至 ${effectiveRange.end}`;
+  const orderScopeLabel = selectedCustomerName
+    ? `客户 ${selectedCustomerName}`
+    : selectedStationName
+      ? `站点 ${selectedStationName}`
+      : vehicleScope === 'external' ? '外部车辆' : '羚牛车辆';
   const peakDay = trendData.reduce<HydrogenDailyRow | null>((best, item) => (!best || item.totalKg > best.totalKg ? item : best), null);
   const lowDay = trendData
     .filter(item => item.totalKg > 0)
@@ -92,93 +111,197 @@ export default function HydrogenDaily() {
   });
 
   const applyQuickPick = (nextPick: DateQuickPick) => {
+    const nextRange = getQuickDateRange(nextPick);
     setPick(nextPick);
-    setDateRange(getQuickRange(nextPick));
+    setDateRange(nextRange);
+    commitDrillContext({
+      ...drillContext,
+      vehicleScope,
+      startDate: nextRange.start,
+      endDate: nextRange.end,
+      selectedDate: undefined,
+      orderPage: undefined,
+    }, 'replace');
   };
 
   const updateDateRange = (field: 'start' | 'end', value: string) => {
     if (!value) return;
+    const nextRange = { ...dateRange, [field]: value };
     setPick('custom');
-    setDateRange(prev => ({ ...prev, [field]: value }));
+    const normalized = normalizeDateRange(nextRange.start, nextRange.end);
+    setDateRange(normalized);
+    commitDrillContext({
+      ...drillContext,
+      vehicleScope,
+      startDate: normalized.start,
+      endDate: normalized.end,
+      selectedDate: undefined,
+      orderPage: undefined,
+    }, 'replace');
   };
 
+  const updateVehicleScope = (next: CustomerType) => {
+    setVehicleScope(next);
+    commitDrillContext({
+      ...drillContext,
+      vehicleScope: next,
+      startDate: effectiveRange.start,
+      endDate: effectiveRange.end,
+      orderPage: undefined,
+    }, 'replace');
+  };
+
+  const clearEntity = () => {
+    commitDrillContext({
+      level: 'overview',
+      year: drillContext.year,
+      vehicleScope,
+      startDate: effectiveRange.start,
+      endDate: effectiveRange.end,
+    }, 'replace');
+  };
+
+  const openOrders = (date: string) => {
+    const activeElement = document.activeElement;
+    if (activeElement instanceof HTMLElement || activeElement instanceof SVGElement) {
+      orderTriggerRef.current = activeElement;
+    }
+    commitDrillContext({
+      ...drillContext,
+      vehicleScope,
+      startDate: effectiveRange.start,
+      endDate: effectiveRange.end,
+      selectedDate: date,
+      orderPage: undefined,
+    }, selectedDate === date ? 'replace' : 'push');
+    window.requestAnimationFrame(() => {
+      const orders = document.getElementById(HYDROGEN_ORDERS_ID);
+      orders?.focus({ preventScroll: true });
+      orders?.scrollIntoView({
+        behavior: window.matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth',
+        block: 'start',
+      });
+    });
+  };
+
+  const closeOrders = () => {
+    commitDrillContext({
+      ...drillContext,
+      vehicleScope,
+      startDate: effectiveRange.start,
+      endDate: effectiveRange.end,
+      selectedDate: undefined,
+      orderPage: undefined,
+    }, 'replace');
+    window.requestAnimationFrame(() => orderTriggerRef.current?.focus());
+  };
+
+  const changeOrderPage = useCallback((page: number, mode: 'push' | 'replace') => {
+    commitDrillContext({
+      ...drillContext,
+      orderPage: page > 1 ? page : undefined,
+    }, mode);
+  }, [commitDrillContext, drillContext]);
+
+  const retryLoad = () => {
+    setRows(null);
+    setError(null);
+    setRetryKey(key => key + 1);
+  };
+
+  useEffect(() => {
+    const handlePopState = () => {
+      const next = parseHydrogenDrillContext(window.location.search);
+      setDrillContext(next);
+      setVehicleScope(next.vehicleScope);
+      if (next.startDate && next.endDate) {
+        const normalized = normalizeDateRange(next.startDate, next.endDate);
+        setPick(inferDateRangeMode(normalized.start, normalized.end));
+        setDateRange(normalized);
+      }
+    };
+    window.addEventListener('popstate', handlePopState);
+    return () => window.removeEventListener('popstate', handlePopState);
+  }, []);
+
   return (
     <div className="flex flex-col gap-3">
       <SurfaceCard className="p-2 md:p-3">
-        <div className="flex items-center gap-2 overflow-x-auto pb-1">
-          {QUICK_PICK_OPTIONS.map(opt => (
-            <button
-              key={opt.id}
-              onClick={() => applyQuickPick(opt.id)}
-              className={`min-h-9 shrink-0 rounded-xl border px-3 text-[12px] font-black transition-colors ${
-                pick === opt.id
-                  ? 'border-blue-200 bg-blue-50 text-blue-600 shadow-sm'
-                  : 'border-slate-100 bg-white text-slate-500 hover:bg-slate-50'
-              }`}
-            >
-              {opt.label}
-            </button>
-          ))}
-          <button
-            onClick={() => setPick('custom')}
-            className={`min-h-9 shrink-0 rounded-xl border px-3 text-[12px] font-black transition-colors ${
-              pick === 'custom'
-                ? 'border-blue-200 bg-blue-50 text-blue-600 shadow-sm'
-                : 'border-slate-100 bg-white text-slate-500 hover:bg-slate-50'
-            }`}
-          >
-            自定义
-          </button>
-        </div>
+        <AnalysisDateFilters
+          idPrefix="hydrogen"
+          mode={pick}
+          startDate={dateRange.start}
+          endDate={dateRange.end}
+          onQuickPick={applyQuickPick}
+          onCustom={() => setPick('custom')}
+          onDateChange={updateDateRange}
+        />
 
-        <div className="mt-2 grid grid-cols-2 gap-2">
-          <label className="min-w-0 rounded-xl border border-slate-100 bg-slate-50 px-3 py-2">
-            <span className="block text-[10px] font-black text-slate-400">开始日期</span>
-            <input
-              type="date"
-              value={dateRange.start}
-              onChange={e => updateDateRange('start', e.target.value)}
-              onInput={e => updateDateRange('start', e.currentTarget.value)}
-              className="mt-1 h-6 w-full bg-transparent text-[12px] font-black text-slate-800 outline-none"
-            />
-          </label>
-          <label className="min-w-0 rounded-xl border border-slate-100 bg-slate-50 px-3 py-2">
-            <span className="block text-[10px] font-black text-slate-400">结束日期</span>
-            <input
-              type="date"
-              value={dateRange.end}
-              onChange={e => updateDateRange('end', e.target.value)}
-              onInput={e => updateDateRange('end', e.currentTarget.value)}
-              className="mt-1 h-6 w-full bg-transparent text-[12px] font-black text-slate-800 outline-none"
-            />
-          </label>
-        </div>
-
-        <div className="mt-2 grid grid-cols-2 gap-1 rounded-xl bg-slate-100 p-1">
-          {(['lingniu', 'external'] as const).map(c => (
-            <button
-              key={c}
-              onClick={() => setCustomer(c)}
-              className={`flex min-h-9 items-center justify-center gap-1.5 rounded-lg text-[12px] font-black transition-all ${
-                customer === c ? 'bg-white text-slate-900 shadow-sm' : 'text-slate-500 hover:text-slate-700'
-              }`}
-            >
-              <Truck size={14} />
-              {c === 'external' ? '外部车辆' : '羚牛车辆'}
-            </button>
-          ))}
-        </div>
+        <AnalysisScopeSwitch
+          ariaLabel="氢能车辆范围"
+          value={vehicleScope}
+          options={VEHICLE_SCOPE_OPTIONS}
+          onChange={updateVehicleScope}
+          icon={Truck}
+          className="mt-2"
+        />
       </SurfaceCard>
 
-      <div className="grid grid-cols-2 gap-3 md:grid-cols-4">
+      {selectedStationName && (
+        <section className="flex items-center gap-3 rounded-xl border border-blue-100 bg-blue-50 px-4 py-3 text-blue-700 shadow-sm">
+          <Building2 size={16} className="shrink-0" />
+          <div className="min-w-0 flex-1">
+            <div className="truncate text-xs font-black">{selectedStationName}</div>
+            <div className="mt-0.5 text-[10px] font-bold text-blue-500">站点每日明细 · {rangeText}</div>
+          </div>
+          <button
+            type="button"
+            onClick={clearEntity}
+            className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-white text-blue-500 shadow-sm ring-1 ring-blue-100 hover:text-blue-700"
+            aria-label="清除站点筛选"
+            title="清除站点筛选"
+          >
+            <X size={14} />
+          </button>
+        </section>
+      )}
+
+      {selectedCustomerName && (
+        <section className="flex items-center gap-3 rounded-xl border border-emerald-100 bg-emerald-50 px-4 py-3 text-emerald-700 shadow-sm">
+          <UserRound size={16} className="shrink-0" />
+          <div className="min-w-0 flex-1">
+            <div className="truncate text-xs font-black">{selectedCustomerName}</div>
+            <div className="mt-0.5 text-[10px] font-bold text-emerald-600">客户每日明细 · {rangeText}</div>
+          </div>
+          <button
+            type="button"
+            onClick={clearEntity}
+            className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-white text-emerald-600 shadow-sm ring-1 ring-emerald-100 hover:text-emerald-800"
+            aria-label="清除客户筛选"
+            title="清除客户筛选"
+          >
+            <X size={14} />
+          </button>
+        </section>
+      )}
+
+      {error && (
+        <ErrorState
+          title="氢能数据源暂不可用"
+          message={error}
+          onRetry={retryLoad}
+        />
+      )}
+
+      {!error && rows !== null && <div className="grid grid-cols-2 gap-3 md:grid-cols-4">
         <MetricTile icon={Fuel} label={`${scopeLabel}加氢量`} value={totalKg.toLocaleString('zh-CN', { maximumFractionDigits: 1 })} unit="Kg" helper={rangeText} />
-        <MetricTile icon={Truck} label="车辆归属" value={customer === 'external' ? '外部' : '羚牛'} helper="当前筛选口径" tone="emerald" />
+        <MetricTile icon={Truck} label="车辆归属" value={vehicleScope === 'external' ? '外部' : '羚牛'} helper="当前筛选口径" tone="emerald" />
         <MetricTile icon={TrendingUp} label="有效天数" value={`${activeDays}/${rows?.length ?? 0}`} helper={`日均 ${avgKg.toLocaleString('zh-CN', { maximumFractionDigits: 1 })} Kg`} tone="amber" />
         <MetricTile icon={Plug} label="涉及加氢站" value={stationCount} unit="站" helper="按明细站点去重" tone="slate" />
-      </div>
+      </div>}
 
       {/* 外部车辆：新系统数据还没准备好 */}
-      {customer === 'external' && rows !== null && totalKg === 0 && (
+      {!error && vehicleScope === 'external' && rows !== null && totalKg === 0 && (
         <motion.div
           initial={{ opacity: 0, y: 8 }}
           animate={{ opacity: 1, y: 0 }}
@@ -199,7 +322,7 @@ export default function HydrogenDaily() {
       )}
 
       {/* 时段加氢量柱图（外部车辆无数据时不渲染） */}
-      {!(customer === 'external' && totalKg === 0) && trendData.length > 0 && (
+      {!error && !(vehicleScope === 'external' && totalKg === 0) && trendData.length > 0 && (
         <SurfaceCard>
           <div className="flex items-center justify-between px-4 pt-4 mb-2">
             <span className="text-sm font-bold text-slate-700">每日加氢量</span>
@@ -259,8 +382,23 @@ export default function HydrogenDaily() {
                 />
               )}
               <Bar dataKey="totalKg" radius={[4, 4, 0, 0]}>
-                {trendData.map((_, i) => (
-                  <Cell key={i} fill="url(#hydrogenBarGrad)" />
+                {trendData.map(item => (
+                  <Cell
+                    key={item.date}
+                    fill="url(#hydrogenBarGrad)"
+                    stroke={selectedDate === item.date ? '#1d4ed8' : undefined}
+                    strokeWidth={selectedDate === item.date ? 2 : undefined}
+                    className={item.totalKg > 0 ? 'cursor-pointer outline-none focus:stroke-blue-700 focus:stroke-2' : undefined}
+                    role={item.totalKg > 0 ? 'button' : undefined}
+                    tabIndex={item.totalKg > 0 ? 0 : -1}
+                    aria-expanded={item.totalKg > 0 ? selectedDate === item.date : undefined}
+                    aria-controls={item.totalKg > 0 ? HYDROGEN_ORDERS_ID : undefined}
+                    aria-label={`${item.date}，加氢量 ${item.totalKg.toLocaleString('zh-CN', { maximumFractionDigits: 2 })} Kg${item.totalKg > 0 ? `，查看${orderScopeLabel}加氢订单` : '，无可下钻订单'}`}
+                    onClick={item.totalKg > 0 ? () => openOrders(item.date) : undefined}
+                    onKeyDown={item.totalKg > 0
+                      ? event => activateDrillOnKeyDown(event, () => openOrders(item.date))
+                      : undefined}
+                  />
                 ))}
               </Bar>
               <defs>
@@ -275,30 +413,41 @@ export default function HydrogenDaily() {
         </SurfaceCard>
       )}
 
+      {selectedDate && (
+        <HydrogenOrders
+          date={selectedDate}
+          dailyRow={selectedDailyRow}
+          page={drillContext.orderPage ?? 1}
+          vehicleScope={vehicleScope}
+          stationId={selectedStationId}
+          customerName={selectedCustomerName}
+          onPageChange={changeOrderPage}
+          onClose={closeOrders}
+        />
+      )}
+
       {/* 表格（外部车辆 + 全 0 时不渲染，由上方友好空状态替代） */}
-      {!(customer === 'external' && rows !== null && totalKg === 0) && (
+      {!error && !(vehicleScope === 'external' && rows !== null && totalKg === 0) && (
       <div className="bg-white rounded-2xl border border-slate-100 shadow-sm overflow-hidden">
         {/* 表头 */}
-        <div className="grid grid-cols-[minmax(0,1fr)_84px_80px] md:grid-cols-[minmax(0,1fr)_140px_120px_104px] gap-2 md:gap-3 px-3 py-2 bg-slate-50 text-[11px] font-bold text-slate-500">
+        <div className="grid grid-cols-[minmax(0,1fr)_72px_64px] md:grid-cols-[minmax(0,1fr)_140px_120px_104px] gap-2 md:gap-3 px-3 py-2 bg-slate-50 text-[11px] font-bold text-slate-500">
           <span>日期 / 加氢站</span>
           <span className="hidden md:block text-right">单价 (元/Kg)</span>
           <span className="text-right">加氢量 (Kg)</span>
           <span className="text-right">环比</span>
         </div>
         {/* 合计行 */}
-        <div className="grid grid-cols-[minmax(0,1fr)_84px_80px] md:grid-cols-[minmax(0,1fr)_140px_120px_104px] gap-2 md:gap-3 px-3 py-2 bg-blue-50/50 text-[12px] text-blue-600 font-bold">
+        <div className="grid grid-cols-[minmax(0,1fr)_72px_64px] md:grid-cols-[minmax(0,1fr)_140px_120px_104px] gap-2 md:gap-3 px-3 py-2 bg-blue-50/50 text-[12px] text-blue-600 font-bold">
           <span>合计</span>
           <span className="hidden md:block" />
           <span className="text-right">{totalKg.toLocaleString('zh-CN', { maximumFractionDigits: 2 })}</span>
           <span />
         </div>
         {/* 主行 + 子行 */}
-        {error ? (
-          <div className="p-3"><ErrorState message={error} /></div>
-        ) : rows === null ? (
-          <div className="p-3"><LoadingState label="正在加载加氢明细" /></div>
+        {rows === null ? (
+          <LoadingState label="正在加载加氢明细" variant="inline" />
         ) : rows.length === 0 ? (
-          <div className="p-3"><EmptyState title="暂无加氢数据" description="请切换时间范围或车辆归属" /></div>
+          <EmptyState title="暂无加氢数据" description="请切换时间范围或车辆归属" variant="inline" />
         ) : rows.map(r => {
           const open = expanded.has(r.date);
           const isAbnormal = Math.abs(r.chainPct) >= 0.3;
@@ -307,20 +456,37 @@ export default function HydrogenDaily() {
             : '';
           return (
             <div key={r.date} className={`border-t border-slate-100 ${abnormalBg}`}>
-              <button
-                onClick={() => toggle(r.date)}
-                className="w-full grid grid-cols-[minmax(0,1fr)_84px_80px] md:grid-cols-[minmax(0,1fr)_140px_120px_104px] gap-2 md:gap-3 px-3 py-2.5 text-left hover:bg-slate-50/60 transition-colors"
-              >
-                <span className="flex items-center gap-1 text-[12px] text-slate-700 font-bold">
-                  <ChevronRight size={14} className={`transition-transform ${open ? 'rotate-90' : ''} text-slate-400`} />
-                  {r.date}
+              <div className={`grid w-full grid-cols-[minmax(0,1fr)_72px_64px] gap-2 px-3 py-2.5 text-left transition-colors hover:bg-slate-50/60 md:grid-cols-[minmax(0,1fr)_140px_120px_104px] md:gap-3 ${selectedDate === r.date ? 'bg-blue-50/70' : ''}`}>
+                <span className="flex min-w-0 items-center gap-1">
+                  <button
+                    type="button"
+                    onClick={() => toggle(r.date)}
+                    className="flex min-w-0 items-center gap-1 text-[12px] font-bold text-slate-700"
+                    aria-expanded={open}
+                    aria-label={`${open ? '收起' : '展开'} ${r.date} 加氢站明细`}
+                  >
+                    <ChevronRight size={14} className={`shrink-0 transition-transform ${open ? 'rotate-90' : ''} text-slate-400`} />
+                    <span className="truncate">{r.date}</span>
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => openOrders(r.date)}
+                    disabled={r.totalKg <= 0}
+                    className="ml-1 flex h-7 w-7 shrink-0 items-center justify-center rounded-lg text-slate-400 hover:bg-blue-100 hover:text-blue-700 disabled:cursor-not-allowed disabled:opacity-25"
+                    aria-label={`查看 ${r.date} 加氢订单`}
+                    aria-expanded={selectedDate === r.date}
+                    aria-controls={HYDROGEN_ORDERS_ID}
+                    title="查看当日订单"
+                  >
+                    <ReceiptText size={13} />
+                  </button>
                 </span>
                 <span className="hidden md:block text-right text-[12px] text-slate-300">—</span>
                 <span className="text-right text-[12px] text-slate-700 font-bold tabular-nums">
                   {r.totalKg.toLocaleString('zh-CN', { maximumFractionDigits: 2 })}
                 </span>
                 <span className="text-right"><TrendBadge value={r.chainPct} /></span>
-              </button>
+              </div>
               <AnimatePresence initial={false}>
                 {open && (
                   <motion.div
@@ -333,7 +499,7 @@ export default function HydrogenDaily() {
                     {r.stations.map(s => (
                       <div
                         key={s.name}
-                        className="grid grid-cols-[minmax(0,1fr)_84px_80px] md:grid-cols-[minmax(0,1fr)_140px_120px_104px] gap-2 md:gap-3 px-3 py-2 pl-6 md:pl-9 border-t border-slate-100 first:border-t-0 items-start"
+                        className="grid grid-cols-[minmax(0,1fr)_72px_64px] md:grid-cols-[minmax(0,1fr)_140px_120px_104px] gap-2 md:gap-3 px-3 py-2 pl-6 md:pl-9 border-t border-slate-100 first:border-t-0 items-start"
                       >
                         <div className="min-w-0">
                           <div className="text-[12px] text-slate-700 font-medium whitespace-nowrap leading-snug">
@@ -362,7 +528,7 @@ export default function HydrogenDaily() {
         })}
       </div>
       )}
-      <RotatingFooterHint />
+      {!error && <RotatingFooterHint />}
     </div>
   );
 }

src/modules/energy/HydrogenModule.tsx

@@ -4,6 +4,7 @@ import HydrogenView, { type HydrogenSubTab } from './HydrogenView';
 import SubTabs from './SubTabs';
 import { useHashSubTab } from './useHashSubTab';
 import { FadeIn, PageFrame } from '../../components/ui/surface';
+import BiHeaderActions from '../../components/BiHeaderActions';
 
 const SUB_TABS = [
   { id: 'daily',    label: '每日', icon: CalendarDays },
@@ -21,11 +22,18 @@ export default function HydrogenModule() {
       icon={CalendarDays}
       eyebrow="ENERGY BI"
       meta="数据单位清晰标注 · 支持日/总览切换"
+      actions={<BiHeaderActions domain="hydrogen" />}
     >
-      <SubTabs tabs={SUB_TABS} active={sub} onChange={setSub} />
+      <SubTabs tabs={SUB_TABS} active={sub} onChange={setSub} idPrefix="hydrogen-view" ariaLabel="氢能分析视图" />
       <AnimatePresence mode="wait">
         <FadeIn key={sub}>
-          <HydrogenView sub={sub} />
+          <div
+            id={`hydrogen-view-panel-${sub}`}
+            role="tabpanel"
+            aria-labelledby={`hydrogen-view-tab-${sub}`}
+          >
+            <HydrogenView sub={sub} />
+          </div>
         </FadeIn>
       </AnimatePresence>
     </PageFrame>

src/modules/energy/HydrogenOrders.tsx

@@ -0,0 +1,185 @@
+import { useEffect, useState } from 'react';
+import { CheckCircle2, ChevronLeft, ChevronRight, ReceiptText, TriangleAlert, X } from 'lucide-react';
+import Blur from '../../components/Blur';
+import { EmptyState, ErrorState, LoadingState } from '../../components/ui/surface';
+import { fetchHydrogenOrders } from './api';
+import type { CustomerType, HydrogenDailyRow, HydrogenOrderResponse } from './types';
+import { reconcileHydrogenDaily } from './hydrogen-reconciliation';
+
+function fmtMoney(value: number): string {
+  return `¥${value.toLocaleString('zh-CN', { minimumFractionDigits: 2, maximumFractionDigits: 2 })}`;
+}
+
+export default function HydrogenOrders({
+  date,
+  dailyRow,
+  page,
+  vehicleScope,
+  stationId,
+  customerName,
+  onPageChange,
+  onClose,
+}: {
+  date: string;
+  dailyRow?: HydrogenDailyRow;
+  page: number;
+  vehicleScope: CustomerType;
+  stationId?: number;
+  customerName?: string;
+  onPageChange: (page: number, mode: 'push' | 'replace') => void;
+  onClose: () => void;
+}) {
+  const [data, setData] = useState<HydrogenOrderResponse | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [retryKey, setRetryKey] = useState(0);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    setData(null);
+    fetchHydrogenOrders({ date, customer: vehicleScope, stationId, customerName, page, limit: 20 })
+      .then(result => {
+        if (cancelled) return;
+        if (page > result.totalPages) {
+          onPageChange(result.totalPages, 'replace');
+          return;
+        }
+        setData(result);
+      })
+      .catch(loadError => {
+        if (!cancelled) setError(loadError instanceof Error ? loadError.message : String(loadError));
+      })
+      .finally(() => { if (!cancelled) setLoading(false); });
+    return () => { cancelled = true; };
+  }, [vehicleScope, customerName, date, onPageChange, page, retryKey, stationId]);
+
+  const totalPages = data?.totalPages ?? 1;
+  const scope = customerName
+    ? `客户：${customerName}`
+    : stationId !== undefined
+      ? `站点 #${stationId}`
+      : vehicleScope === 'external' ? '外部车辆' : '羚牛车辆';
+  const reconciliation = data && dailyRow
+    ? reconcileHydrogenDaily(dailyRow, data, vehicleScope, stationId, customerName)
+    : null;
+  const grainDifferences = reconciliation
+    ? [
+        !reconciliation.dateMatches && '日期',
+        !reconciliation.scopeMatches && '车辆范围',
+        !reconciliation.entityMatches && '站点/客户范围',
+      ].filter(Boolean).join('、')
+    : '';
+
+  return (
+    <section
+      id="hydrogen-orders"
+      tabIndex={-1}
+      className="scroll-mt-3 overflow-hidden rounded-lg border border-blue-100 bg-white shadow-sm outline-none focus-visible:ring-2 focus-visible:ring-blue-500 focus-visible:ring-offset-2"
+    >
+      <header className="flex items-start justify-between gap-3 border-b border-blue-100 bg-blue-50/60 px-3 py-3 md:px-4">
+        <div className="min-w-0">
+          <div className="flex items-center gap-2 text-xs font-black text-blue-800">
+            <ReceiptText size={15} />{date} 加氢订单
+          </div>
+          <div className="mt-1 truncate text-[10px] font-bold text-blue-500">{scope} · 按加氢时间倒序</div>
+        </div>
+        <button
+          type="button"
+          onClick={onClose}
+          className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-white text-blue-500 ring-1 ring-blue-100 hover:text-blue-700"
+          aria-label="关闭加氢订单明细"
+          title="关闭订单明细"
+        >
+          <X size={14} />
+        </button>
+      </header>
+
+      {data ? (
+        <>
+          <div className="grid grid-cols-3 gap-2 border-b border-slate-100 bg-slate-50 px-3 py-2 text-[10px] font-bold md:px-4">
+            <div className="min-w-0"><span className="text-slate-400">订单 / 加氢量</span><div className="mt-1 break-words text-slate-700">{data.recordCount} 笔 · {data.totalKg.toLocaleString('zh-CN')} Kg</div></div>
+            <div className="min-w-0"><span className="text-slate-400">采购成本</span><div className="mt-1 break-all text-slate-700">{fmtMoney(data.totalCost)}</div></div>
+            <div className="min-w-0"><span className="text-slate-400">客户收入</span><div className="mt-1 break-all text-emerald-700">{fmtMoney(data.totalRevenue)}</div></div>
+          </div>
+          {reconciliation && (
+            <div
+              role={reconciliation.matches ? 'status' : 'alert'}
+              className={`flex items-start gap-2 border-b px-3 py-2 text-[10px] font-bold md:px-4 ${
+                reconciliation.matches
+                  ? 'border-emerald-100 bg-emerald-50 text-emerald-700'
+                  : 'border-amber-200 bg-amber-50 text-amber-800'
+              }`}
+            >
+              {reconciliation.matches
+                ? <CheckCircle2 size={14} className="mt-0.5 shrink-0" />
+                : <TriangleAlert size={14} className="mt-0.5 shrink-0" />}
+              <span>
+                {reconciliation.matches
+                  ? `口径核对通过：日汇总与 ${data.recordCount} 笔订单全量加氢量一致`
+                  : `口径存在差异：加氢量 ${reconciliation.kgDifference >= 0 ? '+' : ''}${reconciliation.kgDifference.toFixed(2)} Kg${grainDifferences ? ` · ${grainDifferences}不一致` : ''}`}
+              </span>
+            </div>
+          )}
+        </>
+      ) : null}
+
+      {error ? (
+        <ErrorState
+          title="订单数据暂不可用"
+          message={error}
+          onRetry={() => setRetryKey(key => key + 1)}
+          variant="inline"
+        />
+      ) : loading && !data ? (
+        <LoadingState label="正在加载加氢订单" variant="inline" />
+      ) : data?.items.length === 0 ? (
+        <EmptyState title="当前筛选下无加氢订单" description="请切换日期、车辆归属或实体范围" variant="inline" />
+      ) : data ? (
+        <>
+          <div className="hidden overflow-x-auto md:block">
+            <table className="w-full min-w-[820px] text-left text-[11px]">
+              <thead className="text-[10px] font-black text-slate-400">
+                <tr><th className="px-4 py-2">时间 / 车辆</th><th className="px-3 py-2">客户 / 站点</th><th className="px-3 py-2 text-right">加氢量</th><th className="px-3 py-2 text-right">采购成本</th><th className="px-4 py-2 text-right">客户收入</th></tr>
+              </thead>
+              <tbody className="divide-y divide-slate-100">
+                {data.items.map(order => (
+                  <tr key={order.rowNumber}>
+                    <td className="px-4 py-3"><div className="font-bold text-slate-600">{order.refuelTime}</div><div className="mt-1 font-mono text-[10px] font-black text-slate-800"><Blur>{order.plate}</Blur></div></td>
+                    <td className="px-3 py-3"><div className="font-bold text-slate-700"><Blur>{order.customerName}</Blur></div><div className="mt-1 text-[9px] font-bold text-slate-400">{order.stationName}</div></td>
+                    <td className="px-3 py-3 text-right font-black text-slate-800">{order.amountKg.toLocaleString('zh-CN')} Kg</td>
+                    <td className="px-3 py-3 text-right"><div className="font-black text-slate-800">{fmtMoney(order.costTotal)}</div><div className="mt-1 text-[9px] font-bold text-slate-400">{fmtMoney(order.costPrice)} / Kg</div></td>
+                    <td className="px-4 py-3 text-right"><div className="font-black text-emerald-700">{fmtMoney(order.revenue)}</div><div className="mt-1 text-[9px] font-bold text-slate-400">单价 {fmtMoney(order.customerPrice)}</div></td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </div>
+          <div className="divide-y divide-slate-100 md:hidden">
+            {data.items.map(order => (
+              <article key={order.rowNumber} className="px-3 py-3">
+                <div className="flex items-start justify-between gap-3">
+                  <div className="min-w-0"><div className="font-mono text-xs font-black text-slate-800"><Blur>{order.plate}</Blur></div><div className="mt-1 text-[9px] font-bold text-slate-400">{order.refuelTime}</div></div>
+                  <div className="shrink-0 text-right text-sm font-black text-slate-800">{order.amountKg.toLocaleString('zh-CN')} Kg</div>
+                </div>
+                <div className="mt-2 truncate text-[10px] font-bold text-slate-600"><Blur>{order.customerName}</Blur> · {order.stationName}</div>
+                <div className="mt-2 flex justify-between gap-2 text-[9px] font-bold text-slate-400"><span>成本 {fmtMoney(order.costTotal)}</span><span className="text-emerald-700">收入 {fmtMoney(order.revenue)}</span></div>
+              </article>
+            ))}
+          </div>
+        </>
+      ) : null}
+
+      {data ? (
+        <footer className="flex items-center justify-between border-t border-slate-100 px-3 py-3 md:px-4">
+          <span className="text-[10px] font-bold text-slate-400">第 {page} / {totalPages} 页</span>
+          <div className="flex gap-2">
+            <button type="button" onClick={() => onPageChange(Math.max(1, page - 1), 'push')} disabled={page <= 1 || loading} className="flex h-8 w-8 items-center justify-center rounded-lg border border-slate-200 text-slate-500 disabled:opacity-30" aria-label="上一页加氢订单" title="上一页"><ChevronLeft size={14} /></button>
+            <button type="button" onClick={() => onPageChange(Math.min(totalPages, page + 1), 'push')} disabled={page >= totalPages || loading} className="flex h-8 w-8 items-center justify-center rounded-lg border border-slate-200 text-slate-500 disabled:opacity-30" aria-label="下一页加氢订单" title="下一页"><ChevronRight size={14} /></button>
+          </div>
+        </footer>
+      ) : null}
+    </section>
+  );
+}

src/modules/energy/HydrogenOverview.tsx

@@ -2,10 +2,12 @@ import { useCallback, useEffect, useRef, useState } from 'react';
 import {
   BarChart, Bar, XAxis, YAxis, ResponsiveContainer, Cell, PieChart, Pie, Tooltip, LabelList, Legend,
 } from 'recharts';
-import { Fuel, Wallet, CalendarDays, Sparkles, TrendingUp, RefreshCw, Gauge, AlertTriangle, Building2 } from 'lucide-react';
+import { Fuel, Wallet, CalendarDays, Sparkles, TrendingUp, RefreshCw, Gauge, AlertTriangle, Building2, ChevronRight, UserRound } from 'lucide-react';
 import { motion, AnimatePresence } from 'motion/react';
 import { fetchHydrogenOverview, type HydrogenOverviewResponse } from './api';
 import RotatingFooterHint from '../../components/RotatingFooterHint';
+import { buildHydrogenDrillUrl } from './hydrogen-drill-context';
+import { ErrorState } from '../../components/ui/surface';
 
 const REGION_COLORS = [
   '#3b82f6', '#22d3ee', '#a855f7', '#f59e0b',
@@ -119,7 +121,14 @@ export default function HydrogenOverview() {
   }, [year, load]);
 
   if (error && !data) {
-    return <div className="bg-red-50 text-red-600 rounded-2xl border border-red-100 p-4 text-sm">加载失败：{error}</div>;
+    return (
+      <ErrorState
+        title="氢能数据源暂不可用"
+        message={error}
+        onRetry={() => void load(year, true)}
+        retrying={refreshing}
+      />
+    );
   }
   if (!data) {
     return <HydrogenOverviewSkeleton />;
@@ -155,6 +164,45 @@ export default function HydrogenOverview() {
   const top5Share = top5.reduce((sum, item) => sum + item.kg, 0) / Math.max(1, k.yearKg) * 100;
   const profitYield = k.yearRevenue > 0 ? k.yearProfit / k.yearRevenue * 100 : 0;
   const stationAvgKg = stations.length > 0 ? k.yearKg / stations.length : 0;
+  const openStation = (station: typeof stations[number]) => {
+    const now = new Date();
+    const endDate = activeYear === now.getFullYear()
+      ? `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
+      : `${activeYear}-12-31`;
+    const url = buildHydrogenDrillUrl(
+      { pathname: window.location.pathname, search: window.location.search, hash: '#hydrogen' },
+      {
+        level: 'station',
+        year: activeYear,
+        stationId: station.id,
+        stationName: station.name,
+        vehicleScope: 'lingniu',
+        startDate: `${activeYear}-01-01`,
+        endDate,
+      },
+    );
+    window.history.pushState(null, '', url);
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+  };
+  const openCustomer = (customer: typeof customers[number]) => {
+    const now = new Date();
+    const endDate = activeYear === now.getFullYear()
+      ? `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`
+      : `${activeYear}-12-31`;
+    const url = buildHydrogenDrillUrl(
+      { pathname: window.location.pathname, search: window.location.search, hash: '#hydrogen' },
+      {
+        level: 'customer',
+        year: activeYear,
+        customerName: customer.name,
+        vehicleScope: 'lingniu',
+        startDate: `${activeYear}-01-01`,
+        endDate,
+      },
+    );
+    window.history.pushState(null, '', url);
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+  };
 
   // 月度收支组合数据（推算"年内每月"图）
   const monthlyDual = monthly.map(m => ({
@@ -213,22 +261,22 @@ export default function HydrogenOverview() {
           icon={<Wallet size={14} className="text-blue-600" strokeWidth={2.4} />}
           iconBg="bg-blue-50"
           accentClass="text-slate-800"
-          label="累计加氢费"
+          label="累计加氢成本"
           hero={{ value: `¥${yearFeeFmt.value}`, unit: yearFeeFmt.unit }}
           rows={[
-            { label: '我司承担', value: `¥${fmtYuan(k.ourYearFee).value} ${fmtYuan(k.ourYearFee).unit}` },
-            { label: '客户承担', value: `¥${customerYearFeeFmt.value} ${customerYearFeeFmt.unit}` },
+            { label: '公司单成本', value: `¥${fmtYuan(k.ourYearFee).value} ${fmtYuan(k.ourYearFee).unit}` },
+            { label: '客户单成本', value: `¥${customerYearFeeFmt.value} ${customerYearFeeFmt.unit}` },
           ]}
         />
         <KpiCard
           icon={<TrendingUp size={14} className="text-emerald-600" strokeWidth={2.4} />}
           iconBg="bg-emerald-50"
           accentClass={profitColor}
-          label="时享加氢获利"
+          label="客户单毛利"
           hero={{ value: `¥${yearProfitFmt.value}`, unit: yearProfitFmt.unit }}
           rows={[
             { label: '收入', value: `¥${yearRevenueFmt.value} ${yearRevenueFmt.unit}` },
-            { label: '成本', value: `¥${yearFeeFmt.value} ${yearFeeFmt.unit}` },
+            { label: '客户单成本', value: `¥${customerYearFeeFmt.value} ${customerYearFeeFmt.unit}` },
           ]}
         />
         <KpiCard
@@ -292,7 +340,7 @@ export default function HydrogenOverview() {
         <div className="rounded-2xl border border-slate-100 bg-white p-3 shadow-sm">
           <div className="flex items-center justify-between gap-2">
             <div>
-              <div className="text-[11px] font-black text-slate-400">收支健康度</div>
+              <div className="text-[11px] font-black text-slate-400">客户单毛利率</div>
               <div className={`mt-1 text-lg font-black ${profitYield >= 0 ? 'text-emerald-600' : 'text-rose-600'}`}>
                 {profitYield.toFixed(1)}%
               </div>
@@ -302,7 +350,7 @@ export default function HydrogenOverview() {
             </span>
           </div>
           <div className="mt-2 text-[11px] font-bold leading-relaxed text-slate-500">
-            时享获利 {yearProfitFmt.value}{yearProfitFmt.unit} · 客户收入 {yearRevenueFmt.value}{yearRevenueFmt.unit}
+            客户单毛利 {yearProfitFmt.value}{yearProfitFmt.unit} · 客户收入 {yearRevenueFmt.value}{yearRevenueFmt.unit}
             {profitYield < 0 ? ' · 需关注亏损站点与客户价格' : ' · 当前保持正向收益'}
           </div>
         </div>
@@ -497,7 +545,17 @@ export default function HydrogenOverview() {
                   return (
                     <tr key={s.name + i} className="border-b border-slate-50 hover:bg-slate-50/60">
                       <td className="py-1.5 pl-1 text-slate-400 tabular-nums">{i + 1}</td>
-                      <td className="py-1.5 text-slate-700 truncate max-w-[180px]">{s.name}</td>
+                      <td className="py-1.5 max-w-[180px]">
+                        <button
+                          type="button"
+                          onClick={() => openStation(s)}
+                          className="flex max-w-full items-center gap-1 text-left font-bold text-slate-700 hover:text-blue-600"
+                          title={`查看 ${s.name} 每日明细`}
+                        >
+                          <span className="truncate">{s.name}</span>
+                          <ChevronRight size={12} className="shrink-0 text-slate-300" />
+                        </button>
+                      </td>
                       <td className="py-1.5 text-right tabular-nums font-bold text-slate-700">
                         {kgFmt.value}<span className="text-slate-400 font-normal ml-0.5">{kgFmt.unit}</span>
                       </td>
@@ -556,7 +614,18 @@ export default function HydrogenOverview() {
                   return (
                     <tr key={c2.name + i} className="border-b border-slate-50 hover:bg-slate-50/60">
                       <td className="py-1.5 pl-1 text-slate-400 tabular-nums">{i + 1}</td>
-                      <td className="py-1.5 text-slate-700 truncate max-w-[200px]">{c2.name}</td>
+                      <td className="py-1.5 max-w-[200px]">
+                        <button
+                          type="button"
+                          onClick={() => openCustomer(c2)}
+                          className="flex max-w-full items-center gap-1 text-left font-bold text-slate-700 hover:text-blue-600"
+                          title={`查看 ${c2.name} 每日明细`}
+                        >
+                          <UserRound size={12} className="shrink-0 text-slate-300" />
+                          <span className="truncate">{c2.name}</span>
+                          <ChevronRight size={12} className="shrink-0 text-slate-300" />
+                        </button>
+                      </td>
                       <td className="py-1.5 text-center hidden sm:table-cell">
                         {c2.payer === 'lingniu' ? (
                           <span className="px-1.5 py-0.5 rounded bg-blue-50 text-blue-600 text-[10px] font-bold">羚牛</span>

src/modules/energy/SubTabs.tsx

@@ -11,12 +11,14 @@ interface Props<T extends string> {
   tabs: readonly SubTab<T>[];
   active: T;
   onChange: (id: T) => void;
+  idPrefix: string;
+  ariaLabel: string;
 }
 
-export default function SubTabs<T extends string>({ tabs, active, onChange }: Props<T>) {
+export default function SubTabs<T extends string>({ tabs, active, onChange, idPrefix, ariaLabel }: Props<T>) {
   return (
     <div className="sticky top-0 z-30 -mx-3 bg-[var(--app-bg)] px-3 pb-2 pt-1 shadow-[0_8px_12px_-12px_rgba(15,23,42,0.08)] md:-mx-6 md:top-12 md:px-6">
-      <SegmentedNav tabs={tabs} active={active} onChange={onChange} />
+      <SegmentedNav tabs={tabs} active={active} onChange={onChange} idPrefix={idPrefix} ariaLabel={ariaLabel} />
     </div>
   );
 }

src/modules/energy/api.ts

@@ -1,9 +1,13 @@
 import { fetchJson } from '../../auth/api-client';
 import type {
   HydrogenKpi, HydrogenStationTop, HydrogenRegionShare, HydrogenMonthlyPoint, HydrogenDailyRow,
+  HydrogenOrderResponse,
   HydrogenCustomerRow, HydrogenStationFull,
   ElectricKpi, ElectricDailyRow, ElectricMonthGroup,
-  CustomerType, DateQuickPick,
+  ElectricChargeOrderResponse,
+  EtcOverviewResponse,
+  EtcBillResponse, EtcTollRecordResponse,
+  CustomerType, DateQuickPick, ElectricVehicleScope,
 } from './types';
 
 const BASE = '/api/energy';
@@ -31,29 +35,92 @@ export interface HydrogenDailyQuery {
   range?: DateQuickPick;
   startDate?: string;
   endDate?: string;
+  stationId?: number;
+  customerName?: string;
 }
 
-export function fetchHydrogenDaily(query: HydrogenDailyQuery, customer: CustomerType): Promise<HydrogenDailyRow[]> {
-  const q = new URLSearchParams({ customer });
+export function fetchHydrogenDaily(query: HydrogenDailyQuery, vehicleScope: CustomerType): Promise<HydrogenDailyRow[]> {
+  const q = new URLSearchParams({ customer: vehicleScope });
   if (query.range) q.set('range', query.range);
   if (query.startDate) q.set('startDate', query.startDate);
   if (query.endDate) q.set('endDate', query.endDate);
+  if (query.stationId !== undefined) q.set('stationId', String(query.stationId));
+  if (query.customerName) q.set('customerName', query.customerName);
   return fetchJson<HydrogenDailyRow[]>(`${BASE}/hydrogen/daily?${q.toString()}`);
 }
 
+export interface HydrogenOrderQuery {
+  date: string;
+  customer: CustomerType;
+  stationId?: number;
+  customerName?: string;
+  page?: number;
+  limit?: number;
+}
+
+export function fetchHydrogenOrders(query: HydrogenOrderQuery): Promise<HydrogenOrderResponse> {
+  const params = new URLSearchParams({
+    date: query.date,
+    customer: query.customer,
+    page: String(query.page ?? 1),
+    limit: String(query.limit ?? 20),
+  });
+  if (query.stationId !== undefined) params.set('stationId', String(query.stationId));
+  if (query.customerName) params.set('customerName', query.customerName);
+  return fetchJson<HydrogenOrderResponse>(`${BASE}/hydrogen/orders?${params}`);
+}
+
 export interface ElectricOverviewResponse {
   kpi: ElectricKpi;
   trend: ElectricDailyRow[];
+  latestRecordAt: string | null;
 }
 
 export function fetchElectricOverview(): Promise<ElectricOverviewResponse> {
   return fetchJson<ElectricOverviewResponse>(`${BASE}/electric/overview`);
 }
 
-export function fetchElectricMonthly(customer: CustomerType, query: HydrogenDailyQuery = { range: 'last15' }): Promise<ElectricMonthGroup[]> {
-  const q = new URLSearchParams({ customer });
+export function fetchElectricMonthly(vehicleScope: ElectricVehicleScope, query: HydrogenDailyQuery = { range: 'last15' }): Promise<ElectricMonthGroup[]> {
+  const q = new URLSearchParams({ customer: vehicleScope });
   if (query.range) q.set('range', query.range);
   if (query.startDate) q.set('startDate', query.startDate);
   if (query.endDate) q.set('endDate', query.endDate);
   return fetchJson<ElectricMonthGroup[]>(`${BASE}/electric/monthly?${q.toString()}`);
 }
+
+export function fetchElectricOrders(date: string, vehicleScope: ElectricVehicleScope): Promise<ElectricChargeOrderResponse> {
+  const q = new URLSearchParams({ date, customer: vehicleScope });
+  return fetchJson<ElectricChargeOrderResponse>(`${BASE}/electric/orders?${q.toString()}`);
+}
+
+export function fetchEtcOverview(force = false): Promise<EtcOverviewResponse> {
+  return fetchJson<EtcOverviewResponse>(`${BASE}/etc/overview${force ? '?force=1' : ''}`);
+}
+
+export interface EtcListQuery {
+  page?: number;
+  limit?: number;
+  startDate?: string;
+  endDate?: string;
+  search?: string;
+}
+
+function etcListParams(query: EtcListQuery): string {
+  const params = new URLSearchParams();
+  if (query.page) params.set('page', String(query.page));
+  if (query.limit) params.set('limit', String(query.limit));
+  if (query.startDate) params.set('startDate', query.startDate);
+  if (query.endDate) params.set('endDate', query.endDate);
+  if (query.search) params.set('search', query.search);
+  return params.toString();
+}
+
+export function fetchEtcRecords(query: EtcListQuery): Promise<EtcTollRecordResponse> {
+  const params = etcListParams(query);
+  return fetchJson<EtcTollRecordResponse>(`${BASE}/etc/records${params ? `?${params}` : ''}`);
+}
+
+export function fetchEtcBills(query: EtcListQuery): Promise<EtcBillResponse> {
+  const params = etcListParams(query);
+  return fetchJson<EtcBillResponse>(`${BASE}/etc/bills${params ? `?${params}` : ''}`);
+}

src/modules/energy/date-range.test.ts

@@ -0,0 +1,33 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  dateRangeModeLabel,
+  getQuickDateRange,
+  inferDateRangeMode,
+  normalizeDateRange,
+} from './date-range.js';
+
+const FRIDAY = new Date(2026, 7, 7, 16, 30, 0);
+
+test('builds shared quick date ranges from local calendar days', () => {
+  assert.deepEqual(getQuickDateRange('thisWeek', FRIDAY), { start: '2026-08-03', end: '2026-08-07' });
+  assert.deepEqual(getQuickDateRange('thisMonth', FRIDAY), { start: '2026-08-01', end: '2026-08-07' });
+  assert.deepEqual(getQuickDateRange('last15', FRIDAY), { start: '2026-07-24', end: '2026-08-07' });
+});
+
+test('normalizes date order and publishes consistent labels', () => {
+  assert.deepEqual(normalizeDateRange('2026-08-07', '2026-08-01'), { start: '2026-08-01', end: '2026-08-07' });
+  assert.equal(dateRangeModeLabel('thisMonth'), '本月');
+  assert.equal(dateRangeModeLabel('custom'), '自定义区间');
+});
+
+test('restores a quick mode only while URL dates still match that calendar range', () => {
+  assert.equal(inferDateRangeMode('2026-08-03', '2026-08-07', FRIDAY), 'thisWeek');
+  assert.equal(inferDateRangeMode('2026-08-01', '2026-08-07', FRIDAY), 'thisMonth');
+  assert.equal(inferDateRangeMode('2026-08-07', '2026-07-24', FRIDAY), 'last15');
+  assert.equal(inferDateRangeMode('2026-08-01', '2026-08-06', FRIDAY), 'custom');
+  assert.equal(
+    inferDateRangeMode('2026-08-01', '2026-08-07', new Date(2026, 7, 8, 9, 0, 0)),
+    'custom',
+  );
+});

src/modules/energy/date-range.ts

@@ -0,0 +1,59 @@
+import type { DateQuickPick } from './types';
+
+export type DateRangeMode = DateQuickPick | 'custom';
+
+export interface DateRangeValue {
+  start: string;
+  end: string;
+}
+
+const LABELS: Record<DateQuickPick, string> = {
+  thisWeek: '本周',
+  thisMonth: '本月',
+  last15: '近 15 天',
+};
+
+function fmtYmd(date: Date): string {
+  return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+}
+
+function addDays(date: Date, days: number): Date {
+  const next = new Date(date);
+  next.setDate(next.getDate() + days);
+  return next;
+}
+
+export function getQuickDateRange(pick: DateQuickPick, now = new Date()): DateRangeValue {
+  const today = new Date(now);
+  today.setHours(0, 0, 0, 0);
+  if (pick === 'thisWeek') {
+    const day = today.getDay() || 7;
+    return { start: fmtYmd(addDays(today, -(day - 1))), end: fmtYmd(today) };
+  }
+  if (pick === 'thisMonth') {
+    return { start: fmtYmd(new Date(today.getFullYear(), today.getMonth(), 1)), end: fmtYmd(today) };
+  }
+  return { start: fmtYmd(addDays(today, -14)), end: fmtYmd(today) };
+}
+
+export function normalizeDateRange(start: string, end: string): DateRangeValue {
+  return start <= end ? { start, end } : { start: end, end: start };
+}
+
+export function inferDateRangeMode(start: string, end: string, now = new Date()): DateRangeMode {
+  const range = normalizeDateRange(start, end);
+  const match = QUICK_DATE_OPTIONS.find(({ id }) => {
+    const quickRange = getQuickDateRange(id, now);
+    return quickRange.start === range.start && quickRange.end === range.end;
+  });
+  return match?.id ?? 'custom';
+}
+
+export function dateRangeModeLabel(mode: DateRangeMode): string {
+  return mode === 'custom' ? '自定义区间' : LABELS[mode];
+}
+
+export const QUICK_DATE_OPTIONS = (Object.keys(LABELS) as DateQuickPick[]).map(id => ({
+  id,
+  label: LABELS[id],
+}));

src/modules/energy/drill-interaction.test.ts

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { activateDrillOnKeyDown } from './drill-interaction.js';
+
+test('activates drilldown with Enter and Space only', () => {
+  for (const key of ['Enter', ' ']) {
+    let prevented = false;
+    let activations = 0;
+    const handled = activateDrillOnKeyDown(
+      { key, preventDefault: () => { prevented = true; } },
+      () => { activations += 1; },
+    );
+    assert.equal(handled, true);
+    assert.equal(prevented, true);
+    assert.equal(activations, 1);
+  }
+
+  let activations = 0;
+  const handled = activateDrillOnKeyDown(
+    { key: 'ArrowRight', preventDefault: () => assert.fail('must not prevent navigation keys') },
+    () => { activations += 1; },
+  );
+  assert.equal(handled, false);
+  assert.equal(activations, 0);
+});

src/modules/energy/drill-interaction.ts

@@ -0,0 +1,11 @@
+export interface DrillKeyEvent {
+  key: string;
+  preventDefault: () => void;
+}
+
+export function activateDrillOnKeyDown(event: DrillKeyEvent, activate: () => void): boolean {
+  if (event.key !== 'Enter' && event.key !== ' ') return false;
+  event.preventDefault();
+  activate();
+  return true;
+}

src/modules/energy/electric-drill-context.test.ts

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildElectricDrillUrl,
+  parseElectricDrillContext,
+} from './electric-drill-context.js';
+
+test('parses electric scope, range, and selected day', () => {
+  assert.deepEqual(
+    parseElectricDrillContext('?electricScope=external&electricStart=2026-07-01&electricEnd=2026-07-31&electricDate=2026-07-24'),
+    {
+      vehicleScope: 'external',
+      startDate: '2026-07-01',
+      endDate: '2026-07-31',
+      selectedDate: '2026-07-24',
+    },
+  );
+});
+
+test('drops invalid electric dates and defaults scope', () => {
+  assert.deepEqual(
+    parseElectricDrillContext('?electricScope=unknown&electricDate=2026-02-31'),
+    { vehicleScope: 'lingniu' },
+  );
+});
+
+test('preserves the all-vehicle scope for overview drilldown', () => {
+  assert.deepEqual(
+    parseElectricDrillContext('?electricScope=all&electricDate=2026-07-28'),
+    { vehicleScope: 'all', selectedDate: '2026-07-28' },
+  );
+});
+
+test('builds namespaced electric drill URL and preserves unrelated filters', () => {
+  assert.equal(
+    buildElectricDrillUrl(
+      { pathname: '/energy', search: '?company=5&electricDate=2026-01-01', hash: '#electric' },
+      {
+        vehicleScope: 'lingniu',
+        startDate: '2026-07-24',
+        endDate: '2026-08-07',
+        selectedDate: '2026-07-24',
+      },
+    ),
+    '/energy?company=5&electricScope=lingniu&electricStart=2026-07-24&electricEnd=2026-08-07&electricDate=2026-07-24#electric',
+  );
+});

src/modules/energy/electric-drill-context.ts

@@ -0,0 +1,58 @@
+import type { ElectricVehicleScope } from './types';
+
+export interface ElectricDrillContext {
+  vehicleScope: ElectricVehicleScope;
+  startDate?: string;
+  endDate?: string;
+  selectedDate?: string;
+}
+
+interface LocationParts {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+function validDate(value: string | null): string | undefined {
+  if (!value || !DATE_PATTERN.test(value)) return undefined;
+  const [year, month, day] = value.split('-').map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day
+    ? value
+    : undefined;
+}
+
+export function parseElectricDrillContext(search: string): ElectricDrillContext {
+  const params = new URLSearchParams(search);
+  const scope = params.get('electricScope');
+  const context: ElectricDrillContext = {
+    vehicleScope: scope === 'external' || scope === 'all' ? scope : 'lingniu',
+  };
+  const startDate = validDate(params.get('electricStart'));
+  const endDate = validDate(params.get('electricEnd'));
+  const selectedDate = validDate(params.get('electricDate'));
+  if (startDate) context.startDate = startDate;
+  if (endDate) context.endDate = endDate;
+  if (selectedDate) context.selectedDate = selectedDate;
+  return context;
+}
+
+export function buildElectricDrillUrl(
+  location: LocationParts,
+  context: ElectricDrillContext,
+): string {
+  const params = new URLSearchParams(location.search);
+  for (const key of ['electricScope', 'electricStart', 'electricEnd', 'electricDate']) {
+    params.delete(key);
+  }
+  params.set('electricScope', context.vehicleScope);
+  if (context.startDate) params.set('electricStart', context.startDate);
+  if (context.endDate) params.set('electricEnd', context.endDate);
+  if (context.selectedDate) params.set('electricDate', context.selectedDate);
+  const query = params.toString();
+  return `${location.pathname}${query ? `?${query}` : ''}${location.hash}`;
+}

src/modules/energy/electric-reconciliation.test.ts

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { reconcileElectricDaily } from './electric-reconciliation.js';
+import type { ElectricChargeOrderResponse, ElectricDailyRow } from './types.js';
+
+const daily: ElectricDailyRow = {
+  date: '2026-07-01',
+  kwh: 2736.67,
+  fee: 552.92,
+  chainPct: 0,
+};
+
+const orders: ElectricChargeOrderResponse = {
+  date: '2026-07-01',
+  vehicleScope: 'all',
+  recordCount: 29,
+  totalKwh: 2736.67,
+  totalFee: 552.92,
+  truncated: false,
+  items: [],
+};
+
+test('matches a daily aggregate to the full order summary at hundredth precision', () => {
+  assert.deepEqual(reconcileElectricDaily(daily, orders, 'all'), {
+    matches: true,
+    dateMatches: true,
+    scopeMatches: true,
+    kwhDifference: 0,
+    feeDifference: 0,
+  });
+});
+
+test('reports amount, date, and scope differences without averaging detail rows', () => {
+  const result = reconcileElectricDaily(
+    daily,
+    { ...orders, date: '2026-07-02', vehicleScope: 'lingniu', totalKwh: 2736.68, totalFee: 550 },
+    'all',
+  );
+  assert.equal(result.matches, false);
+  assert.equal(result.dateMatches, false);
+  assert.equal(result.scopeMatches, false);
+  assert.equal(result.kwhDifference, 0.01);
+  assert.equal(result.feeDifference, -2.92);
+});

src/modules/energy/electric-reconciliation.ts

@@ -0,0 +1,35 @@
+import type { ElectricChargeOrderResponse, ElectricDailyRow, ElectricVehicleScope } from './types';
+
+export interface ElectricDailyReconciliation {
+  matches: boolean;
+  dateMatches: boolean;
+  scopeMatches: boolean;
+  kwhDifference: number;
+  feeDifference: number;
+}
+
+function hundredths(value: number): number {
+  return Math.round(value * 100);
+}
+
+export function reconcileElectricDaily(
+  daily: ElectricDailyRow,
+  orders: ElectricChargeOrderResponse,
+  expectedScope: ElectricVehicleScope,
+): ElectricDailyReconciliation {
+  const dateMatches = daily.date === orders.date;
+  const scopeMatches = expectedScope === orders.vehicleScope;
+  const kwhDifferenceInHundredths = hundredths(orders.totalKwh) - hundredths(daily.kwh);
+  const feeDifferenceInHundredths = hundredths(orders.totalFee) - hundredths(daily.fee);
+
+  return {
+    matches: dateMatches
+      && scopeMatches
+      && kwhDifferenceInHundredths === 0
+      && feeDifferenceInHundredths === 0,
+    dateMatches,
+    scopeMatches,
+    kwhDifference: kwhDifferenceInHundredths / 100,
+    feeDifference: feeDifferenceInHundredths / 100,
+  };
+}

src/modules/energy/etc-drill-context.test.ts

@@ -0,0 +1,40 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildEtcDrillUrl, parseEtcDrillContext } from './etc-drill-context.js';
+
+test('parses and normalizes the ETC analysis context', () => {
+  assert.deepEqual(
+    parseEtcDrillContext('?etcView=bills&etcStart=2026-08-07&etcEnd=2026-08-01&etcSearch=%20%E5%AE%A2%E6%88%B7A%20&etcPage=3'),
+    {
+      view: 'bills',
+      startDate: '2026-08-01',
+      endDate: '2026-08-07',
+      search: '客户A',
+      page: 3,
+    },
+  );
+});
+
+test('rejects invalid ETC URL state', () => {
+  assert.deepEqual(
+    parseEtcDrillContext(`?etcView=unknown&etcStart=2026-02-31&etcSearch=${'x'.repeat(129)}&etcPage=-2`),
+    { view: 'records', startDate: '', endDate: '', search: '', page: 1 },
+  );
+});
+
+test('builds ETC state without dropping unrelated URL context', () => {
+  assert.equal(
+    buildEtcDrillUrl({
+      pathname: '/energy',
+      search: '?electricScope=all&etcView=records',
+      hash: '#etc',
+    }, {
+      view: 'bills',
+      startDate: '2026-08-01',
+      endDate: '2026-08-07',
+      search: '客户A',
+      page: 2,
+    }),
+    '/energy?electricScope=all&etcView=bills&etcStart=2026-08-01&etcEnd=2026-08-07&etcSearch=%E5%AE%A2%E6%88%B7A&etcPage=2#etc',
+  );
+});

src/modules/energy/etc-drill-context.ts

@@ -0,0 +1,63 @@
+export type EtcDetailView = 'records' | 'bills';
+
+export interface EtcDrillContext {
+  view: EtcDetailView;
+  startDate: string;
+  endDate: string;
+  search: string;
+  page: number;
+}
+
+interface LocationParts {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+function validDate(value: string | null): string {
+  if (!value || !DATE_PATTERN.test(value)) return '';
+  const [year, month, day] = value.split('-').map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month - 1
+    && date.getUTCDate() === day
+    ? value
+    : '';
+}
+
+function validPage(value: string | null): number {
+  if (!value || !/^\d+$/.test(value)) return 1;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : 1;
+}
+
+export function parseEtcDrillContext(search: string): EtcDrillContext {
+  const params = new URLSearchParams(search);
+  const rawSearch = params.get('etcSearch')?.trim() ?? '';
+  const firstDate = validDate(params.get('etcStart'));
+  const secondDate = validDate(params.get('etcEnd'));
+  const startDate = firstDate && secondDate && firstDate > secondDate ? secondDate : firstDate;
+  const endDate = firstDate && secondDate && firstDate > secondDate ? firstDate : secondDate;
+  return {
+    view: params.get('etcView') === 'bills' ? 'bills' : 'records',
+    startDate,
+    endDate,
+    search: rawSearch.length <= 128 ? rawSearch : '',
+    page: validPage(params.get('etcPage')),
+  };
+}
+
+export function buildEtcDrillUrl(location: LocationParts, context: EtcDrillContext): string {
+  const params = new URLSearchParams(location.search);
+  for (const key of ['etcView', 'etcStart', 'etcEnd', 'etcSearch', 'etcPage']) params.delete(key);
+  params.set('etcView', context.view);
+  if (context.startDate) params.set('etcStart', context.startDate);
+  if (context.endDate) params.set('etcEnd', context.endDate);
+  const search = context.search.trim();
+  if (search && search.length <= 128) params.set('etcSearch', search);
+  if (context.page > 1) params.set('etcPage', String(context.page));
+  const query = params.toString();
+  return `${location.pathname}${query ? `?${query}` : ''}${location.hash}`;
+}

src/modules/energy/etc-reconciliation.test.ts

@@ -0,0 +1,69 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { reconcileEtcBills, reconcileEtcRecords } from './etc-reconciliation.js';
+import type { EtcBillResponse, EtcOverviewResponse, EtcTollRecordResponse } from './types.js';
+
+const kpi: EtcOverviewResponse['kpi'] = {
+  passageCount: 12,
+  vehicleCount: 4,
+  tollAmount: 100.01,
+  serviceFee: 5.02,
+  totalAmount: 105.03,
+  billCount: 2,
+  receivableAmount: 105.03,
+  paidAmount: 80,
+  latestTransactionTime: '2026-07-01 12:00:00',
+};
+
+const records: EtcTollRecordResponse = {
+  page: 1,
+  limit: 20,
+  total: 12,
+  totalPages: 1,
+  filters: { startDate: null, endDate: null, search: '' },
+  summary: { vehicleCount: 4, tollAmount: 100.01, serviceFee: 5.02, totalAmount: 105.03 },
+  items: [],
+};
+
+const bills: EtcBillResponse = {
+  page: 1,
+  limit: 20,
+  total: 2,
+  totalPages: 1,
+  filters: { startDate: null, endDate: null, search: '' },
+  summary: { receivableAmount: 105.03, paidAmount: 80 },
+  items: [],
+};
+
+test('matches ETC overview against full record and bill summaries', () => {
+  assert.equal(reconcileEtcRecords(kpi, records).matches, true);
+  assert.equal(reconcileEtcBills(kpi, bills).matches, true);
+});
+
+test('reports record count, vehicle, and fee differences at hundredth precision', () => {
+  assert.deepEqual(reconcileEtcRecords(kpi, {
+    ...records,
+    total: 13,
+    summary: { vehicleCount: 3, tollAmount: 100, serviceFee: 5.04, totalAmount: 105.04 },
+  }), {
+    matches: false,
+    passageCountDifference: 1,
+    vehicleCountDifference: -1,
+    tollAmountDifference: -0.01,
+    serviceFeeDifference: 0.02,
+    totalAmountDifference: 0.01,
+  });
+});
+
+test('reports bill count and settlement differences at hundredth precision', () => {
+  assert.deepEqual(reconcileEtcBills(kpi, {
+    ...bills,
+    total: 1,
+    summary: { receivableAmount: 100, paidAmount: 80.01 },
+  }), {
+    matches: false,
+    billCountDifference: -1,
+    receivableAmountDifference: -5.03,
+    paidAmountDifference: 0.01,
+  });
+});

src/modules/energy/etc-reconciliation.ts

@@ -0,0 +1,61 @@
+import type { EtcBillResponse, EtcOverviewResponse, EtcTollRecordResponse } from './types';
+
+export interface EtcRecordReconciliation {
+  matches: boolean;
+  passageCountDifference: number;
+  vehicleCountDifference: number;
+  tollAmountDifference: number;
+  serviceFeeDifference: number;
+  totalAmountDifference: number;
+}
+
+export interface EtcBillReconciliation {
+  matches: boolean;
+  billCountDifference: number;
+  receivableAmountDifference: number;
+  paidAmountDifference: number;
+}
+
+function hundredths(value: number): number {
+  return Math.round(value * 100);
+}
+
+export function reconcileEtcRecords(
+  kpi: EtcOverviewResponse['kpi'],
+  records: EtcTollRecordResponse,
+): EtcRecordReconciliation {
+  const tollDifference = hundredths(records.summary.tollAmount) - hundredths(kpi.tollAmount);
+  const serviceFeeDifference = hundredths(records.summary.serviceFee) - hundredths(kpi.serviceFee);
+  const totalDifference = hundredths(records.summary.totalAmount) - hundredths(kpi.totalAmount);
+  const passageCountDifference = records.total - kpi.passageCount;
+  const vehicleCountDifference = records.summary.vehicleCount - kpi.vehicleCount;
+
+  return {
+    matches: passageCountDifference === 0
+      && vehicleCountDifference === 0
+      && tollDifference === 0
+      && serviceFeeDifference === 0
+      && totalDifference === 0,
+    passageCountDifference,
+    vehicleCountDifference,
+    tollAmountDifference: tollDifference / 100,
+    serviceFeeDifference: serviceFeeDifference / 100,
+    totalAmountDifference: totalDifference / 100,
+  };
+}
+
+export function reconcileEtcBills(
+  kpi: EtcOverviewResponse['kpi'],
+  bills: EtcBillResponse,
+): EtcBillReconciliation {
+  const receivableDifference = hundredths(bills.summary.receivableAmount) - hundredths(kpi.receivableAmount);
+  const paidDifference = hundredths(bills.summary.paidAmount) - hundredths(kpi.paidAmount);
+  const billCountDifference = bills.total - kpi.billCount;
+
+  return {
+    matches: billCountDifference === 0 && receivableDifference === 0 && paidDifference === 0,
+    billCountDifference,
+    receivableAmountDifference: receivableDifference / 100,
+    paidAmountDifference: paidDifference / 100,
+  };
+}

src/modules/energy/hydrogen-drill-context.test.ts

@@ -0,0 +1,111 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildHydrogenDrillUrl,
+  parseHydrogenDrillContext,
+} from './hydrogen-drill-context.js';
+
+test('parses a station drill context including station zero', () => {
+  assert.deepEqual(
+    parseHydrogenDrillContext('?hydrogenLevel=station&hydrogenStation=0&hydrogenStationName=%E6%9C%AA%E5%85%B3%E8%81%94%E7%AB%99%E7%82%B9&hydrogenScope=lingniu&hydrogenStart=2026-08-01&hydrogenEnd=2026-08-07'),
+    {
+      level: 'station',
+      stationId: 0,
+      stationName: '未关联站点',
+      vehicleScope: 'lingniu',
+      startDate: '2026-08-01',
+      endDate: '2026-08-07',
+    },
+  );
+});
+
+test('requires a valid entity for station and customer levels', () => {
+  assert.equal(parseHydrogenDrillContext('?hydrogenLevel=station&hydrogenStation=-1').level, 'overview');
+  assert.equal(parseHydrogenDrillContext('?hydrogenLevel=customer').level, 'overview');
+  assert.equal(
+    parseHydrogenDrillContext(`?hydrogenLevel=customer&hydrogenCustomer=${'x'.repeat(129)}`).level,
+    'overview',
+  );
+});
+
+test('parses and builds a customer drill context', () => {
+  const context = parseHydrogenDrillContext(
+    '?hydrogenLevel=customer&hydrogenCustomer=%E6%AD%A6%E6%B1%89%E5%AE%A2%E6%88%B7&hydrogenScope=lingniu&hydrogenStart=2026-01-01&hydrogenEnd=2026-08-07',
+  );
+  assert.deepEqual(context, {
+    level: 'customer',
+    customerName: '武汉客户',
+    vehicleScope: 'lingniu',
+    startDate: '2026-01-01',
+    endDate: '2026-08-07',
+  });
+
+  assert.equal(
+    buildHydrogenDrillUrl(
+      { pathname: '/energy', search: '', hash: '#hydrogen' },
+      { ...context, year: 2026 },
+    ),
+    '/energy?hydrogenLevel=customer&hydrogenYear=2026&hydrogenCustomer=%E6%AD%A6%E6%B1%89%E5%AE%A2%E6%88%B7&hydrogenScope=lingniu&hydrogenStart=2026-01-01&hydrogenEnd=2026-08-07#hydrogen',
+  );
+});
+
+test('builds a namespaced station URL and preserves unrelated parameters', () => {
+  const url = buildHydrogenDrillUrl(
+    { pathname: '/energy', search: '?company=5', hash: '#hydrogen' },
+    {
+      level: 'station',
+      year: 2026,
+      stationId: 18,
+      stationName: '测试加氢站',
+      vehicleScope: 'lingniu',
+      startDate: '2026-08-01',
+      endDate: '2026-08-07',
+    },
+  );
+
+  assert.equal(
+    url,
+    '/energy?company=5&hydrogenLevel=station&hydrogenYear=2026&hydrogenStation=18&hydrogenStationName=%E6%B5%8B%E8%AF%95%E5%8A%A0%E6%B0%A2%E7%AB%99&hydrogenScope=lingniu&hydrogenStart=2026-08-01&hydrogenEnd=2026-08-07#hydrogen',
+  );
+});
+
+test('clears station parameters when returning to overview', () => {
+  const url = buildHydrogenDrillUrl(
+    {
+      pathname: '/energy',
+      search: '?hydrogenLevel=station&hydrogenStation=18&hydrogenStationName=test&company=5',
+      hash: '#hydrogen',
+    },
+    { level: 'overview', vehicleScope: 'lingniu' },
+  );
+
+  assert.equal(url, '/energy?company=5&hydrogenScope=lingniu#hydrogen');
+});
+
+test('preserves a selected order date and page in the hydrogen analysis URL', () => {
+  const context = parseHydrogenDrillContext(
+    '?hydrogenScope=lingniu&hydrogenStart=2026-08-01&hydrogenEnd=2026-08-07&hydrogenDate=2026-08-05&hydrogenPage=3',
+  );
+  assert.equal(context.selectedDate, '2026-08-05');
+  assert.equal(context.orderPage, 3);
+  assert.equal(
+    buildHydrogenDrillUrl(
+      { pathname: '/energy', search: '?company=5', hash: '#hydrogen' },
+      context,
+    ),
+    '/energy?company=5&hydrogenScope=lingniu&hydrogenStart=2026-08-01&hydrogenEnd=2026-08-07&hydrogenDate=2026-08-05&hydrogenPage=3#hydrogen',
+  );
+  assert.equal(
+    parseHydrogenDrillContext('?hydrogenStart=2026-08-01&hydrogenEnd=2026-08-07&hydrogenDate=2026-08-08').selectedDate,
+    undefined,
+  );
+  assert.equal(parseHydrogenDrillContext('?hydrogenPage=3').orderPage, undefined);
+  assert.equal(parseHydrogenDrillContext('?hydrogenDate=2026-08-05&hydrogenPage=0').orderPage, undefined);
+  assert.equal(
+    buildHydrogenDrillUrl(
+      { pathname: '/energy', search: '', hash: '#hydrogen' },
+      { level: 'overview', vehicleScope: 'lingniu', orderPage: 3 },
+    ),
+    '/energy?hydrogenScope=lingniu#hydrogen',
+  );
+});

src/modules/energy/hydrogen-drill-context.ts

@@ -0,0 +1,123 @@
+import type { CustomerType } from './types';
+
+export type HydrogenDrillLevel = 'overview' | 'station' | 'customer';
+
+export interface HydrogenDrillContext {
+  level: HydrogenDrillLevel;
+  year?: number;
+  stationId?: number;
+  stationName?: string;
+  customerName?: string;
+  vehicleScope: CustomerType;
+  startDate?: string;
+  endDate?: string;
+  selectedDate?: string;
+  orderPage?: number;
+}
+
+interface LocationParts {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+function validDate(value: string | null): string | undefined {
+  if (!value || !DATE_PATTERN.test(value)) return undefined;
+  const timestamp = Date.parse(`${value}T00:00:00+08:00`);
+  return Number.isFinite(timestamp) ? value : undefined;
+}
+
+function positiveInteger(value: string | null): number | undefined {
+  if (!value || !/^\d+$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+
+function stationId(value: string | null): number | undefined {
+  if (!value || !/^\d+$/.test(value)) return undefined;
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
+
+export function parseHydrogenDrillContext(search: string): HydrogenDrillContext {
+  const params = new URLSearchParams(search);
+  const requestedLevel = params.get('hydrogenLevel');
+  const parsedStationId = stationId(params.get('hydrogenStation'));
+  const parsedStationName = params.get('hydrogenStationName')?.trim() || undefined;
+  const rawCustomerName = params.get('hydrogenCustomer')?.trim();
+  const customerName = rawCustomerName && rawCustomerName.length <= 128
+    ? rawCustomerName
+    : undefined;
+  const context: HydrogenDrillContext = {
+    level: requestedLevel === 'station' && parsedStationId !== undefined
+      ? 'station'
+      : requestedLevel === 'customer' && customerName
+        ? 'customer'
+        : 'overview',
+    vehicleScope: params.get('hydrogenScope') === 'external' ? 'external' : 'lingniu',
+  };
+
+  const year = positiveInteger(params.get('hydrogenYear'));
+  if (year && year >= 2000 && year <= 2100) context.year = year;
+  if (context.level === 'station') {
+    context.stationId = parsedStationId;
+    if (parsedStationName) context.stationName = parsedStationName;
+  }
+  if (context.level === 'customer') context.customerName = customerName;
+  const startDate = validDate(params.get('hydrogenStart'));
+  const endDate = validDate(params.get('hydrogenEnd'));
+  const selectedDate = validDate(params.get('hydrogenDate'));
+  if (startDate) context.startDate = startDate;
+  if (endDate) context.endDate = endDate;
+  const rangeStart = startDate && endDate ? (startDate <= endDate ? startDate : endDate) : undefined;
+  const rangeEnd = startDate && endDate ? (startDate <= endDate ? endDate : startDate) : undefined;
+  if (selectedDate && (!rangeStart || !rangeEnd || (selectedDate >= rangeStart && selectedDate <= rangeEnd))) {
+    context.selectedDate = selectedDate;
+    const orderPage = positiveInteger(params.get('hydrogenPage'));
+    if (orderPage && orderPage > 1) context.orderPage = orderPage;
+  }
+  return context;
+}
+
+export function buildHydrogenDrillUrl(
+  location: LocationParts,
+  context: HydrogenDrillContext,
+): string {
+  const params = new URLSearchParams(location.search);
+  for (const key of [
+    'hydrogenLevel',
+    'hydrogenYear',
+    'hydrogenStation',
+    'hydrogenStationName',
+    'hydrogenCustomer',
+    'hydrogenScope',
+    'hydrogenStart',
+    'hydrogenEnd',
+    'hydrogenDate',
+    'hydrogenPage',
+  ]) {
+    params.delete(key);
+  }
+
+  if (context.level !== 'overview') params.set('hydrogenLevel', context.level);
+  if (context.year) params.set('hydrogenYear', String(context.year));
+  if (context.level === 'station' && context.stationId !== undefined) {
+    params.set('hydrogenStation', String(context.stationId));
+    if (context.stationName) params.set('hydrogenStationName', context.stationName);
+  }
+  if (context.level === 'customer' && context.customerName) {
+    params.set('hydrogenCustomer', context.customerName);
+  }
+  params.set('hydrogenScope', context.vehicleScope);
+  if (context.startDate) params.set('hydrogenStart', context.startDate);
+  if (context.endDate) params.set('hydrogenEnd', context.endDate);
+  if (context.selectedDate) params.set('hydrogenDate', context.selectedDate);
+  if (context.selectedDate && context.orderPage && context.orderPage > 1) {
+    params.set('hydrogenPage', String(context.orderPage));
+  }
+
+  const query = params.toString();
+  return `${location.pathname}${query ? `?${query}` : ''}${location.hash}`;
+}

src/modules/energy/hydrogen-reconciliation.test.ts

@@ -0,0 +1,67 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { reconcileHydrogenDaily } from './hydrogen-reconciliation.js';
+import type { HydrogenDailyRow, HydrogenOrderResponse } from './types.js';
+
+const daily: HydrogenDailyRow = {
+  date: '2026-07-01',
+  totalKg: 123.45,
+  chainPct: 0,
+  customerType: 'lingniu',
+  stations: [],
+};
+
+const orders: HydrogenOrderResponse = {
+  date: '2026-07-01',
+  vehicleScope: 'lingniu',
+  stationId: 18,
+  customerName: null,
+  page: 1,
+  limit: 20,
+  recordCount: 3,
+  totalPages: 1,
+  totalKg: 123.45,
+  totalCost: 1000,
+  totalRevenue: 1200,
+  items: [],
+};
+
+test('matches daily hydrogen totals at the same date, scope, and entity grain', () => {
+  assert.deepEqual(reconcileHydrogenDaily(daily, orders, 'lingniu', 18), {
+    matches: true,
+    dateMatches: true,
+    scopeMatches: true,
+    entityMatches: true,
+    kgDifference: 0,
+  });
+});
+
+test('reports amount and filter-grain differences independently', () => {
+  const result = reconcileHydrogenDaily(
+    daily,
+    {
+      ...orders,
+      date: '2026-07-02',
+      vehicleScope: 'external',
+      stationId: null,
+      customerName: '武汉客户',
+      totalKg: 123.44,
+    },
+    'lingniu',
+    18,
+  );
+
+  assert.equal(result.matches, false);
+  assert.equal(result.dateMatches, false);
+  assert.equal(result.scopeMatches, false);
+  assert.equal(result.entityMatches, false);
+  assert.equal(result.kgDifference, -0.01);
+});
+
+test('matches an exact customer drill without requiring a station', () => {
+  const customerOrders = { ...orders, stationId: null, customerName: '武汉客户' };
+  assert.equal(
+    reconcileHydrogenDaily(daily, customerOrders, 'lingniu', undefined, '武汉客户').matches,
+    true,
+  );
+});

src/modules/energy/hydrogen-reconciliation.ts

@@ -0,0 +1,35 @@
+import type { CustomerType, HydrogenDailyRow, HydrogenOrderResponse } from './types';
+
+export interface HydrogenDailyReconciliation {
+  matches: boolean;
+  dateMatches: boolean;
+  scopeMatches: boolean;
+  entityMatches: boolean;
+  kgDifference: number;
+}
+
+function hundredths(value: number): number {
+  return Math.round(value * 100);
+}
+
+export function reconcileHydrogenDaily(
+  daily: HydrogenDailyRow,
+  orders: HydrogenOrderResponse,
+  expectedScope: CustomerType,
+  expectedStationId?: number,
+  expectedCustomerName?: string,
+): HydrogenDailyReconciliation {
+  const dateMatches = daily.date === orders.date;
+  const scopeMatches = expectedScope === orders.vehicleScope;
+  const entityMatches = (expectedStationId ?? null) === orders.stationId
+    && (expectedCustomerName ?? null) === orders.customerName;
+  const kgDifferenceInHundredths = hundredths(orders.totalKg) - hundredths(daily.totalKg);
+
+  return {
+    matches: dateMatches && scopeMatches && entityMatches && kgDifferenceInHundredths === 0,
+    dateMatches,
+    scopeMatches,
+    entityMatches,
+    kgDifference: kgDifferenceInHundredths / 100,
+  };
+}

src/modules/energy/types.ts

@@ -1,4 +1,5 @@
 export type CustomerType = 'external' | 'lingniu';
+export type ElectricVehicleScope = CustomerType | 'all';
 export type DateQuickPick = 'thisWeek' | 'thisMonth' | 'last15';
 
 export interface HydrogenKpi {
@@ -22,6 +23,7 @@ export interface HydrogenKpi {
 }
 
 export interface HydrogenStationTop {
+  id: number;
   rank: number;
   name: string;
   kg: number;
@@ -52,6 +54,7 @@ export interface HydrogenCustomerRow {
 }
 
 export interface HydrogenStationFull {
+  id: number;
   name: string;
   kg: number;
   revenue: number;
@@ -60,6 +63,7 @@ export interface HydrogenStationFull {
 }
 
 export interface HydrogenStationRow {
+  stationId: number;
   name: string;
   pricePerKg: number;
   kg: number;
@@ -74,6 +78,34 @@ export interface HydrogenDailyRow {
   stations: HydrogenStationRow[];
 }
 
+export interface HydrogenOrder {
+  rowNumber: number;
+  refuelTime: string;
+  plate: string;
+  customerName: string;
+  stationName: string;
+  amountKg: number;
+  costPrice: number;
+  costTotal: number;
+  customerPrice: number;
+  revenue: number;
+}
+
+export interface HydrogenOrderResponse {
+  date: string;
+  vehicleScope: CustomerType;
+  stationId: number | null;
+  customerName: string | null;
+  page: number;
+  limit: number;
+  recordCount: number;
+  totalPages: number;
+  totalKg: number;
+  totalCost: number;
+  totalRevenue: number;
+  items: HydrogenOrder[];
+}
+
 export interface ElectricKpi {
   totalKwh: number;
   totalFee: number;
@@ -97,3 +129,105 @@ export interface ElectricMonthGroup {
   fee: number;
   rows: ElectricDailyRow[];
 }
+
+export interface ElectricChargeOrder {
+  id: number;
+  orderNo: string;
+  startTime: string;
+  stationName: string;
+  plate: string;
+  vehicleKind: 'internal' | 'external' | 'unknown';
+  orderStatus: string;
+  kwh: number;
+  electricityFee: number;
+  serviceFee: number;
+  totalFee: number;
+}
+
+export interface ElectricChargeOrderResponse {
+  date: string;
+  vehicleScope: ElectricVehicleScope;
+  recordCount: number;
+  totalKwh: number;
+  totalFee: number;
+  truncated: boolean;
+  items: ElectricChargeOrder[];
+}
+
+export interface EtcOverviewResponse {
+  integration: {
+    providerConfigured: boolean;
+    syncEnabled: boolean;
+    providerType: string | null;
+    lastSyncAt: string | null;
+    lastSyncStatus: 'never' | 'success' | 'failed' | 'partial' | 'unknown';
+  };
+  kpi: {
+    passageCount: number;
+    vehicleCount: number;
+    tollAmount: number;
+    serviceFee: number;
+    totalAmount: number;
+    billCount: number;
+    receivableAmount: number;
+    paidAmount: number;
+    latestTransactionTime: string | null;
+  };
+}
+
+export interface EtcListFilters {
+  startDate: string | null;
+  endDate: string | null;
+  search: string;
+}
+
+export interface EtcTollRecord {
+  id: number;
+  recordCode: string;
+  plate: string;
+  customerName: string | null;
+  entryStation: string | null;
+  exitStation: string | null;
+  transTime: string;
+  tollAmount: number;
+  serviceFee: number;
+  totalAmount: number;
+  costType: number;
+  contractMatched: boolean;
+  reviewStatus: number;
+}
+
+export interface EtcTollRecordResponse {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  filters: EtcListFilters;
+  summary: { vehicleCount: number; tollAmount: number; serviceFee: number; totalAmount: number };
+  items: EtcTollRecord[];
+}
+
+export interface EtcBill {
+  id: number;
+  billCode: string;
+  customerName: string | null;
+  periodStart: string;
+  periodEnd: string;
+  tollCount: number;
+  tollAmount: number;
+  serviceFee: number;
+  receivableAmount: number;
+  paidAmount: number;
+  paymentStatus: number;
+  reviewStatus: number;
+}
+
+export interface EtcBillResponse {
+  page: number;
+  limit: number;
+  total: number;
+  totalPages: number;
+  filters: EtcListFilters;
+  summary: { receivableAmount: number; paidAmount: number };
+  items: EtcBill[];
+}

src/modules/energy/useHashSubTab.test.ts

@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildHashSubTab, parseHashSubTab } from './useHashSubTab.js';
+
+const tabs = ['daily', 'overview'] as const;
+
+test('parses valid sub tabs and falls back to the module default', () => {
+  assert.equal(parseHashSubTab('#electric/overview', 'electric', tabs), 'overview');
+  assert.equal(parseHashSubTab('#electric/unknown', 'electric', tabs), 'daily');
+  assert.equal(parseHashSubTab('#hydrogen/overview', 'electric', tabs), 'daily');
+});
+
+test('builds a compact default hash and an explicit secondary hash', () => {
+  assert.equal(buildHashSubTab('electric', 'daily', 'daily'), '#electric');
+  assert.equal(buildHashSubTab('electric', 'overview', 'daily'), '#electric/overview');
+});

src/modules/energy/useHashSubTab.ts

@@ -1,5 +1,19 @@
 import { useEffect, useState } from 'react';
 
+export function parseHashSubTab<T extends string>(
+  hash: string,
+  moduleId: string,
+  subs: readonly T[],
+): T {
+  const [first, second] = hash.replace(/^#/, '').split('/');
+  if (first !== moduleId) return subs[0];
+  return second && (subs as readonly string[]).includes(second) ? second as T : subs[0];
+}
+
+export function buildHashSubTab<T extends string>(moduleId: string, sub: T, defaultSub: T): string {
+  return sub === defaultSub ? `#${moduleId}` : `#${moduleId}/${sub}`;
+}
+
 /**
  * 把模块内子 tab 状态同步到 URL hash 二级段。
  * hash 形如 `#<moduleId>`（= 默认 sub）或 `#<moduleId>/<sub>`。
@@ -11,26 +25,25 @@ export function useHashSubTab<T extends string>(
 ): [T, (sub: T) => void] {
   const defaultSub = subs[0];
 
-  const parse = (): T => {
-    const hash = window.location.hash.slice(1);
-    const [first, second] = hash.split('/');
-    if (first !== moduleId) return defaultSub;
-    if (second && (subs as readonly string[]).includes(second)) return second as T;
-    return defaultSub;
-  };
+  const parse = (): T => parseHashSubTab(window.location.hash, moduleId, subs);
 
   const [sub, setSubState] = useState<T>(parse);
 
   useEffect(() => {
     const onChange = () => setSubState(parse());
     window.addEventListener('hashchange', onChange);
-    return () => window.removeEventListener('hashchange', onChange);
+    window.addEventListener('popstate', onChange);
+    return () => {
+      window.removeEventListener('hashchange', onChange);
+      window.removeEventListener('popstate', onChange);
+    };
   }, [moduleId]);
 
   const setSub = (next: T) => {
+    if (next === sub) return;
     const { pathname, search } = window.location;
-    const newHash = next === defaultSub ? `#${moduleId}` : `#${moduleId}/${next}`;
-    window.history.replaceState(null, '', `${pathname}${search}${newHash}`);
+    const newHash = buildHashSubTab(moduleId, next, defaultSub);
+    window.history.pushState(null, '', `${pathname}${search}${newHash}`);
     setSubState(next);
   };
 

src/modules/hydrogen-heatmap/HydrogenAmapCanvas.tsx

@@ -0,0 +1,148 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { AmapConfig, HydrogenHeatmapMetric, HydrogenHeatmapPoint } from './types';
+
+type Props = {
+  config: AmapConfig;
+  points: HydrogenHeatmapPoint[];
+  max: number;
+  metric: HydrogenHeatmapMetric;
+  focusQuery: string;
+  onMapClick: (longitude: number, latitude: number) => void;
+};
+
+type AmapInstance = {
+  Map: new (container: HTMLElement, options: Record<string, unknown>) => any;
+  HeatMap: new (map: any, options: Record<string, unknown>) => any;
+  ToolBar: new (options?: Record<string, unknown>) => any;
+  Scale: new (options?: Record<string, unknown>) => any;
+  Bounds: new (southWest: [number, number], northEast: [number, number]) => any;
+};
+
+declare global {
+  interface Window {
+    _AMapSecurityConfig?: { securityJsCode: string };
+  }
+}
+
+function getBounds(points: HydrogenHeatmapPoint[]) {
+  if (!points.length) return null;
+  return points.reduce((bounds, point) => ({
+    minLng: Math.min(bounds.minLng, point.lng),
+    maxLng: Math.max(bounds.maxLng, point.lng),
+    minLat: Math.min(bounds.minLat, point.lat),
+    maxLat: Math.max(bounds.maxLat, point.lat),
+  }), { minLng: points[0].lng, maxLng: points[0].lng, minLat: points[0].lat, maxLat: points[0].lat });
+}
+
+export default function HydrogenAmapCanvas({ config, points, max, metric, focusQuery, onMapClick }: Props) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const mapRef = useRef<any>(null);
+  const heatmapRef = useRef<any>(null);
+  const amapRef = useRef<AmapInstance | null>(null);
+  const clickHandlerRef = useRef(onMapClick);
+  const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
+  const intensity = useMemo(() => {
+    const transform = metric === 'kg'
+      ? (value: number) => Math.log1p(value)
+      : (value: number) => Math.sqrt(value);
+    return {
+      points: points.map((point) => ({ ...point, count: transform(point.count) })),
+      max: transform(Math.max(1, max)),
+    };
+  }, [max, metric, points]);
+
+  useEffect(() => {
+    clickHandlerRef.current = onMapClick;
+  }, [onMapClick]);
+
+  useEffect(() => {
+    let cancelled = false;
+    const container = containerRef.current;
+    if (!container) return undefined;
+
+    async function initialize() {
+      try {
+        window._AMapSecurityConfig = { securityJsCode: config.securityCode };
+        const loaderModule = await import('@amap/amap-jsapi-loader');
+        const AMap = await loaderModule.default.load({
+          key: config.key,
+          version: '2.0',
+          plugins: ['AMap.HeatMap', 'AMap.ToolBar', 'AMap.Scale'],
+        }) as unknown as AmapInstance;
+        if (cancelled || !container) return;
+        const map = new AMap.Map(container, {
+          viewMode: '2D',
+          zoom: 5,
+          center: [105.4, 34.4],
+          mapStyle: 'amap://styles/whitesmoke',
+          resizeEnable: true,
+          showLabel: true,
+        });
+        map.addControl(new AMap.ToolBar({ position: { right: '20px', bottom: '76px' } }));
+        map.addControl(new AMap.Scale({ position: { right: '18px', bottom: '24px' } }));
+        const heatmap = new AMap.HeatMap(map, {
+          radius: 34,
+          opacity: [0.14, 0.84],
+          gradient: {
+            0.1: '#2563eb',
+            0.3: '#0891b2',
+            0.5: '#16a34a',
+            0.68: '#eab308',
+            0.84: '#f97316',
+            1: '#dc2626',
+          },
+        });
+        map.on('click', (event: any) => clickHandlerRef.current(event.lnglat.getLng(), event.lnglat.getLat()));
+        mapRef.current = map;
+        heatmapRef.current = heatmap;
+        amapRef.current = AMap;
+        setStatus('ready');
+      } catch (error) {
+        console.error('Hydrogen heatmap AMap initialization failed', error);
+        if (!cancelled) setStatus('error');
+      }
+    }
+
+    initialize();
+    return () => {
+      cancelled = true;
+      heatmapRef.current?.setMap?.(null);
+      mapRef.current?.destroy?.();
+      heatmapRef.current = null;
+      mapRef.current = null;
+      amapRef.current = null;
+    };
+  }, [config.key, config.securityCode]);
+
+  useEffect(() => {
+    if (status !== 'ready' || !heatmapRef.current) return;
+    heatmapRef.current.setDataSet({ data: intensity.points, max: intensity.max });
+    if (!focusQuery || !points.length || !mapRef.current || !amapRef.current) return;
+    const bounds = getBounds(points);
+    if (!bounds) return;
+    if (points.length === 1) {
+      mapRef.current.setZoomAndCenter(12, [points[0].lng, points[0].lat]);
+      return;
+    }
+    mapRef.current.setBounds(new amapRef.current.Bounds(
+      [bounds.minLng, bounds.minLat],
+      [bounds.maxLng, bounds.maxLat],
+    ), false, [80, 80, 80, 80]);
+  }, [focusQuery, intensity, points, status]);
+
+  return (
+    <div className="absolute inset-0 bg-[#eef3f7]">
+      <div ref={containerRef} className="h-full w-full" aria-label="加氢站加氢热力图地图" />
+      {status === 'loading' ? (
+        <div className="absolute inset-0 grid place-items-center bg-white/76 text-sm font-medium text-slate-500 backdrop-blur-[2px]">
+          <span className="flex items-center gap-2.5"><i className="h-4 w-4 animate-spin rounded-full border-2 border-cyan-600 border-t-transparent" />正在加载高德地图</span>
+        </div>
+      ) : null}
+      {status === 'error' ? (
+        <div className="absolute inset-0 grid place-items-center bg-slate-50 text-center">
+          <div><p className="text-sm font-semibold text-slate-700">地图加载失败</p><p className="mt-1 text-xs text-slate-400">请检查高德 Key、域名白名单与网络连接</p></div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

src/modules/hydrogen-heatmap/HydrogenHeatmapDetailPanel.tsx

@@ -0,0 +1,85 @@
+import { ChevronRight, Fuel, X } from 'lucide-react';
+import type { HydrogenHeatmapMetric, HydrogenStationRank } from './types';
+
+type Props = {
+  title: string;
+  subtitle: string;
+  kg: number;
+  refuelCount: number;
+  vehicleCount: number;
+  stationCount: number;
+  stations: HydrogenStationRank[];
+  metric: HydrogenHeatmapMetric;
+  selected: boolean;
+  loading: boolean;
+  coverageText: string;
+  onClose: () => void;
+  onHide: () => void;
+};
+
+const integerFormat = new Intl.NumberFormat('zh-CN');
+const kgFormat = new Intl.NumberFormat('zh-CN', { maximumFractionDigits: 1 });
+
+function metricLabel(metric: HydrogenHeatmapMetric) {
+  if (metric === 'refuels') return '按加氢次数排序';
+  if (metric === 'vehicles') return '按车辆数排序';
+  return '按加氢量排序';
+}
+
+function metricValue(station: HydrogenStationRank, metric: HydrogenHeatmapMetric) {
+  if (metric === 'kg') return `${kgFormat.format(station.kg)} kg`;
+  if (metric === 'refuels') return `${integerFormat.format(station.refuelCount)} 次`;
+  return `${integerFormat.format(station.vehicleCount)} 辆`;
+}
+
+export default function HydrogenHeatmapDetailPanel(props: Props) {
+  return (
+    <aside className="relative z-20 flex h-full w-[310px] shrink-0 flex-col border-l border-slate-200 bg-white max-lg:absolute max-lg:bottom-0 max-lg:left-0 max-lg:right-0 max-lg:h-[43vh] max-lg:w-full max-lg:rounded-t-2xl max-lg:border-l-0 max-lg:border-t max-lg:shadow-[0_-10px_30px_rgba(15,23,42,0.14)] max-md:h-[50dvh]">
+      <div className="border-b border-slate-100 px-5 pb-4 pt-5 max-md:px-4 max-md:pb-3 max-md:pt-3">
+        <div className="flex items-start justify-between gap-3">
+          <div className="min-w-0">
+            <div className="flex items-center gap-2">
+              <h2 className="truncate text-[17px] font-semibold tracking-tight text-slate-900">{props.title}</h2>
+              {props.loading ? <i className="h-3.5 w-3.5 animate-spin rounded-full border-2 border-cyan-600 border-t-transparent" /> : null}
+            </div>
+            <p className="mt-1 text-[11px] text-slate-400">{props.subtitle}</p>
+            <p className="mt-1 text-[10px] font-medium text-emerald-600">{props.coverageText}</p>
+          </div>
+          <div className="flex shrink-0 items-center gap-1">
+            {props.selected ? (
+              <button type="button" onClick={props.onClose} aria-label="关闭加氢区域详情" className="grid h-8 w-8 place-items-center rounded-lg text-slate-400 hover:bg-slate-50 hover:text-slate-700"><X size={18} strokeWidth={1.8} /></button>
+            ) : null}
+            <button type="button" onClick={props.onHide} aria-label="隐藏加氢详情" title="隐藏详情" className="grid h-8 w-8 place-items-center rounded-lg text-slate-400 transition hover:bg-cyan-50 hover:text-cyan-700 max-md:h-10 max-md:w-10"><ChevronRight size={18} strokeWidth={1.8} /></button>
+          </div>
+        </div>
+
+        <div className="mt-4 grid grid-cols-2 gap-x-4 gap-y-3 border-t border-slate-100 pt-4 max-md:mt-3 max-md:gap-y-2 max-md:pt-3">
+          <div><p className="text-[10px] text-slate-400">加氢量</p><p className="mt-0.5 text-[19px] font-semibold tracking-tight text-cyan-700">{kgFormat.format(props.kg)} <small className="text-[10px] font-medium">kg</small></p></div>
+          <div><p className="text-[10px] text-slate-400">加氢次数</p><p className="mt-0.5 text-[19px] font-semibold tracking-tight text-cyan-700">{integerFormat.format(props.refuelCount)}</p></div>
+          <div><p className="text-[10px] text-slate-400">车辆数</p><p className="mt-0.5 text-[16px] font-semibold text-slate-700">{integerFormat.format(props.vehicleCount)}</p></div>
+          <div><p className="text-[10px] text-slate-400">站点数</p><p className="mt-0.5 text-[16px] font-semibold text-slate-700">{integerFormat.format(props.stationCount)}</p></div>
+        </div>
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-auto px-5 py-4 max-md:px-4 max-md:py-3">
+        <div className="mb-3 flex items-center justify-between">
+          <h3 className="text-[13px] font-semibold text-slate-800">加氢站 TOP10</h3>
+          <span className="text-[10px] text-slate-400">{metricLabel(props.metric)}</span>
+        </div>
+        {props.stations.length ? (
+          <ol className="divide-y divide-slate-100">
+            {props.stations.map((station, index) => (
+              <li key={station.stationId} className="grid grid-cols-[24px_minmax(0,1fr)_68px] items-center gap-2 py-2.5">
+                <span className={`text-[11px] font-medium ${index < 3 ? 'text-cyan-700' : 'text-slate-400'}`}>{index + 1}</span>
+                <span className="min-w-0"><span className="block truncate text-[12px] font-medium text-slate-700" title={station.stationName}>{station.stationName}</span><span className="mt-0.5 block truncate text-[9px] text-slate-400" title={station.address}>{station.address || '地址未维护'}</span></span>
+                <span className="text-right text-[10px] tabular-nums text-slate-600">{metricValue(station, props.metric)}</span>
+              </li>
+            ))}
+          </ol>
+        ) : (
+          <div className="grid h-44 place-items-center text-center text-xs text-slate-400"><span><Fuel className="mx-auto mb-2 text-slate-300" size={22} />该范围暂无加氢记录</span></div>
+        )}
+      </div>
+    </aside>
+  );
+}

src/modules/hydrogen-heatmap/HydrogenHeatmapFilters.tsx

@@ -0,0 +1,85 @@
+import { CalendarDays, ChevronUp, RotateCcw, Search } from 'lucide-react';
+import type { HydrogenHeatmapMetric, HydrogenPayer, HydrogenStationOption } from './types';
+
+type Props = {
+  startDate: string;
+  endDate: string;
+  minDate: string;
+  maxDate: string;
+  query: string;
+  payer: HydrogenPayer;
+  metric: HydrogenHeatmapMetric;
+  stations: HydrogenStationOption[];
+  onStartDateChange: (value: string) => void;
+  onEndDateChange: (value: string) => void;
+  onQueryChange: (value: string) => void;
+  onPayerChange: (value: HydrogenPayer) => void;
+  onMetricChange: (value: HydrogenHeatmapMetric) => void;
+  onReset: () => void;
+  onHide: () => void;
+};
+
+const FIELD = 'relative h-11 min-w-0 rounded-lg border border-slate-200 bg-white transition focus-within:border-cyan-400 focus-within:ring-2 focus-within:ring-cyan-100';
+const LABEL = 'pointer-events-none absolute left-3 top-1 z-10 text-[9px] font-medium leading-none text-slate-400';
+const CONTROL = 'h-full w-full min-w-0 rounded-lg border-0 bg-transparent px-3 pt-3 text-[12px] text-slate-700 outline-none';
+
+export default function HydrogenHeatmapFilters(props: Props) {
+  return (
+    <div className="pointer-events-auto grid max-h-[calc(100dvh-180px)] w-full grid-cols-2 gap-2 overflow-y-auto rounded-xl border border-slate-200/80 bg-white/96 p-2 shadow-[0_8px_28px_rgba(15,23,42,0.12)] backdrop-blur-md md:flex md:w-auto md:min-w-max md:items-center md:overflow-visible">
+      <label className={`${FIELD} col-span-2 md:w-[320px]`}>
+        <span className={`${LABEL} left-9`}>日期范围</span>
+        <span className="flex h-full min-w-0 items-center pl-8 pt-2">
+          <CalendarDays className="absolute left-3 top-1/2 -translate-y-1/2 text-slate-400" size={15} strokeWidth={1.8} />
+          <input aria-label="加氢开始日期" type="date" min={props.minDate} max={props.endDate} value={props.startDate} onChange={(event) => props.onStartDateChange(event.target.value)} className="h-full w-[124px] min-w-0 flex-1 border-0 bg-transparent px-1 text-[12px] text-slate-700 outline-none" />
+          <span className="shrink-0 px-0.5 text-slate-300">—</span>
+          <input aria-label="加氢结束日期" type="date" min={props.startDate} max={props.maxDate} value={props.endDate} onChange={(event) => props.onEndDateChange(event.target.value)} className="h-full w-[124px] min-w-0 flex-1 border-0 bg-transparent px-1 text-[12px] text-slate-700 outline-none" />
+        </span>
+      </label>
+
+      <label className={`${FIELD} col-span-2 md:w-[145px]`}>
+        <span className={LABEL}>加氢站</span>
+        <span className="relative block h-full">
+          <input
+            aria-label="搜索加氢站"
+            value={props.query}
+            list="hydrogen-heatmap-stations"
+            onChange={(event) => props.onQueryChange(event.target.value)}
+            placeholder="输入站点名称"
+            className={`${CONTROL} pr-9`}
+          />
+          <Search className="pointer-events-none absolute right-3 top-1/2 -translate-y-1/2 text-slate-400" size={16} strokeWidth={1.8} />
+          <datalist id="hydrogen-heatmap-stations">
+            {props.stations.map((station) => <option key={station.stationId} value={station.stationName} />)}
+          </datalist>
+        </span>
+      </label>
+
+      <label className={`${FIELD} md:w-[100px]`}>
+        <span className={LABEL}>费用承担</span>
+        <select aria-label="费用承担" value={props.payer} onChange={(event) => props.onPayerChange(event.target.value as HydrogenPayer)} className={CONTROL}>
+          <option value="all">全部</option>
+          <option value="lingniu">羚牛承担</option>
+          <option value="customer">客户承担</option>
+        </select>
+      </label>
+
+      <label className={`${FIELD} md:w-[100px]`}>
+        <span className={LABEL}>统计维度</span>
+        <select aria-label="加氢统计维度" value={props.metric} onChange={(event) => props.onMetricChange(event.target.value as HydrogenHeatmapMetric)} className={CONTROL}>
+          <option value="kg">加氢量</option>
+          <option value="refuels">加氢次数</option>
+          <option value="vehicles">车辆覆盖</option>
+        </select>
+      </label>
+
+      <div className="col-span-2 flex min-w-0 justify-end gap-2 md:w-auto">
+        <button type="button" onClick={props.onReset} className="flex h-11 min-w-[72px] items-center justify-center gap-1.5 rounded-lg border border-slate-200 bg-white px-2.5 text-[12px] font-medium text-slate-600 transition hover:border-cyan-300 hover:bg-cyan-50 hover:text-cyan-700">
+          <RotateCcw size={14} strokeWidth={1.8} />重置
+        </button>
+        <button type="button" onClick={props.onHide} aria-label="隐藏加氢筛选" title="隐藏筛选" className="grid h-11 w-11 shrink-0 place-items-center rounded-lg border border-slate-200 bg-white text-slate-400 transition hover:border-cyan-300 hover:bg-cyan-50 hover:text-cyan-700 md:w-10">
+          <ChevronUp size={16} strokeWidth={1.8} />
+        </button>
+      </div>
+    </div>
+  );
+}

src/modules/hydrogen-heatmap/HydrogenHeatmapModule.tsx

@@ -0,0 +1,222 @@
+import { useCallback, useDeferredValue, useEffect, useMemo, useState } from 'react';
+import { AlertTriangle, ChevronLeft, Clock3, Fuel, Maximize2, Minimize2, SlidersHorizontal } from 'lucide-react';
+import HydrogenAmapCanvas from './HydrogenAmapCanvas';
+import HydrogenHeatmapDetailPanel from './HydrogenHeatmapDetailPanel';
+import HydrogenHeatmapFilters from './HydrogenHeatmapFilters';
+import { fetchAmapConfig, fetchHydrogenHeatmapMeta, fetchHydrogenHeatmapPoints, fetchNearbyHydrogenStations } from './api';
+import type { AmapConfig, HydrogenHeatmapMeta, HydrogenHeatmapMetric, HydrogenHeatmapResponse, HydrogenNearbyResponse, HydrogenPayer } from './types';
+
+const DEFAULT_START = '2026-01-01';
+const DEFAULT_END = '2026-07-13';
+const integerFormat = new Intl.NumberFormat('zh-CN');
+const kgFormat = new Intl.NumberFormat('zh-CN', { maximumFractionDigits: 1 });
+
+function Metric({ value, label }: { value: string; label: string }) {
+  return (
+    <div className="min-w-[88px] text-center max-md:min-w-[68px]">
+      <p className="text-[21px] font-semibold leading-none tracking-tight text-cyan-700 tabular-nums max-md:text-[16px]">{value}</p>
+      <p className="mt-1.5 text-[11px] text-slate-500 max-md:mt-1 max-md:text-[9px]">{label}</p>
+    </div>
+  );
+}
+
+function metricName(metric: HydrogenHeatmapMetric) {
+  if (metric === 'refuels') return '加氢频次';
+  if (metric === 'vehicles') return '车辆覆盖';
+  return '加氢量强度';
+}
+
+function metricDescription(metric: HydrogenHeatmapMetric) {
+  if (metric === 'refuels') return '每个站点累计有效加氢订单数；平方根平滑强度。';
+  if (metric === 'vehicles') return '每个站点按车牌去重统计车辆数；平方根平滑强度。';
+  return '每个站点累计有效加氢量（kg）；对数平滑强度。';
+}
+
+export default function HydrogenHeatmapModule() {
+  const [meta, setMeta] = useState<HydrogenHeatmapMeta | null>(null);
+  const [config, setConfig] = useState<AmapConfig | null>(null);
+  const [data, setData] = useState<HydrogenHeatmapResponse | null>(null);
+  const [nearby, setNearby] = useState<HydrogenNearbyResponse | null>(null);
+  const [startDate, setStartDate] = useState(DEFAULT_START);
+  const [endDate, setEndDate] = useState(DEFAULT_END);
+  const [query, setQuery] = useState('');
+  const [payer, setPayer] = useState<HydrogenPayer>('all');
+  const [metric, setMetric] = useState<HydrogenHeatmapMetric>('kg');
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  const [showFilters, setShowFilters] = useState(() => typeof window === 'undefined' || !window.matchMedia('(max-width: 767px)').matches);
+  const [showDetails, setShowDetails] = useState(() => typeof window === 'undefined' || !window.matchMedia('(max-width: 767px)').matches);
+  const [loading, setLoading] = useState(true);
+  const [nearbyLoading, setNearbyLoading] = useState(false);
+  const [error, setError] = useState('');
+  const deferredQuery = useDeferredValue(query.trim());
+
+  useEffect(() => {
+    if (!isFullscreen) return undefined;
+    const previousOverflow = document.body.style.overflow;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setIsFullscreen(false);
+    };
+    document.body.style.overflow = 'hidden';
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.body.style.overflow = previousOverflow;
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [isFullscreen]);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    Promise.all([fetchHydrogenHeatmapMeta(controller.signal), fetchAmapConfig(controller.signal)])
+      .then(([nextMeta, nextConfig]) => {
+        setMeta(nextMeta);
+        setConfig(nextConfig);
+        setStartDate(nextMeta.startDate);
+        setEndDate(nextMeta.endDate);
+      })
+      .catch((requestError) => {
+        if (requestError?.name !== 'AbortError') setError('加氢热力图基础配置加载失败');
+      });
+    return () => controller.abort();
+  }, []);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const timer = window.setTimeout(() => {
+      setLoading(true);
+      setError('');
+      fetchHydrogenHeatmapPoints({ startDate, endDate, query: deferredQuery, payer, metric }, controller.signal)
+        .then((response) => {
+          setData(response);
+          setNearby(null);
+        })
+        .catch((requestError) => {
+          if (requestError?.name !== 'AbortError') setError('加氢热力图数据加载失败，请稍后重试');
+        })
+        .finally(() => setLoading(false));
+    }, 220);
+    return () => {
+      window.clearTimeout(timer);
+      controller.abort();
+    };
+  }, [deferredQuery, endDate, metric, payer, startDate]);
+
+  const handleMapClick = useCallback((longitude: number, latitude: number) => {
+    const controller = new AbortController();
+    setNearbyLoading(true);
+    fetchNearbyHydrogenStations({ lng: longitude, lat: latitude, startDate, endDate, query: deferredQuery, payer, metric }, controller.signal)
+      .then(setNearby)
+      .catch((requestError) => {
+        if (requestError?.name !== 'AbortError') setError('区域加氢站明细加载失败');
+      })
+      .finally(() => setNearbyLoading(false));
+  }, [deferredQuery, endDate, metric, payer, startDate]);
+
+  const reset = () => {
+    setStartDate(meta?.startDate || DEFAULT_START);
+    setEndDate(meta?.endDate || DEFAULT_END);
+    setQuery('');
+    setPayer('all');
+    setMetric('kg');
+    setNearby(null);
+  };
+
+  const coverageText = meta
+    ? `GPS覆盖 ${(meta.gpsCoverageRate * 100).toFixed(3)}% · 已排除 ${integerFormat.format(meta.excludedRefuelCount)} 笔缺坐标数据`
+    : '正在核对站点 GPS 覆盖率';
+
+  const detail = useMemo(() => {
+    if (nearby) {
+      return {
+        title: '选中区域',
+        subtitle: `${nearby.center.lng.toFixed(3)}, ${nearby.center.lat.toFixed(3)} · 半径 ${nearby.radiusKm} 公里`,
+        kg: nearby.kg,
+        refuelCount: nearby.refuelCount,
+        vehicleCount: nearby.vehicleCount,
+        stationCount: nearby.stationCount,
+        stations: nearby.topStations,
+        selected: true,
+      };
+    }
+    return {
+      title: deferredQuery ? '站点筛选结果' : '全国 · 当前范围',
+      subtitle: `${payer === 'all' ? '' : `${payer === 'lingniu' ? '羚牛承担' : '客户承担'} · `}${startDate} ～ ${endDate}`,
+      kg: data?.kg || 0,
+      refuelCount: data?.refuelCount || 0,
+      vehicleCount: data?.vehicleCount || 0,
+      stationCount: data?.stationCount || 0,
+      stations: data?.topStations || [],
+      selected: false,
+    };
+  }, [data, deferredQuery, endDate, nearby, payer, startDate]);
+
+  return (
+    <section className={`flex flex-col overflow-hidden bg-white ${isFullscreen ? 'fixed inset-0 z-[100] h-screen w-screen min-h-0' : 'h-[100dvh] min-h-[620px] max-md:h-[calc(100dvh-4rem)] max-md:min-h-[520px]'}`}>
+      <header className="relative z-30 flex min-h-[98px] shrink-0 items-center justify-between border-b border-slate-200 bg-white px-8 max-md:min-h-[104px] max-md:flex-wrap max-md:gap-y-2 max-md:px-3 max-md:py-3">
+        <div className="min-w-0">
+          <h1 className="truncate text-[25px] font-semibold tracking-[-0.025em] text-slate-950 max-md:text-[18px]">加氢站加氢热力图</h1>
+          <p className="mt-1.5 flex items-center gap-1.5 text-[11px] text-slate-400 max-md:mt-1 max-md:text-[9px]"><Fuel size={13} />加氢账本 × 加氢站 GPS · 上海时区</p>
+        </div>
+        <div className="absolute left-1/2 top-1/2 flex -translate-x-1/2 -translate-y-1/2 items-center gap-7 max-md:order-3 max-md:static max-md:w-full max-md:translate-x-0 max-md:translate-y-0 max-md:justify-center max-md:gap-2">
+          <Metric value={kgFormat.format(data?.kg ?? meta?.eligibleKg ?? 0)} label="加氢量 kg" />
+          <span className="h-8 w-px bg-slate-200" />
+          <Metric value={integerFormat.format(data?.refuelCount ?? meta?.eligibleRefuelCount ?? 0)} label="加氢次数" />
+          <span className="h-8 w-px bg-slate-200" />
+          <Metric value={integerFormat.format(data?.stationCount ?? meta?.eligibleStationCount ?? 0)} label="站点" />
+        </div>
+        <div className="flex items-center gap-3">
+          <p className="flex items-center gap-2 text-[12px] text-slate-500 max-xl:hidden"><Clock3 size={15} strokeWidth={1.7} />数据更新至 {meta?.endDate || DEFAULT_END}</p>
+          <button type="button" onClick={() => setIsFullscreen((current) => !current)} className="grid h-9 w-9 place-items-center rounded-lg border border-slate-200 text-slate-500 transition hover:border-cyan-300 hover:bg-cyan-50 hover:text-cyan-700" title={isFullscreen ? '退出全屏' : '地图全屏'} aria-label={isFullscreen ? '退出加氢地图全屏' : '加氢地图全屏'} aria-pressed={isFullscreen}>
+            {isFullscreen ? <Minimize2 size={17} /> : <Maximize2 size={17} />}
+          </button>
+        </div>
+      </header>
+
+      <div className="relative flex min-h-0 flex-1">
+        <div className="relative z-0 min-w-0 flex-1 overflow-hidden">
+          {config ? <HydrogenAmapCanvas config={config} points={data?.points || []} max={data?.max || 1} metric={metric} focusQuery={deferredQuery} onMapClick={handleMapClick} /> : <div className="absolute inset-0 bg-slate-100" />}
+
+          {showFilters ? (
+            <div className="pointer-events-none absolute left-3 right-3 top-3 z-10 md:left-5 md:right-auto md:top-5">
+              <HydrogenHeatmapFilters
+                startDate={startDate}
+                endDate={endDate}
+                minDate={meta?.startDate || DEFAULT_START}
+                maxDate={meta?.endDate || DEFAULT_END}
+                query={query}
+                payer={payer}
+                metric={metric}
+                stations={meta?.stations || []}
+                onStartDateChange={setStartDate}
+                onEndDateChange={setEndDate}
+                onQueryChange={setQuery}
+                onPayerChange={setPayer}
+                onMetricChange={setMetric}
+                onReset={reset}
+                onHide={() => setShowFilters(false)}
+              />
+            </div>
+          ) : (
+            <button type="button" onClick={() => setShowFilters(true)} aria-label="显示加氢筛选" className="absolute left-3 top-3 z-20 flex h-11 items-center gap-2 rounded-lg border border-slate-200 bg-white/95 px-3 text-xs font-medium text-slate-600 shadow-lg backdrop-blur-sm transition hover:border-cyan-300 hover:bg-cyan-50 hover:text-cyan-700 md:left-5 md:top-5 md:h-10"><SlidersHorizontal size={15} strokeWidth={1.8} />显示筛选</button>
+          )}
+
+          {!showDetails ? (
+            <button type="button" onClick={() => setShowDetails(true)} aria-label="显示加氢详情" className={`absolute right-3 top-3 z-20 flex h-11 items-center gap-2 rounded-lg border border-slate-200 bg-white/95 px-3 text-xs font-medium text-slate-600 shadow-lg backdrop-blur-sm transition hover:border-cyan-300 hover:bg-cyan-50 hover:text-cyan-700 md:right-5 md:top-5 md:h-10 ${showFilters ? 'max-md:hidden' : ''}`}><ChevronLeft size={16} strokeWidth={1.8} />显示详情</button>
+          ) : null}
+
+          <div className="pointer-events-none absolute bottom-5 left-5 z-10 w-[300px] rounded-xl border border-slate-200/80 bg-white/95 p-3.5 shadow-[0_8px_30px_rgba(15,23,42,0.11)] backdrop-blur-sm max-lg:bottom-[calc(43vh+16px)] max-md:hidden">
+            <div className="flex items-center justify-between text-[11px] font-medium text-slate-700"><span>{metricName(metric)}</span>{loading ? <i className="h-3 w-3 animate-spin rounded-full border-2 border-cyan-600 border-t-transparent" /> : null}</div>
+            <p className="mt-1 text-[10px] leading-4 text-slate-500">{metricDescription(metric)}</p>
+            <div className="mt-2.5 h-2.5 rounded-full bg-[linear-gradient(90deg,#2563eb_0%,#0891b2_25%,#16a34a_45%,#eab308_65%,#f97316_82%,#dc2626_100%)]" />
+            <div className="mt-1.5 flex justify-between text-[10px] text-slate-400"><span>相对较低</span><span>相对较高</span></div>
+          </div>
+
+          {error ? <div className="absolute bottom-5 left-1/2 z-30 flex -translate-x-1/2 items-center gap-2 rounded-lg bg-slate-900 px-4 py-2.5 text-xs text-white shadow-xl"><AlertTriangle size={15} className="text-amber-300" />{error}</div> : null}
+        </div>
+
+        {showDetails ? (
+          <HydrogenHeatmapDetailPanel {...detail} metric={metric} loading={nearbyLoading} coverageText={coverageText} onClose={() => setNearby(null)} onHide={() => setShowDetails(false)} />
+        ) : null}
+      </div>
+    </section>
+  );
+}

src/modules/hydrogen-heatmap/api.ts

@@ -0,0 +1,51 @@
+import { fetchJson } from '../../auth/api-client';
+import type {
+  AmapConfig,
+  HydrogenHeatmapMeta,
+  HydrogenHeatmapMetric,
+  HydrogenHeatmapResponse,
+  HydrogenNearbyResponse,
+  HydrogenPayer,
+} from './types';
+
+const BASE = '/api/hydrogen-heatmap';
+
+export function fetchAmapConfig(signal?: AbortSignal) {
+  return fetchJson<AmapConfig>(`${BASE}/config`, { signal });
+}
+
+export function fetchHydrogenHeatmapMeta(signal?: AbortSignal) {
+  return fetchJson<HydrogenHeatmapMeta>(`${BASE}/meta`, { signal });
+}
+
+export function fetchHydrogenHeatmapPoints(
+  params: { startDate: string; endDate: string; query: string; payer: HydrogenPayer; metric: HydrogenHeatmapMetric },
+  signal?: AbortSignal,
+) {
+  return fetchJson<HydrogenHeatmapResponse>(`${BASE}/points?${new URLSearchParams(params)}`, { signal });
+}
+
+export function fetchNearbyHydrogenStations(
+  params: {
+    lng: number;
+    lat: number;
+    startDate: string;
+    endDate: string;
+    query: string;
+    payer: HydrogenPayer;
+    metric: HydrogenHeatmapMetric;
+  },
+  signal?: AbortSignal,
+) {
+  const search = new URLSearchParams({
+    lng: String(params.lng),
+    lat: String(params.lat),
+    startDate: params.startDate,
+    endDate: params.endDate,
+    query: params.query,
+    payer: params.payer,
+    metric: params.metric,
+    radiusKm: '50',
+  });
+  return fetchJson<HydrogenNearbyResponse>(`${BASE}/nearby?${search}`, { signal });
+}

src/modules/hydrogen-heatmap/types.ts

@@ -0,0 +1,72 @@
+export type HydrogenHeatmapMetric = 'kg' | 'refuels' | 'vehicles';
+export type HydrogenPayer = 'all' | 'lingniu' | 'customer';
+
+export type HydrogenHeatmapPoint = {
+  lng: number;
+  lat: number;
+  count: number;
+};
+
+export type HydrogenStationRank = {
+  stationId: string;
+  stationName: string;
+  address: string;
+  lng: number;
+  lat: number;
+  kg: number;
+  refuelCount: number;
+  vehicleCount: number;
+  firstRefuel: string;
+  lastRefuel: string;
+  metricValue: number;
+};
+
+export type HydrogenStationOption = {
+  stationId: string;
+  stationName: string;
+};
+
+export type HydrogenHeatmapMeta = {
+  startDate: string;
+  endDate: string;
+  totalRefuelCount: number;
+  eligibleRefuelCount: number;
+  excludedRefuelCount: number;
+  gpsCoverageRate: number;
+  totalKg: number;
+  eligibleKg: number;
+  vehicleCount: number;
+  totalStationCount: number;
+  eligibleStationCount: number;
+  stations: HydrogenStationOption[];
+};
+
+export type HydrogenHeatmapResponse = {
+  startDate: string;
+  endDate: string;
+  metric: HydrogenHeatmapMetric;
+  payer: HydrogenPayer;
+  kg: number;
+  refuelCount: number;
+  vehicleCount: number;
+  stationCount: number;
+  dayCount: number;
+  points: HydrogenHeatmapPoint[];
+  max: number;
+  topStations: HydrogenStationRank[];
+};
+
+export type HydrogenNearbyResponse = {
+  center: { lng: number; lat: number };
+  radiusKm: number;
+  kg: number;
+  refuelCount: number;
+  vehicleCount: number;
+  stationCount: number;
+  topStations: HydrogenStationRank[];
+};
+
+export type AmapConfig = {
+  key: string;
+  securityCode: string;
+};

src/modules/mileage/DailyReportView.tsx

@@ -1,18 +1,348 @@
-import { FileText } from 'lucide-react';
-import { SurfaceCard } from '../../components/ui/surface';
+import { useCallback, useEffect, useState } from 'react';
+import { motion } from 'motion/react';
+import {
+  Activity,
+  AlertTriangle,
+  CalendarDays,
+  ChevronRight,
+  CircleGauge,
+  Database,
+  RefreshCw,
+  Route,
+  Truck,
+} from 'lucide-react';
+import {
+  Bar,
+  BarChart,
+  CartesianGrid,
+  ResponsiveContainer,
+  Tooltip,
+  XAxis,
+  YAxis,
+} from 'recharts';
+import Blur from '../../components/Blur';
+import { MetricTile, SurfaceCard } from '../../components/ui/surface';
+import {
+  fetchDailyReport,
+  fetchDailyReportTrend,
+  type DailyReportData,
+  type DailyReportVehicle,
+} from './api';
+import { buildMileageDrillUrl } from './drill-context';
 
-export default function DailyReportView() {
+function fmtKm(value: number): string {
+  if (value >= 10000) return `${(value / 10000).toFixed(2)}万`;
+  return value.toLocaleString(undefined, { maximumFractionDigits: 1 });
+}
+
+function fmtTime(value: string): string {
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleString('zh-CN', {
+    month: '2-digit',
+    day: '2-digit',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+  });
+}
+
+function VehicleRow({
+  vehicle,
+  mode,
+  onClick,
+}: {
+  vehicle: DailyReportVehicle;
+  mode: 'top' | 'risk';
+  onClick: () => void;
+}) {
   return (
-    <SurfaceCard className="min-h-[360px]">
-      <div className="flex min-h-[320px] flex-col items-center justify-center px-6 py-10 text-center">
-        <div className="flex h-14 w-14 items-center justify-center rounded-2xl bg-slate-100 text-slate-400">
-          <FileText size={26} />
+    <button
+      type="button"
+      onClick={onClick}
+      className="grid w-full grid-cols-[minmax(0,1fr)_auto_18px] items-center gap-2 px-4 py-3 text-left transition-colors hover:bg-slate-50"
+    >
+      <span className="min-w-0">
+        <span className="flex items-center gap-2">
+          <span className="truncate font-mono text-xs font-black text-slate-800"><Blur>{vehicle.plate}</Blur></span>
+          <span className={`h-1.5 w-1.5 shrink-0 rounded-full ${vehicle.isOnline ? 'bg-emerald-500' : 'bg-slate-300'}`} />
+        </span>
+        <span className="mt-0.5 block truncate text-[9px] font-bold text-slate-400">
+          {vehicle.model} · {vehicle.status} · <Blur>{vehicle.customer}</Blur>
+        </span>
+      </span>
+      <span className="text-right">
+        {mode === 'top' ? (
+          <>
+            <span className="block text-xs font-black text-blue-600">{fmtKm(vehicle.today)} km</span>
+            <span className="block text-[9px] font-bold text-slate-400">当日里程</span>
+          </>
+        ) : (
+          <>
+            <span className="block text-xs font-black text-rose-600">{fmtKm(vehicle.shortfall)} km</span>
+            <span className="block text-[9px] font-bold text-slate-400">任务缺口</span>
+          </>
+        )}
+      </span>
+      <ChevronRight size={14} className="text-slate-300" />
+    </button>
+  );
+}
+
+export default function DailyReportView() {
+  const [report, setReport] = useState<DailyReportData | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [trendLoading, setTrendLoading] = useState(true);
+  const [error, setError] = useState('');
+
+  const load = useCallback(async (force = false) => {
+    setLoading(true);
+    setTrendLoading(true);
+    setError('');
+    const trendRequest = fetchDailyReportTrend(force);
+    try {
+      const nextReport = await fetchDailyReport(force);
+      setReport(nextReport);
+      setLoading(false);
+      try {
+        const trend = await trendRequest;
+        setReport(current => current ? {
+          ...current,
+          trend: trend.map(item => ({ date: item.date, value: item.mileage })),
+        } : current);
+      } catch {
+        setError('7 日趋势加载失败');
+      } finally {
+        setTrendLoading(false);
+      }
+    } catch (cause) {
+      void trendRequest.catch(() => {});
+      setError(cause instanceof Error ? cause.message : '日报加载失败');
+      setLoading(false);
+      setTrendLoading(false);
+    }
+  }, []);
+
+  useEffect(() => {
+    void load();
+  }, [load]);
+
+  const openTarget = useCallback((targetId: number) => {
+    const url = buildMileageDrillUrl(
+      { pathname: window.location.pathname, search: window.location.search, hash: '#mileage/statistics' },
+      { level: 'overview', targetId, sourcePriority: ['instrument'] },
+    );
+    window.history.pushState(null, '', url);
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+  }, []);
+
+  const openVehicle = useCallback((vehicle: DailyReportVehicle) => {
+    if (!report) return;
+    const url = buildMileageDrillUrl(
+      { pathname: window.location.pathname, search: window.location.search, hash: '#mileage' },
+      {
+        level: 'vehicle',
+        targetId: vehicle.targetId,
+        plate: vehicle.plate,
+        startDate: report.reportDate,
+        endDate: report.reportDate,
+        sourcePriority: ['instrument'],
+      },
+    );
+    window.history.pushState(null, '', url);
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+  }, [report]);
+
+  if (loading && !report) {
+    return (
+      <SurfaceCard className="min-h-[360px]">
+        <div className="flex min-h-[320px] items-center justify-center gap-2 text-xs font-bold text-slate-400">
+          <RefreshCw size={16} className="animate-spin" />
+          正在生成里程日报
         </div>
-        <div className="mt-4 text-base font-black text-slate-800">每日汇报接入中</div>
-        <div className="mt-2 max-w-md text-xs font-bold leading-relaxed text-slate-400">
-          日报数据口径正在整理，完成后将接入数据库统计与导出能力。
+      </SurfaceCard>
+    );
+  }
+
+  if (!report) {
+    return (
+      <SurfaceCard className="min-h-[360px]">
+        <div className="flex min-h-[320px] flex-col items-center justify-center gap-3 px-6 text-center">
+          <AlertTriangle size={24} className="text-rose-500" />
+          <div className="text-sm font-black text-slate-800">日报暂不可用</div>
+          <div className="max-w-md text-xs font-bold text-slate-400">{error || '数据接口未返回有效结果'}</div>
+          <button
+            type="button"
+            onClick={() => void load(true)}
+            className="rounded-lg bg-slate-900 px-4 py-2 text-xs font-black text-white"
+          >
+            重新加载
+          </button>
         </div>
+      </SurfaceCard>
+    );
+  }
+
+  return (
+    <div className="space-y-3 pb-4">
+      <section className="flex flex-col gap-3 rounded-xl border border-slate-200 bg-white px-4 py-3 shadow-sm md:flex-row md:items-center md:justify-between">
+        <div className="flex items-center gap-3">
+          <span className="flex h-9 w-9 items-center justify-center rounded-lg bg-blue-50 text-blue-600 ring-1 ring-blue-100">
+            <CalendarDays size={17} />
+          </span>
+          <div>
+            <h2 className="text-sm font-black text-slate-900">{report.reportDate} 里程日报</h2>
+            <p className="mt-0.5 text-[10px] font-bold text-slate-400">统计时间 {fmtTime(report.updatedAt)} · 仪表数据</p>
+          </div>
+        </div>
+        <button
+          type="button"
+          onClick={() => void load(true)}
+          disabled={loading || trendLoading}
+          className="inline-flex h-9 items-center justify-center gap-2 rounded-lg border border-blue-100 bg-blue-50 px-3 text-xs font-black text-blue-600 transition-colors hover:bg-blue-100 disabled:opacity-50"
+        >
+          <RefreshCw size={14} className={loading || trendLoading ? 'animate-spin' : ''} />
+          刷新日报
+        </button>
+      </section>
+
+      <div className="grid grid-cols-2 gap-2 lg:grid-cols-4">
+        <MetricTile
+          label="考核车辆当日里程"
+          value={fmtKm(report.totalToday)}
+          unit="km"
+          helper={`${report.activeCount}/${report.assessmentVehicleCount} 台产生里程`}
+          icon={Route}
+          tone="blue"
+        />
+        <MetricTile
+          label="当日任务缺口"
+          value={fmtKm(report.shortfall)}
+          unit="km"
+          helper={`任务基准 ${fmtKm(report.dailyNeed)} km`}
+          icon={AlertTriangle}
+          tone={report.shortfall > 0 ? 'rose' : 'emerald'}
+        />
+        <MetricTile
+          label="零里程车辆"
+          value={report.zeroCount}
+          unit="台"
+          helper={`考核车辆共 ${report.assessmentVehicleCount} 台`}
+          icon={Truck}
+          tone={report.zeroCount > 0 ? 'amber' : 'emerald'}
+        />
+        <MetricTile
+          label="考核加权完成率"
+          value={report.completionRate.toFixed(1)}
+          unit="%"
+          helper={`${report.qualifiedCount} 台达标 · ${report.halfQualifiedCount} 台过半`}
+          icon={CircleGauge}
+          tone="emerald"
+        />
+      </div>
+
+      <div className="grid gap-3 xl:grid-cols-[minmax(0,1.35fr)_minmax(320px,0.65fr)]">
+        <div className="space-y-3">
+          <SurfaceCard
+            title="全量监控车辆 7 日趋势"
+            subtitle={`当前监控范围 ${report.monitoringVehicleCount} 台，趋势不等同于考核车辆范围`}
+          >
+            <div className="h-[250px] px-2 py-3">
+              {report.trend.length === 0 && trendLoading ? (
+                <div className="flex h-full items-center justify-center gap-2 text-xs font-bold text-slate-400">
+                  <RefreshCw size={14} className="animate-spin" />
+                  正在加载趋势
+                </div>
+              ) : report.trend.length === 0 ? (
+                <div className="flex h-full items-center justify-center text-xs font-bold text-slate-400">
+                  暂无趋势数据
+                </div>
+              ) : (
+                <ResponsiveContainer width="100%" height="100%">
+                <BarChart data={report.trend} margin={{ top: 12, right: 12, left: -12, bottom: 0 }}>
+                  <CartesianGrid vertical={false} stroke="#e2e8f0" strokeDasharray="3 3" />
+                  <XAxis dataKey="date" axisLine={false} tickLine={false} tick={{ fontSize: 10, fill: '#94a3b8' }} />
+                  <YAxis axisLine={false} tickLine={false} tick={{ fontSize: 10, fill: '#94a3b8' }} tickFormatter={fmtKm} />
+                  <Tooltip
+                    formatter={(value) => [`${fmtKm(Number(value))} km`, '总里程']}
+                    contentStyle={{ borderRadius: 8, border: '1px solid #e2e8f0', fontSize: 11 }}
+                  />
+                  <Bar dataKey="value" fill="#2563eb" radius={[4, 4, 0, 0]} maxBarSize={30} />
+                </BarChart>
+                </ResponsiveContainer>
+              )}
+            </div>
+          </SurfaceCard>
+
+          <SurfaceCard title="考核目标表现" subtitle="按当日任务缺口排序，点击进入考核统计">
+            <div className="divide-y divide-slate-100">
+              {report.models.map((model, index) => (
+                <motion.button
+                  type="button"
+                  key={model.id}
+                  initial={{ opacity: 0, y: 4 }}
+                  animate={{ opacity: 1, y: 0 }}
+                  transition={{ delay: index * 0.025 }}
+                  onClick={() => openTarget(model.id)}
+                  className="grid w-full grid-cols-[minmax(0,1fr)_72px_78px_20px] items-center gap-2 px-4 py-3 text-left transition-colors hover:bg-slate-50"
+                >
+                  <span className="min-w-0">
+                    <span className="block truncate text-xs font-black text-slate-800">{model.name}</span>
+                    <span className="mt-0.5 block text-[9px] font-bold text-slate-400">
+                      {model.active}/{model.count} 台有里程 · {model.zero} 台零里程
+                      {model.missingDailyTaskCount > 0 ? ` · ${model.missingDailyTaskCount} 台缺任务值` : ''}
+                    </span>
+                  </span>
+                  <span className="text-right">
+                    <span className="block text-[11px] font-black text-blue-600">{fmtKm(model.today)}</span>
+                    <span className="block text-[9px] font-bold text-slate-400">当日 km</span>
+                  </span>
+                  <span className="text-right">
+                    <span className={`block text-[11px] font-black ${model.shortfall > 0 ? 'text-rose-600' : 'text-emerald-600'}`}>
+                      {fmtKm(model.shortfall)}
+                    </span>
+                    <span className="block text-[9px] font-bold text-slate-400">缺口 km</span>
+                  </span>
+                  <ChevronRight size={14} className="text-slate-300" />
+                </motion.button>
+              ))}
+            </div>
+          </SurfaceCard>
+        </div>
+
+        <div className="space-y-3">
+          <SurfaceCard title="当日里程 TOP 5" subtitle="考核车辆范围">
+            <div className="divide-y divide-slate-100">
+              {report.topVehicles.map(vehicle => (
+                <VehicleRow key={vehicle.plate} vehicle={vehicle} mode="top" onClick={() => openVehicle(vehicle)} />
+              ))}
+            </div>
+          </SurfaceCard>
+
+          <SurfaceCard title="任务缺口车辆" subtitle="按车辆当日任务缺口排序，仅含已返回任务值的车辆">
+            <div className="divide-y divide-slate-100">
+              {report.riskVehicles.map(vehicle => (
+                <VehicleRow key={vehicle.plate} vehicle={vehicle} mode="risk" onClick={() => openVehicle(vehicle)} />
+              ))}
+            </div>
+          </SurfaceCard>
+
+          <section className="rounded-xl border border-slate-200 bg-white px-4 py-3 shadow-sm">
+            <div className="flex items-start gap-3">
+              <Database size={16} className="mt-0.5 shrink-0 text-slate-400" />
+              <div className="min-w-0 text-[10px] font-bold leading-relaxed text-slate-500">
+                <div>考核车辆 {report.assessmentVehicleCount} 台 · 监控车辆 {report.monitoringVehicleCount} 台</div>
+                <div className="mt-1">重复考核归属 {report.duplicateAssignmentCount} 条</div>
+                <div className={report.missingDailyTaskCount > 0 ? 'mt-1 text-amber-600' : 'mt-1'}>
+                  缺少车辆级任务值 {report.missingDailyTaskCount} 台
+                </div>
+                {error && <div className="mt-1 text-rose-600">最近刷新失败：{error}</div>}
+              </div>
+              <Activity size={14} className="ml-auto shrink-0 text-emerald-500" />
+            </div>
+          </section>
+        </div>
       </div>
-    </SurfaceCard>
+    </div>
   );
 }

src/modules/mileage/MileageAttributionView.tsx

@@ -0,0 +1,141 @@
+import { AlertTriangle, Building2, ChevronRight, Users } from 'lucide-react';
+import type { TargetVehicle } from './types';
+import {
+  buildMileageAttribution,
+  reconcileMileageAttribution,
+  type AttributionDimension,
+} from './attribution';
+import { ErrorState } from '../../components/ui/surface';
+
+interface Props {
+  vehicles: TargetVehicle[];
+  dimension: AttributionDimension;
+  selectedValue?: string;
+  loading?: boolean;
+  error?: string | null;
+  targetMileagePerVehicle: number;
+  expectedShortfallMileage?: number;
+  assessmentLabel?: string;
+  onDimensionChange: (dimension: AttributionDimension) => void;
+  onSelect: (value: string) => void;
+  onRetry?: () => void;
+}
+
+function fmtKm(value: number): string {
+  return value >= 10000 ? `${(value / 10000).toFixed(2)}万` : value.toLocaleString(undefined, { maximumFractionDigits: 1 });
+}
+
+export default function MileageAttributionView({
+  vehicles,
+  dimension,
+  selectedValue,
+  loading = false,
+  error,
+  targetMileagePerVehicle,
+  expectedShortfallMileage,
+  assessmentLabel,
+  onDimensionChange,
+  onSelect,
+  onRetry,
+}: Props) {
+  const groups = buildMileageAttribution(vehicles, dimension, targetMileagePerVehicle);
+  const totalShortfall = groups.reduce((sum, group) => sum + group.shortfallMileage, 0);
+  const totalBehind = groups.reduce((sum, group) => sum + group.behindCount, 0);
+  const reconciliation = expectedShortfallMileage == null
+    ? null
+    : reconcileMileageAttribution(groups, expectedShortfallMileage);
+
+  return (
+    <section className="overflow-hidden rounded-xl border border-slate-200 bg-white shadow-sm">
+      <div className="flex flex-col gap-3 border-b border-slate-100 px-4 py-3 md:flex-row md:items-center md:justify-between">
+        <div>
+          <div className="flex items-center gap-2">
+            <span className="h-4 w-1 rounded-full bg-blue-600" />
+            <h2 className="text-sm font-black text-slate-800">考核缺口归因</h2>
+          </div>
+          <p className="mt-1 text-[10px] font-bold text-slate-400">
+            {assessmentLabel ? `${assessmentLabel} · ` : ''}
+            {loading
+              ? '正在加载归因车辆'
+              : error
+                ? '归因数据暂不可用'
+                : `${totalBehind} 台未达标，累计缺口 ${fmtKm(totalShortfall)} km`}
+          </p>
+          {!loading && !error && reconciliation && (
+            <p
+              role={reconciliation.matches ? 'status' : 'alert'}
+              className={`mt-1 text-[10px] font-black ${reconciliation.matches ? 'text-emerald-600' : 'text-rose-600'}`}
+            >
+              {reconciliation.matches
+                ? '与考核目标汇总一致'
+                : `与考核目标汇总相差 ${reconciliation.difference > 0 ? '+' : ''}${fmtKm(reconciliation.difference)} km`}
+            </p>
+          )}
+        </div>
+        <div className="flex rounded-lg bg-slate-100 p-1" aria-label="归因维度">
+          {([
+            ['department', '部门', Building2],
+            ['customer', '客户', Users],
+          ] as const).map(([value, label, Icon]) => (
+            <button
+              key={value}
+              type="button"
+              onClick={() => onDimensionChange(value)}
+              className={`flex min-w-[72px] items-center justify-center gap-1.5 rounded-md px-3 py-1.5 text-[10px] font-black transition-colors ${
+                dimension === value ? 'bg-white text-blue-600 shadow-sm' : 'text-slate-500 hover:text-slate-800'
+              }`}
+            >
+              <Icon size={12} />
+              {label}
+            </button>
+          ))}
+        </div>
+      </div>
+
+      {loading ? (
+        <div className="px-4 py-8 text-center text-xs font-bold text-slate-400">正在计算归因...</div>
+      ) : error ? (
+        <ErrorState message={error} onRetry={onRetry} variant="inline" />
+      ) : groups.length === 0 ? (
+        <div className="px-4 py-8 text-center text-xs font-bold text-slate-400">暂无可归因车辆</div>
+      ) : (
+        <div className="divide-y divide-slate-100">
+          {groups.slice(0, 8).map(group => (
+            <button
+              key={group.key}
+              type="button"
+              onClick={() => onSelect(group.key)}
+              className={`grid w-full grid-cols-[minmax(0,1fr)_70px_82px_24px] items-center gap-2 px-4 py-3 text-left transition-colors hover:bg-slate-50 ${
+                selectedValue === group.key ? 'bg-blue-50/60' : ''
+              }`}
+            >
+              <span className="min-w-0">
+                <span className="block truncate text-xs font-black text-slate-800">{group.label}</span>
+                <span className="mt-0.5 flex items-center gap-2 text-[9px] font-bold text-slate-400">
+                  <span>{group.vehicleCount} 台</span>
+                  <span>{group.onlineCount} 台在线</span>
+                  {group.zeroMileageCount > 0 && (
+                    <span className="flex items-center gap-0.5 text-amber-600">
+                      <AlertTriangle size={9} /> {group.zeroMileageCount} 台零里程
+                    </span>
+                  )}
+                </span>
+              </span>
+              <span className="text-right">
+                <span className="block text-[11px] font-black text-slate-800">{fmtKm(group.todayMileage)}</span>
+                <span className="block text-[9px] font-bold text-slate-400">贡献 {group.contributionRate.toFixed(1)}%</span>
+              </span>
+              <span className="text-right">
+                <span className={`block text-[11px] font-black ${group.shortfallMileage > 0 ? 'text-rose-600' : 'text-emerald-600'}`}>
+                  {fmtKm(group.shortfallMileage)}
+                </span>
+                <span className="block text-[9px] font-bold text-slate-400">累计缺口 · {group.behindCount} 台</span>
+              </span>
+              <ChevronRight size={14} className="text-slate-300" />
+            </button>
+          ))}
+        </div>
+      )}
+    </section>
+  );
+}

src/modules/mileage/MileageModule.tsx

@@ -6,6 +6,7 @@ import DailyReportView from './DailyReportView';
 import { useHashSubTab } from '../energy/useHashSubTab';
 import RotatingFooterHint from '../../components/RotatingFooterHint';
 import { FadeIn, PageFrame, SegmentedNav } from '../../components/ui/surface';
+import BiHeaderActions from '../../components/BiHeaderActions';
 
 type MileageSubTab = 'monitoring' | 'statistics' | 'report';
 
@@ -27,21 +28,34 @@ export default function MileageModule() {
       icon={LayoutDashboard}
       eyebrow="MILEAGE BI"
       meta="实时监控 · 统计报表 · 每日汇报"
+      actions={<BiHeaderActions domain="mileage" />}
       compactInfo
     >
       <div className="sticky top-0 z-30 -mx-3 bg-[var(--app-bg)] px-3 pb-2 pt-1 shadow-[0_8px_12px_-12px_rgba(15,23,42,0.08)] md:-mx-6 md:top-12 md:px-6">
-        <SegmentedNav tabs={MILEAGE_TABS} active={activeSubTab} onChange={setActiveSubTab} />
+        <SegmentedNav
+          tabs={MILEAGE_TABS}
+          active={activeSubTab}
+          onChange={setActiveSubTab}
+          idPrefix="mileage-view"
+          ariaLabel="里程分析视图"
+        />
       </div>
 
       <AnimatePresence mode="wait">
         <FadeIn key={activeSubTab}>
-          {activeSubTab === 'monitoring' ? (
-            <MonitoringView />
-          ) : activeSubTab === 'statistics' ? (
-            <StatisticsView />
-          ) : (
-            <DailyReportView />
-          )}
+          <div
+            id={`mileage-view-panel-${activeSubTab}`}
+            role="tabpanel"
+            aria-labelledby={`mileage-view-tab-${activeSubTab}`}
+          >
+            {activeSubTab === 'monitoring' ? (
+              <MonitoringView />
+            ) : activeSubTab === 'statistics' ? (
+              <StatisticsView />
+            ) : (
+              <DailyReportView />
+            )}
+          </div>
         </FadeIn>
       </AnimatePresence>
       <RotatingFooterHint />

src/modules/mileage/StatisticsView.tsx

@@ -1,4 +1,4 @@
-import { useState, useEffect } from 'react';
+import { useState, useEffect, useMemo, useCallback, useRef } from 'react';
 import { motion, AnimatePresence } from 'motion/react';
 import {
   BarChart, Bar, XAxis, YAxis, CartesianGrid, Tooltip,
@@ -6,12 +6,26 @@ import {
   Cell, LabelList,
 } from 'recharts';
 import {
-  Truck, ChevronDown, Maximize2, Minimize2,
+  AlertTriangle, Truck, ChevronDown, Maximize2, Minimize2,
   Search, ArrowUpDown, X, RotateCcw, Calendar,
 } from 'lucide-react';
 import type { TargetSummary, TargetVehicle, TargetYearlyAssessment, TrendPoint } from './types';
 import { fetchTargets, fetchTargetVehicles, fetchTrend } from './api';
 import Blur from '../../components/Blur';
+import { EmptyState, ErrorState, LoadingState } from '../../components/ui/surface';
+import { weightedCompletionRate } from '../../shared/analytics/metrics';
+import { formatMileageSnapshotDateTime } from './data-freshness';
+import { assessVehicleCoverage } from './assessment-coverage';
+import MileageAttributionView from './MileageAttributionView';
+import {
+  filterAttributionVehicles,
+  type AttributionDimension,
+} from './attribution';
+import {
+  buildMileageDrillUrl,
+  parseMileageDrillContext,
+  type MileageDrillContext,
+} from './drill-context';
 
 function getDefaultDate(): string {
   const now = new Date();
@@ -19,11 +33,6 @@ function getDefaultDate(): string {
   return `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
 }
 
-function getCurrentDateLabel(): string {
-  const now = new Date();
-  return `${now.getFullYear()}.${now.getMonth() + 1}.${now.getDate()}`;
-}
-
 function fmtKm(value: number): string {
   if (value >= 10000) return (value / 10000).toFixed(2) + '万';
   return value.toLocaleString();
@@ -38,10 +47,8 @@ function getTargetAssessment(target: TargetSummary, selectedYear?: number): Targ
   return target.yearlyAssessments.find(item => item.yearNumber === selectedYear) || target.yearlyAssessments[0];
 }
 
-function fmtDateLabel(date: string | null): string {
-  if (!date) return '';
-  const [year, month, day] = date.split('-');
-  return `${year}.${Number(month)}.${Number(day)}`;
+function resolveAssessmentYear(target: TargetSummary, requestedYear?: number): number | undefined {
+  return getTargetAssessment(target, requestedYear)?.yearNumber;
 }
 
 function shortTargetName(name: string): string {
@@ -58,75 +65,373 @@ function shortTargetName(name: string): string {
   return `${count}台${desc}`;
 }
 
+function getRequestErrorMessage(error: unknown, fallback: string): string {
+  if (error instanceof Error && error.message && error.message !== 'Failed to fetch') {
+    return error.message;
+  }
+  return fallback;
+}
+
 export default function StatisticsView() {
-  const currentDateLabel = getCurrentDateLabel();
+  const [drillContext, setDrillContext] = useState<MileageDrillContext>(() => (
+    parseMileageDrillContext(window.location.search)
+  ));
   const [targets, setTargets] = useState<TargetSummary[]>([]);
+  const [targetsLoading, setTargetsLoading] = useState(true);
+  const [targetsError, setTargetsError] = useState<string | null>(null);
+  const [targetsRequestVersion, setTargetsRequestVersion] = useState(0);
   const [trendData, setTrendData] = useState<TrendPoint[]>([]);
+  const [trendLoading, setTrendLoading] = useState(false);
+  const [trendError, setTrendError] = useState<string | null>(null);
+  const [trendRequestVersion, setTrendRequestVersion] = useState(0);
   const [targetVehiclesMap, setTargetVehiclesMap] = useState<Record<number, TargetVehicle[]>>({});
-  const [selectedTargetId, setSelectedTargetId] = useState<number | null>(null);
+  const [targetVehicleLoadingMap, setTargetVehicleLoadingMap] = useState<Record<number, boolean>>({});
+  const [targetVehicleErrorMap, setTargetVehicleErrorMap] = useState<Record<number, string>>({});
+  const [selectedTargetId, setSelectedTargetId] = useState<number | null>(drillContext.targetId || null);
+  const [attributionDimension, setAttributionDimension] = useState<AttributionDimension>(() => (
+    drillContext.level === 'breakdown' && drillContext.dimension === 'customer' ? 'customer' : 'department'
+  ));
 
   const [chartType, setChartType] = useState<'bar' | 'line' | 'area'>('bar');
   const [isTableFullscreen, setIsTableFullscreen] = useState(false);
   const [expandedTargetId, setExpandedTargetId] = useState<number | null>(null);
   const [assessmentYearMap, setAssessmentYearMap] = useState<Record<number, number>>({});
-  const [viewAllTargetId, setViewAllTargetId] = useState<number | null>(null);
+  const [viewAllTargetId, setViewAllTargetId] = useState<number | null>(() => (
+    drillContext.level === 'breakdown' ? drillContext.targetId || null : null
+  ));
   const [viewAllTargetName, setViewAllTargetName] = useState<string>('');
   const [viewAllSearch, setViewAllSearch] = useState('');
   const [viewAllSort, setViewAllSort] = useState<'asc' | 'desc'>('desc');
   const [viewAllDate, setViewAllDate] = useState(getDefaultDate);
   const [viewAllLoading, setViewAllLoading] = useState(false);
+  const [viewAllError, setViewAllError] = useState<string | null>(null);
+  const [viewAllRequestVersion, setViewAllRequestVersion] = useState(0);
+  const [viewAllHistoricalVehicles, setViewAllHistoricalVehicles] = useState<TargetVehicle[] | null>(null);
+  const [viewAllLoadedDate, setViewAllLoadedDate] = useState<string | null>(null);
+  const [viewAllLoadedTargetId, setViewAllLoadedTargetId] = useState<number | null>(null);
+  const targetVehicleRequestsRef = useRef(new Set<number>());
+  const initialDrillContextRef = useRef(drillContext);
 
   const selectedTarget = targets.find(t => t.id === selectedTargetId);
+  const selectedTargetVehicles = selectedTargetId === null ? [] : targetVehiclesMap[selectedTargetId] || [];
   const selectedAssessment = selectedTarget ? getTargetAssessment(selectedTarget, assessmentYearMap[selectedTarget.id]) : null;
+  const selectedCoverage = selectedTarget
+    ? assessVehicleCoverage(selectedTarget.declaredVehicleCount, selectedTarget.vehicleCount)
+    : null;
+  const selectedAssessmentYear = selectedAssessment?.yearNumber;
   const selectedCompletion = selectedAssessment?.completionRate ?? selectedTarget?.avgCompletion ?? 0;
   const selectedRemaining = selectedAssessment?.remaining ?? 0;
   const selectedDaysLeft = selectedAssessment?.daysLeft ?? selectedTarget?.daysLeft ?? 0;
   const selectedDailyTarget = selectedAssessment?.dailyTarget ?? (selectedDaysLeft > 0 ? selectedRemaining / selectedDaysLeft : 0);
   const selectedQualifiedRate = selectedAssessment?.qualifiedRate ?? (selectedTarget?.vehicleCount ? selectedTarget.yearQualifiedCount / selectedTarget.vehicleCount * 100 : 0);
+  const selectedYearCompletionRate = weightedCompletionRate(
+    targets.flatMap(target => {
+      const assessment = getTargetAssessment(target, assessmentYearMap[target.id]);
+      return assessment ? [{ completed: assessment.completed, target: assessment.target }] : [];
+    }),
+  );
   const latestTrend = trendData[trendData.length - 1];
   const previousTrend = trendData[trendData.length - 2];
   const trendDelta = latestTrend && previousTrend ? latestTrend.mileage - previousTrend.mileage : 0;
   const pressureLevel = selectedCompletion >= 90 ? '健康' : selectedCompletion >= 70 ? '关注' : '高压';
+  const selectedBreakdownValue = drillContext.level === 'breakdown'
+    ? drillContext.dimensionValue
+    : undefined;
 
-  // Load targets on mount
+  const commitDrillContext = useCallback((next: MileageDrillContext, mode: 'push' | 'replace') => {
+    const url = buildMileageDrillUrl(window.location, next);
+    window.history[mode === 'push' ? 'pushState' : 'replaceState'](null, '', url);
+    setDrillContext(next);
+  }, []);
+
+  const retryTargets = useCallback(() => {
+    setTargetsRequestVersion(version => version + 1);
+  }, []);
+
+  const retryTrend = useCallback(() => {
+    setTrendRequestVersion(version => version + 1);
+  }, []);
+
+  const retryViewAllVehicles = useCallback(() => {
+    setViewAllRequestVersion(version => version + 1);
+  }, []);
+
+  const loadCurrentTargetVehicles = useCallback((targetId: number) => {
+    if (targetVehicleRequestsRef.current.has(targetId)) return;
+    targetVehicleRequestsRef.current.add(targetId);
+    setTargetVehicleLoadingMap(prev => ({ ...prev, [targetId]: true }));
+    setTargetVehicleErrorMap(prev => {
+      const next = { ...prev };
+      delete next[targetId];
+      return next;
+    });
+    fetchTargetVehicles(targetId).then(vehicles => {
+      setTargetVehiclesMap(prev => ({ ...prev, [targetId]: vehicles }));
+    }).catch(error => {
+      setTargetVehicleErrorMap(prev => ({
+        ...prev,
+        [targetId]: getRequestErrorMessage(error, '无法获取考核车辆数据，请稍后重试。'),
+      }));
+    }).finally(() => {
+      setTargetVehicleLoadingMap(prev => ({ ...prev, [targetId]: false }));
+      targetVehicleRequestsRef.current.delete(targetId);
+    });
+  }, []);
+
+  const selectTarget = useCallback((targetId: number) => {
+    const target = targets.find(item => item.id === targetId);
+    const assessmentYear = target
+      ? resolveAssessmentYear(target, assessmentYearMap[targetId])
+      : undefined;
+    setSelectedTargetId(targetId);
+    setExpandedTargetId(targetId);
+    setViewAllTargetId(null);
+    setViewAllSearch('');
+    commitDrillContext({
+      level: 'overview',
+      targetId,
+      assessmentYear,
+      sourcePriority: ['instrument'],
+    }, 'replace');
+  }, [assessmentYearMap, commitDrillContext, targets]);
+
+  const openAttributionGroup = useCallback((value: string) => {
+    if (selectedTargetId === null) return;
+    setViewAllTargetId(selectedTargetId);
+    setViewAllTargetName(selectedTarget?.targetName || '考核车辆');
+    setViewAllSearch('');
+    setViewAllDate(getDefaultDate());
+    setViewAllHistoricalVehicles(null);
+    setViewAllLoadedDate(null);
+    setViewAllLoadedTargetId(null);
+    setViewAllError(null);
+    commitDrillContext({
+      level: 'breakdown',
+      targetId: selectedTargetId,
+      assessmentYear: selectedAssessmentYear,
+      dimension: attributionDimension,
+      dimensionValue: value,
+      sourcePriority: ['instrument'],
+    }, 'push');
+  }, [attributionDimension, commitDrillContext, selectedAssessmentYear, selectedTarget?.targetName, selectedTargetId]);
+
+  const openTargetVehicles = useCallback((target: TargetSummary) => {
+    const assessmentYear = resolveAssessmentYear(target, assessmentYearMap[target.id]);
+    setViewAllTargetId(target.id);
+    setViewAllTargetName(target.targetName);
+    setViewAllSearch('');
+    setViewAllDate(getDefaultDate());
+    setViewAllHistoricalVehicles(null);
+    setViewAllLoadedDate(null);
+    setViewAllLoadedTargetId(null);
+    setViewAllError(null);
+    commitDrillContext({
+      level: 'breakdown',
+      targetId: target.id,
+      assessmentYear,
+      dimension: 'assessment-target',
+      dimensionValue: target.targetName,
+      sourcePriority: ['instrument'],
+    }, 'push');
+  }, [assessmentYearMap, commitDrillContext]);
+
+  const closeVehiclePanel = useCallback(() => {
+    setViewAllTargetId(null);
+    setViewAllSearch('');
+    if (drillContext.level === 'breakdown') {
+      commitDrillContext({
+        level: 'overview',
+        targetId: selectedTargetId || undefined,
+        assessmentYear: selectedAssessmentYear,
+        sourcePriority: ['instrument'],
+      }, 'replace');
+    }
+  }, [commitDrillContext, drillContext.level, selectedAssessmentYear, selectedTargetId]);
+
+  const openVehicleDiagnostic = useCallback((vehicle: TargetVehicle) => {
+    const url = buildMileageDrillUrl(
+      { pathname: window.location.pathname, search: window.location.search, hash: '#mileage' },
+      {
+        level: 'vehicle',
+        targetId: viewAllTargetId || selectedTargetId || undefined,
+        assessmentYear: selectedAssessmentYear,
+        plate: vehicle.plateNumber,
+        startDate: viewAllDate,
+        endDate: viewAllDate,
+        sourcePriority: ['instrument'],
+      },
+    );
+    window.history.pushState(null, '', url);
+    window.dispatchEvent(new HashChangeEvent('hashchange'));
+  }, [selectedAssessmentYear, selectedTargetId, viewAllDate, viewAllTargetId]);
+
+  // Load targets on mount and through the shared retry path.
   useEffect(() => {
+    let cancelled = false;
+    setTargetsLoading(true);
+    setTargetsError(null);
     fetchTargets().then(data => {
+      if (cancelled) return;
+      const initialContext = initialDrillContextRef.current;
       const focused = data.find(item => item.targetName.includes('羚牛136')) || data[0];
       const ordered = focused
         ? [focused, ...data.filter(item => item.id !== focused.id)]
         : data;
       setTargets(ordered);
-      if (ordered.length > 0 && !selectedTargetId) {
-        setSelectedTargetId(focused.id);
-        setExpandedTargetId(focused.id);
-        setAssessmentYearMap(Object.fromEntries(ordered.map(item => [item.id, item.yearlyAssessments[0]?.yearNumber || 1])));
-        fetchTargetVehicles(focused.id).then(vehicles => {
-          setTargetVehiclesMap(prev => ({ ...prev, [focused.id]: vehicles }));
-        }).catch(() => {});
+      const initialTarget = ordered.find(item => item.id === selectedTargetId) || focused;
+      if (initialTarget) {
+        setSelectedTargetId(initialTarget.id);
+        setExpandedTargetId(initialTarget.id);
+        const initialYears = Object.fromEntries(ordered.map(item => [
+          item.id,
+          resolveAssessmentYear(item, item.id === initialContext.targetId ? initialContext.assessmentYear : undefined) || 1,
+        ]));
+        setAssessmentYearMap(initialYears);
+
+        if (initialContext.targetId === initialTarget.id) {
+          const resolvedYear = initialYears[initialTarget.id];
+          if (resolvedYear && resolvedYear !== initialContext.assessmentYear) {
+            const normalizedContext = { ...initialContext, assessmentYear: resolvedYear };
+            window.history.replaceState(null, '', buildMileageDrillUrl(window.location, normalizedContext));
+            setDrillContext(normalizedContext);
+          }
+        }
+      } else {
+        setSelectedTargetId(null);
+        setExpandedTargetId(null);
+        setAssessmentYearMap({});
       }
-    }).catch(() => {});
-  }, []);
+    }).catch(error => {
+      if (!cancelled) {
+        setTargetsError(getRequestErrorMessage(error, '无法获取考核目标数据，请检查服务连接后重试。'));
+      }
+    }).finally(() => {
+      if (!cancelled) setTargetsLoading(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [targetsRequestVersion]);
 
   // Load trend when selectedTargetId changes
   useEffect(() => {
-    if (selectedTargetId === null) return;
+    if (selectedTargetId === null) {
+      setTrendData([]);
+      setTrendError(null);
+      setTrendLoading(false);
+      return;
+    }
+    let cancelled = false;
     setExpandedTargetId(selectedTargetId);
     if (!targetVehiclesMap[selectedTargetId]) {
-      fetchTargetVehicles(selectedTargetId).then(vehicles => {
-        setTargetVehiclesMap(prev => ({ ...prev, [selectedTargetId]: vehicles }));
-      }).catch(() => {});
+      loadCurrentTargetVehicles(selectedTargetId);
     }
-    fetchTrend(selectedTargetId).then(setTrendData).catch(() => setTrendData([]));
-  }, [selectedTargetId]);
+    setTrendLoading(true);
+    setTrendError(null);
+    fetchTrend(selectedTargetId).then(data => {
+      if (!cancelled) setTrendData(data);
+    }).catch(error => {
+      if (!cancelled) {
+        setTrendData([]);
+        setTrendError(getRequestErrorMessage(error, '无法获取里程趋势，请稍后重试。'));
+      }
+    }).finally(() => {
+      if (!cancelled) setTrendLoading(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [selectedTargetId, trendRequestVersion]);
 
   // Re-fetch target vehicles when viewAllDate changes
   useEffect(() => {
     if (viewAllTargetId === null) return;
+    let cancelled = false;
     setViewAllLoading(true);
+    setViewAllError(null);
     fetchTargetVehicles(viewAllTargetId, viewAllDate).then(data => {
-      setTargetVehiclesMap(prev => ({ ...prev, [viewAllTargetId]: data }));
-    }).catch(() => {}).finally(() => setViewAllLoading(false));
-  }, [viewAllTargetId, viewAllDate]);
+      if (cancelled) return;
+      setViewAllHistoricalVehicles(data);
+      setViewAllLoadedDate(viewAllDate);
+      setViewAllLoadedTargetId(viewAllTargetId);
+    }).catch(error => {
+      if (!cancelled) {
+        setViewAllError(getRequestErrorMessage(error, '无法获取所选日期的车辆明细，请稍后重试。'));
+      }
+    }).finally(() => {
+      if (!cancelled) setViewAllLoading(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [viewAllTargetId, viewAllDate, viewAllRequestVersion]);
+
+  useEffect(() => {
+    const handlePopState = () => {
+      const next = parseMileageDrillContext(window.location.search);
+      setDrillContext(next);
+      if (next.targetId) {
+        setSelectedTargetId(next.targetId);
+        const target = targets.find(item => item.id === next.targetId);
+        const resolvedYear = target ? resolveAssessmentYear(target, next.assessmentYear) : undefined;
+        if (resolvedYear) {
+          setAssessmentYearMap(prev => ({ ...prev, [next.targetId!]: resolvedYear }));
+        }
+      }
+      if (next.level === 'breakdown' && next.targetId && next.dimensionValue) {
+        setAttributionDimension(next.dimension === 'customer' ? 'customer' : 'department');
+        setViewAllTargetId(next.targetId);
+      } else {
+        setViewAllTargetId(null);
+      }
+    };
+    window.addEventListener('popstate', handlePopState);
+    return () => window.removeEventListener('popstate', handlePopState);
+  }, [targets]);
+
+  const hasViewAllSnapshot = viewAllHistoricalVehicles !== null
+    && viewAllLoadedTargetId === viewAllTargetId;
+  const viewAllVehicles = useMemo(() => {
+    const vehicles = hasViewAllSnapshot ? viewAllHistoricalVehicles : [];
+    if (
+      drillContext.level === 'breakdown'
+      && drillContext.dimensionValue
+      && (drillContext.dimension === 'department' || drillContext.dimension === 'customer')
+    ) {
+      return filterAttributionVehicles(vehicles, drillContext.dimension, drillContext.dimensionValue);
+    }
+    return vehicles;
+  }, [drillContext, hasViewAllSnapshot, viewAllHistoricalVehicles]);
+
+  const searchedViewAllVehicles = useMemo(() => (
+    viewAllVehicles.filter(vehicle => (
+      vehicle.plateNumber.toLowerCase().includes(viewAllSearch.toLowerCase())
+    ))
+  ), [viewAllSearch, viewAllVehicles]);
+
+  if (targetsLoading && targets.length === 0) {
+    return <LoadingState label="正在加载考核统计" />;
+  }
+
+  if (targetsError && targets.length === 0) {
+    return (
+      <ErrorState
+        title="考核统计加载失败"
+        message={targetsError}
+        onRetry={retryTargets}
+        retrying={targetsLoading}
+      />
+    );
+  }
+
+  if (!targetsLoading && targets.length === 0) {
+    return (
+      <EmptyState
+        title="暂无考核目标"
+        description="当前权限范围内没有有效考核目标"
+      />
+    );
+  }
 
   return (
     <div className="space-y-2 pb-2 landscape:pb-4 landscape:h-full landscape:overflow-hidden landscape:flex landscape:flex-col flex-none landscape:flex-1 [overflow-anchor:none]" style={{ overflowX: 'clip' }}>
@@ -135,10 +440,7 @@ export default function StatisticsView() {
         {targets.map(target => (
           <button
             key={target.id}
-            onClick={() => {
-              setSelectedTargetId(target.id);
-              setExpandedTargetId(target.id);
-            }}
+            onClick={() => selectTarget(target.id)}
             className={`px-4 py-2 rounded-xl text-xs font-bold transition-all whitespace-nowrap ${
               selectedTargetId === target.id
                 ? 'bg-blue-600 text-white shadow-md shadow-blue-200'
@@ -150,6 +452,16 @@ export default function StatisticsView() {
         ))}
       </div>
 
+      {targetsError && (
+        <ErrorState
+          title="考核统计刷新失败"
+          message={`${targetsError} 当前仍展示上一次成功加载的数据。`}
+          onRetry={retryTargets}
+          retrying={targetsLoading}
+          variant="inline"
+        />
+      )}
+
       {selectedTarget && (
         <motion.div
           initial={{ opacity: 0, y: 8 }}
@@ -181,14 +493,48 @@ export default function StatisticsView() {
           </div>
           <div className="rounded-2xl border border-slate-100 bg-white p-3 shadow-sm">
             <div className="text-[10px] font-black uppercase tracking-wide text-slate-400">最新日变化</div>
-            <div className={`mt-1 text-lg font-black ${trendDelta >= 0 ? 'text-emerald-600' : 'text-rose-600'}`}>
-              {trendDelta >= 0 ? '+' : ''}{fmtKm(trendDelta)}
+            <div className={`mt-1 text-lg font-black ${trendLoading || trendError ? 'text-slate-500' : trendDelta >= 0 ? 'text-emerald-600' : 'text-rose-600'}`}>
+              {trendLoading ? '加载中' : trendError ? '暂不可用' : `${trendDelta >= 0 ? '+' : ''}${fmtKm(trendDelta)}`}
             </div>
             <div className="mt-1 text-[10px] font-bold text-slate-400">达标率 {fmtPercent(selectedQualifiedRate)}</div>
           </div>
         </motion.div>
       )}
 
+      {selectedTarget && selectedCoverage && selectedCoverage.status !== 'matched' && (
+        <div role="alert" className="flex items-start gap-2 rounded-xl border border-amber-200 bg-amber-50 px-3 py-2 text-amber-900">
+          <AlertTriangle size={15} className="mt-0.5 shrink-0 text-amber-600" />
+          <div className="min-w-0 text-[11px] font-bold leading-5">
+            <span className="font-black">考核车辆配置不一致：</span>
+            目标 {selectedCoverage.declaredCount} 台，当前有效 {selectedCoverage.activeCount} 台，
+            {selectedCoverage.status === 'missing'
+              ? `缺少 ${Math.abs(selectedCoverage.difference)} 台`
+              : `超出 ${selectedCoverage.difference} 台`}。
+            完成率、缺口和归因按当前有效车辆计算。
+          </div>
+        </div>
+      )}
+
+      {selectedTarget && (
+        <MileageAttributionView
+          vehicles={selectedTargetVehicles}
+          dimension={attributionDimension}
+          selectedValue={selectedBreakdownValue}
+          loading={targetVehicleLoadingMap[selectedTarget.id]
+            || (!targetVehiclesMap[selectedTarget.id] && !targetVehicleErrorMap[selectedTarget.id])}
+          error={targetVehicleErrorMap[selectedTarget.id]}
+          targetMileagePerVehicle={selectedTarget.annualMileagePerVehicle * (selectedAssessmentYear || 1)}
+          expectedShortfallMileage={selectedAssessment?.remaining}
+          assessmentLabel={selectedAssessment?.label}
+          onDimensionChange={(dimension) => {
+            setAttributionDimension(dimension);
+            if (drillContext.level === 'breakdown') closeVehiclePanel();
+          }}
+          onSelect={openAttributionGroup}
+          onRetry={() => loadCurrentTargetVehicles(selectedTarget.id)}
+        />
+      )}
+
       <div className="flex flex-col landscape:flex-row gap-4 flex-1 landscape:overflow-hidden">
         {/* Left Side: Trend Chart / Dashboard Sidebar */}
         <div className="flex-none landscape:flex-1 landscape:w-2/3 space-y-4 flex flex-col overflow-y-auto no-scrollbar min-w-0">
@@ -250,6 +596,13 @@ export default function StatisticsView() {
               </div>
             </div>
             <div className="h-[280px] w-full min-w-0">
+              {trendLoading ? (
+                <LoadingState label="正在加载里程趋势" variant="inline" />
+              ) : trendError ? (
+                <ErrorState message={trendError} onRetry={retryTrend} variant="inline" />
+              ) : trendData.length === 0 ? (
+                <EmptyState title="暂无趋势数据" description="当前考核目标在最近 7 天没有可用里程" variant="inline" />
+              ) : (
                 <ResponsiveContainer width="100%" height={280} minWidth={0}>
                 {chartType === 'bar' ? (
                   <BarChart data={trendData} margin={{ top: 20, right: 10, left: 0, bottom: 0 }}>
@@ -292,6 +645,7 @@ export default function StatisticsView() {
                   </AreaChart>
                 )}
                 </ResponsiveContainer>
+              )}
             </div>
           </div>
         </div>
@@ -327,11 +681,6 @@ export default function StatisticsView() {
                 className="bg-white px-3 py-2 rounded-xl border border-slate-100 shadow-sm flex flex-col active:bg-slate-50 transition-all cursor-pointer"
                 onClick={() => {
                   setExpandedTargetId(target.id);
-                  if (!targetVehiclesMap[target.id]) {
-                    fetchTargetVehicles(target.id).then(data => {
-                      setTargetVehiclesMap(prev => ({ ...prev, [target.id]: data }));
-                    }).catch(() => {});
-                  }
                 }}
               >
                 <div className="flex items-center justify-between">
@@ -391,7 +740,13 @@ export default function StatisticsView() {
                             onClick={(e) => e.stopPropagation()}
                             onChange={(e) => {
                               e.stopPropagation();
-                              setAssessmentYearMap(prev => ({ ...prev, [target.id]: Number(e.target.value) }));
+                              const assessmentYear = Number(e.target.value);
+                              setAssessmentYearMap(prev => ({ ...prev, [target.id]: assessmentYear }));
+                              commitDrillContext({
+                                ...drillContext,
+                                targetId: target.id,
+                                assessmentYear,
+                              }, 'replace');
                             }}
                             className="bg-white border border-blue-100 rounded-lg px-2 py-1 text-[10px] font-bold text-blue-700 outline-none"
                           >
@@ -441,7 +796,7 @@ export default function StatisticsView() {
                               <p className="text-[8px] font-bold text-slate-400 uppercase tracking-wider">{assessment.label}已完成</p>
                               <p className="text-[10px] font-black text-emerald-600">{fmtKm(assessment.completed)} km</p>
                               <p className="text-[8px] font-bold text-slate-300">
-                                数据截至 {assessment.daysLeft === 0 ? fmtDateLabel(assessment.endDate) : currentDateLabel}
+                                数据截至 {formatMileageSnapshotDateTime(target.snapshotUpdatedAt)}
                               </p>
                             </div>
                             <div className="space-y-0.5">
@@ -480,9 +835,7 @@ export default function StatisticsView() {
                             <button
                               onClick={(e) => {
                                 e.stopPropagation();
-                                setViewAllTargetId(target.id);
-                                setViewAllTargetName(target.targetName);
-                                setViewAllDate(getDefaultDate());
+                                openTargetVehicles(target);
                               }}
                               className="text-[8px] text-blue-500 font-bold hover:underline"
                             >
@@ -541,15 +894,19 @@ export default function StatisticsView() {
                   <span className="text-slate-700">|</span>
                   <span className="text-slate-500">车辆 <span className="text-white font-black">{targets.reduce((sum, t) => sum + t.vehicleCount, 0)}</span> 台</span>
                   <span className="text-slate-700">|</span>
-                  <span className="text-slate-500">所选年度完成率 <span className="text-white font-black">{targets.length > 0 ? (targets.reduce((sum, t) => sum + (getTargetAssessment(t, assessmentYearMap[t.id])?.completionRate ?? t.avgCompletion), 0) / targets.length).toFixed(1) : '0.0'}</span> <span className="text-blue-400">%</span></span>
+                  <span className="text-slate-500">所选年度完成率 <span className="text-white font-black">{selectedYearCompletionRate.toFixed(1)}</span> <span className="text-blue-400">%</span></span>
                 </div>
               </div>
               <div className="flex items-center gap-2">
                 <button
-                  onClick={() => { fetchTargets().then(data => { setTargets(data); }).catch(() => {}); }}
+                  type="button"
+                  onClick={retryTargets}
+                  disabled={targetsLoading}
+                  title="刷新考核统计"
+                  aria-label="刷新考核统计"
                   className="p-1.5 text-slate-500 hover:text-blue-400 transition-colors"
                 >
-                  <RotateCcw size={13} />
+                  <RotateCcw size={13} className={targetsLoading ? 'animate-spin' : ''} />
                 </button>
                 <button
                   onClick={() => setIsTableFullscreen(false)}
@@ -560,6 +917,15 @@ export default function StatisticsView() {
               </div>
             </div>
 
+            {targetsError && (
+              <div role="alert" className="flex items-center justify-between gap-3 border-b border-rose-900/50 bg-rose-950/60 px-3 py-2 text-[10px] font-bold text-rose-200">
+                <span>{targetsError} 当前仍展示上一次成功加载的数据。</span>
+                <button type="button" onClick={retryTargets} disabled={targetsLoading} className="shrink-0 text-rose-100 underline disabled:opacity-60">
+                  重试
+                </button>
+              </div>
+            )}
+
             {/* Table Area */}
             <div className="flex-1 overflow-auto">
               <table className="w-full text-left border-collapse">
@@ -643,7 +1009,7 @@ export default function StatisticsView() {
               initial={{ opacity: 0 }}
               animate={{ opacity: 1 }}
               exit={{ opacity: 0 }}
-              onClick={() => setViewAllTargetId(null)}
+              onClick={closeVehiclePanel}
               className="fixed inset-0 z-[110] bg-slate-950/60 backdrop-blur-sm"
             />
             <motion.div
@@ -655,21 +1021,25 @@ export default function StatisticsView() {
             >
               <div className="p-6 border-b border-slate-100 flex items-center justify-between">
                 <div>
-                  <h3 className="text-lg font-black text-slate-900">{viewAllTargetName}</h3>
-                  <p className="text-xs font-bold text-slate-400 uppercase tracking-widest mt-1">车辆实时明细清单</p>
+                  <h3 className="text-lg font-black text-slate-900">
+                    {viewAllTargetName || selectedTarget?.targetName || '考核车辆'}
+                  </h3>
+                  <p className="mt-1 text-xs font-bold uppercase tracking-widest text-slate-400">
+                    {selectedAssessment ? `${selectedAssessment.label} · ` : ''}车辆日期明细清单
+                  </p>
+                  {selectedBreakdownValue && drillContext.dimension !== 'assessment-target' && (
+                    <p className="mt-1 text-[10px] font-bold text-blue-600">{selectedBreakdownValue}</p>
+                  )}
                 </div>
                 <button
-                  onClick={() => {
-                    setViewAllTargetId(null);
-                    setViewAllSearch('');
-                  }}
+                  onClick={closeVehiclePanel}
                   className="p-2 hover:bg-slate-100 rounded-full transition-colors text-slate-400 hover:text-slate-900"
                 >
                   <X size={20} />
                 </button>
               </div>
 
-              <div className="px-6 py-3 border-b border-slate-50 space-y-2">
+              <div className="px-4 py-3 border-b border-slate-50 space-y-2 md:px-6">
                 <div className="flex items-center gap-2">
                   <div className="relative flex-1">
                     <Search className="absolute left-3 top-1/2 -translate-y-1/2 text-slate-400" size={14} />
@@ -687,17 +1057,27 @@ export default function StatisticsView() {
                       type="date"
                       value={viewAllDate}
                       onChange={(e) => setViewAllDate(e.target.value)}
-                      className="pl-8 pr-2 py-2 bg-slate-50 border border-slate-100 rounded-xl text-xs font-bold text-slate-700 focus:outline-none focus:ring-2 focus:ring-blue-500/20 focus:border-blue-500 transition-all w-[130px]"
+                      className="w-[145px] bg-slate-50 py-2 pl-8 pr-2 text-xs font-bold text-slate-700 border border-slate-100 rounded-xl focus:outline-none focus:ring-2 focus:ring-blue-500/20 focus:border-blue-500 transition-all"
                     />
                   </div>
                 </div>
                 <div className="flex items-center justify-between">
                   <span className="text-[10px] font-bold text-slate-400 uppercase tracking-wider">
-                    {viewAllLoading ? '加载中...' : (() => {
-                      const filtered = (viewAllTargetId !== null ? (targetVehiclesMap[viewAllTargetId] || []) : []).filter(tv => tv.plateNumber.toLowerCase().includes(viewAllSearch.toLowerCase()));
-                      const totalKm = filtered.reduce((sum, tv) => sum + (tv.todayMileage || 0), 0);
-                      return `${filtered.length} 辆 · 合计 ${fmtKm(totalKm)} km`;
-                    })()}
+                    {viewAllLoading
+                      ? hasViewAllSnapshot
+                        ? `正在加载 ${viewAllDate} · 当前显示 ${viewAllLoadedDate}`
+                        : `正在加载 ${viewAllDate}`
+                      : viewAllError
+                        ? hasViewAllSnapshot
+                          ? `当前显示 ${viewAllLoadedDate} 已成功数据`
+                          : `${viewAllDate} 暂不可用`
+                        : (() => {
+                            const totalKm = searchedViewAllVehicles.reduce(
+                              (sum, vehicle) => sum + (vehicle.todayMileage || 0),
+                              0,
+                            );
+                            return `${viewAllLoadedDate || viewAllDate} · ${searchedViewAllVehicles.length} 辆 · 合计 ${fmtKm(totalKm)} km`;
+                          })()}
                   </span>
                   <button
                     onClick={() => setViewAllSort(prev => prev === 'desc' ? 'asc' : 'desc')}
@@ -710,45 +1090,78 @@ export default function StatisticsView() {
               </div>
 
               <div className="flex-1 overflow-y-auto p-4 space-y-2 no-scrollbar">
-                {(viewAllTargetId !== null ? (targetVehiclesMap[viewAllTargetId] || []) : []).filter(tv =>
-                  tv.plateNumber.toLowerCase().includes(viewAllSearch.toLowerCase())
-                ).sort((a, b) => {
-                  const valA = a.todayMileage || 0;
-                  const valB = b.todayMileage || 0;
-                  return viewAllSort === 'desc' ? valB - valA : valA - valB;
-                }).map(tv => (
-                  <div key={tv.plateNumber} className="bg-white px-3 py-2 rounded-xl border border-slate-50 shadow-sm flex items-center justify-between hover:border-blue-200 transition-all">
-                    <div className="flex items-center gap-3 overflow-hidden flex-1">
-                      <div className="relative flex-shrink-0">
-                        <div className="w-8 h-8 rounded-lg bg-slate-50 flex items-center justify-center">
-                          <Truck size={14} className="text-slate-400" />
+                {viewAllLoading && !hasViewAllSnapshot ? (
+                  <LoadingState label={`正在加载 ${viewAllDate} 车辆明细`} variant="inline" />
+                ) : viewAllError && !hasViewAllSnapshot ? (
+                  <ErrorState
+                    title="车辆明细加载失败"
+                    message={viewAllError}
+                    onRetry={retryViewAllVehicles}
+                    retrying={viewAllLoading}
+                    variant="inline"
+                  />
+                ) : (
+                  <>
+                    {viewAllError && (
+                      <ErrorState
+                        title={`${viewAllDate} 车辆明细刷新失败`}
+                        message={`${viewAllError} 当前保留 ${viewAllLoadedDate} 已成功加载的数据。`}
+                        onRetry={retryViewAllVehicles}
+                        retrying={viewAllLoading}
+                        variant="inline"
+                      />
+                    )}
+                    {!viewAllLoading && !viewAllError && searchedViewAllVehicles.length === 0 ? (
+                      <EmptyState
+                        title={viewAllHistoricalVehicles?.length ? '没有匹配车辆' : '该日期暂无车辆里程'}
+                        description={viewAllHistoricalVehicles?.length ? '请调整车牌搜索条件' : `${viewAllLoadedDate || viewAllDate} 未返回可展示的车辆数据`}
+                        variant="inline"
+                      />
+                    ) : null}
+                    {[...searchedViewAllVehicles].sort((a, b) => {
+                      const valA = a.todayMileage || 0;
+                      const valB = b.todayMileage || 0;
+                      return viewAllSort === 'desc' ? valB - valA : valA - valB;
+                    }).map(tv => (
+                      <button
+                        type="button"
+                        key={tv.plateNumber}
+                        onClick={() => openVehicleDiagnostic(tv)}
+                        className="flex w-full items-center justify-between rounded-xl border border-slate-100 bg-white px-3 py-2 text-left shadow-sm transition-all hover:border-blue-200 hover:shadow-md"
+                      >
+                        <div className="flex items-center gap-3 overflow-hidden flex-1">
+                          <div className="relative flex-shrink-0">
+                            <div className="w-8 h-8 rounded-lg bg-slate-50 flex items-center justify-center">
+                              <Truck size={14} className="text-slate-400" />
+                            </div>
+                            <div className={`absolute -bottom-0.5 -right-0.5 w-2.5 h-2.5 rounded-full border-2 border-white ${tv.isOnline ? 'bg-green-500' : 'bg-slate-300'}`} />
+                          </div>
+                          <div className="overflow-hidden flex-1">
+                            <div className="flex items-center gap-1.5">
+                              <span className="text-xs font-black text-slate-900 font-mono"><Blur>{tv.plateNumber}</Blur></span>
+                              <span className={`text-[8px] px-1 rounded ${tv.isOnline ? 'bg-green-50 text-green-600' : 'bg-slate-100 text-slate-400'} font-bold`}>
+                                {tv.isOnline ? '在线' : '离线'}
+                              </span>
+                            </div>
+                            <div className="flex items-center gap-1.5">
+                              <span className="text-[8px] text-slate-300 font-bold">{tv.rentStatus || ''}{tv.department ? ` · ${tv.department.replace('业务', '')}` : ''}</span>
+                              <span className="text-[9px] font-bold text-slate-600 truncate">{tv.customer || '-'}</span>
+                            </div>
+                          </div>
                         </div>
-                        <div className={`absolute -bottom-0.5 -right-0.5 w-2.5 h-2.5 rounded-full border-2 border-white ${tv.isOnline ? 'bg-green-500' : 'bg-slate-300'}`} />
-                      </div>
-                      <div className="overflow-hidden flex-1">
-                        <div className="flex items-center gap-1.5">
-                          <span className="text-xs font-black text-slate-900 font-mono"><Blur>{tv.plateNumber}</Blur></span>
-                          <span className={`text-[8px] px-1 rounded ${tv.isOnline ? 'bg-green-50 text-green-600' : 'bg-slate-100 text-slate-400'} font-bold`}>
-                            {tv.isOnline ? '在线' : '离线'}
-                          </span>
+                        <div className="text-right flex-shrink-0 ml-2">
+                          <div className="text-sm font-black text-blue-600">{tv.todayMileage.toLocaleString()} <span className="text-[8px] text-slate-400">KM</span></div>
+                          <div className="text-[9px] font-bold text-slate-300 mt-0.5">累计: {fmtKm(tv.totalMileage || 0)} km</div>
                         </div>
-                        <div className="flex items-center gap-1.5">
-                          <span className="text-[8px] text-slate-300 font-bold">{tv.rentStatus || ''}{tv.department ? ` · ${tv.department.replace('业务', '')}` : ''}</span>
-                          <span className="text-[9px] font-bold text-slate-600 truncate">{tv.customer || '-'}</span>
-                        </div>
-                      </div>
-                    </div>
-                    <div className="text-right flex-shrink-0 ml-2">
-                      <div className="text-sm font-black text-blue-600">{tv.todayMileage.toLocaleString()} <span className="text-[8px] text-slate-400">KM</span></div>
-                      <div className="text-[9px] font-bold text-slate-300 mt-0.5">累计: {fmtKm(tv.totalMileage || 0)} km</div>
-                    </div>
-                  </div>
-                ))}
+                      </button>
+                    ))}
+                  </>
+                )}
               </div>
 
               <div className="p-4 bg-slate-50 border-t border-slate-100">
                 <button
-                  onClick={() => setViewAllTargetId(null)}
+                  onClick={closeVehiclePanel}
                   className="w-full py-3 bg-slate-900 text-white rounded-xl text-sm font-bold shadow-lg shadow-slate-200 active:scale-[0.98] transition-all"
                 >
                   关闭明细

src/modules/mileage/VehicleDetailModal.tsx

@@ -1,85 +1,112 @@
 import { useEffect, useMemo, useState } from 'react';
 import { motion, AnimatePresence, useDragControls } from 'motion/react';
-import { X, Truck } from 'lucide-react';
+import { RefreshCw, X, Truck } from 'lucide-react';
 import {
   BarChart, Bar, XAxis, YAxis, ResponsiveContainer, Tooltip, Cell,
 } from 'recharts';
-import type { MonitoringVehicle } from './types';
+import type { MileageSourceGroup, MonitoringVehicle } from './types';
 import { fetchVehicleRecent, type VehicleRecentDay } from './api';
 import Blur from '../../components/Blur';
+import { EmptyState, ErrorState } from '../../components/ui/surface';
+import {
+  includeCurrentDayInVehicleDetail,
+  normalizeVehicleDetailContext,
+  resolveVehicleDetailRange,
+  vehicleDetailContextLabel,
+  type VehicleDetailRangeKey,
+} from './vehicle-detail-range';
 
 interface Props {
   vehicle: MonitoringVehicle | null;
   onClose: () => void;
+  sourcePriority: MileageSourceGroup[];
+  initialStartDate?: string;
+  initialEndDate?: string;
 }
 
-type RangeKey = 'last15' | 'month' | 'quarter';
-
-const RANGE_TABS: { key: RangeKey; label: string }[] = [
+const RANGE_TABS: { key: VehicleDetailRangeKey; label: string }[] = [
   { key: 'last15', label: '近 15 天' },
   { key: 'month', label: '本月' },
   { key: 'quarter', label: '本季度' },
 ];
 
-function fmtYmd(d: Date): string {
-  const y = d.getFullYear();
-  const m = String(d.getMonth() + 1).padStart(2, '0');
-  const dd = String(d.getDate()).padStart(2, '0');
-  return `${y}-${m}-${dd}`;
-}
-
-function rangeFor(key: RangeKey): { start: string; end: string; rangeLabel: string } {
-  const today = new Date();
-  today.setHours(0, 0, 0, 0);
-  const end = fmtYmd(today);
-  if (key === 'last15') {
-    const start = new Date(today);
-    start.setDate(today.getDate() - 14);
-    return { start: fmtYmd(start), end, rangeLabel: '近 15 天' };
-  }
-  if (key === 'month') {
-    const start = new Date(today.getFullYear(), today.getMonth(), 1);
-    return { start: fmtYmd(start), end, rangeLabel: '本月' };
-  }
-  const q = Math.floor(today.getMonth() / 3);
-  const start = new Date(today.getFullYear(), q * 3, 1);
-  return { start: fmtYmd(start), end, rangeLabel: '本季度' };
-}
-
 function isToday(date: string): boolean {
-  return date === fmtYmd(new Date());
+  const now = new Date();
+  const today = `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-${String(now.getDate()).padStart(2, '0')}`;
+  return date === today;
 }
 
-function formatLabel(date: string, key: RangeKey): string {
+function formatLabel(date: string, key: VehicleDetailRangeKey): string {
   // YYYY-MM-DD → MM-DD（季度时仍展示 MM-DD）
   void key;
   return date.slice(5);
 }
 
-export default function VehicleDetailModal({ vehicle, onClose }: Props) {
-  const [days, setDays] = useState<VehicleRecentDay[]>([]);
-  const [loading, setLoading] = useState(false);
-  const [range, setRange] = useState<RangeKey>('last15');
-  const dragControls = useDragControls();
+function daySourceLabel(day: VehicleRecentDay): string {
+  if (day.sourceCategory === 'INSTRUMENT') return '仪表数据';
+  if (day.sourceCategory === 'GPS') return 'GPS数据';
+  return day.isDataSynced ? '来源待接口' : '无数据';
+}
 
-  // 切换车辆时重置区间为默认
-  useEffect(() => {
-    if (vehicle) setRange('last15');
-  }, [vehicle?.plate]); // eslint-disable-line react-hooks/exhaustive-deps
+export default function VehicleDetailModal({
+  vehicle,
+  onClose,
+  sourcePriority,
+  initialStartDate,
+  initialEndDate,
+}: Props) {
+  const contextRange = useMemo(
+    () => normalizeVehicleDetailContext(initialStartDate, initialEndDate),
+    [initialEndDate, initialStartDate],
+  );
+  const [days, setDays] = useState<VehicleRecentDay[]>([]);
+  const [loadedRequestKey, setLoadedRequestKey] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [requestVersion, setRequestVersion] = useState(0);
+  const [range, setRange] = useState<VehicleDetailRangeKey>(() => (
+    contextRange ? 'context' : 'last15'
+  ));
+  const dragControls = useDragControls();
+  const resolvedRange = useMemo(
+    () => resolveVehicleDetailRange(range, contextRange),
+    [contextRange, range],
+  );
+  const sourceKey = sourcePriority.join(',');
+  const requestKey = vehicle
+    ? `${vehicle.plate}|${resolvedRange.start}|${resolvedRange.end}|${sourceKey}`
+    : null;
+  const hasSnapshot = requestKey !== null && loadedRequestKey === requestKey;
+  const rangeTabs = useMemo(() => (
+    contextRange
+      ? [{ key: 'context' as const, label: vehicleDetailContextLabel(contextRange) }, ...RANGE_TABS]
+      : RANGE_TABS
+  ), [contextRange]);
 
   // 拉取数据（车辆或区间变化）
   useEffect(() => {
-    if (!vehicle) return;
-    const { start, end } = rangeFor(range);
+    if (!vehicle || !requestKey) return;
     setLoading(true);
-    setDays([]);
+    setError(null);
     let cancelled = false;
-    fetchVehicleRecent(vehicle.plate, { start, end })
-      .then(d => { if (!cancelled) setDays(d.days); })
-      .catch(() => { if (!cancelled) setDays([]); })
+    fetchVehicleRecent(vehicle.plate, {
+      start: resolvedRange.start,
+      end: resolvedRange.end,
+      sourcePriority,
+    })
+      .then(d => {
+        if (cancelled) return;
+        setDays(d.days);
+        setLoadedRequestKey(requestKey);
+      })
+      .catch(cause => {
+        if (!cancelled) {
+          setError(cause instanceof Error ? cause.message : '车辆近期里程加载失败，请稍后重试。');
+        }
+      })
       .finally(() => { if (!cancelled) setLoading(false); });
     return () => { cancelled = true; };
-  }, [vehicle?.plate, range]); // eslint-disable-line react-hooks/exhaustive-deps
+  }, [requestKey, requestVersion]); // eslint-disable-line react-hooks/exhaustive-deps
 
   // 锁滚动
   useEffect(() => {
@@ -88,8 +115,11 @@ export default function VehicleDetailModal({ vehicle, onClose }: Props) {
     return () => { document.body.style.overflow = ''; };
   }, [vehicle]);
 
-  // 排除"今日"列（数据未到位时易引起误读）
-  const historyDays = useMemo(() => days.filter(d => !isToday(d.date)), [days]);
+  // 预设区间排除未完整的今日；显式下钻区间严格保留用户选择的日期。
+  const historyDays = useMemo(() => {
+    if (!hasSnapshot) return [];
+    return includeCurrentDayInVehicleDetail(range) ? days : days.filter(d => !isToday(d.date));
+  }, [days, hasSnapshot, range]);
   const stats = useMemo(() => {
     const totalKm = historyDays.reduce((s, d) => s + d.dailyKm, 0);
     const synced = historyDays.filter(d => d.isDataSynced).length;
@@ -100,12 +130,12 @@ export default function VehicleDetailModal({ vehicle, onClose }: Props) {
 
   // 骨架天数：根据区间预估
   const skeletonCount = useMemo(() => {
-    if (range === 'last15') return 15;
-    const { start, end } = rangeFor(range);
-    const s = new Date(start);
-    const e = new Date(end);
-    return Math.max(1, Math.round((e.getTime() - s.getTime()) / 86400000));
-  }, [range]);
+    const start = new Date(`${resolvedRange.start}T00:00:00`);
+    const end = new Date(`${resolvedRange.end}T00:00:00`);
+    return Math.max(1, Math.round((end.getTime() - start.getTime()) / 86400000) + 1);
+  }, [resolvedRange.end, resolvedRange.start]);
+  const showInitialLoading = loading && !hasSnapshot;
+  const showUnavailable = !!error && !hasSnapshot;
 
   return (
     <AnimatePresence>
@@ -135,6 +165,9 @@ export default function VehicleDetailModal({ vehicle, onClose }: Props) {
             }}
             className="bg-white w-full md:max-w-md md:rounded-3xl rounded-t-3xl shadow-2xl max-h-[92vh] overflow-hidden flex flex-col touch-pan-y"
             onClick={(e) => e.stopPropagation()}
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="vehicle-detail-title"
           >
             {/* iOS 风格 drag handle —— 长按下滑可关闭 */}
             <div
@@ -153,7 +186,7 @@ export default function VehicleDetailModal({ vehicle, onClose }: Props) {
                 </div>
                 <div className="min-w-0">
                   <div className="flex items-center gap-1.5">
-                    <span className="text-sm font-black text-slate-900 font-mono truncate"><Blur>{vehicle.plate}</Blur></span>
+                    <span id="vehicle-detail-title" className="text-sm font-black text-slate-900 font-mono truncate"><Blur>{vehicle.plate}</Blur></span>
                     <span className={`text-[8px] px-1 rounded font-bold ${vehicle.isOnline ? 'bg-green-50 text-green-600' : 'bg-slate-100 text-slate-400'}`}>
                       {vehicle.isOnline ? '在线' : '离线'}
                     </span>
@@ -166,19 +199,22 @@ export default function VehicleDetailModal({ vehicle, onClose }: Props) {
                   </div>
                 </div>
               </div>
-              <button onClick={onClose} className="p-2 -mr-1 text-slate-400 hover:text-slate-700 flex-shrink-0">
+              <button type="button" onClick={onClose} aria-label="关闭车辆详情" className="p-2 -mr-1 text-slate-400 hover:text-slate-700 flex-shrink-0">
                 <X size={18} />
               </button>
             </div>
 
             {/* 时间范围切换 */}
             <div className="px-4 pt-3">
-              <div className="relative inline-flex bg-slate-100 p-0.5 rounded-lg">
-                {RANGE_TABS.map(tab => (
+              <div className="relative inline-flex max-w-full overflow-x-auto bg-slate-100 p-0.5 rounded-lg" role="tablist" aria-label="车辆里程区间">
+                {rangeTabs.map(tab => (
                   <button
+                    type="button"
                     key={tab.key}
                     onClick={() => setRange(tab.key)}
-                    className={`relative px-3 py-1 text-[10px] font-bold rounded-md transition-colors ${range === tab.key ? 'text-blue-600' : 'text-slate-500 hover:text-slate-700'}`}
+                    role="tab"
+                    aria-selected={range === tab.key}
+                    className={`relative shrink-0 px-3 py-1 text-[10px] font-bold rounded-md transition-colors ${range === tab.key ? 'text-blue-600' : 'text-slate-500 hover:text-slate-700'}`}
                   >
                     {range === tab.key && (
                       <motion.div
@@ -191,29 +227,49 @@ export default function VehicleDetailModal({ vehicle, onClose }: Props) {
                   </button>
                 ))}
               </div>
+              {loading && hasSnapshot ? (
+                <span className="ml-2 inline-flex items-center gap-1 text-[9px] font-bold text-slate-400">
+                  <RefreshCw size={10} className="animate-spin" /> 刷新中
+                </span>
+              ) : null}
             </div>
 
+            {error ? (
+              <div className="px-4 pt-3">
+                <ErrorState
+                  title="车辆近期里程加载失败"
+                  message={hasSnapshot ? `${error} 当前保留上一次成功加载的数据。` : error}
+                  onRetry={() => setRequestVersion(version => version + 1)}
+                  retrying={loading}
+                  variant="inline"
+                />
+              </div>
+            ) : null}
+
             {/* KPI cards */}
             <div className="px-4 py-3 grid grid-cols-3 gap-2">
               <div className="bg-slate-50 rounded-xl p-2.5">
                 <div className="text-[9px] font-bold text-slate-400 uppercase">区间合计</div>
                 <div className="text-base font-black text-slate-900 leading-tight">
-                  {loading ? <span className="inline-block h-4 w-14 bg-slate-200 rounded animate-pulse align-middle" />
-                    : <>{Math.round(stats.totalKm).toLocaleString()}<span className="text-[9px] font-bold text-slate-400 ml-0.5">km</span></>}
+                  {showInitialLoading ? <span className="inline-block h-4 w-14 bg-slate-200 rounded animate-pulse align-middle" />
+                    : showUnavailable ? <span className="text-slate-300">—</span>
+                      : <>{Math.round(stats.totalKm).toLocaleString()}<span className="text-[9px] font-bold text-slate-400 ml-0.5">km</span></>}
                 </div>
               </div>
               <div className="bg-slate-50 rounded-xl p-2.5">
                 <div className="text-[9px] font-bold text-slate-400 uppercase">日均</div>
                 <div className="text-base font-black text-slate-900 leading-tight">
-                  {loading ? <span className="inline-block h-4 w-10 bg-slate-200 rounded animate-pulse align-middle" />
-                    : <>{Math.round(stats.avg).toLocaleString()}<span className="text-[9px] font-bold text-slate-400 ml-0.5">km</span></>}
+                  {showInitialLoading ? <span className="inline-block h-4 w-10 bg-slate-200 rounded animate-pulse align-middle" />
+                    : showUnavailable ? <span className="text-slate-300">—</span>
+                      : <>{Math.round(stats.avg).toLocaleString()}<span className="text-[9px] font-bold text-slate-400 ml-0.5">km</span></>}
                 </div>
               </div>
               <div className="bg-slate-50 rounded-xl p-2.5">
                 <div className="text-[9px] font-bold text-slate-400 uppercase">有数据天</div>
                 <div className="text-base font-black text-slate-900 leading-tight">
-                  {loading ? <span className="inline-block h-4 w-12 bg-slate-200 rounded animate-pulse align-middle" />
-                    : <>{stats.synced}<span className="text-[9px] font-bold text-slate-400 ml-0.5">/{stats.totalDays}</span></>}
+                  {showInitialLoading ? <span className="inline-block h-4 w-12 bg-slate-200 rounded animate-pulse align-middle" />
+                    : showUnavailable ? <span className="text-slate-300">—</span>
+                      : <>{stats.synced}<span className="text-[9px] font-bold text-slate-400 ml-0.5">/{stats.totalDays}</span></>}
                 </div>
               </div>
             </div>
@@ -226,8 +282,12 @@ export default function VehicleDetailModal({ vehicle, onClose }: Props) {
               </div>
               <div className="bg-white rounded-xl border border-slate-50">
                 <div className="h-[140px]">
-                  {loading ? (
+                  {showInitialLoading ? (
                     <SkeletonBars count={Math.min(skeletonCount, 30)} />
+                  ) : showUnavailable ? (
+                    <div className="flex h-full items-center justify-center text-[10px] font-bold text-slate-300">所选区间趋势暂不可用</div>
+                  ) : historyDays.length === 0 ? (
+                    <EmptyState title="暂无里程数据" description="所选区间没有可展示的车辆里程" variant="inline" />
                   ) : (
                     <ResponsiveContainer width="100%" height="100%">
                       <BarChart data={historyDays} margin={{ top: 8, right: 8, bottom: 0, left: 0 }}>
@@ -262,8 +322,12 @@ export default function VehicleDetailModal({ vehicle, onClose }: Props) {
             {/* 每日明细 */}
             <div className="flex-1 overflow-y-auto px-4 pb-4">
               <div className="text-[10px] font-bold text-slate-500 mb-1.5">每日明细</div>
-              {loading ? (
+              {showInitialLoading ? (
                 <SkeletonList count={Math.min(skeletonCount, 15)} />
+              ) : showUnavailable ? (
+                <div className="py-6 text-center text-[10px] font-bold text-slate-300">请重试加载车辆每日明细</div>
+              ) : historyDays.length === 0 ? (
+                <div className="py-6 text-center text-[10px] font-bold text-slate-300">所选区间暂无每日明细</div>
               ) : (
                 <motion.div
                   key={range}
@@ -280,7 +344,21 @@ export default function VehicleDetailModal({ vehicle, onClose }: Props) {
                       transition={{ delay: Math.min(i * 0.012, 0.4), duration: 0.18 }}
                       className="flex items-center justify-between py-1.5 px-2 rounded-lg hover:bg-slate-50"
                     >
-                      <span className="text-[11px] font-mono font-bold text-slate-600">{d.date}</span>
+                      <div className="w-[88px] flex-shrink-0">
+                        <div className="text-[11px] font-mono font-bold text-slate-600">{d.date}</div>
+                        <div
+                          className={`text-[8px] font-bold ${
+                            d.sourceCategory === 'INSTRUMENT'
+                              ? 'text-violet-500'
+                              : d.sourceCategory === 'GPS'
+                                ? 'text-emerald-500'
+                                : 'text-amber-500'
+                          }`}
+                          title={d.sourceProtocol || 'OneOS 当前未返回 sourceProtocol'}
+                        >
+                          {daySourceLabel(d)}
+                        </div>
+                      </div>
                       <div className="flex items-center gap-2 flex-1 ml-3">
                         <div className="flex-1 h-1.5 bg-slate-100 rounded-full overflow-hidden">
                           <motion.div

src/modules/mileage/api.ts

@@ -1,11 +1,29 @@
-import type { MonitoringData, TargetSummary, TargetVehicle, TrendPoint } from './types';
+import type {
+  MileageSourceCategory,
+  MileageSourceGroup,
+  MileageSourceProtocol,
+  MonitoringData,
+  TargetSummary,
+  TargetVehicle,
+  TrendPoint,
+} from './types';
 import { fetchJson } from '../../auth/api-client';
+import {
+  buildDailyReport,
+  type DailyReportData,
+} from './daily-report';
+
+export type {
+  DailyReportData,
+  DailyReportModel,
+  DailyReportVehicle,
+} from './daily-report';
 
 const BASE = '/api/mileage';
 
 export async function fetchMonitoring(params?: {
-  sortBy?: string;
-  sortOrder?: string;
+  sortBy?: 'today' | 'total' | 'statisticTime';
+  sortOrder?: 'asc' | 'desc';
   limit?: number;
   page?: number;
   search?: string;
@@ -24,6 +42,9 @@ export async function fetchMonitoring(params?: {
   date?: string;
   startDate?: string;
   endDate?: string;
+  brands?: string[];
+  sourcePriority?: MileageSourceGroup[];
+  force?: boolean;
 }): Promise<MonitoringData> {
   const query = new URLSearchParams();
   if (params?.sortBy) query.set('sortBy', params.sortBy);
@@ -44,12 +65,19 @@ export async function fetchMonitoring(params?: {
     });
   }
   if (params?.region) query.set('region', params.region);
+  if (params?.brands) {
+    params.brands.forEach(brand => {
+      if (brand) query.append('brand', brand);
+    });
+  }
   if (params?.plate) query.set('plate', params.plate);
   if (params?.mileageMin) query.set('mileageMin', params.mileageMin);
   if (params?.mileageMax) query.set('mileageMax', params.mileageMax);
   if (params?.date) query.set('date', params.date);
   if (params?.startDate) query.set('startDate', params.startDate);
   if (params?.endDate) query.set('endDate', params.endDate);
+  if (params?.sourcePriority?.length) query.set('sourcePriority', params.sourcePriority.join(','));
+  if (params?.force) query.set('force', '1');
   const qs = query.toString();
   return fetchJson<MonitoringData>(`${BASE}/monitoring${qs ? `?${qs}` : ''}`);
 }
@@ -76,6 +104,8 @@ export interface VehicleRecentDay {
   date: string;
   dailyKm: number;
   isDataSynced: boolean;
+  sourceProtocol: MileageSourceProtocol | null;
+  sourceCategory: Exclude<MileageSourceCategory, 'MIXED'> | null;
 }
 
 export interface VehicleRecentResponse {
@@ -83,53 +113,28 @@ export interface VehicleRecentResponse {
   start?: string;
   end?: string;
   days: VehicleRecentDay[];
+  sourcePriority?: MileageSourceGroup[];
 }
 
 export async function fetchVehicleRecent(
   plate: string,
-  range: { days?: number; start?: string; end?: string } = { days: 15 },
+  range: {
+    days?: number;
+    start?: string;
+    end?: string;
+    sourcePriority?: MileageSourceGroup[];
+  } = { days: 15 },
 ): Promise<VehicleRecentResponse> {
   const params = new URLSearchParams();
   if (range.start) params.set('start', range.start);
   if (range.end) params.set('end', range.end);
   if (range.days != null) params.set('days', String(range.days));
+  if (range.sourcePriority?.length) params.set('sourcePriority', range.sourcePriority.join(','));
   return fetchJson<VehicleRecentResponse>(
     `${BASE}/vehicle/${encodeURIComponent(plate)}/recent?${params.toString()}`
   );
 }
 
-export interface DailyReportModel {
-  id: number;
-  name: string;
-  count: number;
-  today: number;
-  total: number;
-  completion: number;
-  active: number;
-  zero: number;
-  dailyNeed: number;
-}
-
-export interface DailyReportVehicle {
-  plate: string;
-  model: string;
-  status: string;
-  customer: string;
-  today?: number;
-  completion?: number;
-}
-
-export interface DailyReportData {
-  reportDate: string;
-  updatedAt: string;
-  models: DailyReportModel[];
-  trend: { date: string; value: number }[];
-  topVehicles: DailyReportVehicle[];
-  zeroRisk: DailyReportVehicle[];
-  qualifiedCount: number;
-  halfQualifiedCount: number;
-}
-
 function reportDateFromUpdatedAt(updatedAt: string): string {
   if (/^\d{4}-\d{2}-\d{2}$/.test(updatedAt)) return updatedAt;
   const d = new Date(updatedAt);
@@ -137,95 +142,58 @@ function reportDateFromUpdatedAt(updatedAt: string): string {
   return new Date().toISOString().slice(0, 10);
 }
 
-function compactTargetName(name: string): string {
-  return name
-    .replace(/^羚牛/, '')
-    .replace(/辆/g, '台')
-    .replace(/4\.5T普货/g, '普货')
-    .replace(/4\.5T冷链车/g, '冷链车')
-    .replace(/4\.5T冷链/g, '冷链车');
-}
+let dailyReportRequest: Promise<DailyReportData> | null = null;
+let dailyReportCache: { data: DailyReportData; expiresAt: number } | null = null;
+const DAILY_REPORT_CACHE_MS = 60_000;
 
-function normalizeStatus(status: string | null): string {
-  if (!status) return '未标注';
-  if (status === '自营' || status === '租赁') return status;
-  if (/租/.test(status)) return '租赁';
-  if (/自/.test(status)) return '自营';
-  if (/库|Inventory/i.test(status)) return '在库';
-  return status;
-}
-
-export async function fetchDailyReport(): Promise<DailyReportData> {
-  const [targets, trend, monitoring, topMonitoring] = await Promise.all([
+async function loadDailyReport(): Promise<DailyReportData> {
+  const [targets, monitoring] = await Promise.all([
     fetchTargets(),
-    fetchTrend(undefined, 7),
-    fetchMonitoring({ limit: 1 }),
     fetchMonitoring({ sortBy: 'today', sortOrder: 'desc', limit: 5 }),
   ]);
+  const reportDate = monitoring.dateRange?.end || reportDateFromUpdatedAt(monitoring.updatedAt);
 
-  const targetVehiclesEntries = await Promise.all(
+  const targetVehicles = await Promise.all(
     targets.map(async target => {
-      const vehicles = await fetchTargetVehicles(target.id);
-      return [target.id, vehicles] as const;
+      const vehicles = await fetchTargetVehicles(target.id, reportDate);
+      return { target, vehicles };
     }),
   );
-  const targetVehiclesMap = new Map(targetVehiclesEntries);
 
-  const models: DailyReportModel[] = targets.map(target => {
-    const vehicles = targetVehiclesMap.get(target.id) ?? [];
-    const active = vehicles.filter(vehicle => vehicle.todayMileage > 0).length;
-    return {
-      id: target.id,
-      name: compactTargetName(target.targetName),
-      count: target.vehicleCount,
-      today: target.todayTotal,
-      total: target.cumulativeTotal,
-      completion: target.avgCompletion,
-      active,
-      zero: Math.max(0, target.vehicleCount - active),
-      dailyNeed: target.dailyTarget,
-    };
-  });
+  return buildDailyReport(targets, targetVehicles, monitoring, [], reportDate);
+}
 
-  const targetNameByPlate = new Map<string, string>();
-  for (const target of targets) {
-    const vehicles = targetVehiclesMap.get(target.id) ?? [];
-    for (const vehicle of vehicles) targetNameByPlate.set(vehicle.plateNumber, compactTargetName(target.targetName));
+export async function fetchDailyReport(force = false): Promise<DailyReportData> {
+  if (!force && dailyReportCache && dailyReportCache.expiresAt > Date.now()) {
+    return dailyReportCache.data;
   }
+  if (!force && dailyReportRequest) return dailyReportRequest;
+  const request = loadDailyReport();
+  dailyReportRequest = request;
+  try {
+    const data = await request;
+    dailyReportCache = { data, expiresAt: Date.now() + DAILY_REPORT_CACHE_MS };
+    return data;
+  } finally {
+    if (dailyReportRequest === request) dailyReportRequest = null;
+  }
+}
 
-  const topVehicles: DailyReportVehicle[] = topMonitoring.vehicles.map(vehicle => ({
-    plate: vehicle.plate,
-    model: targetNameByPlate.get(vehicle.plate) || vehicle.project || '未归入考核',
-    status: normalizeStatus(vehicle.rentStatus),
-    today: vehicle.dailyKm,
-    customer: vehicle.customer || '未绑定客户',
-  }));
+let dailyReportTrendRequest: Promise<TrendPoint[]> | null = null;
+let dailyReportTrendCache: { data: TrendPoint[]; expiresAt: number } | null = null;
 
-  const zeroRisk = targetVehiclesEntries
-    .flatMap(([targetId, vehicles]) => {
-      const target = targets.find(item => item.id === targetId);
-      const model = target ? compactTargetName(target.targetName) : '未归入考核';
-      return vehicles
-        .filter(vehicle => vehicle.todayMileage <= 0 && ['自营', '租赁'].includes(normalizeStatus(vehicle.rentStatus)))
-        .map(vehicle => ({
-          plate: vehicle.plateNumber,
-          model,
-          status: normalizeStatus(vehicle.rentStatus),
-          customer: vehicle.customer || '未绑定客户',
-          completion: vehicle.completionRate,
-        }));
-    })
-    .sort((a, b) => (b.completion ?? 0) - (a.completion ?? 0))
-    .slice(0, 5);
-
-  return {
-    reportDate: reportDateFromUpdatedAt(monitoring.updatedAt),
-    updatedAt: monitoring.updatedAt,
-    models,
-    trend: trend.map(item => ({ date: item.date, value: item.mileage })),
-    topVehicles,
-    zeroRisk,
-    qualifiedCount: targets.reduce((sum, target) => sum + target.yearQualifiedCount, 0),
-    halfQualifiedCount: targets.reduce((sum, target) => sum + target.halfQualifiedCount, 0),
-  };
+export async function fetchDailyReportTrend(force = false): Promise<TrendPoint[]> {
+  if (!force && dailyReportTrendCache && dailyReportTrendCache.expiresAt > Date.now()) {
+    return dailyReportTrendCache.data;
+  }
+  if (!force && dailyReportTrendRequest) return dailyReportTrendRequest;
+  const request = fetchTrend(undefined, 7);
+  dailyReportTrendRequest = request;
+  try {
+    const data = await request;
+    dailyReportTrendCache = { data, expiresAt: Date.now() + DAILY_REPORT_CACHE_MS };
+    return data;
+  } finally {
+    if (dailyReportTrendRequest === request) dailyReportTrendRequest = null;
+  }
 }

src/modules/mileage/assessment-coverage.test.ts

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { assessVehicleCoverage } from './assessment-coverage.js';
+
+test('reports matched, missing, and excess assessment vehicles', () => {
+  assert.deepEqual(assessVehicleCoverage(50, 46), {
+    status: 'missing',
+    declaredCount: 50,
+    activeCount: 46,
+    difference: -4,
+    coverageRate: 92,
+  });
+  assert.equal(assessVehicleCoverage(40, 40).status, 'matched');
+  assert.equal(assessVehicleCoverage(40, 42).status, 'excess');
+});
+
+test('normalizes invalid counts without inventing configured vehicles', () => {
+  assert.deepEqual(assessVehicleCoverage(Number.NaN, -2), {
+    status: 'matched',
+    declaredCount: 0,
+    activeCount: 0,
+    difference: 0,
+    coverageRate: 100,
+  });
+});

src/modules/mileage/assessment-coverage.ts

@@ -0,0 +1,26 @@
+export type AssessmentCoverageStatus = 'matched' | 'missing' | 'excess';
+
+export interface AssessmentCoverage {
+  status: AssessmentCoverageStatus;
+  declaredCount: number;
+  activeCount: number;
+  difference: number;
+  coverageRate: number;
+}
+
+function count(value: number): number {
+  return Math.max(0, Math.trunc(Number(value) || 0));
+}
+
+export function assessVehicleCoverage(declaredCount: number, activeCount: number): AssessmentCoverage {
+  const declared = count(declaredCount);
+  const active = count(activeCount);
+  const difference = active - declared;
+  return {
+    status: difference === 0 ? 'matched' : difference < 0 ? 'missing' : 'excess',
+    declaredCount: declared,
+    activeCount: active,
+    difference,
+    coverageRate: declared > 0 ? active / declared * 100 : active === 0 ? 100 : 0,
+  };
+}

src/modules/mileage/attribution.test.ts

@@ -0,0 +1,88 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildMileageAttribution,
+  filterAttributionVehicles,
+  reconcileMileageAttribution,
+} from './attribution.js';
+import type { TargetVehicle } from './types.js';
+
+function vehicle(overrides: Partial<TargetVehicle>): TargetVehicle {
+  return {
+    plateNumber: '粤A00000',
+    todayMileage: 0,
+    totalMileage: 0,
+    completionRate: 0,
+    isQualified: false,
+    currentYearIsQualified: false,
+    dailyRequiredMileage: 100,
+    rentStatus: null,
+    department: null,
+    customer: null,
+    isOnline: false,
+    ...overrides,
+  };
+}
+
+test('groups vehicles and calculates additive attribution metrics', () => {
+  const result = buildMileageAttribution([
+    vehicle({ plateNumber: '粤A1', department: '业务一部', todayMileage: 120, totalMileage: 1000, completionRate: 0.8, isOnline: true }),
+    vehicle({ plateNumber: '粤A2', department: '业务一部', todayMileage: 40, totalMileage: 500, completionRate: 0.4 }),
+    vehicle({ plateNumber: '粤A3', department: '业务二部', todayMileage: 40, totalMileage: 400, completionRate: 0.2 }),
+  ], 'department', 1000);
+
+  const first = result.find(group => group.key === '业务一部');
+  assert.deepEqual(first, {
+    key: '业务一部',
+    label: '业务一部',
+    vehicleCount: 2,
+    onlineCount: 1,
+    zeroMileageCount: 0,
+    behindCount: 1,
+    todayMileage: 160,
+    totalMileage: 1500,
+    targetMileage: 2000,
+    completedMileage: 1500,
+    shortfallMileage: 500,
+    completionRate: 75,
+    contributionRate: 80,
+  });
+});
+
+test('keeps unassigned vehicles visible and sorts largest shortfall first', () => {
+  const result = buildMileageAttribution([
+    vehicle({ plateNumber: '粤A1', department: null, todayMileage: 0 }),
+    vehicle({ plateNumber: '粤A2', department: '业务一部', todayMileage: 80, totalMileage: 100 }),
+  ], 'department', 100);
+
+  assert.equal(result[0].label, '未分配部门');
+  assert.equal(result[0].shortfallMileage, 100);
+  assert.equal(result[0].zeroMileageCount, 1);
+});
+
+test('reconciles additive group shortfall with the target summary at display precision', () => {
+  const groups = buildMileageAttribution([
+    vehicle({ plateNumber: '粤A1', department: '业务一部', totalMileage: 1200 }),
+    vehicle({ plateNumber: '粤A2', department: '业务二部', totalMileage: 499.96 }),
+  ], 'department', 1000);
+
+  assert.deepEqual(reconcileMileageAttribution(groups, 500), {
+    matches: true,
+    attributedShortfall: 500,
+    expectedShortfall: 500,
+    difference: 0,
+  });
+  assert.equal(reconcileMileageAttribution(groups, 450).difference, 50);
+});
+
+test('filters a group using the same empty-value semantics as aggregation', () => {
+  const vehicles = [
+    vehicle({ plateNumber: '粤A1', customer: null }),
+    vehicle({ plateNumber: '粤A2', customer: '客户甲' }),
+  ];
+
+  assert.deepEqual(
+    filterAttributionVehicles(vehicles, 'customer', '未绑定客户').map(item => item.plateNumber),
+    ['粤A1'],
+  );
+});

src/modules/mileage/attribution.ts

@@ -0,0 +1,121 @@
+import type { TargetVehicle } from './types';
+
+export type AttributionDimension = 'department' | 'customer';
+
+export interface MileageAttributionGroup {
+  key: string;
+  label: string;
+  vehicleCount: number;
+  onlineCount: number;
+  zeroMileageCount: number;
+  behindCount: number;
+  todayMileage: number;
+  totalMileage: number;
+  targetMileage: number;
+  completedMileage: number;
+  shortfallMileage: number;
+  completionRate: number;
+  contributionRate: number;
+}
+
+export interface MileageAttributionReconciliation {
+  matches: boolean;
+  attributedShortfall: number;
+  expectedShortfall: number;
+  difference: number;
+}
+
+const EMPTY_LABELS: Record<AttributionDimension, string> = {
+  department: '未分配部门',
+  customer: '未绑定客户',
+};
+
+export function attributionValue(
+  vehicle: TargetVehicle,
+  dimension: AttributionDimension,
+): string {
+  return vehicle[dimension]?.trim() || EMPTY_LABELS[dimension];
+}
+
+export function buildMileageAttribution(
+  vehicles: TargetVehicle[],
+  dimension: AttributionDimension,
+  targetMileagePerVehicle: number,
+): MileageAttributionGroup[] {
+  const perVehicleTarget = Math.max(0, Number(targetMileagePerVehicle) || 0);
+  const totalTodayMileage = vehicles.reduce(
+    (sum, vehicle) => sum + Math.max(0, Number(vehicle.todayMileage) || 0),
+    0,
+  );
+  const grouped = new Map<string, TargetVehicle[]>();
+
+  for (const vehicle of vehicles) {
+    const key = attributionValue(vehicle, dimension);
+    const current = grouped.get(key) || [];
+    current.push(vehicle);
+    grouped.set(key, current);
+  }
+
+  return Array.from(grouped, ([key, members]) => {
+    const todayMileage = members.reduce((sum, vehicle) => sum + Math.max(0, Number(vehicle.todayMileage) || 0), 0);
+    const totalMileage = members.reduce((sum, vehicle) => sum + Math.max(0, Number(vehicle.totalMileage) || 0), 0);
+    const targetMileage = perVehicleTarget * members.length;
+    const completedMileage = members.reduce((sum, vehicle) => (
+      sum + Math.min(Math.max(0, Number(vehicle.totalMileage) || 0), perVehicleTarget)
+    ), 0);
+    const shortfallMileage = members.reduce((sum, vehicle) => {
+      const completed = Math.max(0, Number(vehicle.totalMileage) || 0);
+      return sum + Math.max(0, perVehicleTarget - completed);
+    }, 0);
+
+    return {
+      key,
+      label: key,
+      vehicleCount: members.length,
+      onlineCount: members.filter(vehicle => vehicle.isOnline).length,
+      zeroMileageCount: members.filter(vehicle => (Number(vehicle.todayMileage) || 0) <= 0).length,
+      behindCount: members.filter(vehicle => (
+        (Number(vehicle.totalMileage) || 0) < perVehicleTarget
+      )).length,
+      todayMileage,
+      totalMileage,
+      targetMileage,
+      completedMileage,
+      shortfallMileage,
+      completionRate: targetMileage > 0 ? completedMileage / targetMileage * 100 : 0,
+      contributionRate: totalTodayMileage > 0 ? todayMileage / totalTodayMileage * 100 : 0,
+    };
+  }).sort((a, b) => (
+    b.shortfallMileage - a.shortfallMileage
+    || b.behindCount - a.behindCount
+    || b.todayMileage - a.todayMileage
+    || a.label.localeCompare(b.label, 'zh-CN')
+  ));
+}
+
+function roundMileage(value: number): number {
+  return Math.round((Number(value) || 0) * 10) / 10;
+}
+
+export function reconcileMileageAttribution(
+  groups: MileageAttributionGroup[],
+  expectedShortfall: number,
+): MileageAttributionReconciliation {
+  const attributedShortfall = roundMileage(groups.reduce((sum, group) => sum + group.shortfallMileage, 0));
+  const normalizedExpected = roundMileage(expectedShortfall);
+  const difference = roundMileage(attributedShortfall - normalizedExpected);
+  return {
+    matches: difference === 0,
+    attributedShortfall,
+    expectedShortfall: normalizedExpected,
+    difference,
+  };
+}
+
+export function filterAttributionVehicles(
+  vehicles: TargetVehicle[],
+  dimension: AttributionDimension,
+  value: string,
+): TargetVehicle[] {
+  return vehicles.filter(vehicle => attributionValue(vehicle, dimension) === value);
+}

src/modules/mileage/daily-report.test.ts

@@ -0,0 +1,98 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildDailyReport } from './daily-report.js';
+import type { MonitoringData, TargetSummary, TargetVehicle } from './types.js';
+
+function target(id: number, completed: number, goal: number): TargetSummary {
+  return {
+    id,
+    targetName: `目标${id}`,
+    vehicleCount: 2,
+    cumulativeTotal: completed,
+    currentYearCompleted: completed,
+    currentYearTarget: goal,
+    yearQualifiedCount: 0,
+    halfQualifiedCount: 0,
+  } as TargetSummary;
+}
+
+function vehicle(plateNumber: string, todayMileage: number, dailyRequiredMileage: number): TargetVehicle {
+  return {
+    plateNumber,
+    todayMileage,
+    totalMileage: 1000,
+    completionRate: 0.5,
+    isQualified: false,
+    currentYearIsQualified: false,
+    dailyRequiredMileage,
+    rentStatus: '租赁',
+    department: '业务一部',
+    customer: '客户甲',
+    isOnline: true,
+  };
+}
+
+const monitoring = {
+  stats: { totalToday: 0, totalAll: 0, vehicleCount: 10, yesterdayTotal: 0 },
+  updatedAt: '2026-08-07T10:00:00+08:00',
+} as MonitoringData;
+
+test('builds a weighted, additive daily report', () => {
+  const first = target(1, 50, 100);
+  const second = target(2, 100, 300);
+  const report = buildDailyReport(
+    [first, second],
+    [
+      { target: first, vehicles: [vehicle('粤A1', 120, 100), vehicle('粤A2', 0, 100)] },
+      { target: second, vehicles: [vehicle('粤A3', 50, 100)] },
+    ],
+    monitoring,
+    [{ date: '08-06', mileage: 500 }],
+    '2026-08-07',
+  );
+
+  assert.equal(report.totalToday, 170);
+  assert.equal(report.dailyNeed, 300);
+  assert.equal(report.shortfall, 150);
+  assert.equal(report.activeCount, 2);
+  assert.equal(report.zeroCount, 1);
+  assert.equal(report.completionRate, 37.5);
+  assert.equal(report.models[0].shortfall, 100);
+  assert.deepEqual(report.trend, [{ date: '08-06', value: 500 }]);
+});
+
+test('deduplicates vehicles assigned to multiple targets', () => {
+  const first = target(1, 50, 100);
+  const second = target(2, 100, 300);
+  const report = buildDailyReport(
+    [first, second],
+    [
+      { target: first, vehicles: [vehicle('粤A1', 80, 100)] },
+      { target: second, vehicles: [vehicle('粤A1', 80, 100)] },
+    ],
+    monitoring,
+    [],
+    '2026-08-07',
+  );
+
+  assert.equal(report.assessmentVehicleCount, 1);
+  assert.equal(report.duplicateAssignmentCount, 1);
+  assert.equal(report.totalToday, 80);
+});
+
+test('falls back to the target daily need when vehicle tasks are missing', () => {
+  const item = target(5, 100, 300);
+  item.dailyTarget = 250;
+  const report = buildDailyReport(
+    [item],
+    [{ target: item, vehicles: [vehicle('粤A1', 100, 0), vehicle('粤A2', 50, 0)] }],
+    monitoring,
+    [],
+    '2026-08-07',
+  );
+
+  assert.equal(report.dailyNeed, 250);
+  assert.equal(report.shortfall, 100);
+  assert.equal(report.missingDailyTaskCount, 2);
+  assert.equal(report.models[0].missingDailyTaskCount, 2);
+});

src/modules/mileage/daily-report.ts

@@ -0,0 +1,200 @@
+import { weightedCompletionRate } from '../../shared/analytics/metrics';
+import type {
+  MonitoringData,
+  TargetSummary,
+  TargetVehicle,
+  TrendPoint,
+} from './types';
+
+export interface DailyReportModel {
+  id: number;
+  name: string;
+  count: number;
+  today: number;
+  total: number;
+  completion: number;
+  active: number;
+  zero: number;
+  dailyNeed: number;
+  shortfall: number;
+  missingDailyTaskCount: number;
+}
+
+export interface DailyReportVehicle {
+  targetId: number;
+  plate: string;
+  model: string;
+  status: string;
+  customer: string;
+  today: number;
+  completion: number;
+  dailyNeed: number;
+  shortfall: number;
+  isOnline: boolean;
+  hasDailyTask: boolean;
+}
+
+export interface DailyReportData {
+  reportDate: string;
+  updatedAt: string;
+  monitoringVehicleCount: number;
+  assessmentVehicleCount: number;
+  duplicateAssignmentCount: number;
+  missingDailyTaskCount: number;
+  totalToday: number;
+  activeCount: number;
+  zeroCount: number;
+  dailyNeed: number;
+  shortfall: number;
+  completionRate: number;
+  models: DailyReportModel[];
+  trend: { date: string; value: number }[];
+  topVehicles: DailyReportVehicle[];
+  riskVehicles: DailyReportVehicle[];
+  qualifiedCount: number;
+  halfQualifiedCount: number;
+}
+
+interface TargetVehicleEntry {
+  target: TargetSummary;
+  vehicles: TargetVehicle[];
+}
+
+function compactTargetName(name: string): string {
+  return name
+    .replace(/^羚牛/, '')
+    .replace(/辆/g, '台')
+    .replace(/4\.5T普货/g, '普货')
+    .replace(/4\.5T冷链车/g, '冷链车')
+    .replace(/4\.5T冷链/g, '冷链车');
+}
+
+function normalizeStatus(status: string | null): string {
+  if (!status) return '未标注';
+  if (status === '自营' || status === '租赁') return status;
+  if (/租/.test(status)) return '租赁';
+  if (/自/.test(status)) return '自营';
+  if (/库|Inventory/i.test(status)) return '在库';
+  return status;
+}
+
+function positive(value: number | null | undefined): number {
+  return Math.max(0, Number(value) || 0);
+}
+
+function vehicleReportRow(
+  vehicle: TargetVehicle,
+  targetId: number,
+  model: string,
+  targetDailyNeed: number,
+): DailyReportVehicle {
+  const today = positive(vehicle.todayMileage);
+  const dailyNeed = positive(vehicle.dailyRequiredMileage);
+  return {
+    targetId,
+    plate: vehicle.plateNumber,
+    model,
+    status: normalizeStatus(vehicle.rentStatus),
+    customer: vehicle.customer || '未绑定客户',
+    today,
+    completion: positive(vehicle.completionRate) * 100,
+    dailyNeed,
+    shortfall: Math.max(0, dailyNeed - today),
+    isOnline: vehicle.isOnline,
+    hasDailyTask: dailyNeed > 0 || targetDailyNeed <= 0,
+  };
+}
+
+export function buildDailyReport(
+  targets: TargetSummary[],
+  targetVehicles: TargetVehicleEntry[],
+  monitoring: MonitoringData,
+  trend: TrendPoint[],
+  reportDate: string,
+): DailyReportData {
+  const models = targetVehicles.map(({ target, vehicles }) => {
+    const today = vehicles.reduce((sum, vehicle) => sum + positive(vehicle.todayMileage), 0);
+    const vehicleDailyNeed = vehicles.reduce((sum, vehicle) => sum + positive(vehicle.dailyRequiredMileage), 0);
+    const targetDailyNeed = positive(target.dailyTarget);
+    const dailyNeed = Math.max(vehicleDailyNeed, targetDailyNeed);
+    const vehicleShortfall = vehicles.reduce((sum, vehicle) => (
+      sum + Math.max(0, positive(vehicle.dailyRequiredMileage) - positive(vehicle.todayMileage))
+    ), 0);
+    const shortfall = Math.max(vehicleShortfall, Math.max(0, dailyNeed - today));
+    return {
+      id: target.id,
+      name: compactTargetName(target.targetName),
+      count: vehicles.length,
+      today,
+      total: positive(target.cumulativeTotal),
+      completion: weightedCompletionRate([{
+        completed: positive(target.currentYearCompleted),
+        target: positive(target.currentYearTarget),
+      }]),
+      active: vehicles.filter(vehicle => positive(vehicle.todayMileage) > 0).length,
+      zero: vehicles.filter(vehicle => positive(vehicle.todayMileage) <= 0).length,
+      dailyNeed,
+      shortfall,
+      missingDailyTaskCount: targetDailyNeed > 0
+        ? vehicles.filter(vehicle => positive(vehicle.dailyRequiredMileage) <= 0).length
+        : 0,
+    };
+  });
+
+  const uniqueVehicles = new Map<string, DailyReportVehicle>();
+  let duplicateAssignmentCount = 0;
+  for (const { target, vehicles } of targetVehicles) {
+    const model = compactTargetName(target.targetName);
+    for (const vehicle of vehicles) {
+      const next = vehicleReportRow(vehicle, target.id, model, positive(target.dailyTarget));
+      const existing = uniqueVehicles.get(next.plate);
+      if (!existing) {
+        uniqueVehicles.set(next.plate, next);
+        continue;
+      }
+      duplicateAssignmentCount += 1;
+      uniqueVehicles.set(next.plate, {
+        ...existing,
+        today: Math.max(existing.today, next.today),
+        completion: Math.max(existing.completion, next.completion),
+        dailyNeed: Math.max(existing.dailyNeed, next.dailyNeed),
+        shortfall: Math.max(existing.shortfall, next.shortfall),
+        isOnline: existing.isOnline || next.isOnline,
+        hasDailyTask: existing.hasDailyTask || next.hasDailyTask,
+      });
+    }
+  }
+
+  const vehicles = Array.from(uniqueVehicles.values());
+  const activeCount = vehicles.filter(vehicle => vehicle.today > 0).length;
+  const totalToday = vehicles.reduce((sum, vehicle) => sum + vehicle.today, 0);
+  const dailyNeed = models.reduce((sum, model) => sum + model.dailyNeed, 0);
+  const shortfall = models.reduce((sum, model) => sum + model.shortfall, 0);
+
+  return {
+    reportDate,
+    updatedAt: monitoring.updatedAt,
+    monitoringVehicleCount: monitoring.stats.vehicleCount,
+    assessmentVehicleCount: vehicles.length,
+    duplicateAssignmentCount,
+    missingDailyTaskCount: models.reduce((sum, model) => sum + model.missingDailyTaskCount, 0),
+    totalToday,
+    activeCount,
+    zeroCount: vehicles.length - activeCount,
+    dailyNeed,
+    shortfall,
+    completionRate: weightedCompletionRate(targets.map(target => ({
+      completed: positive(target.currentYearCompleted),
+      target: positive(target.currentYearTarget),
+    }))),
+    models: models.sort((a, b) => b.shortfall - a.shortfall || b.today - a.today),
+    trend: trend.map(item => ({ date: item.date, value: item.mileage })),
+    topVehicles: [...vehicles].sort((a, b) => b.today - a.today).slice(0, 5),
+    riskVehicles: [...vehicles]
+      .filter(vehicle => vehicle.shortfall > 0)
+      .sort((a, b) => b.shortfall - a.shortfall || a.completion - b.completion)
+      .slice(0, 5),
+    qualifiedCount: targets.reduce((sum, target) => sum + target.yearQualifiedCount, 0),
+    halfQualifiedCount: targets.reduce((sum, target) => sum + target.halfQualifiedCount, 0),
+  };
+}

src/modules/mileage/data-freshness.test.ts

@@ -0,0 +1,18 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { formatMileageSnapshotDateTime, formatMileageSnapshotTime } from './data-freshness.js';
+
+test('formats snapshot instants in Asia/Shanghai', () => {
+  assert.equal(formatMileageSnapshotTime('2026-08-07T07:45:06.000Z'), '15:45:06');
+});
+
+test('keeps historical date snapshots explicit', () => {
+  assert.equal(formatMileageSnapshotTime('2026-08-06'), '2026-08-06');
+  assert.equal(formatMileageSnapshotTime(null), '--:--:--');
+});
+
+test('formats assessment snapshot instants with the business date and minute', () => {
+  assert.equal(formatMileageSnapshotDateTime('2026-08-07T09:45:01.000Z'), '2026.8.7 17:45');
+  assert.equal(formatMileageSnapshotDateTime(null), '--');
+  assert.equal(formatMileageSnapshotDateTime('not-a-date'), 'not-a-date');
+});

src/modules/mileage/data-freshness.ts

@@ -0,0 +1,32 @@
+export function formatMileageSnapshotTime(value: string | null): string {
+  if (!value) return '--:--:--';
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) return value;
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return new Intl.DateTimeFormat('zh-CN', {
+    timeZone: 'Asia/Shanghai',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    hour12: false,
+    hourCycle: 'h23',
+  }).format(date);
+}
+
+export function formatMileageSnapshotDateTime(value: string | null): string {
+  if (!value) return '--';
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  const parts = new Intl.DateTimeFormat('zh-CN', {
+    timeZone: 'Asia/Shanghai',
+    year: 'numeric',
+    month: 'numeric',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    hour12: false,
+    hourCycle: 'h23',
+  }).formatToParts(date);
+  const part = (type: Intl.DateTimeFormatPartTypes) => parts.find(item => item.type === type)?.value || '';
+  return `${part('year')}.${part('month')}.${part('day')} ${part('hour')}:${part('minute')}`;
+}

src/modules/mileage/drill-context.test.ts

@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildMileageDrillUrl, parseMileageDrillContext } from './drill-context.js';
+
+test('parses a vehicle drill context', () => {
+  const context = parseMileageDrillContext(
+    '?mileageLevel=vehicle&mileageTarget=5&mileagePlate=%E7%B2%A4A08190F&mileageStart=2026-08-01&mileageEnd=2026-08-07&mileageSource=instrument,gps',
+  );
+
+  assert.deepEqual(context, {
+    level: 'vehicle',
+    targetId: 5,
+    plate: '粤A08190F',
+    startDate: '2026-08-01',
+    endDate: '2026-08-07',
+    sourcePriority: ['instrument', 'gps'],
+  });
+});
+
+test('requires complete context for breakdown and vehicle levels', () => {
+  assert.equal(parseMileageDrillContext('?mileageLevel=vehicle').level, 'overview');
+  assert.equal(parseMileageDrillContext('?mileageLevel=breakdown&mileageDimension=region').level, 'overview');
+});
+
+test('parses a target-scoped breakdown context', () => {
+  assert.deepEqual(
+    parseMileageDrillContext('?mileageLevel=breakdown&mileageTarget=5&mileageYear=2&mileageDimension=department&mileageValue=%E4%B8%9A%E5%8A%A1%E4%B8%80%E9%83%A8'),
+    {
+      level: 'breakdown',
+      targetId: 5,
+      assessmentYear: 2,
+      dimension: 'department',
+      dimensionValue: '业务一部',
+      sourcePriority: ['instrument'],
+    },
+  );
+});
+
+test('accepts assessment years only with a target', () => {
+  assert.equal(parseMileageDrillContext('?mileageTarget=5&mileageYear=3').assessmentYear, 3);
+  assert.equal(parseMileageDrillContext('?mileageYear=3').assessmentYear, undefined);
+  assert.equal(parseMileageDrillContext('?mileageTarget=5&mileageYear=0').assessmentYear, undefined);
+});
+
+test('builds a namespaced URL and preserves unrelated parameters', () => {
+  const url = buildMileageDrillUrl(
+    { pathname: '/asset', search: '?company=5&legacy=1', hash: '#mileage' },
+    {
+      level: 'vehicle',
+      targetId: 5,
+      assessmentYear: 2,
+      plate: '粤A08190F',
+      startDate: '2026-08-01',
+      endDate: '2026-08-07',
+      sourcePriority: ['instrument'],
+    },
+  );
+
+  assert.equal(
+    url,
+    '/asset?company=5&legacy=1&mileageLevel=vehicle&mileageTarget=5&mileageYear=2&mileagePlate=%E7%B2%A4A08190F&mileageStart=2026-08-01&mileageEnd=2026-08-07&mileageSource=instrument#mileage',
+  );
+});
+
+test('clears entity drill parameters when returning to overview', () => {
+  const url = buildMileageDrillUrl(
+    {
+      pathname: '/asset',
+      search: '?mileageLevel=vehicle&mileageTarget=5&mileageYear=2&mileagePlate=%E7%B2%A4A08190F&company=5',
+      hash: '#mileage',
+    },
+    { level: 'overview', sourcePriority: ['instrument'] },
+  );
+
+  assert.equal(url, '/asset?company=5&mileageSource=instrument#mileage');
+});

src/modules/mileage/drill-context.ts

@@ -0,0 +1,125 @@
+import type { MileageSourceGroup } from './types';
+
+export type MileageDrillLevel = 'overview' | 'breakdown' | 'vehicle';
+export type MileageBreakdownDimension =
+  | 'department'
+  | 'region'
+  | 'customer'
+  | 'vehicle-model'
+  | 'assessment-target';
+
+export interface MileageDrillContext {
+  level: MileageDrillLevel;
+  targetId?: number;
+  assessmentYear?: number;
+  dimension?: MileageBreakdownDimension;
+  dimensionValue?: string;
+  plate?: string;
+  startDate?: string;
+  endDate?: string;
+  sourcePriority: MileageSourceGroup[];
+}
+
+interface LocationParts {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const BREAKDOWN_DIMENSIONS = new Set<MileageBreakdownDimension>([
+  'department',
+  'region',
+  'customer',
+  'vehicle-model',
+  'assessment-target',
+]);
+
+function validDate(value: string | null): string | undefined {
+  if (!value || !DATE_PATTERN.test(value)) return undefined;
+  const timestamp = Date.parse(`${value}T00:00:00+08:00`);
+  return Number.isFinite(timestamp) ? value : undefined;
+}
+
+function parseSourcePriority(value: string | null): MileageSourceGroup[] {
+  if (!value) return ['instrument'];
+  const sources = value
+    .split(',')
+    .filter((source): source is MileageSourceGroup => source === 'instrument' || source === 'gps');
+  return Array.from(new Set(sources)).slice(0, 2).length > 0
+    ? Array.from(new Set(sources)).slice(0, 2)
+    : ['instrument'];
+}
+
+export function parseMileageDrillContext(search: string): MileageDrillContext {
+  const params = new URLSearchParams(search);
+  const rawTargetId = Number(params.get('mileageTarget'));
+  const targetId = Number.isInteger(rawTargetId) && rawTargetId > 0 ? rawTargetId : undefined;
+  const rawAssessmentYear = Number(params.get('mileageYear'));
+  const assessmentYear = Number.isInteger(rawAssessmentYear) && rawAssessmentYear > 0
+    ? rawAssessmentYear
+    : undefined;
+  const plate = params.get('mileagePlate')?.trim() || undefined;
+  const rawDimension = params.get('mileageDimension');
+  const dimension = rawDimension && BREAKDOWN_DIMENSIONS.has(rawDimension as MileageBreakdownDimension)
+    ? rawDimension as MileageBreakdownDimension
+    : undefined;
+  const dimensionValue = params.get('mileageValue')?.trim() || undefined;
+  const requestedLevel = params.get('mileageLevel');
+
+  let level: MileageDrillLevel = 'overview';
+  if (requestedLevel === 'vehicle' && plate) level = 'vehicle';
+  if (requestedLevel === 'breakdown' && dimension && dimensionValue) level = 'breakdown';
+
+  const context: MileageDrillContext = {
+    level,
+    sourcePriority: parseSourcePriority(params.get('mileageSource')),
+  };
+  if (targetId) context.targetId = targetId;
+  if (targetId && assessmentYear) context.assessmentYear = assessmentYear;
+  if (level === 'breakdown') {
+    context.dimension = dimension;
+    context.dimensionValue = dimensionValue;
+  }
+  if (level === 'vehicle') context.plate = plate;
+  const startDate = validDate(params.get('mileageStart'));
+  const endDate = validDate(params.get('mileageEnd'));
+  if (startDate) context.startDate = startDate;
+  if (endDate) context.endDate = endDate;
+  return context;
+}
+
+export function buildMileageDrillUrl(
+  location: LocationParts,
+  context: MileageDrillContext,
+): string {
+  const params = new URLSearchParams(location.search);
+  for (const key of [
+    'mileageLevel',
+    'mileageTarget',
+    'mileageYear',
+    'mileageDimension',
+    'mileageValue',
+    'mileagePlate',
+    'mileageStart',
+    'mileageEnd',
+    'mileageSource',
+  ]) {
+    params.delete(key);
+  }
+
+  if (context.level !== 'overview') params.set('mileageLevel', context.level);
+  if (context.targetId) params.set('mileageTarget', String(context.targetId));
+  if (context.targetId && context.assessmentYear) params.set('mileageYear', String(context.assessmentYear));
+  if (context.level === 'breakdown' && context.dimension && context.dimensionValue) {
+    params.set('mileageDimension', context.dimension);
+    params.set('mileageValue', context.dimensionValue);
+  }
+  if (context.level === 'vehicle' && context.plate) params.set('mileagePlate', context.plate);
+  if (context.startDate) params.set('mileageStart', context.startDate);
+  if (context.endDate) params.set('mileageEnd', context.endDate);
+  if (context.sourcePriority.length > 0) params.set('mileageSource', context.sourcePriority.join(','));
+
+  const query = params.toString();
+  return `${location.pathname}${query ? `?${query}` : ''}${location.hash}`;
+}

src/modules/mileage/monitoring-context.test.ts

@@ -0,0 +1,100 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  buildMileageMonitoringUrl,
+  parseMileageMonitoringContext,
+} from './monitoring-context.js';
+
+test('parses a complete mileage monitoring context', () => {
+  const context = parseMileageMonitoringContext(
+    '?mileageStart=2026-08-01&mileageEnd=2026-08-07&mileageSource=gps,instrument'
+      + '&mileageBatch=%E4%BA%A4%E6%8A%95190%E8%BE%86&mileageBatch=%E7%BE%9A%E7%89%9B136%E8%BE%86'
+      + '&mileageRegion=%E5%B9%BF%E5%B7%9E&mileageFilterPlate=%E7%B2%A4A12345&mileageDepartment=%E4%B8%9A%E5%8A%A1%E4%B8%80%E9%83%A8'
+      + '&mileageCustomer=%E5%AE%A2%E6%88%B7A&mileageProject=%E9%A1%B9%E7%9B%AEA&mileageEntity=%E4%B8%BB%E4%BD%93A'
+      + '&mileageRentStatus=%E7%A7%9F%E8%B5%81&mileageBrand=%E7%8E%B0%E4%BB%A3&mileagePlatePrefix=%E7%B2%A4A'
+      + '&mileageSearch=123&mileageMin=10&mileageMax=500&mileageSort=total&mileageOrder=asc',
+  );
+
+  assert.deepEqual(context, {
+    startDate: '2026-08-01',
+    endDate: '2026-08-07',
+    sourcePriority: ['gps', 'instrument'],
+    targetNames: ['交投190辆', '羚牛136辆'],
+    region: '广州',
+    plates: ['粤A12345'],
+    department: '业务一部',
+    customer: '客户A',
+    project: '项目A',
+    entity: '主体A',
+    rentStatus: '租赁',
+    brands: ['现代'],
+    platePrefix: '粤A',
+    search: '123',
+    mileageMin: '10',
+    mileageMax: '500',
+    sortBy: 'total',
+    sortOrder: 'asc',
+  });
+});
+
+test('normalizes invalid monitoring URL values', () => {
+  const context = parseMileageMonitoringContext(
+    '?mileageStart=invalid&mileageSource=unknown&mileageBatch=&mileageRegion=All&mileageSort=unknown&mileageOrder=unknown',
+  );
+
+  assert.deepEqual(context, {
+    startDate: undefined,
+    endDate: undefined,
+    sourcePriority: ['instrument'],
+    targetNames: [],
+    region: undefined,
+    plates: [],
+    department: undefined,
+    customer: undefined,
+    project: undefined,
+    entity: undefined,
+    rentStatus: undefined,
+    brands: [],
+    platePrefix: undefined,
+    search: undefined,
+    mileageMin: undefined,
+    mileageMax: undefined,
+    sortBy: 'today',
+    sortOrder: 'desc',
+  });
+});
+
+test('builds monitoring state without removing drill or unrelated context', () => {
+  const url = buildMileageMonitoringUrl(
+    {
+      pathname: '/asset',
+      search: '?company=5&mileageLevel=vehicle&mileagePlate=%E7%B2%A4A08190F&mileageBatch=old',
+      hash: '#mileage',
+    },
+    {
+      startDate: '2026-08-01',
+      endDate: '2026-08-07',
+      sourcePriority: ['instrument'],
+      targetNames: ['交投190辆', '羚牛136辆'],
+      region: '广州',
+      plates: ['粤A12345'],
+      department: undefined,
+      customer: undefined,
+      project: undefined,
+      entity: undefined,
+      rentStatus: undefined,
+      brands: [],
+      platePrefix: undefined,
+      search: undefined,
+      mileageMin: undefined,
+      mileageMax: undefined,
+      sortBy: 'statisticTime',
+      sortOrder: 'asc',
+    },
+  );
+
+  assert.equal(
+    url,
+    '/asset?company=5&mileageLevel=vehicle&mileagePlate=%E7%B2%A4A08190F&mileageStart=2026-08-01&mileageEnd=2026-08-07&mileageSource=instrument&mileageBatch=%E4%BA%A4%E6%8A%95190%E8%BE%86&mileageBatch=%E7%BE%9A%E7%89%9B136%E8%BE%86&mileageRegion=%E5%B9%BF%E5%B7%9E&mileageFilterPlate=%E7%B2%A4A12345&mileageSort=statisticTime&mileageOrder=asc#mileage',
+  );
+});

src/modules/mileage/monitoring-context.ts

@@ -0,0 +1,136 @@
+import type { MileageSourceGroup } from './types';
+
+export type MonitoringSortBy = 'today' | 'total' | 'statisticTime';
+export type MonitoringSortOrder = 'asc' | 'desc';
+
+export interface MileageMonitoringContext {
+  startDate?: string;
+  endDate?: string;
+  sourcePriority: MileageSourceGroup[];
+  targetNames: string[];
+  region?: string;
+  plates: string[];
+  department?: string;
+  customer?: string;
+  project?: string;
+  entity?: string;
+  rentStatus?: string;
+  brands: string[];
+  platePrefix?: string;
+  search?: string;
+  mileageMin?: string;
+  mileageMax?: string;
+  sortBy: MonitoringSortBy;
+  sortOrder: MonitoringSortOrder;
+}
+
+interface LocationParts {
+  pathname: string;
+  search: string;
+  hash: string;
+}
+
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+const CONTEXT_KEYS = [
+  'mileageStart',
+  'mileageEnd',
+  'mileageSource',
+  'mileageBatch',
+  'mileageRegion',
+  'mileageFilterPlate',
+  'mileageDepartment',
+  'mileageCustomer',
+  'mileageProject',
+  'mileageEntity',
+  'mileageRentStatus',
+  'mileageBrand',
+  'mileagePlatePrefix',
+  'mileageSearch',
+  'mileageMin',
+  'mileageMax',
+  'mileageSort',
+  'mileageOrder',
+] as const;
+
+function validDate(value: string | null): string | undefined {
+  if (!value || !DATE_PATTERN.test(value)) return undefined;
+  const timestamp = Date.parse(`${value}T00:00:00+08:00`);
+  return Number.isFinite(timestamp) ? value : undefined;
+}
+
+function boundedValue(value: string | null, maxLength = 200): string | undefined {
+  const normalized = value?.trim();
+  if (!normalized || normalized === 'All') return undefined;
+  return normalized.slice(0, maxLength);
+}
+
+function uniqueValues(values: string[], limit = 200): string[] {
+  return Array.from(new Set(values.map(value => boundedValue(value)).filter((value): value is string => !!value))).slice(0, limit);
+}
+
+function parseSourcePriority(value: string | null): MileageSourceGroup[] {
+  const sources = value
+    ?.split(',')
+    .filter((source): source is MileageSourceGroup => source === 'instrument' || source === 'gps');
+  return sources && sources.length > 0 ? Array.from(new Set(sources)).slice(0, 2) : ['instrument'];
+}
+
+function appendValues(params: URLSearchParams, key: string, values: string[]): void {
+  uniqueValues(values).forEach(value => params.append(key, value));
+}
+
+export function parseMileageMonitoringContext(search: string): MileageMonitoringContext {
+  const params = new URLSearchParams(search);
+  const rawSortBy = params.get('mileageSort');
+  const rawSortOrder = params.get('mileageOrder');
+  return {
+    startDate: validDate(params.get('mileageStart')),
+    endDate: validDate(params.get('mileageEnd')),
+    sourcePriority: parseSourcePriority(params.get('mileageSource')),
+    targetNames: uniqueValues(params.getAll('mileageBatch')),
+    region: boundedValue(params.get('mileageRegion')),
+    plates: uniqueValues(params.getAll('mileageFilterPlate')),
+    department: boundedValue(params.get('mileageDepartment')),
+    customer: boundedValue(params.get('mileageCustomer')),
+    project: boundedValue(params.get('mileageProject')),
+    entity: boundedValue(params.get('mileageEntity')),
+    rentStatus: boundedValue(params.get('mileageRentStatus')),
+    brands: uniqueValues(params.getAll('mileageBrand')),
+    platePrefix: boundedValue(params.get('mileagePlatePrefix')),
+    search: boundedValue(params.get('mileageSearch')),
+    mileageMin: boundedValue(params.get('mileageMin'), 32),
+    mileageMax: boundedValue(params.get('mileageMax'), 32),
+    sortBy: rawSortBy === 'total' || rawSortBy === 'statisticTime' ? rawSortBy : 'today',
+    sortOrder: rawSortOrder === 'asc' ? 'asc' : 'desc',
+  };
+}
+
+export function buildMileageMonitoringUrl(
+  location: LocationParts,
+  context: MileageMonitoringContext,
+): string {
+  const params = new URLSearchParams(location.search);
+  CONTEXT_KEYS.forEach(key => params.delete(key));
+
+  if (context.startDate) params.set('mileageStart', context.startDate);
+  if (context.endDate) params.set('mileageEnd', context.endDate);
+  if (context.sourcePriority.length > 0) params.set('mileageSource', context.sourcePriority.join(','));
+  appendValues(params, 'mileageBatch', context.targetNames);
+  if (context.region) params.set('mileageRegion', context.region);
+  appendValues(params, 'mileageFilterPlate', context.plates);
+  if (context.department) params.set('mileageDepartment', context.department);
+  if (context.customer) params.set('mileageCustomer', context.customer);
+  if (context.project) params.set('mileageProject', context.project);
+  if (context.entity) params.set('mileageEntity', context.entity);
+  if (context.rentStatus) params.set('mileageRentStatus', context.rentStatus);
+  appendValues(params, 'mileageBrand', context.brands);
+  if (context.platePrefix) params.set('mileagePlatePrefix', context.platePrefix);
+  if (context.search) params.set('mileageSearch', context.search);
+  if (context.mileageMin) params.set('mileageMin', context.mileageMin);
+  if (context.mileageMax) params.set('mileageMax', context.mileageMax);
+  if (context.sortBy !== 'today') params.set('mileageSort', context.sortBy);
+  if (context.sortOrder !== 'desc') params.set('mileageOrder', context.sortOrder);
+
+  const query = params.toString();
+  return `${location.pathname}${query ? `?${query}` : ''}${location.hash}`;
+}

src/modules/mileage/monitoring-kpis.test.ts

@@ -0,0 +1,47 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildMonitoringKpis } from './monitoring-kpis.js';
+
+test('builds daily monitoring KPIs from the selected-day flow metric', () => {
+  const model = buildMonitoringKpis(
+    { totalToday: 120, totalAll: 3_000, vehicleCount: 3, yesterdayTotal: 100 },
+    { start: '2026-08-07', end: '2026-08-07' },
+  );
+
+  assert.deepEqual(model, {
+    distanceMetricId: 'mileage.daily_total',
+    distanceLabel: '当日总里程',
+    distanceShortLabel: '当日',
+    distanceKm: 120,
+    averagePerVehicleKm: 40,
+    vehicleCount: 3,
+    cumulativeOdometerKm: 3_000,
+  });
+});
+
+test('builds range KPIs without substituting cumulative odometer values', () => {
+  const model = buildMonitoringKpis(
+    { totalToday: 900, totalAll: 30_000, vehicleCount: 6, yesterdayTotal: 0 },
+    { start: '2026-08-01', end: '2026-08-07' },
+  );
+
+  assert.equal(model.distanceMetricId, 'mileage.period_total');
+  assert.equal(model.distanceLabel, '区间总里程');
+  assert.equal(model.distanceKm, 900);
+  assert.equal(model.averagePerVehicleKm, 150);
+  assert.equal(model.cumulativeOdometerKm, 30_000);
+});
+
+test('normalizes invalid monitoring KPI inputs', () => {
+  const model = buildMonitoringKpis({
+    totalToday: Number.NaN,
+    totalAll: -10,
+    vehicleCount: Number.POSITIVE_INFINITY,
+    yesterdayTotal: 0,
+  });
+
+  assert.equal(model.distanceKm, 0);
+  assert.equal(model.averagePerVehicleKm, 0);
+  assert.equal(model.vehicleCount, 0);
+  assert.equal(model.cumulativeOdometerKm, 0);
+});

src/modules/mileage/monitoring-kpis.ts

@@ -0,0 +1,31 @@
+import type { MonitoringStats } from './types';
+
+export interface MonitoringKpiModel {
+  distanceMetricId: 'mileage.daily_total' | 'mileage.period_total';
+  distanceLabel: '当日总里程' | '区间总里程';
+  distanceShortLabel: '当日' | '区间';
+  distanceKm: number;
+  averagePerVehicleKm: number;
+  vehicleCount: number;
+  cumulativeOdometerKm: number;
+}
+
+export function buildMonitoringKpis(
+  stats: MonitoringStats,
+  dateRange?: { start: string; end: string },
+): MonitoringKpiModel {
+  const isRange = !!dateRange?.start && !!dateRange?.end && dateRange.start !== dateRange.end;
+  const vehicleCount = Number.isFinite(stats.vehicleCount) ? Math.max(0, stats.vehicleCount) : 0;
+  const distanceKm = Number.isFinite(stats.totalToday) ? Math.max(0, stats.totalToday) : 0;
+  const cumulativeOdometerKm = Number.isFinite(stats.totalAll) ? Math.max(0, stats.totalAll) : 0;
+
+  return {
+    distanceMetricId: isRange ? 'mileage.period_total' : 'mileage.daily_total',
+    distanceLabel: isRange ? '区间总里程' : '当日总里程',
+    distanceShortLabel: isRange ? '区间' : '当日',
+    distanceKm,
+    averagePerVehicleKm: vehicleCount > 0 ? distanceKm / vehicleCount : 0,
+    vehicleCount,
+    cumulativeOdometerKm,
+  };
+}

src/modules/mileage/types.ts

@@ -1,3 +1,7 @@
+export type MileageSourceGroup = 'instrument' | 'gps';
+export type MileageSourceCategory = 'INSTRUMENT' | 'GPS' | 'MIXED';
+export type MileageSourceProtocol = 'GB32960' | 'MQTT' | 'JT808';
+
 export interface MonitoringVehicle {
   plate: string;
   vin: string;
@@ -5,6 +9,12 @@ export interface MonitoringVehicle {
   dailyMileage?: Record<string, number>;
   totalKm: number | null;
   source: string;
+  sourceProtocol: MileageSourceProtocol | null;
+  sourceCategory: MileageSourceCategory | null;
+  dailySourceProtocols?: Record<string, MileageSourceProtocol | null>;
+  dataTime: string | null;
+  calculatedAt: string | null;
+  updatedAt: string | null;
   isOnline: boolean;
   isDataSynced: boolean;
   customer: string | null;
@@ -14,6 +24,7 @@ export interface MonitoringVehicle {
   entity: string | null;
   project: string | null;
   region: string | null;
+  brand: string | null;
   targetNames: string[];
 }
 
@@ -34,6 +45,7 @@ export interface MonitoringFilters {
   platePrefixes: { prefix: string; count: number }[];
   targetNames: string[];
   regions: string[];
+  brands: string[];
 }
 
 export interface MonitoringData {
@@ -46,11 +58,14 @@ export interface MonitoringData {
   page: number;
   totalPages: number;
   updatedAt: string;
+  sourcePriority: MileageSourceGroup[];
 }
 
 export interface TargetSummary {
   id: number;
   targetName: string;
+  snapshotUpdatedAt: string | null;
+  declaredVehicleCount: number;
   vehicleCount: number;
   totalMileagePerVehicle: number;
   annualMileagePerVehicle: number;

src/modules/mileage/vehicle-detail-range.test.ts

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {
+  includeCurrentDayInVehicleDetail,
+  normalizeVehicleDetailContext,
+  resolveVehicleDetailRange,
+  vehicleDetailContextLabel,
+} from './vehicle-detail-range.js';
+
+const NOW = new Date(2026, 7, 7, 12, 0, 0);
+
+test('normalizes and preserves a selected vehicle drill range', () => {
+  const context = normalizeVehicleDetailContext('2026-08-07', '2026-08-05');
+  assert.deepEqual(context, { start: '2026-08-05', end: '2026-08-07' });
+  assert.deepEqual(resolveVehicleDetailRange('context', context, NOW), context);
+});
+
+test('rejects invalid context dates and resolves calendar presets', () => {
+  assert.equal(normalizeVehicleDetailContext('2026-02-30', '2026-03-01'), null);
+  assert.deepEqual(resolveVehicleDetailRange('last15', null, NOW), {
+    start: '2026-07-24',
+    end: '2026-08-07',
+  });
+  assert.deepEqual(resolveVehicleDetailRange('month', null, NOW), {
+    start: '2026-08-01',
+    end: '2026-08-07',
+  });
+  assert.deepEqual(resolveVehicleDetailRange('quarter', null, NOW), {
+    start: '2026-07-01',
+    end: '2026-08-07',
+  });
+});
+
+test('labels selected dates and includes today only for explicit context', () => {
+  const context = { start: '2026-08-07', end: '2026-08-07' };
+  assert.equal(vehicleDetailContextLabel(context), '8月7日');
+  assert.equal(includeCurrentDayInVehicleDetail('context'), true);
+  assert.equal(includeCurrentDayInVehicleDetail('last15'), false);
+});

src/modules/mileage/vehicle-detail-range.ts

@@ -0,0 +1,66 @@
+export type VehicleDetailRangeKey = 'context' | 'last15' | 'month' | 'quarter';
+
+export interface VehicleDetailDateRange {
+  start: string;
+  end: string;
+}
+
+const DATE_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+
+function fmtYmd(date: Date): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+function validDate(value?: string): string | null {
+  if (!value) return null;
+  const match = DATE_PATTERN.exec(value);
+  if (!match) return null;
+  const date = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+  return fmtYmd(date) === value ? value : null;
+}
+
+export function normalizeVehicleDetailContext(
+  startDate?: string,
+  endDate?: string,
+): VehicleDetailDateRange | null {
+  const start = validDate(startDate);
+  const end = validDate(endDate);
+  if (!start || !end) return null;
+  return start <= end ? { start, end } : { start: end, end: start };
+}
+
+export function resolveVehicleDetailRange(
+  key: VehicleDetailRangeKey,
+  context: VehicleDetailDateRange | null,
+  now = new Date(),
+): VehicleDetailDateRange {
+  if (key === 'context' && context) return context;
+
+  const today = new Date(now.getFullYear(), now.getMonth(), now.getDate());
+  const end = fmtYmd(today);
+  if (key === 'month') {
+    return { start: fmtYmd(new Date(today.getFullYear(), today.getMonth(), 1)), end };
+  }
+  if (key === 'quarter') {
+    const quarterStartMonth = Math.floor(today.getMonth() / 3) * 3;
+    return { start: fmtYmd(new Date(today.getFullYear(), quarterStartMonth, 1)), end };
+  }
+
+  const start = new Date(today);
+  start.setDate(today.getDate() - 14);
+  return { start: fmtYmd(start), end };
+}
+
+export function vehicleDetailContextLabel(context: VehicleDetailDateRange): string {
+  if (context.start === context.end) {
+    return `${Number(context.start.slice(5, 7))}月${Number(context.start.slice(8, 10))}日`;
+  }
+  return '所选区间';
+}
+
+export function includeCurrentDayInVehicleDetail(key: VehicleDetailRangeKey): boolean {
+  return key === 'context';
+}

src/modules/mileage/xlsx-export.ts

@@ -5,14 +5,21 @@ interface ExportContext {
   date?: string;
   startDate?: string;
   endDate?: string;
-  sortBy: 'today' | 'total';
+  sortBy: 'today' | 'total' | 'statisticTime';
 }
 
-const HEADERS = [
-  '状态', '车牌号', '客户', '业务部门', '项目', '租赁状态',
-  '运营区域', '区间里程(km)', '累计里程(km)',
+const BASE_HEADERS = [
+  '状态', '数据来源', '车牌号', '客户', '业务部门', '项目', '租赁状态',
+  '运营区域',
 ] as const;
 
+function sourceLabel(v: MonitoringVehicle): string {
+  if (v.sourceCategory === 'INSTRUMENT') return '仪表数据';
+  if (v.sourceCategory === 'GPS') return 'GPS数据';
+  if (v.sourceCategory === 'MIXED') return '仪表数据+GPS数据';
+  return v.isDataSynced ? '来源待接口' : '无数据';
+}
+
 function statusLabel(v: MonitoringVehicle): string {
   if (!v.isDataSynced) return '未对接';
   return v.isOnline ? '在线' : '离线';
@@ -20,7 +27,6 @@ function statusLabel(v: MonitoringVehicle): string {
 
 function mileageCell(v: MonitoringVehicle, kind: 'today' | 'total'): string | number {
   if (kind === 'today') {
-    // 区间内未对接但有历史累计，视作区间 0；只有完全无数据才标「未对接」。
     if (!v.isDataSynced && v.totalKm == null) return '未对接';
     return Math.max(0, v.dailyKm || 0);
   }
@@ -31,46 +37,73 @@ export function exportMileageXlsx(vehicles: MonitoringVehicle[], ctx: ExportCont
   const start = ctx.startDate || ctx.date || '';
   const end = ctx.endDate || ctx.date || '';
   const isRange = !!start && !!end && start !== end;
+
+  const dayKeys = Array.from(
+    new Set(vehicles.flatMap(v => Object.keys(v.dailyMileage || {})))
+  ).sort();
+
+  // 车辆汇总 sheet：基础列 + 每日里程列 + 区间合计 + 累计里程
+  const dailyHeaders = dayKeys.map(day => `${day.slice(5)}里程(km)`);
+  const summaryHeaders = [
+    ...BASE_HEADERS,
+    ...(dayKeys.length > 0 ? dailyHeaders : []),
+    isRange ? '区间合计(km)' : '当日里程(km)',
+    '累计里程(km)',
+  ];
+
   const summaryData: (string | number)[][] = [
-    [...HEADERS],
-    ...vehicles.map(v => [
-      statusLabel(v),
-      v.plate,
-      v.customer || '',
-      v.department || '',
-      v.project || '',
-      v.rentStatus || '',
-      v.region || '',
-      mileageCell(v, 'today'),
-      mileageCell(v, 'total'),
-    ]),
+    summaryHeaders,
+    ...vehicles.map(v => {
+      const baseRow = [
+        statusLabel(v),
+        sourceLabel(v),
+        v.plate,
+        v.customer || '',
+        v.department || '',
+        v.project || '',
+        v.rentStatus || '',
+        v.region || '',
+      ];
+      const dailyCols = dayKeys.map(day => v.dailyMileage?.[day] ?? 0);
+      return [
+        ...baseRow,
+        ...dailyCols,
+        mileageCell(v, 'today'),
+        mileageCell(v, 'total'),
+      ];
+    }),
   ];
 
   const ws = XLSX.utils.aoa_to_sheet(summaryData);
 
-  ws['!cols'] = [
+  const numFixedCols = BASE_HEADERS.length;
+  const wsCols: { wch: number }[] = [
     { wch: 8 },   // 状态
+    { wch: 16 },  // 数据来源
     { wch: 12 },  // 车牌号
     { wch: 28 },  // 客户
     { wch: 14 },  // 业务部门
     { wch: 16 },  // 项目
     { wch: 10 },  // 租赁状态
     { wch: 12 },  // 运营区域
-    { wch: 14 },  // 区间里程
-    { wch: 14 },  // 累计里程
   ];
+  for (let i = 0; i < dayKeys.length; i++) wsCols.push({ wch: 12 });
+  wsCols.push({ wch: 14 }); // 区间合计
+  wsCols.push({ wch: 14 }); // 累计里程
+  ws['!cols'] = wsCols;
 
-  ws['!freeze'] = { xSplit: 0, ySplit: 1 } as never;
+  // 冻结首行 + 固定列
+  ws['!freeze'] = { xSplit: numFixedCols, ySplit: 1 } as never;
 
   for (let r = 1; r < summaryData.length; r++) {
-    for (const c of [7, 8]) {
+    for (let c = numFixedCols; c < summaryHeaders.length; c++) {
       const ref = XLSX.utils.encode_cell({ r, c });
       if (ws[ref]?.t === 'n') ws[ref].z = '0.##########';
     }
   }
 
-  // 表头样式（在客户端 SheetJS 社区版仅基本样式生效）
-  for (let c = 0; c < HEADERS.length; c++) {
+  // 表头样式
+  for (let c = 0; c < summaryHeaders.length; c++) {
     const ref = XLSX.utils.encode_cell({ r: 0, c });
     if (ws[ref]) {
       (ws[ref] as { s?: unknown }).s = {
@@ -84,12 +117,10 @@ export function exportMileageXlsx(vehicles: MonitoringVehicle[], ctx: ExportCont
   const wb = XLSX.utils.book_new();
   XLSX.utils.book_append_sheet(wb, ws, '车辆汇总');
 
-  const dayKeys = Array.from(
-    new Set(vehicles.flatMap(v => Object.keys(v.dailyMileage || {})))
-  ).sort();
+  // 每日明细 sheet：保留原有格式
   if (dayKeys.length > 0) {
     const detailHeaders = [
-      '车牌号', '客户', '业务部门', '项目', '租赁状态', '运营区域',
+      '车牌号', '数据来源', '客户', '业务部门', '项目', '租赁状态', '运营区域',
       ...dayKeys.map(day => `${day}里程(km)`),
       '区间合计(km)',
       '累计里程(km)',
@@ -98,6 +129,7 @@ export function exportMileageXlsx(vehicles: MonitoringVehicle[], ctx: ExportCont
       detailHeaders,
       ...vehicles.map(v => [
         v.plate,
+        sourceLabel(v),
         v.customer || '',
         v.department || '',
         v.project || '',
@@ -111,6 +143,7 @@ export function exportMileageXlsx(vehicles: MonitoringVehicle[], ctx: ExportCont
     const detailWs = XLSX.utils.aoa_to_sheet(detailData);
     detailWs['!cols'] = [
       { wch: 12 },
+      { wch: 16 },
       { wch: 28 },
       { wch: 14 },
       { wch: 16 },
@@ -120,9 +153,9 @@ export function exportMileageXlsx(vehicles: MonitoringVehicle[], ctx: ExportCont
       { wch: 14 },
       { wch: 14 },
     ];
-    detailWs['!freeze'] = { xSplit: 6, ySplit: 1 } as never;
+    detailWs['!freeze'] = { xSplit: 7, ySplit: 1 } as never;
     for (let r = 1; r < detailData.length; r++) {
-      for (let c = 6; c < detailHeaders.length; c++) {
+      for (let c = 7; c < detailHeaders.length; c++) {
         const ref = XLSX.utils.encode_cell({ r, c });
         if (detailWs[ref]?.t === 'n') detailWs[ref].z = '0.##########';
       }
@@ -139,6 +172,11 @@ export function exportMileageXlsx(vehicles: MonitoringVehicle[], ctx: ExportCont
   const dateTag = start && end
     ? `${start.replace(/-/g, '')}-${end.replace(/-/g, '')}`
     : `${y}${m}${d}`;
-  const filename = `里程看板_${dateTag}_${hh}${mm}_${ctx.sortBy === 'today' ? (isRange ? '区间' : '今日') : '累计'}.xlsx`;
+  const sortLabel = ctx.sortBy === 'total'
+    ? '累计'
+    : ctx.sortBy === 'statisticTime'
+      ? '统计时间'
+      : isRange ? '区间' : '今日';
+  const filename = `里程看板_${dateTag}_${hh}${mm}_${sortLabel}.xlsx`;
   XLSX.writeFile(wb, filename);
 }

src/modules/vehicle-heatmap/AmapHeatmapCanvas.tsx

@@ -0,0 +1,158 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import type { AmapConfig, HeatmapMetric, HeatmapPoint } from './types';
+
+type Props = {
+  config: AmapConfig;
+  points: HeatmapPoint[];
+  max: number;
+  metric: HeatmapMetric;
+  focusQuery: string;
+  onMapClick: (longitude: number, latitude: number) => void;
+};
+
+type AmapInstance = {
+  Map: new (container: HTMLElement, options: Record<string, unknown>) => any;
+  HeatMap: new (map: any, options: Record<string, unknown>) => any;
+  ToolBar: new (options?: Record<string, unknown>) => any;
+  Scale: new (options?: Record<string, unknown>) => any;
+  Bounds: new (southWest: [number, number], northEast: [number, number]) => any;
+};
+
+declare global {
+  interface Window {
+    _AMapSecurityConfig?: { securityJsCode: string };
+  }
+}
+
+function getBounds(points: HeatmapPoint[]) {
+  if (points.length === 0) return null;
+  let minLng = points[0].lng;
+  let maxLng = points[0].lng;
+  let minLat = points[0].lat;
+  let maxLat = points[0].lat;
+  for (let index = 1; index < points.length; index += 1) {
+    const point = points[index];
+    minLng = Math.min(minLng, point.lng);
+    maxLng = Math.max(maxLng, point.lng);
+    minLat = Math.min(minLat, point.lat);
+    maxLat = Math.max(maxLat, point.lat);
+  }
+  return { minLng, maxLng, minLat, maxLat };
+}
+
+export default function AmapHeatmapCanvas({ config, points, max, metric, focusQuery, onMapClick }: Props) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const mapRef = useRef<any>(null);
+  const heatmapRef = useRef<any>(null);
+  const amapRef = useRef<AmapInstance | null>(null);
+  const clickHandlerRef = useRef(onMapClick);
+  const [status, setStatus] = useState<'loading' | 'ready' | 'error'>('loading');
+  const intensity = useMemo(() => {
+    const transform = metric === 'locations'
+      ? (value: number) => Math.log1p(value)
+      : (value: number) => Math.sqrt(value);
+    return {
+      points: points.map((point) => ({ ...point, count: transform(point.count) })),
+      max: transform(Math.max(1, max)),
+    };
+  }, [max, metric, points]);
+
+  useEffect(() => {
+    clickHandlerRef.current = onMapClick;
+  }, [onMapClick]);
+
+  useEffect(() => {
+    let cancelled = false;
+    const container = containerRef.current;
+    if (!container) return undefined;
+
+    async function initialize() {
+      try {
+        window._AMapSecurityConfig = { securityJsCode: config.securityCode };
+        const loaderModule = await import('@amap/amap-jsapi-loader');
+        const AMap = await loaderModule.default.load({
+          key: config.key,
+          version: '2.0',
+          plugins: ['AMap.HeatMap', 'AMap.ToolBar', 'AMap.Scale'],
+        }) as unknown as AmapInstance;
+        if (cancelled || !container) return;
+
+        const map = new AMap.Map(container, {
+          viewMode: '2D',
+          zoom: 5,
+          center: [105.4, 34.4],
+          mapStyle: 'amap://styles/whitesmoke',
+          resizeEnable: true,
+          showLabel: true,
+        });
+        map.addControl(new AMap.ToolBar({ position: { right: '20px', bottom: '76px' } }));
+        map.addControl(new AMap.Scale({ position: { right: '18px', bottom: '24px' } }));
+        const heatmap = new AMap.HeatMap(map, {
+          radius: 25,
+          opacity: [0.12, 0.82],
+          gradient: {
+            0.1: '#2563eb',
+            0.3: '#0891b2',
+            0.5: '#16a34a',
+            0.68: '#eab308',
+            0.84: '#f97316',
+            1: '#dc2626',
+          },
+        });
+        map.on('click', (event: any) => {
+          clickHandlerRef.current(event.lnglat.getLng(), event.lnglat.getLat());
+        });
+        mapRef.current = map;
+        heatmapRef.current = heatmap;
+        amapRef.current = AMap;
+        setStatus('ready');
+      } catch (error) {
+        console.error('AMap initialization failed', error);
+        if (!cancelled) setStatus('error');
+      }
+    }
+
+    initialize();
+    return () => {
+      cancelled = true;
+      heatmapRef.current?.setMap?.(null);
+      mapRef.current?.destroy?.();
+      heatmapRef.current = null;
+      mapRef.current = null;
+      amapRef.current = null;
+    };
+  }, [config.key, config.securityCode]);
+
+  useEffect(() => {
+    if (status !== 'ready' || !heatmapRef.current) return;
+    heatmapRef.current.setDataSet({ data: intensity.points, max: intensity.max });
+
+    if (!focusQuery || points.length === 0 || !mapRef.current || !amapRef.current) return;
+    const bounds = getBounds(points);
+    if (!bounds) return;
+    if (points.length === 1) {
+      mapRef.current.setZoomAndCenter(12, [points[0].lng, points[0].lat]);
+      return;
+    }
+    mapRef.current.setBounds(new amapRef.current.Bounds(
+      [bounds.minLng, bounds.minLat],
+      [bounds.maxLng, bounds.maxLat],
+    ), false, [80, 80, 80, 80]);
+  }, [focusQuery, intensity, points, status]);
+
+  return (
+    <div className="absolute inset-0 bg-[#eef3f7]">
+      <div ref={containerRef} className="h-full w-full" aria-label="车辆运营热力图地图" />
+      {status === 'loading' ? (
+        <div className="absolute inset-0 grid place-items-center bg-white/76 text-sm font-medium text-slate-500 backdrop-blur-[2px]">
+          <span className="flex items-center gap-2.5"><i className="h-4 w-4 animate-spin rounded-full border-2 border-blue-600 border-t-transparent" />正在加载高德地图</span>
+        </div>
+      ) : null}
+      {status === 'error' ? (
+        <div className="absolute inset-0 grid place-items-center bg-slate-50 text-center">
+          <div><p className="text-sm font-semibold text-slate-700">地图加载失败</p><p className="mt-1 text-xs text-slate-400">请检查高德 Key、域名白名单与网络连接</p></div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

src/modules/vehicle-heatmap/HeatmapDetailPanel.tsx

@@ -0,0 +1,86 @@
+import { ChevronRight, Crosshair, X } from 'lucide-react';
+import type { VehicleRank } from './types';
+
+type Props = {
+  title: string;
+  subtitle: string;
+  locationCount: number;
+  vehicleCount: number;
+  vehicles: VehicleRank[];
+  selected: boolean;
+  loading: boolean;
+  onClose: () => void;
+  onHide: () => void;
+};
+
+const numberFormat = new Intl.NumberFormat('zh-CN');
+
+export default function HeatmapDetailPanel(props: Props) {
+  return (
+    <aside className="relative z-20 flex h-full w-[300px] shrink-0 flex-col border-l border-slate-200 bg-white max-lg:absolute max-lg:bottom-0 max-lg:left-0 max-lg:right-0 max-lg:h-[43vh] max-lg:w-full max-lg:rounded-t-2xl max-lg:border-l-0 max-lg:border-t max-lg:shadow-[0_-10px_30px_rgba(15,23,42,0.14)] max-md:h-[50dvh]">
+      <div className="border-b border-slate-100 px-5 pb-4 pt-5 max-md:px-4 max-md:pb-3 max-md:pt-3">
+        <div className="flex items-start justify-between gap-3">
+          <div>
+            <div className="flex items-center gap-2">
+              <h2 className="text-[17px] font-semibold tracking-tight text-slate-900">{props.title}</h2>
+              {props.loading ? <i className="h-3.5 w-3.5 animate-spin rounded-full border-2 border-blue-600 border-t-transparent" /> : null}
+            </div>
+            <p className="mt-1 text-[11px] text-slate-400">{props.subtitle}</p>
+          </div>
+          <div className="flex shrink-0 items-center gap-1">
+            {props.selected ? (
+              <button type="button" onClick={props.onClose} aria-label="关闭区域详情" className="grid h-8 w-8 place-items-center rounded-lg text-slate-400 hover:bg-slate-50 hover:text-slate-700">
+                <X size={18} strokeWidth={1.8} />
+              </button>
+            ) : null}
+            <button
+              type="button"
+              onClick={props.onHide}
+              aria-label="隐藏详情"
+              title="隐藏详情"
+              className="grid h-8 w-8 place-items-center rounded-lg text-slate-400 transition hover:bg-blue-50 hover:text-blue-600 max-md:h-10 max-md:w-10"
+            >
+              <ChevronRight size={18} strokeWidth={1.8} />
+            </button>
+          </div>
+        </div>
+
+        <div className="mt-5 grid grid-cols-2 divide-x divide-slate-200 border-t border-slate-100 pt-4 max-md:mt-3 max-md:pt-3">
+          <div>
+            <p className="text-[11px] text-slate-400">定位点数</p>
+            <p className="mt-1 text-[22px] font-semibold tracking-tight text-blue-600">{numberFormat.format(props.locationCount)}</p>
+          </div>
+          <div className="pl-5">
+            <p className="text-[11px] text-slate-400">车辆数</p>
+            <p className="mt-1 text-[22px] font-semibold tracking-tight text-blue-600">{numberFormat.format(props.vehicleCount)}</p>
+          </div>
+        </div>
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-auto px-5 py-4 max-md:px-4 max-md:py-3">
+        <div className="mb-3 flex items-center justify-between">
+          <h3 className="text-[13px] font-semibold text-slate-800">车辆 TOP10</h3>
+          <span className="text-[10px] text-slate-400">按出现天数排序</span>
+        </div>
+        {props.vehicles.length ? (
+          <ol className="divide-y divide-slate-100">
+            {props.vehicles.map((vehicle, index) => (
+              <li key={vehicle.vin} className="grid grid-cols-[24px_minmax(0,1fr)_42px] items-center gap-2 py-2.5">
+                <span className={`text-[11px] font-medium ${index < 3 ? 'text-blue-600' : 'text-slate-400'}`}>{index + 1}</span>
+                <span className="min-w-0">
+                  <span className="block truncate text-[12px] font-medium text-slate-700">{vehicle.plateNumber || '未绑定车牌'}</span>
+                  <span className="mt-0.5 block truncate font-mono text-[9px] text-slate-400">{vehicle.vin}</span>
+                </span>
+                <span className="text-right text-[12px] tabular-nums text-slate-600">{vehicle.locationCount}</span>
+              </li>
+            ))}
+          </ol>
+        ) : (
+          <div className="grid h-44 place-items-center text-center text-xs text-slate-400">
+            <span><Crosshair className="mx-auto mb-2 text-slate-300" size={22} />该区域暂无车辆定位</span>
+          </div>
+        )}
+      </div>
+    </aside>
+  );
+}

src/modules/vehicle-heatmap/HeatmapFilters.tsx

@@ -0,0 +1,115 @@
+import { CalendarDays, ChevronUp, RotateCcw, Search } from 'lucide-react';
+import type { HeatmapMetric, VehicleOption } from './types';
+
+type Props = {
+  startDate: string;
+  endDate: string;
+  minDate: string;
+  maxDate: string;
+  query: string;
+  batchModel: string;
+  batchModels: string[];
+  metric: HeatmapMetric;
+  vehicles: VehicleOption[];
+  onStartDateChange: (value: string) => void;
+  onEndDateChange: (value: string) => void;
+  onQueryChange: (value: string) => void;
+  onBatchModelChange: (value: string) => void;
+  onMetricChange: (value: HeatmapMetric) => void;
+  onReset: () => void;
+  onHide: () => void;
+};
+
+const FIELD = 'relative h-11 min-w-0 rounded-lg border border-slate-200 bg-white transition focus-within:border-blue-400 focus-within:ring-2 focus-within:ring-blue-100';
+const LABEL = 'pointer-events-none absolute left-3 top-1 z-10 text-[9px] font-medium leading-none text-slate-400';
+const CONTROL = 'h-full w-full min-w-0 rounded-lg border-0 bg-transparent px-3 pt-3 text-[12px] text-slate-700 outline-none';
+
+export default function HeatmapFilters(props: Props) {
+  return (
+    <div className="pointer-events-auto grid max-h-[calc(100dvh-180px)] w-full grid-cols-2 gap-2 overflow-y-auto rounded-xl border border-slate-200/80 bg-white/96 p-2 shadow-[0_8px_28px_rgba(15,23,42,0.12)] backdrop-blur-md md:flex md:w-auto md:min-w-max md:items-center md:overflow-visible">
+      <label className={`${FIELD} col-span-2 md:w-[320px]`}>
+        <span className={`${LABEL} left-9`}>日期范围</span>
+        <span className="flex h-full min-w-0 items-center pl-8 pt-2">
+          <CalendarDays className="absolute left-3 top-1/2 -translate-y-1/2 text-slate-400" size={15} strokeWidth={1.8} />
+          <input
+            aria-label="开始日期"
+            type="date"
+            min={props.minDate}
+            max={props.endDate}
+            value={props.startDate}
+            onChange={(event) => props.onStartDateChange(event.target.value)}
+            className="h-full w-[124px] min-w-0 flex-1 border-0 bg-transparent px-1 text-[12px] text-slate-700 outline-none"
+          />
+          <span className="shrink-0 px-0.5 text-slate-300">—</span>
+          <input
+            aria-label="结束日期"
+            type="date"
+            min={props.startDate}
+            max={props.maxDate}
+            value={props.endDate}
+            onChange={(event) => props.onEndDateChange(event.target.value)}
+            className="h-full w-[124px] min-w-0 flex-1 border-0 bg-transparent px-1 text-[12px] text-slate-700 outline-none"
+          />
+        </span>
+      </label>
+
+      <label className={`${FIELD} col-span-2 md:w-[145px]`}>
+        <span className={LABEL}>VIN / 车牌</span>
+        <span className="relative block h-full">
+          <input
+            aria-label="搜索 VIN 或车牌"
+            value={props.query}
+            list="vehicle-heatmap-options"
+            onChange={(event) => props.onQueryChange(event.target.value)}
+            placeholder="输入 VIN 或车牌"
+            className={`${CONTROL} pr-9`}
+          />
+          <Search className="pointer-events-none absolute right-3 top-1/2 -translate-y-1/2 text-slate-400" size={16} strokeWidth={1.8} />
+          <datalist id="vehicle-heatmap-options">
+            {props.vehicles.map((vehicle) => (
+              <option key={vehicle.vin} value={vehicle.plateNumber || vehicle.vin}>{vehicle.vin}</option>
+            ))}
+          </datalist>
+        </span>
+      </label>
+
+      <label className={`${FIELD} col-span-2 md:w-[150px]`}>
+        <span className={LABEL}>车型 / 批次型号</span>
+        <select
+          aria-label="车型 / 批次型号"
+          value={props.batchModel}
+          onChange={(event) => props.onBatchModelChange(event.target.value)}
+          className={CONTROL}
+          title={props.batchModel || '全部车型'}
+        >
+          <option value="">全部车型</option>
+          {props.batchModels.map((batchModel) => (
+            <option key={batchModel} value={batchModel}>{batchModel}</option>
+          ))}
+        </select>
+      </label>
+
+      <label className={`${FIELD} md:w-[110px]`}>
+        <span className={LABEL}>统计维度</span>
+        <select
+          aria-label="统计维度"
+          value={props.metric}
+          onChange={(event) => props.onMetricChange(event.target.value as HeatmapMetric)}
+          className={CONTROL}
+        >
+          <option value="locations">定位活跃度</option>
+          <option value="vehicles">车辆覆盖度</option>
+        </select>
+      </label>
+
+      <div className="flex min-w-0 gap-2 md:w-auto">
+        <button type="button" onClick={props.onReset} className="flex h-11 min-w-0 flex-1 items-center justify-center gap-1.5 rounded-lg border border-slate-200 bg-white px-2.5 text-[12px] font-medium text-slate-600 transition hover:border-blue-300 hover:bg-blue-50 hover:text-blue-600 md:flex-none">
+          <RotateCcw size={14} strokeWidth={1.8} />重置
+        </button>
+        <button type="button" onClick={props.onHide} aria-label="隐藏筛选" title="隐藏筛选" className="grid h-11 w-11 shrink-0 place-items-center rounded-lg border border-slate-200 bg-white text-slate-400 transition hover:border-blue-300 hover:bg-blue-50 hover:text-blue-600 md:w-10">
+          <ChevronUp size={16} strokeWidth={1.8} />
+        </button>
+      </div>
+    </div>
+  );
+}

src/modules/vehicle-heatmap/VehicleHeatmapModule.tsx

@@ -0,0 +1,249 @@
+import { useCallback, useDeferredValue, useEffect, useMemo, useState } from 'react';
+import { AlertTriangle, ChevronLeft, Clock3, MapPinned, Maximize2, Minimize2, SlidersHorizontal } from 'lucide-react';
+import AmapHeatmapCanvas from './AmapHeatmapCanvas';
+import HeatmapDetailPanel from './HeatmapDetailPanel';
+import HeatmapFilters from './HeatmapFilters';
+import { fetchAmapConfig, fetchHeatmapMeta, fetchHeatmapPoints, fetchNearbyVehicles } from './api';
+import type { AmapConfig, HeatmapMeta, HeatmapMetric, HeatmapResponse, NearbyResponse } from './types';
+
+const DEFAULT_START = '2026-01-01';
+const DEFAULT_END = '2026-07-13';
+const numberFormat = new Intl.NumberFormat('zh-CN');
+
+function Metric({ value, label }: { value: number; label: string }) {
+  return (
+    <div className="min-w-[82px] text-center max-md:min-w-[64px]">
+      <p className="text-[22px] font-semibold leading-none tracking-tight text-blue-600 tabular-nums max-md:text-[16px]">{numberFormat.format(value)}</p>
+      <p className="mt-1.5 text-[11px] text-slate-500 max-md:mt-1 max-md:text-[9px]">{label}</p>
+    </div>
+  );
+}
+
+export default function VehicleHeatmapModule() {
+  const [meta, setMeta] = useState<HeatmapMeta | null>(null);
+  const [config, setConfig] = useState<AmapConfig | null>(null);
+  const [data, setData] = useState<HeatmapResponse | null>(null);
+  const [nearby, setNearby] = useState<NearbyResponse | null>(null);
+  const [startDate, setStartDate] = useState(DEFAULT_START);
+  const [endDate, setEndDate] = useState(DEFAULT_END);
+  const [query, setQuery] = useState('');
+  const [batchModel, setBatchModel] = useState('');
+  const [metric, setMetric] = useState<HeatmapMetric>('locations');
+  const [isFullscreen, setIsFullscreen] = useState(false);
+  const [showFilters, setShowFilters] = useState(() => typeof window === 'undefined' || !window.matchMedia('(max-width: 767px)').matches);
+  const [showDetails, setShowDetails] = useState(() => typeof window === 'undefined' || !window.matchMedia('(max-width: 767px)').matches);
+  const [loading, setLoading] = useState(true);
+  const [nearbyLoading, setNearbyLoading] = useState(false);
+  const [error, setError] = useState('');
+  const deferredQuery = useDeferredValue(query.trim());
+
+  useEffect(() => {
+    if (!isFullscreen) return undefined;
+    const previousOverflow = document.body.style.overflow;
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'Escape') setIsFullscreen(false);
+    };
+    document.body.style.overflow = 'hidden';
+    document.addEventListener('keydown', handleKeyDown);
+    return () => {
+      document.body.style.overflow = previousOverflow;
+      document.removeEventListener('keydown', handleKeyDown);
+    };
+  }, [isFullscreen]);
+
+  const toggleFullscreen = useCallback(() => {
+    setIsFullscreen((current) => !current);
+  }, []);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    Promise.all([fetchHeatmapMeta(controller.signal), fetchAmapConfig(controller.signal)])
+      .then(([nextMeta, nextConfig]) => {
+        setMeta(nextMeta);
+        setConfig(nextConfig);
+        setStartDate(nextMeta.startDate);
+        setEndDate(nextMeta.endDate);
+      })
+      .catch((requestError) => {
+        if (requestError?.name !== 'AbortError') setError('热力图基础配置加载失败');
+      });
+    return () => controller.abort();
+  }, []);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const timer = window.setTimeout(() => {
+      setLoading(true);
+      setError('');
+      fetchHeatmapPoints({ startDate, endDate, query: deferredQuery, batchModel, metric }, controller.signal)
+        .then((response) => {
+          setData(response);
+          setNearby(null);
+        })
+        .catch((requestError) => {
+          if (requestError?.name !== 'AbortError') setError('热力图数据加载失败，请稍后重试');
+        })
+        .finally(() => setLoading(false));
+    }, 220);
+    return () => {
+      window.clearTimeout(timer);
+      controller.abort();
+    };
+  }, [batchModel, deferredQuery, endDate, metric, startDate]);
+
+  const handleMapClick = useCallback((longitude: number, latitude: number) => {
+    const controller = new AbortController();
+    setNearbyLoading(true);
+    fetchNearbyVehicles({ lng: longitude, lat: latitude, startDate, endDate, query: deferredQuery, batchModel }, controller.signal)
+      .then(setNearby)
+      .catch((requestError) => {
+        if (requestError?.name !== 'AbortError') setError('区域车辆明细加载失败');
+      })
+      .finally(() => setNearbyLoading(false));
+  }, [batchModel, deferredQuery, endDate, startDate]);
+
+  const reset = () => {
+    setStartDate(meta?.startDate || DEFAULT_START);
+    setEndDate(meta?.endDate || DEFAULT_END);
+    setQuery('');
+    setBatchModel('');
+    setMetric('locations');
+    setNearby(null);
+  };
+
+  const detail = useMemo(() => {
+    if (nearby) {
+      return {
+        title: '选中区域',
+        subtitle: `${nearby.center.lng.toFixed(3)}, ${nearby.center.lat.toFixed(3)} · 半径 ${nearby.radiusKm} 公里`,
+        locationCount: nearby.locationCount,
+        vehicleCount: nearby.vehicleCount,
+        vehicles: nearby.topVehicles,
+        selected: true,
+      };
+    }
+    return {
+      title: deferredQuery ? '车辆定位概览' : '全国 · 当前范围',
+      subtitle: `${batchModel ? `${batchModel} · ` : ''}${startDate} ～ ${endDate}`,
+      locationCount: data?.locationCount || 0,
+      vehicleCount: data?.vehicleCount || 0,
+      vehicles: data?.topVehicles || [],
+      selected: false,
+    };
+  }, [batchModel, data, deferredQuery, endDate, nearby, startDate]);
+
+  return (
+    <section className={`flex flex-col overflow-hidden bg-white ${isFullscreen ? 'fixed inset-0 z-[100] h-screen w-screen min-h-0' : 'h-[100dvh] min-h-[620px] max-md:h-[calc(100dvh-4rem)] max-md:min-h-[520px]'}`}>
+      <header className="relative z-30 flex min-h-[98px] shrink-0 items-center justify-between border-b border-slate-200 bg-white px-8 max-md:min-h-[104px] max-md:flex-wrap max-md:gap-y-2 max-md:px-3 max-md:py-3">
+        <div className="min-w-0">
+          <h1 className="truncate text-[25px] font-semibold tracking-[-0.025em] text-slate-950 max-md:text-[18px]">车辆运营热力图</h1>
+          <p className="mt-1.5 flex items-center gap-1.5 text-[11px] text-slate-400 max-md:mt-1 max-md:text-[9px]"><MapPinned size={13} />每日每车首个有效定位 · 上海时区</p>
+        </div>
+        <div className="absolute left-1/2 top-1/2 flex -translate-x-1/2 -translate-y-1/2 items-center gap-7 max-md:order-3 max-md:static max-md:w-full max-md:translate-x-0 max-md:translate-y-0 max-md:justify-center max-md:gap-2">
+          <Metric value={data?.locationCount ?? meta?.locationCount ?? 0} label="定位点" />
+          <span className="h-8 w-px bg-slate-200" />
+          <Metric value={data?.vehicleCount ?? meta?.vehicleCount ?? 0} label="辆车" />
+          <span className="h-8 w-px bg-slate-200" />
+          <Metric value={data?.dayCount ?? meta?.dayCount ?? 0} label="天" />
+        </div>
+        <div className="flex items-center gap-3">
+          <p className="flex items-center gap-2 text-[12px] text-slate-500 max-xl:hidden"><Clock3 size={15} strokeWidth={1.7} />数据更新至 {meta?.endDate || DEFAULT_END}</p>
+          <button
+            type="button"
+            onClick={toggleFullscreen}
+            className="grid h-9 w-9 place-items-center rounded-lg border border-slate-200 text-slate-500 transition hover:border-blue-300 hover:bg-blue-50 hover:text-blue-600"
+            title={isFullscreen ? '退出全屏' : '地图全屏'}
+            aria-label={isFullscreen ? '退出地图全屏' : '地图全屏'}
+            aria-pressed={isFullscreen}
+          >
+            {isFullscreen ? <Minimize2 size={17} /> : <Maximize2 size={17} />}
+          </button>
+        </div>
+      </header>
+
+      <div className="relative flex min-h-0 flex-1">
+        <div className="relative z-0 min-w-0 flex-1 overflow-hidden">
+          {config ? (
+            <AmapHeatmapCanvas
+              config={config}
+              points={data?.points || []}
+              max={data?.max || 1}
+              metric={metric}
+              focusQuery={deferredQuery}
+              onMapClick={handleMapClick}
+            />
+          ) : <div className="absolute inset-0 bg-slate-100" />}
+
+          {showFilters ? (
+            <div className="pointer-events-none absolute left-3 right-3 top-3 z-10 md:left-5 md:right-auto md:top-5">
+              <HeatmapFilters
+                startDate={startDate}
+                endDate={endDate}
+                minDate={meta?.startDate || DEFAULT_START}
+                maxDate={meta?.endDate || DEFAULT_END}
+                query={query}
+                batchModel={batchModel}
+                batchModels={meta?.batchModels || []}
+                metric={metric}
+                vehicles={meta?.vehicles || []}
+                onStartDateChange={setStartDate}
+                onEndDateChange={setEndDate}
+                onQueryChange={setQuery}
+                onBatchModelChange={setBatchModel}
+                onMetricChange={setMetric}
+                onReset={reset}
+                onHide={() => setShowFilters(false)}
+              />
+            </div>
+          ) : (
+            <button
+              type="button"
+              onClick={() => setShowFilters(true)}
+              aria-label="显示筛选"
+              className="absolute left-3 top-3 z-20 flex h-11 items-center gap-2 rounded-lg border border-slate-200 bg-white/95 px-3 text-xs font-medium text-slate-600 shadow-lg backdrop-blur-sm transition hover:border-blue-300 hover:bg-blue-50 hover:text-blue-600 md:left-5 md:top-5 md:h-10"
+            >
+              <SlidersHorizontal size={15} strokeWidth={1.8} />显示筛选
+            </button>
+          )}
+
+          {!showDetails ? (
+            <button
+              type="button"
+              onClick={() => setShowDetails(true)}
+              aria-label="显示详情"
+              className={`absolute right-3 top-3 z-20 flex h-11 items-center gap-2 rounded-lg border border-slate-200 bg-white/95 px-3 text-xs font-medium text-slate-600 shadow-lg backdrop-blur-sm transition hover:border-blue-300 hover:bg-blue-50 hover:text-blue-600 md:right-5 md:top-5 md:h-10 ${showFilters ? 'max-md:hidden' : ''}`}
+            >
+              <ChevronLeft size={16} strokeWidth={1.8} />显示详情
+            </button>
+          ) : null}
+
+          <div className="pointer-events-none absolute bottom-5 left-5 z-10 w-[286px] rounded-xl border border-slate-200/80 bg-white/95 p-3.5 shadow-[0_8px_30px_rgba(15,23,42,0.11)] backdrop-blur-sm max-lg:bottom-[calc(43vh+16px)] max-md:hidden">
+            <div className="flex items-center justify-between text-[11px] font-medium text-slate-700"><span>{metric === 'locations' ? '定位活跃度' : '车辆覆盖度'}</span>{loading ? <i className="h-3 w-3 animate-spin rounded-full border-2 border-blue-600 border-t-transparent" /> : null}</div>
+            <p className="mt-1 text-[10px] leading-4 text-slate-500">
+              {metric === 'locations'
+                ? '同一网格累计每日首个定位，同车跨天重复计数；对数平滑强度。'
+                : '同一网格按 VIN 去重，同车仅计 1 辆；平方根平滑强度。'}
+            </p>
+            <div className="mt-2.5 h-2.5 rounded-full bg-[linear-gradient(90deg,#2563eb_0%,#0891b2_25%,#16a34a_45%,#eab308_65%,#f97316_82%,#dc2626_100%)]" />
+            <div className="mt-1.5 flex justify-between text-[10px] text-slate-400"><span>相对较低</span><span>相对较高</span></div>
+          </div>
+
+          {error ? (
+            <div className="absolute bottom-5 left-1/2 z-30 flex -translate-x-1/2 items-center gap-2 rounded-lg bg-slate-900 px-4 py-2.5 text-xs text-white shadow-xl">
+              <AlertTriangle size={15} className="text-amber-300" />{error}
+            </div>
+          ) : null}
+        </div>
+
+        {showDetails ? (
+          <HeatmapDetailPanel
+            {...detail}
+            loading={nearbyLoading}
+            onClose={() => setNearby(null)}
+            onHide={() => setShowDetails(false)}
+          />
+        ) : null}
+      </div>
+    </section>
+  );
+}

src/modules/vehicle-heatmap/api.ts

@@ -0,0 +1,34 @@
+import { fetchJson } from '../../auth/api-client';
+import type { AmapConfig, HeatmapMeta, HeatmapMetric, HeatmapResponse, NearbyResponse } from './types';
+
+export function fetchAmapConfig(signal?: AbortSignal) {
+  return fetchJson<AmapConfig>('/api/vehicle-heatmap/config', { signal });
+}
+
+export function fetchHeatmapMeta(signal?: AbortSignal) {
+  return fetchJson<HeatmapMeta>('/api/vehicle-heatmap/meta', { signal });
+}
+
+export function fetchHeatmapPoints(
+  params: { startDate: string; endDate: string; query: string; batchModel: string; metric: HeatmapMetric },
+  signal?: AbortSignal,
+) {
+  const search = new URLSearchParams(params);
+  return fetchJson<HeatmapResponse>(`/api/vehicle-heatmap/points?${search}`, { signal });
+}
+
+export function fetchNearbyVehicles(
+  params: { lng: number; lat: number; startDate: string; endDate: string; query: string; batchModel: string },
+  signal?: AbortSignal,
+) {
+  const search = new URLSearchParams({
+    lng: String(params.lng),
+    lat: String(params.lat),
+    startDate: params.startDate,
+    endDate: params.endDate,
+    query: params.query,
+    batchModel: params.batchModel,
+    radiusKm: '50',
+  });
+  return fetchJson<NearbyResponse>(`/api/vehicle-heatmap/nearby?${search}`, { signal });
+}

src/modules/vehicle-heatmap/types.ts

@@ -0,0 +1,59 @@
+export type HeatmapMetric = 'locations' | 'vehicles';
+
+export type HeatmapPoint = {
+  lng: number;
+  lat: number;
+  count: number;
+};
+
+export type VehicleRank = {
+  vin: string;
+  plateNumber: string;
+  locationCount: number;
+  firstSeen: string;
+  lastSeen: string;
+};
+
+export type VehicleOption = {
+  vin: string;
+  plateNumber: string;
+};
+
+export type HeatmapMeta = {
+  startDate: string;
+  endDate: string;
+  locationCount: number;
+  vehicleCount: number;
+  dayCount: number;
+  totalLocationCount: number;
+  excludedLocationCount: number;
+  outsideMainlandCount: number;
+  tibetCount: number;
+  batchModels: string[];
+  vehicles: VehicleOption[];
+};
+
+export type HeatmapResponse = {
+  startDate: string;
+  endDate: string;
+  metric: HeatmapMetric;
+  locationCount: number;
+  vehicleCount: number;
+  dayCount: number;
+  points: HeatmapPoint[];
+  max: number;
+  topVehicles: VehicleRank[];
+};
+
+export type NearbyResponse = {
+  center: { lng: number; lat: number };
+  radiusKm: number;
+  locationCount: number;
+  vehicleCount: number;
+  topVehicles: VehicleRank[];
+};
+
+export type AmapConfig = {
+  key: string;
+  securityCode: string;
+};

src/server/auth/login.ts

@@ -1,13 +1,14 @@
 import { Hono } from 'hono';
 import jwt from 'jsonwebtoken';
 import pool from '../db.js';
+import { requireEnv } from '../config.js';
 import type { AuthUser, JwtPayload, PermissionLevel } from './types.js';
 import { FULL_ACCESS_ROLES, DEPT_ACCESS_ROLES } from './types.js';
 
 const app = new Hono();
 
 const EXTERNAL_API_BASE = process.env.EXTERNAL_API_BASE || 'https://beta.lnh2e.com';
-const JWT_SECRET = process.env.JWT_SECRET || 'ln-bi-default-secret';
+const JWT_SECRET = requireEnv('JWT_SECRET');
 
 /** GET /api/auth/exchange?jumpToken=xxx — 一步完成：换取用户信息 + 签发 JWT */
 app.get('/exchange', async (c) => {

src/server/auth/middleware.ts

@@ -1,8 +1,9 @@
 import type { Context, Next } from 'hono';
 import jwt from 'jsonwebtoken';
+import { requireEnv } from '../config.js';
 import type { JwtPayload, AuthUser } from './types.js';
 
-const JWT_SECRET = process.env.JWT_SECRET || 'ln-bi-default-secret';
+const JWT_SECRET = requireEnv('JWT_SECRET');
 
 // 临时：跳过所有认证（保留完整逻辑便于快速恢复）
 const BYPASS_AUTH = false;
@@ -30,7 +31,11 @@ export async function authMiddleware(c: Context, next: Next) {
   }
 
   // 跳过不需要认证的路径
-  if (path === '/api/health' || path.startsWith('/api/auth/')) {
+  if (
+    path === '/api/health'
+    || path === '/api/health/readiness'
+    || path.startsWith('/api/auth/')
+  ) {
     return next();
   }
 

src/server/config.test.ts

@@ -0,0 +1,26 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { envPort, MissingEnvironmentError, requireEnv } from './config.js';
+
+test('requireEnv returns a trimmed value', () => {
+  assert.equal(requireEnv('TOKEN', { TOKEN: '  configured  ' }), 'configured');
+});
+
+test('requireEnv identifies the missing variable without exposing values', () => {
+  assert.throws(
+    () => requireEnv('TOKEN', {}),
+    (error: unknown) => {
+      assert.ok(error instanceof MissingEnvironmentError);
+      assert.equal(error.code, 'MISSING_ENVIRONMENT_VARIABLE');
+      assert.equal(error.variableName, 'TOKEN');
+      return true;
+    },
+  );
+});
+
+test('envPort validates configured ports', () => {
+  assert.equal(envPort('PORT', 3306, {}), 3306);
+  assert.equal(envPort('PORT', 3306, { PORT: '8111' }), 8111);
+  assert.throws(() => envPort('PORT', 3306, { PORT: '70000' }));
+  assert.throws(() => envPort('PORT', 3306, { PORT: 'invalid' }));
+});

src/server/config.ts

@@ -0,0 +1,33 @@
+import 'dotenv/config';
+
+export class MissingEnvironmentError extends Error {
+  readonly code = 'MISSING_ENVIRONMENT_VARIABLE';
+
+  constructor(readonly variableName: string) {
+    super(`Missing required environment variable: ${variableName}`);
+    this.name = 'MissingEnvironmentError';
+  }
+}
+
+export function requireEnv(
+  name: string,
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const value = env[name]?.trim();
+  if (!value) throw new MissingEnvironmentError(name);
+  return value;
+}
+
+export function envPort(
+  name: string,
+  fallback: number,
+  env: NodeJS.ProcessEnv = process.env,
+): number {
+  const raw = env[name]?.trim();
+  if (!raw) return fallback;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 1 || value > 65535) {
+    throw new Error(`Invalid port in environment variable: ${name}`);
+  }
+  return value;
+}

src/server/heatmap-db.ts

@@ -0,0 +1,29 @@
+import dotenv from 'dotenv';
+import pg from 'pg';
+
+dotenv.config();
+
+const { Pool } = pg;
+
+const heatmapPool = new Pool({
+  host: process.env.HEATMAP_DB_HOST,
+  port: Number(process.env.HEATMAP_DB_PORT) || 5432,
+  user: process.env.HEATMAP_DB_USER,
+  password: process.env.HEATMAP_DB_PASSWORD,
+  database: process.env.HEATMAP_DB_NAME,
+  ssl: process.env.HEATMAP_DB_SSL === 'true'
+    ? { rejectUnauthorized: false }
+    : false,
+  max: 5,
+  idleTimeoutMillis: 30_000,
+  connectionTimeoutMillis: 10_000,
+  statement_timeout: 30_000,
+  application_name: 'ln-bi-vehicle-heatmap',
+  options: '-c timezone=Asia/Shanghai -c default_transaction_read_only=on',
+});
+
+heatmapPool.on('error', (error) => {
+  console.error('[vehicle-heatmap] idle PostgreSQL client error:', error);
+});
+
+export default heatmapPool;

src/server/hydrogen-db.ts

@@ -1,17 +1,20 @@
-import mysql from 'mysql2/promise';
-import dotenv from 'dotenv';
+import mysql, { type Pool } from 'mysql2/promise';
+import { envPort, requireEnv } from './config.js';
 
-dotenv.config();
+let hydrogenPool: Pool | null = null;
 
-const hydrogenPool = mysql.createPool({
-  host: process.env.HYDROGEN_DB_HOST || '47.99.185.173',
-  port: Number(process.env.HYDROGEN_DB_PORT) || 3306,
-  user: process.env.HYDROGEN_DB_USER || 'root',
-  password: process.env.HYDROGEN_DB_PASSWORD || 'lnMysql.',
-  database: process.env.HYDROGEN_DB_NAME || 'ln_asset_management',
-  waitForConnections: true,
-  connectionLimit: 5,
-  queueLimit: 0,
-});
+export function getHydrogenPool(): Pool {
+  if (hydrogenPool) return hydrogenPool;
 
-export default hydrogenPool;
+  hydrogenPool = mysql.createPool({
+    host: requireEnv('HYDROGEN_DB_HOST'),
+    port: envPort('HYDROGEN_DB_PORT', 3306),
+    user: requireEnv('HYDROGEN_DB_USER'),
+    password: requireEnv('HYDROGEN_DB_PASSWORD'),
+    database: requireEnv('HYDROGEN_DB_NAME'),
+    waitForConnections: true,
+    connectionLimit: 5,
+    queueLimit: 0,
+  });
+  return hydrogenPool;
+}

src/server/index.ts

@@ -9,6 +9,10 @@ import schedulingRouter from './routes/scheduling/index.js';
 import energyRouter from './routes/energy/index.js';
 import eleRouter from './routes/ele/index.js';
 import feedbackRouter from './routes/feedback/index.js';
+import vehicleHeatmapRouter from './routes/vehicle-heatmap.js';
+import hydrogenHeatmapRouter from './routes/hydrogen-heatmap.js';
+import analyticsRouter from './routes/analytics/index.js';
+import healthRouter from './routes/health.js';
 import { ensureSchedulingTables } from './routes/scheduling/db-schema.js';
 import authRouter from './auth/login.js';
 import { authMiddleware } from './auth/middleware.js';
@@ -21,6 +25,7 @@ app.use('/api/*', cors());
 
 // Auth 路由（不需要中间件）
 app.route('/api/auth', authRouter);
+app.route('/api/health', healthRouter);
 
 // Auth 中间件（保护后续所有 /api/* 路由）
 app.use('/api/*', authMiddleware);
@@ -31,8 +36,11 @@ app.route('/api/scheduling', schedulingRouter);
 app.route('/api/energy', energyRouter);
 app.route('/api/ele', eleRouter);
 app.route('/api/feedback', feedbackRouter);
+app.route('/api/vehicle-heatmap', vehicleHeatmapRouter);
+app.route('/api/hydrogen-heatmap', hydrogenHeatmapRouter);
+app.route('/api/analytics', analyticsRouter);
 
-app.get('/api/health', (c) => c.json({ status: 'ok', time: new Date().toISOString() }));
+app.all('/api/*', (c) => c.json({ error: 'API route not found' }, 404));
 
 // Serve static files in production
 app.use('/*', serveStatic({ root: './dist' }));

src/server/mileage-db.ts

@@ -1,17 +1,20 @@
-import mysql from 'mysql2/promise';
-import dotenv from 'dotenv';
+import mysql, { type Pool } from 'mysql2/promise';
+import { envPort, requireEnv } from './config.js';
 
-dotenv.config();
+let mileagePool: Pool | null = null;
 
-const mileagePool = mysql.createPool({
-  host: process.env.MILEAGE_DB_HOST || '101.133.130.65',
-  port: Number(process.env.MILEAGE_DB_PORT) || 3306,
-  user: process.env.MILEAGE_DB_USER || 'bi_reader_02',
-  password: process.env.MILEAGE_DB_PASSWORD || 'bi_reader_02_Pass',
-  database: process.env.MILEAGE_DB_NAME || 'hydrogen_energy',
-  waitForConnections: true,
-  connectionLimit: 5,
-  queueLimit: 0,
-});
+export function getMileagePool(): Pool {
+  if (mileagePool) return mileagePool;
 
-export default mileagePool;
+  mileagePool = mysql.createPool({
+    host: requireEnv('MILEAGE_DB_HOST'),
+    port: envPort('MILEAGE_DB_PORT', 3306),
+    user: requireEnv('MILEAGE_DB_USER'),
+    password: requireEnv('MILEAGE_DB_PASSWORD'),
+    database: requireEnv('MILEAGE_DB_NAME'),
+    waitForConnections: true,
+    connectionLimit: 5,
+    queueLimit: 0,
+  });
+  return mileagePool;
+}

src/server/readiness.test.ts

@@ -0,0 +1,50 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { buildReadinessReport } from './readiness.js';
+
+const completeEnv: NodeJS.ProcessEnv = {
+  DB_HOST: 'configured',
+  DB_USER: 'configured',
+  DB_PASSWORD: 'do-not-expose-secret',
+  DB_NAME: 'configured',
+  JWT_SECRET: 'configured',
+  ONEOS_MILEAGE_API_BASE_URL: 'configured',
+  ONEOS_MILEAGE_API_KEY: 'configured',
+  HYDROGEN_DB_HOST: 'configured',
+  HYDROGEN_DB_USER: 'configured',
+  HYDROGEN_DB_PASSWORD: 'configured',
+  HYDROGEN_DB_NAME: 'configured',
+  HEATMAP_DB_HOST: 'configured',
+  HEATMAP_DB_USER: 'configured',
+  HEATMAP_DB_PASSWORD: 'configured',
+  HEATMAP_DB_NAME: 'configured',
+  AMAP_WEB_KEY: 'configured',
+  AMAP_SECURITY_JS_CODE: 'configured',
+  OSS_ENDPOINT: 'configured',
+  OSS_ACCESS_KEY_ID: 'configured',
+  OSS_ACCESS_KEY_SECRET: 'configured',
+  OSS_BUCKET: 'configured',
+};
+
+test('reports ready only when core and integration configuration is complete', () => {
+  const report = buildReadinessReport(completeEnv, new Date('2026-08-07T08:00:00Z'));
+  assert.equal(report.status, 'ready');
+  assert.equal(report.semantics, 'configuration-only');
+  assert.equal(report.checkedAt, '2026-08-07T08:00:00.000Z');
+});
+
+test('distinguishes optional integration gaps from core readiness failures', () => {
+  const degraded = buildReadinessReport({ ...completeEnv, HYDROGEN_DB_PASSWORD: '' });
+  assert.equal(degraded.status, 'degraded');
+  assert.equal(degraded.integrations.hydrogenDatabase, 'incomplete');
+
+  const notReady = buildReadinessReport({ ...completeEnv, DB_PASSWORD: '' });
+  assert.equal(notReady.status, 'not-ready');
+  assert.equal(notReady.core.assetDatabase, 'incomplete');
+});
+
+test('does not expose configuration values or variable names', () => {
+  const serialized = JSON.stringify(buildReadinessReport(completeEnv));
+  assert.equal(serialized.includes('do-not-expose-secret'), false);
+  assert.equal(serialized.includes('DB_PASSWORD'), false);
+});

src/server/readiness.ts

@@ -0,0 +1,64 @@
+export type ConfigurationState = 'configured' | 'incomplete';
+
+export interface ReadinessReport {
+  status: 'ready' | 'degraded' | 'not-ready';
+  semantics: 'configuration-only';
+  checkedAt: string;
+  core: {
+    assetDatabase: ConfigurationState;
+    authentication: ConfigurationState;
+  };
+  integrations: {
+    oneOsMileage: ConfigurationState;
+    hydrogenDatabase: ConfigurationState;
+    heatmapDatabase: ConfigurationState;
+    mapSdk: ConfigurationState;
+    objectStorage: ConfigurationState;
+  };
+}
+
+function hasAll(env: NodeJS.ProcessEnv, names: readonly string[]): ConfigurationState {
+  return names.every(name => Boolean(env[name]?.trim())) ? 'configured' : 'incomplete';
+}
+
+export function buildReadinessReport(
+  env: NodeJS.ProcessEnv = process.env,
+  now = new Date(),
+): ReadinessReport {
+  const core = {
+    assetDatabase: hasAll(env, ['DB_HOST', 'DB_USER', 'DB_PASSWORD', 'DB_NAME']),
+    authentication: hasAll(env, ['JWT_SECRET']),
+  } as const;
+  const integrations = {
+    oneOsMileage: hasAll(env, ['ONEOS_MILEAGE_API_BASE_URL', 'ONEOS_MILEAGE_API_KEY']),
+    hydrogenDatabase: hasAll(env, [
+      'HYDROGEN_DB_HOST',
+      'HYDROGEN_DB_USER',
+      'HYDROGEN_DB_PASSWORD',
+      'HYDROGEN_DB_NAME',
+    ]),
+    heatmapDatabase: hasAll(env, [
+      'HEATMAP_DB_HOST',
+      'HEATMAP_DB_USER',
+      'HEATMAP_DB_PASSWORD',
+      'HEATMAP_DB_NAME',
+    ]),
+    mapSdk: hasAll(env, ['AMAP_WEB_KEY', 'AMAP_SECURITY_JS_CODE']),
+    objectStorage: hasAll(env, [
+      'OSS_ENDPOINT',
+      'OSS_ACCESS_KEY_ID',
+      'OSS_ACCESS_KEY_SECRET',
+      'OSS_BUCKET',
+    ]),
+  } as const;
+
+  const coreReady = Object.values(core).every(value => value === 'configured');
+  const integrationsReady = Object.values(integrations).every(value => value === 'configured');
+  return {
+    status: !coreReady ? 'not-ready' : integrationsReady ? 'ready' : 'degraded',
+    semantics: 'configuration-only',
+    checkedAt: now.toISOString(),
+    core,
+    integrations,
+  };
+}

src/server/routes/analytics/index.test.ts

@@ -0,0 +1,63 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import app from './index.js';
+
+test('returns the published mileage metric contract', async () => {
+  const response = await app.request('/metrics?domain=mileage');
+  const payload = await response.json();
+
+  assert.equal(response.status, 200);
+  assert.equal(payload.catalogVersion, 7);
+  assert.deepEqual(payload.domains, ['mileage']);
+  assert.ok(payload.metrics.some((metric: { id: string }) => metric.id === 'mileage.assessment_completion_rate'));
+  assert.ok(payload.metrics.some((metric: { id: string }) => metric.id === 'mileage.average_per_vehicle'));
+});
+
+test('returns the published hydrogen metric contract', async () => {
+  const response = await app.request('/metrics?domain=hydrogen');
+  const payload = await response.json();
+
+  assert.equal(response.status, 200);
+  assert.deepEqual(payload.domains, ['hydrogen']);
+  assert.ok(payload.metrics.some((metric: { id: string }) => metric.id === 'hydrogen.customer_revenue'));
+  assert.ok(payload.metrics.some((metric: { id: string }) => metric.id === 'hydrogen.customer_order_gross_profit'));
+});
+
+test('returns the published electric metric contract', async () => {
+  const response = await app.request('/metrics?domain=electric');
+  const payload = await response.json();
+
+  assert.equal(response.status, 200);
+  assert.equal(payload.catalogVersion, 7);
+  assert.deepEqual(payload.domains, ['electric']);
+  assert.ok(payload.metrics.some((metric: { id: string }) => metric.id === 'electric.charge_total_fee'));
+  assert.ok(payload.metrics.some((metric: { id: string }) => metric.id === 'electric.blended_cost_intensity'));
+  assert.ok(payload.metrics.some((metric: { id: string }) => metric.id === 'electric.data_freshness'));
+});
+
+test('returns the published ETC metric contract', async () => {
+  const response = await app.request('/metrics?domain=etc');
+  const payload = await response.json();
+
+  assert.equal(response.status, 200);
+  assert.equal(payload.catalogVersion, 7);
+  assert.deepEqual(payload.domains, ['etc']);
+  assert.ok(payload.metrics.some((metric: { id: string }) => metric.id === 'etc.total_amount'));
+  assert.ok(payload.metrics.some((metric: { id: string }) => metric.id === 'etc.bill_receivable'));
+});
+
+test('rejects unpublished metric domains', async () => {
+  const response = await app.request('/metrics?domain=energy');
+
+  assert.equal(response.status, 400);
+});
+
+test('returns observed data-source outcomes without sensitive details', async () => {
+  const response = await app.request('/data-sources');
+  const payload = await response.json();
+
+  assert.equal(response.status, 200);
+  assert.equal(payload.semantics, 'observed-requests');
+  assert.ok(Array.isArray(payload.sources));
+  assert.equal(JSON.stringify(payload).includes('password'), false);
+});

src/server/routes/analytics/index.ts

@@ -0,0 +1,32 @@
+import { Hono } from 'hono';
+import {
+  METRIC_CATALOG_VERSION,
+  isMetricDomain,
+  listMetricDefinitions,
+  type MetricDomain,
+} from '../../../shared/analytics/catalog.js';
+import { getDataSourceTelemetry } from '../../source-telemetry.js';
+
+const app = new Hono();
+
+app.get('/metrics', (c) => {
+  const requestedDomain = c.req.query('domain');
+  let domain: MetricDomain | undefined;
+  if (requestedDomain) {
+    if (!isMetricDomain(requestedDomain)) {
+      return c.json({ error: 'Unsupported metric domain', domain: requestedDomain }, 400);
+    }
+    domain = requestedDomain;
+  }
+
+  const metrics = listMetricDefinitions(domain);
+  return c.json({
+    catalogVersion: METRIC_CATALOG_VERSION,
+    domains: Array.from(new Set(metrics.map(metric => metric.domain))),
+    metrics,
+  });
+});
+
+app.get('/data-sources', (c) => c.json(getDataSourceTelemetry()));
+
+export default app;

src/server/routes/energy/cache.ts

@@ -1,3 +1,5 @@
+import { observeDataSource, type DataSourceId } from '../../source-telemetry.js';
+
 /**
  * SWR 缓存：始终返回热数据，后台定时刷新。
  *
@@ -70,24 +72,28 @@ async function runRefresh(key: string) {
 
 export interface CachedOpts {
   force?: boolean;
+  source?: DataSourceId;
 }
 
 export async function cached<T>(key: string, loader: () => Promise<T>, opts: CachedOpts = {}): Promise<T> {
+  const effectiveLoader = opts.source
+    ? () => observeDataSource(opts.source!, loader)
+    : loader;
   const now = Date.now();
   const hit = cache.get(key) as Entry<T> | undefined;
   if (hit) {
     hit.lastAccess = now;
-    hit.loader = loader;
+    hit.loader = effectiveLoader;
   }
 
   // 强制刷新：等待 loader 完成
   if (opts.force) {
     const ongoing = inflight.get(key) as Promise<T> | undefined;
     if (ongoing) return ongoing;
-    const p = loader()
+    const p = effectiveLoader()
       .then(value => {
         const t = Date.now();
-        const next: Entry<T> = { value, freshAt: t, expiresAt: t + TTL_MS, loader, lastAccess: t };
+        const next: Entry<T> = { value, freshAt: t, expiresAt: t + TTL_MS, loader: effectiveLoader, lastAccess: t };
         cache.set(key, next);
         scheduleRefresh(key, next);
         return value;
@@ -112,10 +118,10 @@ export async function cached<T>(key: string, loader: () => Promise<T>, opts: Cac
   const ongoing = inflight.get(key) as Promise<T> | undefined;
   if (ongoing) return ongoing;
 
-  const p = loader()
+  const p = effectiveLoader()
     .then(value => {
       const t = Date.now();
-      const entry: Entry<T> = { value, freshAt: t, expiresAt: t + TTL_MS, loader, lastAccess: t };
+      const entry: Entry<T> = { value, freshAt: t, expiresAt: t + TTL_MS, loader: effectiveLoader, lastAccess: t };
       cache.set(key, entry);
       scheduleRefresh(key, entry);
       return value;