# MEIZU Battery Healthy

> **专机专配 · 仅针对魅族设备开发**
>
> 一款面向魅族手机的电池健康度与充电状态监测工具。

MEIZU Battery Healthy 是一款基于 Flutter 开发的 Android 电池监测工具，主要针对魅族设备及其 Flyme 系统进行适配。

应用以设备生成的 BMS 充电日志为核心数据来源，结合 Android `BatteryManager` API，读取电池容量、电压、温度、循环次数及实时充电参数，并通过本地数据库积累历史数据。

与仅展示系统电量百分比的工具不同，本项目更关注**底层数据的读取、不同数据源的对照，以及电池状态的长期观测**。

## 功能特性

### 🔋 日常健康观察

- **电池容量提取**：优先读取 `learned_cap`，部分机型回退至 `remaining_cap` 与 `status=Full` 的组合。
- **健康度计算**：根据当前可用容量与机型设计容量计算健康度百分比。
- **循环次数**：解析 BMS 日志中的 `cycle` 字段。
- **电压监测**：显示当前电压及当日最高、最低电压。
- **温度监测**：显示当前温度、当日最高温度、最低温度与平均温度。
- **异常数据提示**：对容量低于 60%、高于 115% 等异常读数进行标记，并提示电压异常。

### ⚡ 实时充电监控

- **充电状态识别**：识别有线充电、无线充电及 USB 相关状态。
- **充电协议识别**：解析 PPS、SDP、EPP 等协议标识。
- **充电档位解析**：将 BMS 日志中的 `L-n` 标定档位转换为对应的功率信息。
- **双数据源监测**：
  - BMS 侧：读取充电器端电压、电流、功率及无线充电参数。
  - BatteryManager 侧：读取电池端电压、电流，并计算电池端功率。
- **独立刷新策略**：BatteryManager 数据约每秒刷新一次；BMS 数据采用约 15 秒的轮询策略，实际更新还受到日志生成与落盘延迟影响。
- **充电详情页**：分别展示 BMS 日志与 BatteryManager 数据，方便对照观察。

主界面充电信息示例：

`充电中 · PPS · 5.98W / 7.5W`

- **PPS**：当前识别到的充电协议。
- **5.98W**：由 Android `BatteryManager` API 获取电池端电流，并结合电压计算得到的当前功率，反映电池端的实时充电状态。
- **7.5W**：由 BMS 日志解析得到的当前充电档位对应的标定功率，用于表示该档位的功率信息。

其中，电池端功率为实时计算值，充电档位功率为 BMS 提供的档位信息。两者的数据来源、更新频率与测量口径不同，不应直接视为同一测量点的实际功率与额定功率。

### 📈 历史数据与趋势

- 使用 SQLite 在本地持久化每日容量、电压极值及平均温度。
- 支持全量日志扫描与历史数据入库。
- 提供近 15 天电池容量百分比趋势柱状图。
- 支持数据库版本管理与自动迁移，目前 v2 版本新增 `temp_avg` 字段。

### 🎨 主题与界面

- 支持浅色、深色及跟随系统三种主题模式。
- 使用 Flutter `ThemeExtension` 统一管理深浅主题色板。
- 首页、详情页、更新日志页及关于页适配深色模式。
- 使用 SharedPreferences 持久化主题选择。
- 针对中文与数字采用不同的字体显示策略。

## 机型兼容性

本项目采用**机型与 Flyme 版本联合适配**的策略。同一机型在不同系统版本下，可能存在日志格式变化、字段缺失或日志停止生成等情况。

以下为当前已知的适配情况。

| 机型 | 系统版本 | 容量数据来源 | 设计容量 | 状态 |
|---|---|---|---:|---|
| 魅族 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 版本下可能使用不同的日志格式或字段。请以具体机型和系统版本的实际测试结果为准。

**日志生成状态**

部分设备升级系统后可能不再生成新的 BMS 日志。即使日志目录仍然存在，也不代表其中的数据持续更新。

**设计容量**

设计容量用于计算健康度，并非由应用实时测量。计算结果会受到机型参数、底层容量字段含义及电池管理系统校准状态的影响。

**适配策略**

当前优先维护日志格式相对稳定、已完成实机验证的机型。旧机型及其他系统版本的适配将根据实际日志样本逐步推进。

## 数据来源与测量说明

本项目使用两套数据来源，分别承担底层日志分析与实时电池监测的职责。

### 1. BMS 日志：充电器端及设备充电状态

- **数据位置**：`/storage/emulated/0/mbattery_charger/`
- **主要字段**：`learned_cap`、`remaining_cap`、`cycle`、`tbat`、`vbat`、`ibus`、`vbus`、`wls_volt`、`wls_curr` 等。
- **主要用途**：容量提取、循环次数解析、充电协议识别、充电档位解析及充电器端参数展示。
- **更新特征**：日志写入与落盘存在延迟，应用的轮询间隔不等于底层数据的实际更新频率。

BMS 日志的可用字段取决于设备及系统版本。不同机型不一定提供完全相同的数据。

### 2. BatteryManager：电池端实时监测

- **接口**：`BatteryManager.BATTERY_PROPERTY_CURRENT_NOW`
- **主要用途**：获取电池端电流，并结合电压计算电池端功率。
- **刷新策略**：应用侧约每秒轮询一次。
- **数据特征**：电流读数的单位、符号及实际更新行为需要结合 Android 实现与设备厂商行为处理。

本项目会对电流极性进行归一化，使充电方向以正值显示。

需要注意，BatteryManager 提供的电流读数并不等同于充电器的输出电流。它反映的是电池端的电流状态，可能受到系统功耗、充电管理策略及电量计实现的影响。

### 3. 两套数据如何对照？

BMS 数据主要用于观察充电器端及充电协议相关信息，BatteryManager 数据主要用于观察电池端电流、电压与功率。

在采样时间接近、测量口径明确的情况下，两侧功率的差异可以帮助分析系统运行功耗与转换损耗。但由于日志延迟、采样时差及两侧测量边界不同，**功率差值只能作为参考，不能直接视为精确的系统功耗或充电转换损耗**。

### 4. 数据可信度与适用边界

- 健康度是根据可读取的容量字段与预设设计容量计算得到的结果，不等同于专业电池检测设备给出的容量测试结果。
- 容量、电压与温度异常标记用于辅助识别可疑读数，不单独构成电池故障诊断。
- 日志数据可能存在缺失、延迟、格式差异或历史记录不完整的情况。
- 应用不会将尚未验证的机型适配能力视为已经得到实机确认。

## 技术架构

项目采用 Flutter 与 Kotlin 原生通道协作的结构。

```text
MEIZU Battery Healthy
│
├── Flutter UI
│   ├── 首页
│   ├── 充电详情页
│   ├── 历史趋势
│   ├── 更新日志
│   └── 关于页面
│
├── 业务逻辑层
│   ├── ChargeParser
│   ├── CapacityExtractor
│   ├── BatteryDataService
│   └── ChargeUtils
│
├── 服务层
│   ├── SafStorageService
│   ├── BatteryManagerService
│   ├── DatabaseService
│   └── ThemeService
│
└── Kotlin 原生层
    ├── /saf
    ├── /charge
    ├── /charge_events
    ├── /frame_rate
    └── BatteryManagerHelper
```

### 主要技术组件

- **Flutter**：跨层 UI 与业务逻辑实现。
- **Kotlin / Android 原生接口**：文件访问、BatteryManager 数据读取、充电插拔事件与刷新率控制。
- **SQLite**：本地历史数据持久化及数据库迁移。
- **SharedPreferences**：主题配置与授权相关状态的持久化。

日志访问通过 Android Storage Access Framework（SAF）授权机制管理。实际可读取的数据取决于用户授权状态及设备系统对相关文件的访问权限。

## 开发环境

| 组件 | 版本要求 |
|---|---|
| Flutter SDK | `^3.9.2` |
| Android | API 26+（Android 8.0+） |
| Android Gradle Plugin | 9.0.0 |
| Kotlin Gradle Plugin | 2.2.20 |
| Gradle | 9.3.1 |

当前版本使用经过验证的构建工具组合。升级 AGP、KGP 或 Gradle 前，建议先完成构建兼容性验证。

## 从源码构建

### 1. 获取源码

```bash
git clone https://git.whitetop.xyz/lxh2875931338/MEIZU-Battery-Healthy.git
cd MEIZU-Battery-Healthy
```

### 2. 安装依赖

```bash
flutter pub get
```

### 3. 运行 Debug 版本

```bash
flutter run --debug
```

### 4. 构建 Release APK

当前发布构建面向 ARM64 Android 设备：

```bash
flutter build apk --release --target-platform android-arm64
```

### 构建注意事项

- 修改 Kotlin 原生代码后，需要重新执行构建或运行流程；热重载不会重新编译原生代码。
- Release 构建需要 `android/app/proguard-rules.pro`，项目已包含对应规则。
- 不建议在未完成验证前随意升级 AGP、KGP 或 Gradle。
- 实际构建结果还取决于本地 Android SDK、JDK 及依赖环境。

## 版本历史

| 版本 | 主要更新 | 状态 |
|---|---|---|
| 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 上位机充电信息记录 | 📋 远景规划 |

以上规划不代表相关功能已经包含在当前发布版本中，实际进度以仓库更新为准。

## 反馈与机型适配

项目优先关注真实设备上的数据可用性与日志格式差异。

如果你希望协助适配新机型，欢迎提交 Issue，并尽可能提供以下信息：

- 手机型号。
- Flyme 系统版本。
- BMS 日志是否持续生成。
- 容量字段及充电相关字段的可用情况。
- 对应的异常现象与复现步骤。

日志样本可能包含设备运行信息。提交前请检查并移除个人信息、设备标识及其他不希望公开的内容。

**源码仓库：**

[MEIZU Battery Healthy](https://git.whitetop.xyz/lxh2875931338/MEIZU-Battery-Healthy)

> 本项目专注于魅族设备的电池状态观测与数据分析，不保证所有魅族机型或所有 Flyme 版本均可使用。监测结果仅供参考，不构成电池故障诊断或维修依据。