# 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：核心下钻闭环

- 已完成里程考核归因、车辆详情和每日汇报跳转。
- 已完成氢能站点、客户下钻代码。
- 已完成氢能每日趋势到加氢订单的 URL 下钻、分页和结构化故障状态；待数据源恢复后验收真实明细。
- 已为电能总览与氢能每日趋势柱图统一 Enter/Space 键盘下钻；氢能有效日期柱提供可读名称、焦点和选中反馈。
- 已完成电能全部车辆、日期和订单下钻。
- 电能每日列表打开新日期订单使用浏览器历史 `pushState`，返回/前进可恢复进入前后的分析状态；筛选调整仍使用 `replaceState`。
- 已完成 ETC 通行记录与结算账单下钻代码、筛选、分页和未同步空状态；待首次真实同步后验收真实数据。

### 阶段 C：数据可信度

- 已完成电能数据截至时间和实际趋势月展示。
- 电能日期下钻自动核对日汇总与订单全量合计的日期、车辆范围、电量和费用，并显式展示通过或差异状态。
- 已完成氢能结构化故障状态与重试体验。
- 已完成里程今日仪表快照复用：普通查询命中分钟级快照，手动刷新生成一致的分页快照。
- 已在各 BI 模块头部提供当前数据源的真实请求状态、失败率和最后成功/失败时间。
- 待恢复氢能数据库后进行总览、站点、客户三层对账。
- 待 ETC 同步后进行通行记录、账单和收款三层对账。

### 阶段 D：部署与安全

- 已将部署清单、氢能和里程连接中的数据库敏感值迁移为必填环境变量。
- 轮换已经进入版本历史的氢能数据库凭据。
- 已提供无敏感值的 `.env.example`；测试、生产值由各环境密钥管理。
- 已拆分进程存活检查与无敏感值的配置就绪检查。
- 已增加基于真实业务请求的数据源最后结果、最后成功时间和滚动失败率监控。

## 9. 每批验收门槛

每次提交至少满足：

1. TypeScript 检查通过。
2. 受影响的口径、URL 或查询测试通过。
3. 生产前端构建通过，服务端入口可加载。
4. `git diff --check` 通过。
5. 桌面和移动端检查无溢出、遮挡或不可操作控件。
6. 使用真实接口核对至少一个父级汇总与子级明细。
7. 不提交本地数据、临时脚本、凭据或无关工作区修改。

## 10. 当前外部依赖

- 氢能数据库连接尚未恢复，真实数据对账未完成。
- ETC 供应商未配置、未执行首次同步；记录与账单下钻代码已完成，但真实数据仍不可验收。
- 氢能连接信息已从当前版本迁出，但历史凭据仍必须在数据库侧轮换；文档不记录任何连接值。