diff --git a/docs/bi-refactor-roadmap.md b/docs/bi-refactor-roadmap.md
new file mode 100644
index 0000000..19e8079
--- /dev/null
+++ b/docs/bi-refactor-roadmap.md
@@ -0,0 +1,191 @@
+# 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 状态。
+- 已完成并发同参 GET 去重。
+
+### 阶段 B：核心下钻闭环
+
+- 已完成里程考核归因、车辆详情和每日汇报跳转。
+- 已完成氢能站点、客户下钻代码。
+- 已完成电能全部车辆、日期和订单下钻。
+- ETC 等待首次真实同步后实施。
+
+### 阶段 C：数据可信度
+
+- 已完成电能数据截至时间和实际趋势月展示。
+- 已完成氢能结构化故障状态与重试体验。
+- 待恢复氢能数据库后进行总览、站点、客户三层对账。
+- 待 ETC 同步后进行通行记录、账单和收款三层对账。
+
+### 阶段 D：部署与安全
+
+- 将数据库地址、账号和密码从受版本控制文件迁移到部署密钥。
+- 轮换已经进入版本历史的氢能数据库凭据。
+- 为开发、测试和生产分别提供无敏感值的配置模板。
+- 增加服务健康检查、数据源状态和错误率监控。
+
+## 9. 每批验收门槛
+
+每次提交至少满足：
+
+1. TypeScript 检查通过。
+2. 受影响的口径、URL 或查询测试通过。
+3. 生产前端构建通过，服务端入口可加载。
+4. `git diff --check` 通过。
+5. 桌面和移动端检查无溢出、遮挡或不可操作控件。
+6. 使用真实接口核对至少一个父级汇总与子级明细。
+7. 不提交本地数据、临时脚本、凭据或无关工作区修改。
+
+## 10. 当前外部依赖
+
+- 氢能数据库连接尚未恢复，真实数据对账未完成。
+- ETC 供应商未配置、未执行首次同步，记录与账单下钻无数据可验收。
+- 氢能连接信息仍存在于版本控制文件，必须迁移并轮换；文档不记录任何连接值。