# MEIZU Battery Healthy

> 专机专配 · 仅针对魅族独家开发

一个简洁的手机电池健康度监测工具  
通过读取 BMS 日志（`/storage/emulated/0/mbattery_charger/`）与 Android BatteryManager API  
直接获取电池真实数据，不依赖系统 API 估算。

---

## 功能

### 🔋 日常健康观察
- 读取 BMS 日志，解析 `learned_cap`、`cycle`、`tbat`、`vbat` 等关键字段
- 显示电池健康度（当前容量 / 设计容量）、循环次数、电压、温度
- 温度面板提供当日最高 / 最低 / **平均**三项数据
- 异常数据自动标红（容量 < 60% 或 > 115%、电压异常）

### ⚡ 实时充电监控
- 系统级充电状态识别（有线 / 无线 / USB）
- **双数据源融合**：
  - BMS 侧：充电协议（PPS / SDP / EPP）、标定档位、充电器端功率
  - 电池端：BatteryManager 实时电压、电流、功率（1 秒刷新）
- 主界面充电行格式：`充电中 · PPS · 5.98W / 7.5W`
- 充电详情页拆分为「BMS 日志」与「BatteryManager」双分区展示

### 📈 历史数据积累
- 本地 SQLite 数据库持久化每日容量、电压极值、平均温度
- 近 15 天容量百分比趋势柱状图
- 数据库自动迁移（v1 → v2 引入 `temp_avg` 字段）

### 🎨 个性化
- 支持浅色 / 深色 / 跟随系统三种主题模式
- 首页、详情页、更新日志页、关于页全场景深色适配
- 主题选择自动持久化

---

## 版本状态

| 版本 | 主题 | 状态 |
| :--- | :--- | :--- |
| 1.5.0 | 功率计算优化 | ✅ 已发布 |
| 1.5.2 | 部分场景字体替换 | ✅ 已发布 |
| 1.6.0 | 更新日志独立页面 | ✅ 已发布 |
| 1.7.0 | 关于页 + 数据反作弊校验 | ✅ 已发布 |
| 1.7.1 | 平均温度显示 + 数据库 v2 | ✅ 已发布 |
| 1.8.0 | 夜间模式 + 主题系统重构 | ✅ 已发布 |
| 1.9.0 | BatteryManager 实时数据接入 | ✅ 已发布 |
| 2.0.0 | 数据看板月份扩展、充电曲线 | 📋 开发中 |
| 3.0.0 | PC 上位机充电信息记录 | 📋 远景 |

---

## 数据来源说明

本应用同时使用两套数据源，用户看到的每个数值都标注了来源：

### BMS 日志（充电器端）
- 来源：`/storage/emulated/0/mbattery_charger/` 目录下的日志文件
- 特点：数据详尽（协议、档位、充电器输出功率），但**刷新有延迟**（日志落盘需几秒到十几秒）
- 用途：判断充电协议协商、快充档位、充电器端能力

### BatteryManager（电池端）
- 来源：Android 官方 `BatteryManager.BATTERY_PROPERTY_CURRENT_NOW`
- 特点：**1 秒实时刷新**，反映电池实际吸收的功率
- 用途：显示电池端真实能量流
- 注意：读数为**电池端净电流**（充电器输入减去系统功耗），电池接近满电时数值会明显偏低，属正常现象

**两套数据的差异**：BMS 侧数据回答"充电器给了多少"，BatteryManager 数据回答"电池吸收了多少"，两者之差即为系统运行时消耗 + 转换损耗。

---

## 技术架构

```
┌─────────────────────────────────────────┐
│              Flutter UI                  │
│  主页 / 详情 / 更新日志 / 关于            │
├─────────────────────────────────────────┤
│          业务逻辑层                      │
│  ChargeParser / CapacityExtractor        │
│  BatteryDataService / ChargeUtils        │
├─────────────────────────────────────────┤
│              服务层                      │
│  SafStorageService   ← BMS 日志读取      │
│  BatteryManagerService ← BM 数据读取     │
│  DatabaseService     ← SQLite 持久化     │
│  ThemeService        ← 主题持久化        │
├─────────────────────────────────────────┤
│        原生通道（Kotlin）                │
│  /saf /charge /charge_events /frame_rate │
│  BatteryManagerHelper                    │
└─────────────────────────────────────────┘
```

---

## 环境要求

- Flutter SDK: ^3.9.2
- Android: 8.0+ (API 26+)
- 构建环境：AGP 9.0.0 / KGP 2.2.20 / Gradle 9.3.1

---

## 机型匹配情况

| 机型 | 系统版本 | 容量来源 | 设计容量 | 状态 |
|---|---|---|---|---|
| 魅族 22 | Flyme 12.x | 系统未生成日志目录 | 5510 mAh | ❌ 不支持 |
| 魅族 21 | Flyme 12.x | `learned_cap` | 4800 mAh | ✅ 支持 |
| 魅族 21 Pro | Flyme 12.x | `learned_cap` | 5050 mAh | ✅ 支持 |
| 魅族 21 Note | Flyme 12.x | `learned_cap` | 5500 mAh | ✅ 支持 |
| 魅族 21 Note | Flyme 10 / 11 | 日志格式异常 | — | ❌ 不支持 |
| 魅族 20 | Flyme 12.x | `remaining_cap` + `status=Full` | 4700 mAh | ✅ 支持 |
| 魅族 20 Pro | Flyme 12.x | `remaining_cap` + `status=Full` | 5000 mAh | ✅ 支持 |
| 魅族 20 INFINITY | Flyme 10.x | `remaining_cap` + `status=Full` | 4800 mAh | ✅ 支持 |
| 魅族 18 / 18s 系列 | Flyme 9 | 日志停止生成 | 4000 / 4500 mAh | ❌ 无适配条件 |
| 魅族 18 / 18s 系列 | Flyme 10 | — | 4000 / 4500 mAh | ⚠️ 实验性支持 |
| 魅族 17 / 17 Pro | Flyme 8 / 9 / 10 | 待群友提供字段 | 4500 mAh | ⚠️ 待验证 |
| 魅族 16 系列 | Flyme 7 / 8 / 9 | 需回退原厂固件验证 | — | ⚠️ 实验性支持 |

### 状态说明

| 状态 | 含义 |
|---|---|
| ✅ 支持 | 已通过实机验证，字段完整解析 |
| ⚠️ 实验性支持 | 理论可支持，需用户协助验证 |
| ⚠️ 待验证 | 尚未收到实机日志反馈 |
| ❌ 不支持 | 系统未生成日志，或日志格式无法解析 |

### 特别说明

- **Flyme 版本差异**：同一机型在不同 Flyme 版本下日志格式可能不同。例如 21 Note 在 Flyme 12.x 下可正常读取 `learned_cap`，但在 Flyme 10/11 下日志格式异常。
- **日志停止生成**：部分机型升级到新系统后（如 17/18 系升级到 Flyme 10），系统不再向 `mbattery_charger` 目录写入新日志，文件夹虽存在但停止更新。
- **适配策略**：优先支持日志格式稳定的 Flyme 12.x 机型，旧版本系统暂不主动适配。

---

## 从源码构建

```bash
# 拉取依赖
flutter pub get

# Debug 版本
flutter run --debug

# Release APK（仅 arm64）
flutter build apk --release --target-platform android-arm64
```

### 已知构建注意事项

- **原生通道改动需完整重建**：修改 Kotlin 代码后必须 `flutter run`（不要热重载）
- **ProGuard 规则**：release 构建需要 `android/app/proguard-rules.pro`（已包含）
- **Gradle 版本锁定**：不要随意升级 AGP / KGP / Gradle，当前组合已通过验证

---

## 反馈与贡献

- 源码仓库：https://git.whitetop.xyz/lxh2875931338/MEIZU-Battery-Healthy
- 机型适配、字段解析问题欢迎提 Issue
- 新机型支持需要提供当日 `mbattery_charger_log_*.` 日志样本