richard/digital-pilates
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
digital-pilates/docs/workout-monitoring-feature.md
richarjiang 971aebd560 feat(workout): 新增锻炼结束监听和个性化通知功能 
实现了iOS HealthKit锻炼数据实时监听，当用户完成锻炼时自动发送个性化鼓励通知。包括锻炼类型筛选、时间范围控制、用户偏好设置等完整功能，并提供了测试工具和详细文档。
2025-10-13 10:05:02 +08:00

5.6 KiB
Raw Permalink Blame History

锻炼结束监听和推送通知功能

功能概述

这个功能实现了在 iOS 设备上监听用户锻炼结束事件，并在锻炼完成后自动发送个性化的鼓励推送通知。当用户完成锻炼（如跑步30分钟）时，系统会自动获取锻炼数据并分析，然后发送包含锻炼详情的鼓励消息。

技术架构

iOS 原生层

  • HKObserverQuery: 使用 HealthKit 的观察者查询监听锻炼数据变化
  • 后台执行: 配置应用在后台执行查询的能力
  • 事件桥接: 通过 React Native 桥接将原生事件传递到 JS 层

JavaScript 服务层

  • WorkoutMonitorService: 锻炼监听服务，处理原生事件
  • WorkoutNotificationService: 锻炼通知服务，分析和发送通知
  • WorkoutPreferences: 用户偏好设置管理

通知系统

  • 个性化内容: 基于锻炼类型、持续时间、消耗卡路里等生成定制消息
  • 智能时机: 避免深夜打扰，尊重用户偏好设置
  • 用户控制: 完整的开关和类型筛选功能

文件结构

ios/OutLive/
├── HealthKitManager.swift          # iOS 原生 HealthKit 管理器（已扩展）
├── HealthKitManager.m              # Objective-C 桥接文件（已扩展）

services/
├── workoutMonitor.ts               # 锻炼监听服务
├── workoutNotificationService.ts    # 锻炼通知服务
└── notifications.ts                # 通知服务（已扩展）

utils/
├── workoutPreferences.ts           # 锻炼通知偏好设置
└── workoutTestHelper.ts            # 测试工具

app/workout/
└── notification-settings.tsx       # 通知设置页面

app/_layout.tsx                     # 应用入口（已集成）

功能特性

1. 实时监听

  • 使用 HKObserverQuery 实现真正的实时监听
  • 当 HealthKit 中有新的锻炼数据时立即触发
  • 支持后台执行，即使应用在后台也能监听

2. 智能分析

  • 复用现有的锻炼数据分析功能
  • 支持心率区间分析、METs 计算、强度评估
  • 基于锻炼类型生成个性化鼓励内容

3. 个性化通知

不同锻炼类型的专属消息：

  • 跑步: "🏃‍♂️ 跑步完成！太棒了！您刚刚完成了30分钟的跑步，消耗了约250千卡热量。平均心率140次/分。坚持运动让身体更健康！💪"
  • 瑜伽: "🧘‍♀️ 瑜伽完成！45分钟的瑜伽练习完成！提升了柔韧性和内心平静。继续保持这份宁静！🌸"
  • HIIT: "🔥 HIIT训练完成！高强度间歇训练20分钟完成！消耗了约200千卡热量。心肺功能得到有效提升，您的努力值得称赞！⚡"

4. 用户控制

  • 功能开关: 允许用户启用/禁用锻炼结束通知
  • 时间段设置: 限制通知发送时间（如 8:00-22:00）
  • 锻炼类型筛选: 允许用户选择关心的锻炼类型
  • 通知频率控制: 避免短时间内重复通知

使用方法

用户设置

  1. 打开应用
  2. 进入设置页面（可通过锻炼历史页面访问）
  3. 配置锻炼通知偏好：
    • 启用/禁用功能
    • 设置通知时间范围
    • 选择要接收通知的锻炼类型

开发者测试

import { WorkoutTestHelper } from '@/utils/workoutTestHelper';

// 测试通知功能
await WorkoutTestHelper.testWorkoutNotifications();

// 测试偏好设置
await WorkoutTestHelper.testPreferences();

// 模拟锻炼完成
await WorkoutTestHelper.simulateWorkoutCompletion();

// 运行完整测试套件
await WorkoutTestHelper.runFullTestSuite();

权限要求

iOS 权限

  1. HealthKit 权限: 需要读取锻炼数据
  2. 通知权限: 需要发送推送通知
  3. 后台执行权限: 需要在后台监听数据变化

配置文件

在 app.json 中已配置必要的后台模式：

"UIBackgroundModes": [
  "processing",
  "fetch",
  "remote-notification"
]

技术细节

防抖处理

  • 使用 5 秒延迟避免短时间内重复处理
  • 确保 HealthKit 数据完全更新后再处理

错误处理

  • 完善的错误捕获和日志记录
  • 权限检查和用户友好提示

性能优化

  • 使用 HealthKit 原生后台查询，最小化电池消耗
  • 智能判断锻炼结束时机，避免频繁查询

故障排除

常见问题

  1. 通知未发送

    • 检查通知权限是否已授予
    • 检查锻炼通知是否在设置中启用
    • 检查当前时间是否在允许的时间范围内

  2. 监听不工作

    • 确保 HealthKit 权限已授予
    • 检查应用是否有后台执行权限
    • 重启应用重新初始化监听服务

  3. 重复通知

    • 系统有防重复机制，记录已处理的锻炼ID
    • 如果出现问题，可以清除应用数据重新开始

调试方法

  1. 使用 WorkoutTestHelper 进行测试
  2. 查看控制台日志了解详细执行过程
  3. 检查 iOS 设备的设置中的通知权限

未来扩展

  1. 更多锻炼类型支持: 添加更多运动类型的个性化消息
  2. 成就系统: 基于锻炼历史生成成就和里程碑
  3. 社交分享: 允许用户分享锻炼成就
  4. 智能建议: 基于锻炼数据提供个性化建议

注意事项

  1. 电池使用: 虽然使用了优化的后台查询，但仍会消耗一定电量
  2. 隐私保护: 所有数据仅在本地处理，不会上传到服务器
  3. 兼容性: 仅支持 iOS，需要 iOS 16.0+
  4. 测试环境: 在模拟器上可能无法完全测试，建议使用真机

更新日志

v1.0.0

  • 初始版本发布
  • 支持基本的锻炼结束监听和通知
  • 完整的用户偏好设置
  • 测试工具和文档