# Gem Plan

**Repository Path**: Dangerous828/gem-plan

## Basic Information

- **Project Name**: Gem Plan
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-19
- **Last Updated**: 2026-01-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# GemPlan - 智能健身计划应用

一个基于 Flutter 的健身计划管理应用，支持蓝牙设备连接（麦瑞克单车、小米手环）。

## 免责声明

### 设备兼容性
本应用**仅在以下设备上进行过测试**：
- 麦瑞克绝影one单车（Merach Jueying One）
- 小米手环9pro（Xiaomi Mi Band 9 Pro）

其他设备可能存在兼容性问题，使用前请自行确认。

### 使用限制
- 本项目**仅用于学习目的**，**禁止用于任何商业用途**
- 本应用仅提供一个用户自行设定运动计划的功能界面

### 风险提示
用户应当自行确保：
1. 创建的运动计划符合自身身体状况
2. 运动强度不超过身体负荷能力
3. 计划本身科学合理、不存在危害身体健康的设计

**因用户个人计划问题或运动过程中产生的任何身体伤害、心血管问题或其他健康风险，本应用概不负责。使用者应自行评估风险并对自己的健康负责。**

## 功能特性

### 核心功能
- **训练计划管理**：创建、编辑、删除自定义训练计划
- **蓝牙设备连接**：支持麦瑞克绝影one单车和小米手环9pro
- **实时运动数据**：在运动过程中实时显示心率、阻力等数据
- **训练历史记录**：记录并查看历史运动数据
- **计划导入导出**：支持通过文件分享训练计划
- **本地数据持久化**：SQLite 数据库与 JSON 文件双重存储

### 技术特点
- 跨平台支持（iOS、Android、Web、macOS、Linux、Windows）
- 完整的蓝牙协议实现
- 智能文件系统管理
- 响应式 UI 设计

## 环境要求

- Flutter SDK 3.0+
- Dart 3.0+
- Android SDK (API 21+) 或 iOS 11.0+

## 快速开始

### 1. 安装依赖

```bash
flutter pub get
```

### 2. 运行应用

```bash
flutter run
```

### 3. 构建发布

```bash
# Android
flutter build apk --release

# iOS
flutter build ios --release
```

## 项目结构

```
lib/
├── main.dart                 # 应用入口
├── core/
│   └── theme.dart            # 主题配置
├── models/
│   ├── training_plan.dart    # 训练计划模型
│   └── workout_record.dart   # 运动记录模型
├── services/
│   ├── bike_protocol_constants.dart  # 蓝牙协议常量
│   ├── bike_service.dart              # 单车控制服务
│   ├── ble_manager.dart               # BLE 设备管理
│   ├── database_service.dart          # 数据库服务
│   ├── device_storage.dart            # 设备存储
│   ├── hr_service.dart                # 心率服务
│   ├── plan_engine.dart               # 计划引擎
│   └── plan_storage_service.dart      # 计划存储服务
├── views/
│   ├── dashboard_screen.dart          # 仪表盘页面
│   ├── history_screen.dart            # 历史记录页面
│   ├── plan_editor_screen.dart        # 计划编辑页面
│   ├── plan_library_screen.dart       # 计划库页面
│   └── workout_session_screen.dart    # 运动会话页面
└── widgets/
    ├── auto_connect_handler.dart      # 自动连接处理
    ├── ble_scanner_dialog.dart        # 蓝牙扫描对话框
    ├── import_plan_dialog.dart        # 导入计划对话框
    └── timeline_editor/
        └── timeline_view.dart         # 时间线编辑器
```

## 使用说明

### 创建训练计划
1. 在计划库页面点击右上角 "+" 按钮
2. 输入计划名称和总时长
3. 添加训练阶段（时间、阻力等级）
4. 保存计划

### 连接设备
1. 进入仪表盘页面
2. 点击设备连接按钮
3. 选择要连接的蓝牙设备
4. 等待连接成功

### 开始训练
1. 选择一个训练计划
2. 点击开始训练按钮
3. 应用将引导完成整个训练过程

### 分享计划
1. 在计划库中找到要分享的计划
2. 点击更多按钮，选择"分享"
3. 选择分享方式（文件、社交媒体等）

### 导入计划
1. 点击右上角"导入"按钮
2. 选择要导入的计划文件
3. 确认导入

## 协议说明

### 麦瑞克单车协议
本项目实现了麦瑞克绝影one单车的蓝牙通信协议，包括：
- 设备握手连接
- 阻力等级控制
- 实时数据获取
- 校验和计算

详细信息请参阅 [BIKE_PROTOCOL.md](BIKE_PROTOCOL.md)。

## 开发指南

### 添加新功能
1. 创建对应的 Service 类处理业务逻辑
2. 在 models/ 目录添加数据模型
3. 在 views/ 目录创建 UI 页面
4. 更新路由配置

### 代码规范
- 遵循 Flutter 官方代码风格指南
- 使用 provider 或 GetX 进行状态管理
- 所有公开 API 需要添加注释

### 测试
```bash
flutter test
```

## 依赖说明

主要依赖：
- `provider`: 状态管理
- `shared_preferences`: 本地存储
- `sqflite`: SQLite 数据库
- `file_picker`: 文件选择
- `flutter_blue_plus`: 蓝牙通信
- `share_plus`: 分享功能

完整依赖列表请查看 `pubspec.yaml`。

## 故障排查

### 常见问题

**设备无法连接**
- 确保蓝牙已开启
- 检查设备是否在有效范围内
- 重启应用后重试

**计划无法保存**
- 检查存储权限
- 确认设备存储空间充足
- 查看日志输出具体错误信息

**导入失败**
- 确认文件格式正确
- 检查文件是否损坏
- 验证文件权限

### 日志查看
```bash
flutter logs
```

## 版本历史

### v1.0.0
- 初始版本发布
- 基础训练计划管理功能
- 蓝牙设备连接支持
- 麦瑞克单车协议实现

## 许可证

本项目仅供学习使用，禁止任何商业用途。

## 贡献指南

欢迎提交 Issue 和 Pull Request，但在提交前请确保：
1. 代码符合项目规范
2. 添加必要的测试用例
3. 更新相关文档

## 联系方式

- 项目地址：https://gitee.com/Dangerous828/gem-plan
- 问题反馈：https://gitee.com/Dangerous828/gem-plan/issues

---

**健康提示**：运动前请进行充分热身，运动过程中如感到不适应立即停止并寻求医疗帮助。