# running

**Repository Path**: zpblatand/running

## Basic Information

- **Project Name**: running
- **Description**: 跑步Android App，数据保存到本地数据库,默认使用高德地图。
- **Primary Language**: Kotlin
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-12-01
- **Last Updated**: 2025-12-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Running Assistant

一个基于MVI架构的跑步助手应用，用于记录跑步轨迹、统计跑步数据和查看历史记录。支持根据地区自动切换地图服务。

## 技术栈

- **开发语言**: Kotlin
- **框架**: Android Jetpack
- **架构**: MVI (Model-View-Intent)
- **数据库**: Room
- **位置服务**: Android Location API
- **依赖注入**: ViewModel + Repository Pattern
- **地图服务**: 高德地图 (中国大陆) / Google地图 (其他地区)
- **地图切换机制**: 基于地区自动切换

## 项目结构

```
app/src/main/java/com/blt/run/
├── MainActivity.kt      # 主活动
├── db/                  # 数据库相关代码
│   ├── Converters.kt    # 数据类型转换器
│   ├── RunDatabase.kt   # 数据库实例
│   └── RunDao.kt        # 数据访问对象
├── map/                 # 地图相关代码
│   ├── MapFactory.kt    # 地图工厂，用于创建不同地区的地图实例
│   ├── MapHandler.kt    # 地图处理接口
│   ├── AmapHandler.kt   # 高德地图实现
│   └── GoogleMapHandler.kt # Google地图实现
├── model/               # 数据模型
│   └── RunRecord.kt     # 跑步记录
├── mvi/                 # MVI架构核心组件
│   ├── running/         # RunningFragment的MVI组件
│   ├── statistics/      # StatisticsFragment的MVI组件
│   └── history/         # HistoryFragment的MVI组件
├── repository/          # 数据仓库
│   └── RunRepository.kt # 跑步数据仓库
├── service/             # 服务
│   ├── LocationService.kt # 定位服务
│   ├── LocationFactory.kt # 定位服务工厂
│   ├── LocationHandler.kt # 定位处理接口
│   ├── AmapLocationHandler.kt # 高德定位实现
│   └── GoogleLocationHandler.kt # Google定位实现
├── ui/                  # UI组件
│   ├── running/         # 跑步界面
│   ├── history/         # 历史记录
│   └── statistics/      # 统计数据
└── utils/               # 工具类
    └── RegionUtils.kt   # 地区判断工具
```

## 核心功能

1. **跑步记录**: 实时记录跑步轨迹、距离、时间和平均速度
2. **地图显示**: 显示实时跑步路线，支持地图缩放和平移
3. **智能地图切换**: 根据设备所在地区自动切换地图服务
   - 中国大陆地区使用高德地图
   - 其他地区使用Google地图
4. **数据统计**: 统计总跑步距离、总跑步次数和每日跑步距离
5. **历史记录**: 查看历史跑步记录
6. **实时定位**: 利用GPS定位获取实时位置信息

## MVI架构设计

### 核心组件

- **State**: 表示UI的状态，包含所有UI相关的数据
- **Intent**: 表示用户的操作或系统事件
- **ViewModel**: 处理Intent，更新State，并将新的State发送给View
- **View**: 观察State变化，更新UI，并将用户操作转换为Intent发送给ViewModel

### 实现示例

```kotlin
// State类
data class RunningState(
    val isLoading: Boolean = false,
    val isRunning: Boolean = false,
    val currentLocation: Location? = null,
    val trackPoints: List<Location> = emptyList(),
    val distance: Double = 0.0,
    val duration: Long = 0L,
    val averageSpeed: Double = 0.0
)

// Intent类
sealed class RunningIntent {
    object StartRunning : RunningIntent()
    object StopRunning : RunningIntent()
    object PauseRunning : RunningIntent()
    object ResumeRunning : RunningIntent()
    data class LocationUpdate(val location: Location) : RunningIntent()
}

// ViewModel类
class RunningViewModel(application: Application) : AndroidViewModel(application) {
    private val _state = MutableStateFlow(RunningState())
    val state: StateFlow<RunningState> = _state
    
    // 处理Intent
    fun handleIntent(intent: RunningIntent) {
        // 更新状态逻辑
    }
}

// View类 (Fragment)
class RunningFragment : Fragment() {
    private val runningViewModel: RunningViewModel by viewModels()
    
    override fun onViewCreated(view: View, savedInstanceState: Bundle?) {
        super.onViewCreated(view, savedInstanceState)
        
        // 观察State变化
        viewLifecycleOwner.lifecycleScope.launch {
            runningViewModel.state.collect {
                // 更新UI
            }
        }
        
        // 发送Intent
        startButton.setOnClickListener {
            runningViewModel.handleIntent(RunningIntent.StartRunning)
        }
    }
}
```

## 如何构建和运行

### 前置条件

- Android Studio Arctic Fox 或更高版本
- Android SDK 24 或更高版本
- Kotlin 1.5 或更高版本

### 地图配置

1. **高德地图配置** (中国大陆使用)
   - 在 `AndroidManifest.xml` 中添加高德地图API Key
   - 示例: `<meta-data android:name="com.amap.api.v2.apikey" android:value="your_amap_api_key"/>`

2. **Google地图配置** (其他地区使用)
   - 在 `AndroidManifest.xml` 中添加Google地图API Key
   - 示例: `<meta-data android:name="com.google.android.geo.API_KEY" android:value="your_google_maps_api_key"/>`
   - 确保在Google Cloud Console中启用了Maps SDK for Android

### 构建步骤

1. 克隆项目到本地
2. 打开Android Studio
3. 导入项目
4. 等待Gradle同步完成
5. 运行应用到Android设备或模拟器

### 命令行构建

```bash
./gradlew assembleDebug
```

## 地图切换机制

应用采用了基于地区的自动地图切换机制：

1. **地区判断**: 通过 `RegionUtils.isChinaRegion()` 方法判断设备所在地区
2. **工厂模式**: 使用 `MapFactory` 根据地区创建对应的地图处理器
3. **统一接口**: 所有地图处理器实现 `MapHandler` 接口，保证使用方式一致
4. **无缝切换**: 应用启动时自动选择合适的地图服务，用户无需手动切换

### 地图切换逻辑

```kotlin
// MapFactory.kt 核心代码
fun createMapHandler(fragment: Fragment): MapHandler {
    return if (RegionUtils.isChinaRegion()) {
        // 中国大陆使用高德地图
        AmapHandler(fragment)
    } else {
        // 其他地区使用Google地图
        GoogleMapHandler(fragment)
    }
}
```

## 许可证

MIT License

## 贡献

欢迎提交Issue和Pull Request！