ln-bi/docs/bi-refactor-roadmap.md

BI 渐进式重构方案

更新日期：2026-08-07

1. 目标

本次重构不重做整套系统，采用可回滚的小批次交付，逐步解决三个核心问题：

1. UI/UX：统一信息层级、筛选方式、状态反馈和移动端行为。
2. 下钻：任何汇总指标都能沿同一统计口径进入可核对的明细。
3. 统计逻辑：指标公式、时间语义、数据来源和数据截至时间均可查询、可测试。

不在当前阶段引入新的 BI 引擎或替换现有 React、Hono、MySQL 技术栈。

2. 设计原则

• 先口径，后图表：没有明确公式和数据源的指标不得进入主看板。
• 父子一致：下钻前后的时间、车辆范围、组织范围和数据源必须一致。
• URL 即分析状态：日期、范围、实体和数据源写入 URL，支持刷新、返回和分享。
• 空值不等于零值：接口失败、尚未接入、没有权限和真实零业务使用不同状态。
• 汇总可对账：页面汇总应等于明细全量聚合，明细截断不能影响顶部合计。
• 数据新鲜度显式展示：业务时间与页面刷新时间分开表达。
• 渐进发布：每批只修改一个口径或一条下钻链路，通过测试和真实数据核对后提交。

3. 目标信息架构

每个 BI 模块统一为三级信息结构：

层级	用途	页面内容
总览	判断经营状态	核心 KPI、趋势、结构、异常、数据截至时间
分析	定位变化来源	时间筛选、组织/车辆范围、分组排行、归因
明细	核对原始业务	车辆、订单、站点、账单或通行记录

页面头部统一提供模块名称、简短业务说明和“指标口径”入口。筛选条件位于内容上方，实体下钻状态紧邻筛选区展示，避免用户忘记当前分析范围。

4. 模块与下钻矩阵

4.1 里程

父级	下钻目标	必须继承的上下文	当前状态
实时监控汇总	车辆详情	日期区间、协议优先级、车牌	已完成
考核目标	部门/客户归因	考核年份、目标、归因维度	已完成
归因分组	车辆清单	目标、部门或客户值	已完成
每日汇报	实时监控/考核目标	汇报日期、目标或车牌	已完成

考核完成率使用目标里程加权：

SUM(completed_mileage_km) / NULLIF(SUM(target_mileage_km), 0) * 100

禁止直接平均车辆完成率或考核组完成率。

4.2 氢能

父级	下钻目标	必须继承的上下文	当前状态
站点排行	站点每日明细	年份、站点、日期区间、车辆范围	已完成
客户排行	客户每日明细	年份、客户、日期区间、车辆范围	已完成
每日趋势	加氢订单	日期、车辆范围、站点或客户	下钻代码已完成，待数据源恢复后验收

成本、收入和毛利必须分开：

成本 = SUM(cost_total)
客户收入 = SUM(fee_total)
客户单毛利 = 客户收入 - 客户单对应成本

数据库不可用时返回可识别的 503 状态，页面不得显示派生零值。

4.3 电能

父级	下钻目标	必须继承的上下文	当前状态
总览日柱	当日订单	日期、全部车辆范围	已完成
月份	日期	车辆范围、日期区间	已完成
日期	充电订单	日期、车辆范围	已完成

电能范围包括“全部车辆、羚牛车辆、外部车辆”。总览使用全部车辆口径，因此总览下钻必须进入 all，不能默认切换为羚牛车辆。

综合费用强度使用加权公式：

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 下钻、分页和结构化故障状态；待数据源恢复后验收真实明细。
• 已完成电能全部车辆、日期和订单下钻。
• 已完成 ETC 通行记录与结算账单下钻代码、筛选、分页和未同步空状态；待首次真实同步后验收真实数据。

阶段 C：数据可信度

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

阶段 D：部署与安全

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

9. 每批验收门槛

每次提交至少满足：

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

10. 当前外部依赖

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