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

## 概述

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

## 实现内容

### 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. 开发者使用

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

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

### 3. 测试功能

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

```typescript
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. **性能影响**：每次发送推送前会进行异步检查，但影响微乎其微

## 未来扩展

可以考虑添加更细粒度的推送控制：
- 按通知类型分别控制（运动提醒、目标通知等）
- 时间段控制（勿扰时间）
- 频率控制（每日最大推送数量）

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