210 lines
11 KiB
Markdown
210 lines
11 KiB
Markdown
# 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 状态；目标、部门/客户归因和车辆清单下钻继承同一年度，无效年度会按目标真实年度归一。
|
|
- 已完成氢能站点、客户下钻代码。
|
|
- 已完成氢能每日趋势到加氢订单的 URL 下钻、分页和结构化故障状态；待数据源恢复后验收真实明细。
|
|
- 已为电能总览与氢能每日趋势柱图统一 Enter/Space 键盘下钻；氢能有效日期柱提供可读名称、焦点和选中反馈。
|
|
- 已完成电能全部车辆、日期和订单下钻。
|
|
- 电能每日列表打开新日期订单使用浏览器历史 `pushState`，返回/前进可恢复进入前后的分析状态；筛选调整仍使用 `replaceState`。
|
|
- 已完成 ETC 通行记录与结算账单下钻代码、筛选、分页和未同步空状态；待首次真实同步后验收真实数据。
|
|
|
|
### 阶段 C：数据可信度
|
|
|
|
- 里程年度归因使用考核台账 `current_mileage` 快照，按车辆目标封顶后加总完成量与缺口，并自动核对归因合计和目标汇总；带日期的 OneOS 里程只用于车辆实时明细。
|
|
- 里程考核目标接口发布车辆台账 `MAX(update_time)`，统计页使用真实日期和时间展示数据截至点，不再用页面访问日或考核结束日代替快照时间。
|
|
- 里程考核接口区分目标声明台数与当前有效车辆数；两者不一致时页面明确标注缺少或超配数量，并说明完成率、缺口和归因的实际计算范围。
|
|
- 里程考核统计主数据已区分加载、真实空数据、首次请求故障和保留旧数据的刷新故障，并提供统一重试入口，接口失败不再显示为零值或空页面。
|
|
- 里程考核归因车辆与 7 天趋势已提供独立加载、故障、空数据和重试状态；子请求失败时停止展示“0 台未达标”和“最新日变化 +0”等伪业务结果。
|
|
- 已完成电能数据截至时间和实际趋势月展示。
|
|
- 电能日期下钻自动核对日汇总与订单全量合计的日期、车辆范围、电量和费用，并显式展示通过或差异状态。
|
|
- 已完成氢能结构化故障状态与重试体验。
|
|
- 已完成里程今日仪表快照复用：监控查询和考核车辆当前日明细命中同一分钟级快照，手动刷新生成一致的分页快照；历史日仍使用独立日期缓存。
|
|
- 已在各 BI 模块头部提供当前数据源的真实请求状态、失败率和最后成功/失败时间。
|
|
- 待恢复氢能数据库后进行总览、站点、客户三层对账。
|
|
- 待 ETC 同步后进行通行记录、账单和收款三层对账。
|
|
|
|
### 阶段 D：部署与安全
|
|
|
|
- 已将部署清单、氢能和里程连接中的数据库敏感值迁移为必填环境变量。
|
|
- 轮换已经进入版本历史的氢能数据库凭据。
|
|
- 已提供无敏感值的 `.env.example`；测试、生产值由各环境密钥管理。
|
|
- 已拆分进程存活检查与无敏感值的配置就绪检查。
|
|
- 已增加基于真实业务请求的数据源最后结果、最后成功时间和滚动失败率监控。
|
|
|
|
## 9. 每批验收门槛
|
|
|
|
每次提交至少满足：
|
|
|
|
1. TypeScript 检查通过。
|
|
2. 受影响的口径、URL 或查询测试通过。
|
|
3. 生产前端构建通过，服务端入口可加载。
|
|
4. `git diff --check` 通过。
|
|
5. 桌面和移动端检查无溢出、遮挡或不可操作控件。
|
|
6. 使用真实接口核对至少一个父级汇总与子级明细。
|
|
7. 不提交本地数据、临时脚本、凭据或无关工作区修改。
|
|
|
|
## 10. 当前外部依赖
|
|
|
|
- 氢能数据库连接尚未恢复，真实数据对账未完成。
|
|
- ETC 供应商未配置、未执行首次同步；记录与账单下钻代码已完成，但真实数据仍不可验收。
|
|
- 氢能连接信息已从当前版本迁出，但历史凭据仍必须在数据库侧轮换；文档不记录任何连接值。
|