digital-pilates/docs/notification-user-preference-implementation.md

推送通知用户偏好设置控制实现文档

概述

本次实现为项目的推送通知系统添加了用户偏好设置控制功能。用户现在可以通过个人页面的开关来控制是否接收推送通知，该设置会在底层推送服务中生效。

实现内容

1. 用户偏好设置扩展 (utils/userPreferences.ts)

新增了以下功能：

• 接口扩展：在 UserPreferences 接口中添加了 notificationEnabled: boolean 字段
• 存储键：添加了 NOTIFICATION_ENABLED 存储键
• 默认值：推送通知默认开启 (true)
• 新增方法：
  • setNotificationEnabled(enabled: boolean): 设置推送开关状态
  • getNotificationEnabled(): 获取推送开关状态
  • 更新了 resetUserPreferences() 以包含推送设置

2. 推送服务核心控制 (services/notifications.ts)

在 NotificationService 类中添加了用户偏好检查机制：

• 新增方法：isNotificationAllowed() - 检查用户是否允许推送通知
• 双重检查：
  1. 检查用户偏好设置中的推送开关
  2. 检查系统推送权限状态
• 统一拦截：在 scheduleLocalNotification() 方法中统一检查，确保所有推送都受控制

3. 个人页面开关同步 (app/(tabs)/personal.tsx)

更新了个人页面的推送开关逻辑：

• 状态同步：开关状态与用户偏好设置保持同步
• 页面加载：页面聚焦时自动加载用户推送偏好设置
• 开关处理：
  • 开启时：先检查系统权限，成功后保存用户偏好
  • 关闭时：直接保存用户偏好设置
• 错误处理：提供友好的错误提示和引导

工作流程

用户操作推送开关
       ↓
检查系统推送权限 (仅开启时)
       ↓
保存用户偏好设置
       ↓
底层推送服务检查
       ↓
发送/阻止推送通知

使用方式

1. 用户操作

用户可以在个人页面的"通知"部分找到"消息推送"开关：

• 开启：需要系统权限，成功后会发送测试通知
• 关闭：立即生效，不会收到任何推送通知

2. 开发者使用

所有现有的推送通知方法都会自动受到用户偏好设置控制：

// 这些方法都会自动检查用户偏好设置
await notificationService.sendImmediateNotification(notification);
await WorkoutNotificationHelpers.sendWorkoutStartReminder(userName);
await GoalNotificationHelpers.sendGoalAchievementNotification(userName, goalName);

3. 测试功能

提供了完整的测试工具 (utils/notificationTest.ts)：

import { NotificationTestHelpers } from '@/utils/notificationTest';

// 测试用户偏好设置控制
await NotificationTestHelpers.testUserPreferenceControl();

// 测试权限状态
await NotificationTestHelpers.testPermissionStatus();

// 测试不同类型的通知
await NotificationTestHelpers.testDifferentNotificationTypes();

技术特点

1. 双重保护机制

• 用户偏好层：用户主动控制是否接收推送
• 系统权限层：系统级别的推送权限控制

2. 统一拦截点

• 所有推送通知都通过 NotificationService.scheduleLocalNotification() 方法
• 在此方法中统一检查用户偏好和系统权限
• 确保没有推送能绕过用户设置

3. 状态同步

• 个人页面开关与用户偏好设置实时同步
• 页面聚焦时自动刷新状态
• 避免状态不一致问题

4. 向后兼容

• 不影响现有推送通知代码
• 所有现有方法自动获得用户偏好控制功能
• 默认开启推送，保持原有用户体验

日志和调试

系统会在控制台输出相关日志：

用户已在偏好设置中关闭推送通知
推送通知被用户偏好设置或系统权限阻止，跳过发送
本地通知已安排，ID: notification-id-123

注意事项

1. 权限优先级：即使用户开启了偏好设置，如果系统权限被拒绝，推送仍然无法发送
2. 测试通知：用户开启推送时会发送一条测试通知，确认功能正常
3. 错误处理：所有操作都有完善的错误处理和用户提示
4. 性能影响：每次发送推送前会进行异步检查，但影响微乎其微

未来扩展

可以考虑添加更细粒度的推送控制：

• 按通知类型分别控制（运动提醒、目标通知等）
• 时间段控制（勿扰时间）
• 频率控制（每日最大推送数量）

这些功能可以基于当前的架构轻松扩展。