ln-bi/docs/superpowers/specs/2026-04-28-energy-module-design.md

能源管理模块设计

在底部导航增加「能源管理」入口，集中展示加氢/充电的成本与用量数据。当前阶段只做前端原型，数据全部走前端 mock，后端接入留作下一阶段。

业务背景

参考 FineBI 既有的三张大屏：

BI 链接	标题	内容
link/0iqP	氢气管理（氢费统计）	年/月/日加氢量与加氢费 KPI、加氢业务区域分布、Top5 加氢站、各区域占比
link/GBSp	加氢站氢量每日汇总	每日加氢量与环比，下钻到站点级带单价
link/TPqB	龙王路停车场充电站每日充电汇总	每日充电量(度) + 充电费用(元)

这些大屏目前只在桌面浏览器里好看，移动端体验较差，且与现有应用风格割裂。新模块的目标是把核心信息按「移动优先 + 双端响应」重新组织进当前 BI App 的底部导航，让一线运营在手机上也能秒级抓取关键能耗指标。

用户故事

• 作为运营人员，进 App 底部 Tab 「能源管理」，第一屏立刻能看到本年/本月/今日的加氢量与加氢费。
• 作为运营人员，能切换查看「氢能」和「电能」两类业务。
• 作为氢能业务方，能看到每日加氢明细，并下钻到站点级别（站名 + 单价）。
• 作为电能业务方，能看到龙王路充电站每日充电量与充电费。

范围

在范围内

• 新模块 src/modules/energy/，遵循 mileage 模块的目录骨架
• EnergyModule 顶级组件 + 二级 Tab（氢能 / 电能）
• 氢能下：总览（KPI + Top5 横柱 + 区域占比环）+ 每日（明细表带下钻）
• 电能下：mini KPI 头 + 每日明细表
• 全前端 mock 数据，数据值从 BI 截图取真实样本，文件 mock.ts
• 双端响应（mobile + web）
• 在 App.tsx 的 BASE_MODULES 注册（登录即可见）

不在范围内

• 后端接入、真实数据库表设计（下一期）
• 中国地图（加氢业务区域分布）— 工作量与依赖（高德/echarts-geo）大，后续单独立项
• iframe 嵌入 FineBI（已否决）
• 角色权限门禁（暂不需要）
• 数据导出 / CSV
• 站点详情页 / 区域详情页

模块注册（App.tsx）

import { Truck, Route, Activity, Zap } from 'lucide-react';
import EnergyModule from './modules/energy/EnergyModule';

const BASE_MODULES: ModuleConfig[] = [
  { id: 'assets',  label: '资产管理', icon: Truck,    component: AssetsModule },
  { id: 'mileage', label: '里程管理', icon: Route,    component: MileageModule },
  { id: 'energy',  label: '能源管理', icon: Zap,      component: EnergyModule },
];

并在 Shell.tsx 的 PATH_MAP 加 '/energy': 'energy'。#energy hash 由 Shell 已有逻辑兜底。

页面结构

EnergyModule
├── 顶部 sticky sub-nav: [氢能] [电能]   ← motion layoutId 滑块动画
│
├── 氢能 view (HydrogenView)
│   ├── 内层 sticky tab: [总览] [每日]
│   ├── HydrogenOverview
│   │   ├── 数据时间提示条：「数据自 2025-01-01 起，每 5 分钟更新」
│   │   ├── KPI 网格（移动 2×2 / 桌面 1×4）
│   │   ├── Top5 加氢站横柱图
│   │   └── 各区域加氢占比环形图
│   └── HydrogenDaily
│       ├── 日期速选 6 选 1：当天 / 本周 / 本月 / 本季度 / 最近7天 / 最近30天
│       ├── 客户类型 2 选 1：外部 / 羚牛
│       ├── 合计行（pin 在表头下）
│       └── 表格：日期 → 加氢量(Kg) → 环比%（日期行可展开为站点级）
│
└── 电能 view (ElectricView)
    ├── 数据时间提示条：「龙王路停车场充电站，期初 2025-01-01，手工导入每日更新」
    ├── 横向 mini KPI 头（3 列：累计 / 本月 / 今日）
    ├── 客户类型 2 选 1：外部 / 羚牛
    └── 表格：月份/日期 → 充电电量(度) → 充电费用(元)（月份组可展开为日级）

文件结构

src/modules/energy/
├── EnergyModule.tsx         # 顶级容器 + 氢能/电能 切换
├── HydrogenView.tsx         # 含「总览/每日」二级 Tab
├── HydrogenOverview.tsx     # KPI + Top5 + 区域占比
├── HydrogenDaily.tsx        # 加氢量明细表
├── ElectricView.tsx         # 充电汇总表
├── mock.ts                  # 所有 mock 数据
└── types.ts                 # 共享类型

参照 src/modules/mileage/ 风格。没有 api.ts（后端先不接）。

数据形状（mock.ts / types.ts）

// types.ts
export type CustomerType = 'external' | 'lingniu';   // 外部 / 羚牛
export type DateQuickPick = 'today' | 'thisWeek' | 'thisMonth' | 'thisQuarter' | 'last7' | 'last30';

export interface HydrogenKpi {
  yearKg: number;          // 年加氢量 Kg
  yearFee: number;         // 年加氢费 元
  ourYearKg: number;       // 我方年加氢量
  ourYearFee: number;      // 我方年加氢费
  customerYearKg: number;  // 客户产生年加氢量
  monthKg: number;
  monthFee: number;
  todayKg: number;
  todayFee: number;
  lingniuBornKg: number;   // 累计羚牛承担量
  lingniuBornFee: number;  // 累计羚牛承担费
}

export interface HydrogenStation {
  name: string;
  kg: number;
  fee: number;
}

export interface HydrogenRegionShare {
  region: string;
  kg: number;
  share: number;            // 0-1
}

export interface HydrogenStationRow {
  name: string;
  pricePerKg: number;       // 单价 元/Kg
  kg: number;
  chainPct: number;         // 环比 -1..+1
}

export interface HydrogenDailyRow {
  date: string;             // 'YYYY-MM-DD'
  totalKg: number;
  chainPct: number;
  stations: HydrogenStationRow[];
}

export interface ElectricKpi {
  totalKwh: number;
  totalFee: number;
  monthKwh: number;
  monthFee: number;
  todayKwh: number;
  todayFee: number;
  todayChainPct: number;
}

export interface ElectricDailyRow {
  date: string;             // 'YYYY-MM-DD'
  kwh: number;
  fee: number;
  chainPct: number;         // 环比，用于趋势箭头
}

export interface ElectricMonthGroup {
  month: string;            // 'YYYY-MM'
  kwh: number;
  fee: number;
  rows: ElectricDailyRow[];
}

mock.ts 提供：

• hydrogenKpi：取自 0iqP 的 362.43T / ¥1066.46 万 / 10.03 万 等真实样本
• hydrogenStationsTop5：5 家站，名字取自 GBSp 截图
• hydrogenRegionShare：约 8-12 个区域条目
• hydrogenDaily：约 30 天数据，前 7 天每天 3-4 个站点；剩余天只有汇总 + 1-2 站点
• electricKpi：取自 TPqB 合计 817,632.24 度 / ¥151,542.92
• electricMonthly：以月为顶级 group，含每日明细，至少覆盖 2026-04 起若干天

数字均做轻微抖动，但保留量级与百分比，避免与 BI 大屏数字"完全一致"误导。

视觉规范

通用

• 容器：min-h-screen bg-[#F8F9FB] text-gray-800 font-sans p-3 md:p-6 + max-w-6xl mx-auto
• 横屏：保留 landscape:pb-0 landscape:h-full landscape:flex-1 landscape:overflow-hidden
• 卡片：bg-white rounded-2xl border border-slate-100 shadow-sm
• sub-nav：bg-white px-4 py-2 rounded-2xl border border-slate-100 shadow-sm + sticky top 0
• Tab active 用 motion.div layoutId="..." 下划线动画（沿用 mileage 模式）
• 主色：text-blue-600 / bg-blue-50
• 正向：text-emerald-500 / bg-emerald-50
• 负向：text-red-500 / bg-red-50
• 警示：text-amber-500 / bg-amber-50

氢能总览

• KPI 卡：4 张主角卡，顺序固定
  1. 年加氢量（青蓝渐变 from-cyan-50 to-blue-50）+ 主数 362.43T + 分解两行（我方 / 客户产生）
  2. 年加氢费（蓝紫渐变 from-blue-50 to-violet-50）+ 主数 ¥1066.46万 + 分解（我方）
  3. 累计羚牛承担（蜜橙渐变 from-amber-50 to-orange-50）+ 主数 ¥10.03万 + 分解（量 / 费）
  4. 本月/今日合并卡（浅灰）+ 左半月度 + 右半今日，文字主数 text-2xl md:text-3xl
• 卡左上 lucide icon：Fuel / Wallet / Coins / CalendarClock
• KPI 主数移动端 text-2xl font-bold，桌面 md:text-3xl，分解行 text-[11px] text-slate-500 font-bold
• Top5 加氢站：横向柱状（recharts BarChart layout="vertical"），柱子蓝→青渐变，柱左侧带数字徽章 1-5，柱右端贴 XX,XXX Kg · XX%，<ResponsiveContainer width="100%" height={240}>
• 区域占比环形：recharts PieChart，外环切片，中心圆心放年合计 362.43T，下方两列图例（移动单列、桌面双列）

氢能每日表

• 日期速选：6 个 pill 一行，可横向滚动，激活态 bg-blue-50 text-blue-600 border-blue-200
• 客户类型：2 列等宽 segmented control（背景 bg-slate-100 rounded-xl，激活态白底+阴影）
• 合计行：bg-blue-50/50 text-blue-600 粗体
• 主行 = 日期：左侧 ▶ 折叠图标 + 日期；展开后子行内缩进 pl-6，子行内容 = 站名 - 单价 元/Kg
• 环比 pill 双端共用样式：
  • 上 ↑ 绿底 bg-emerald-50 text-emerald-600
  • 下 ↓ 红底 bg-red-50 text-red-600
  • 持平 – 灰底 bg-slate-100 text-slate-500
  • 圆角 rounded-full px-2 py-0.5 text-[11px] font-bold
• 移动 3 列（日期 / 量 / 环比），桌面 4 列加站价列（站点级行用网格而非缩进）

电能

• mini KPI 头：3 卡横排（移动也保持横排，不堆叠），每卡上排 ¥金额 主数（text-xl md:text-2xl），下排 XXX 度 副数 + 今日卡再加 pill 环比
• 月份组：▶ + 2026-04 + 该月合计 度 / 元；展开后是日级行
• 月份组 active 时背景 bg-blue-50/30
• 行的趋势图标 → 与氢能页用同一 pill 组件（保证视觉一致）

响应式行为

区域	移动 (<md)	桌面 (≥md)
顶部 sub-nav (氢/电)	sticky 满宽	sticky 满宽，左对齐
氢能内层 sub-tab	紧贴 sub-nav 下	同
氢能总览 KPI 网格	grid-cols-2	md:grid-cols-4
Top5 横柱 + 区域占比	上下叠 grid-cols-1	md:grid-cols-2 gap-4
每日氢能表	3 列：日期/量/环比	4 列：日期/站价/量/环比，站点级行同样 4 列
电能 mini KPI 头	横排 3 卡（gap 紧凑）	3 卡（gap 宽松）
电能表格	3 列	4-5 列（可加客户类型 / 趋势火花线，留作后期）
容器宽度上限	100%	max-w-6xl mx-auto
recharts 图	<ResponsiveContainer width="100%">	同

组件复用

• 内层 sub-nav 抄 MileageModule.tsx 的 sticky tab 实现（含 motion 滑块）
• segmented control（客户类型 / 日期速选）抄 mileage 已有的实现
• 表格行 chevron 折叠抄 assets 模块里现有展开行的写法
• 环比 pill 单独抽 <TrendBadge value={number} /> 共用组件，放在 src/modules/energy/HydrogenDaily.tsx 顶端 export

边界与开放点

1. 氢费字面口径：用户原始描述「每日氢费」，但 BI GBSp 实际只有加氢量+环比，单价在站点级。本期采纳 BI 的口径——表格只展示量+环比+单价（嵌入站名），费汇总放氢能总览的 KPI 卡。
2. 数据时间：mock 用 2026-04-28 为「今天」（currentDate 取自 user 自动 memory）。今日加氢 在 0Kg 时显示 0 而非 --，避免误判为缺失。
3. 空态：mock 数据已写满，UI 仍要支持 rows.length === 0 时显示「暂无数据」灰文 + 图标。
4. 未来后端接入：mock 文件命名 mock.ts，不放在 api.ts；后期添加 api.ts 时同名 export，UI 切到 useEffect + fetch 即可。
5. icon 选型：Zap 作为模块底栏 icon。备选 Fuel / Battery。
6. lucide 大小：底部 nav 沿用 Icon size={20}。

验收标准

• 底部 nav 多出「能源管理」Tab，icon Zap，登录后可见
• 进入后默认在「氢能 → 总览」
• 氢能总览 4 张 KPI 卡数据正确、移动 2×2 / 桌面 1×4
• Top5 横柱 + 区域占比环 双端可见，柱图站名不被截断
• 切换到「氢能 → 每日」，日期速选/客户类型 toggle 工作（前端筛选 mock 即可）
• 点开任意日期行能展开站点级行，环比 pill 颜色正确
• 切到电能 Tab，3 张 mini KPI + 月份分组表，月份能展开日级行
• 横屏不出现底部 nav 遮挡内容
• npm run lint 通过
• 不引入新依赖（recharts / lucide-react / motion 已有）