# iOS APNs 推送通知集成文档

## 概述

本文档描述了如何在数字普拉提应用中集成iOS APNs (Apple Push Notification Service) 推送通知功能。该功能包括设备令牌管理、权限请求和与后端API的交互。

## 功能特性

- ✅ 设备令牌自动获取和注册
- ✅ 设备令牌更新和注销
- ✅ 推送通知权限管理
- ✅ 本地通知和远程推送支持
- ✅ 用户友好的设置界面
- ✅ 错误处理和状态管理

## 文件结构

```
services/
├── pushNotifications.ts        # 推送通知API服务
├── pushNotificationManager.ts  # 推送通知管理器
└── notifications.ts            # 本地通知服务（已更新）

hooks/
└── usePushNotifications.ts     # 推送通知Hook

app/
├── index.tsx                   # 应用入口（已更新）
├── push-notification-settings.tsx # 推送通知设置页面
└── (tabs)/personal.tsx         # 个人页面（已更新）
```

## API接口

### 1. 注册设备令牌

```typescript
POST /api/push-notifications/register-token
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "deviceToken": "a9d0ed10e9cfd022a61cb08753f49c5a0b0dfb383697bf9f9d750a1003da19c7",
  "deviceType": "IOS",
  "appVersion": "1.0.0",
  "osVersion": "iOS 15.0",
  "deviceName": "iPhone 13"
}
```

### 2. 更新设备令牌

```typescript
PUT /api/push-notifications/update-token
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "currentDeviceToken": "old-device-token",
  "newDeviceToken": "new-device-token",
  "appVersion": "1.0.1",
  "osVersion": "iOS 15.1"
}
```

### 3. 注销设备令牌

```typescript
DELETE /api/push-notifications/unregister-token
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "deviceToken": "device-token-to-unregister"
}
```

## 使用方法

### 1. 自动初始化

推送通知功能会在应用启动时自动初始化，无需手动调用。初始化过程包括：

1. 请求推送通知权限
2. 获取设备令牌
3. 注册设备令牌到后端
4. 设置监听器

### 2. 使用Hook

```typescript
import { usePushNotifications } from '@/hooks/usePushNotifications';

function MyComponent() {
  const {
    isInitialized,
    tokenStatus,
    isLoading,
    registerToken,
    getCurrentToken,
    updateTokenStatus,
    clearAllData,
  } = usePushNotifications();

  // 使用状态和方法
}
```

### 3. 手动管理令牌

```typescript
import { pushNotificationManager } from '@/services/pushNotificationManager';

// 注册设备令牌
await pushNotificationManager.registerDeviceToken();

// 更新设备令牌
await pushNotificationManager.updateDeviceToken(newToken);

// 注销设备令牌
await pushNotificationManager.unregisterDeviceToken();

// 获取当前令牌
const token = pushNotificationManager.getCurrentToken();
```

### 4. 发送本地通知

```typescript
import { notificationService } from '@/services/notifications';

// 发送立即通知
await notificationService.sendImmediateNotification({
  title: '标题',
  body: '内容',
  data: { type: 'custom' },
  sound: true,
  priority: 'high',
});

// 发送定时通知
await notificationService.scheduleNotificationAtDate(
  {
    title: '定时通知',
    body: '这是一个定时通知',
    data: { type: 'scheduled' },
  },
  new Date(Date.now() + 60000) // 1分钟后
);
```

## 用户界面

### 推送通知设置页面

用户可以通过以下路径访问推送通知设置：

`个人页面 → 通知 → 推送通知设置`

设置页面包含：

- 初始化状态显示
- 令牌状态信息
- 设备令牌显示（部分隐藏）
- 手动注册按钮
- 状态刷新按钮
- 数据清除按钮

### 个人页面集成

在个人页面的通知部分添加了"推送通知设置"入口，用户可以：

- 开启/关闭消息推送
- 访问详细的推送通知设置
- 查看和管理设备令牌

## 状态管理

### 令牌状态

```typescript
enum TokenStatus {
  UNKNOWN = 'unknown',      // 状态未知
  GRANTED = 'granted',      // 权限已授予，但未注册
  DENIED = 'denied',        // 权限被拒绝
  REGISTERED = 'registered', // 设备令牌已注册
  FAILED = 'failed',        // 初始化失败
}
```

### 本地存储

- `@device_token`: 存储当前设备令牌
- `@token_registered`: 标记令牌是否已注册

## 错误处理

### 常见错误及解决方案

1. **权限被拒绝**
   - 引导用户到系统设置中开启通知权限
   - 提供友好的错误提示

2. **设备令牌获取失败**
   - 检查设备是否支持推送通知
   - 确保在真实设备上测试（模拟器不支持）

3. **网络请求失败**
   - 提供重试机制
   - 显示网络错误提示

4. **API调用失败**
   - 记录详细错误日志
   - 提供用户友好的错误信息

## 开发注意事项

1. **真机测试**
   - 推送通知功能必须在真实iOS设备上测试
   - 模拟器无法获取设备令牌

2. **证书配置**
   - 确保APNs证书正确配置
   - Bundle Identifier与证书匹配

3. **后台模式**
   - 在`app.json`中启用了`remote-notification`后台模式
   - 支持后台接收推送通知

4. **调试技巧**
   - 使用Xcode控制台查看推送相关日志
   - 检查设备令牌是否正确获取
   - 验证API请求和响应

## 测试建议

1. **功能测试**
   - 测试权限请求流程
   - 验证设备令牌注册
   - 测试本地通知功能

2. **边界情况**
   - 权限被拒绝时的处理
   - 网络不可用时的行为
   - 应用被杀死时的推送接收

3. **性能测试**
   - 初始化时间测试
   - 内存使用情况
   - 电池消耗评估

## 后续优化

1. **功能增强**
   - 添加推送通知统计
   - 支持通知分类管理
   - 实现推送消息历史

2. **用户体验**
   - 优化设置页面UI
   - 添加推送通知预览
   - 提供更详细的状态说明

3. **技术改进**
   - 实现令牌自动刷新
   - 添加推送送达统计
   - 优化错误恢复机制