BATTERY_CHART_DESIGN.md

设备页电量图设计逻辑记录

本文用于记录 /devices 页面「最近 24 小时电量图」的产品与交互设计逻辑，便于后续产品、前端、后端统一口径。

1. 设计目标

• 用户在 3 秒内看懂「当前电量趋势」与「是否发生充电」。
• 主视图优先服务骑行决策（还能骑多久），而不是展示复杂能耗分析。
• 在不牺牲可读性的前提下，保留耗电/充入分析入口。

2. 指标分层策略

• 一级（默认）电量：展示每小时 SOC（battery_percent）。
• 二级（可切换）耗电：展示相邻小时的下降值（放电变化）。
• 二级（可切换）充入：展示相邻小时的上升值（回充变化）。

说明：耗电/充入 用于分析习惯与效率，不作为默认主图，避免用户误把变化量当剩余电量。

3. 视觉编码规则

• 柱体颜色
  • 该小时发生充电（show_charging_icon=true）：绿色柱子（优先级最高）。
  • 非充电且混合状态（is_mixed_state=true）：琥珀色柱子。
  • 其他：主题主色柱子。
• 充电符号
  • 在 电量 视图中展示 ⚡，用于表达该小时发生过充电行为。
• X 轴
  • 小时标签稀疏显示（每 2 小时显示一次）以减少拥挤。
• Y 轴
  • 使用动态范围（自适应最小值/最大值并加留白），提升局部变化可读性。

4. 数值标签策略

• 默认隐藏柱内数值，减少噪音。
• 提供开关（Switch 样式）控制「数值标签」显示/隐藏。
• 开启后仅展示非 0 柱子数值（value > 0），进一步保持界面干净。
• 数值显示在柱体内部，使用小字号与描边保证对比度。
• 同一规则应用于 电量 / 耗电 / 充入 三个视图。

5. Tooltip 信息策略

• Tooltip 统一提供：
  • 当前小时
  • 当前小时 SOC（便于建立上下文）
  • 状态说明（充电/混合/无充电）
• 视图值名称随 Tab 变化：
  • 电量 -> 电量
  • 耗电 -> 耗电
  • 充入 -> 充入

6. 埋点口径（前端事件）

当前通过 battery-chart-telemetry 自定义事件上报：

• exposure：图表曝光
• view_switch：视图切换
• tooltip_open：tooltip 打开
• dwell：停留时长
• confused_feedback：用户点击「看不懂这个图？」

建议后续由统一埋点层接入平台（如 PostHog/GA）并建立看板。

7. 验收参考

• 用户是否能快速回答：
  • 当前电量大致处于什么区间
  • 最近是否有充电行为
• 是否减少「把耗电柱高误解为剩余电量」的反馈。
• 图表交互行为是否提升（切换、tooltip、停留时长）。