feat(workout): 新增锻炼结束监听和个性化通知功能

实现了iOS HealthKit锻炼数据实时监听，当用户完成锻炼时自动发送个性化鼓励通知。包括锻炼类型筛选、时间范围控制、用户偏好设置等完整功能，并提供了测试工具和详细文档。
2025-10-13 10:05:02 +08:00
parent 12883c5410
commit 971aebd560
18 changed files with 2210 additions and 1264 deletions
--- a/docs/workout-monitoring-feature.md
+++ b/docs/workout-monitoring-feature.md
@@ -0,0 +1,171 @@
+# 锻炼结束监听和推送通知功能
+
+## 功能概述
+
+这个功能实现了在 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. 配置锻炼通知偏好：
+   - 启用/禁用功能
+   - 设置通知时间范围
+   - 选择要接收通知的锻炼类型
+
+### 开发者测试
+```typescript
+import { WorkoutTestHelper } from '@/utils/workoutTestHelper';
+
+// 测试通知功能
+await WorkoutTestHelper.testWorkoutNotifications();
+
+// 测试偏好设置
+await WorkoutTestHelper.testPreferences();
+
+// 模拟锻炼完成
+await WorkoutTestHelper.simulateWorkoutCompletion();
+
+// 运行完整测试套件
+await WorkoutTestHelper.runFullTestSuite();
+```
+
+## 权限要求
+
+### iOS 权限
+1. **HealthKit 权限**: 需要读取锻炼数据
+2. **通知权限**: 需要发送推送通知
+3. **后台执行权限**: 需要在后台监听数据变化
+
+### 配置文件
+在 `app.json` 中已配置必要的后台模式：
+```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
+- 初始版本发布
+- 支持基本的锻炼结束监听和通知
+- 完整的用户偏好设置
+- 测试工具和文档