plates-server/docs/ios-push-notification-design.md

# iOS远程推送功能设计方案

## 1. 技术方案概述

### 1.1 推送服务选择
- **服务提供商**: Apple官方APNs (Apple Push Notification service)
- **Node.js库**: @parse/node-apn (Trust Score: 9.8，支持HTTP/2，维护良好)
- **认证方式**: Token-based authentication (推荐) 或 Certificate-based authentication

### 1.2 技术架构
```
iOS App -> APNs -> 后端服务器 (NestJS) -> APNs Provider -> iOS设备
```

### 1.3 核心组件
1. **推送令牌管理**: 存储和管理设备推送令牌
2. **APNs服务**: 与Apple推送服务通信
3. **消息模板系统**: 管理推送消息内容
4. **推送日志**: 记录推送状态和结果
5. **API接口**: 提供推送令牌注册和推送发送功能

## 2. 数据库设计

### 2.1 推送令牌表 (t_user_push_tokens)
```sql
CREATE TABLE t_user_push_tokens (
  id VARCHAR(36) PRIMARY KEY DEFAULT (UUID()),
  user_id VARCHAR(255) NOT NULL,
  device_token VARCHAR(255) NOT NULL,
  device_type ENUM('IOS', 'ANDROID') NOT NULL DEFAULT 'IOS',
  app_version VARCHAR(50),
  os_version VARCHAR(50),
  device_name VARCHAR(255),
  is_active BOOLEAN DEFAULT TRUE,
  last_used_at DATETIME,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  
  INDEX idx_user_id (user_id),
  INDEX idx_device_token (device_token),
  INDEX idx_user_device (user_id, device_token),
  UNIQUE KEY uk_user_device_token (user_id, device_token)
);
```

### 2.2 推送消息表 (t_push_messages)
```sql
CREATE TABLE t_push_messages (
  id VARCHAR(36) PRIMARY KEY DEFAULT (UUID()),
  user_id VARCHAR(255) NOT NULL,
  device_token VARCHAR(255) NOT NULL,
  message_type VARCHAR(50) NOT NULL,
  title VARCHAR(255),
  body TEXT,
  payload JSON,
  push_type ENUM('ALERT', 'BACKGROUND', 'VOIP', 'LIVEACTIVITY') DEFAULT 'ALERT',
  priority TINYINT DEFAULT 10,
  expiry DATETIME,
  collapse_id VARCHAR(64),
  status ENUM('PENDING', 'SENT', 'FAILED', 'EXPIRED') DEFAULT 'PENDING',
  apns_response JSON,
  error_message TEXT,
  sent_at DATETIME,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  
  INDEX idx_user_id (user_id),
  INDEX idx_status (status),
  INDEX idx_created_at (created_at),
  INDEX idx_message_type (message_type)
);
```

### 2.3 推送模板表 (t_push_templates)
```sql
CREATE TABLE t_push_templates (
  id VARCHAR(36) PRIMARY KEY DEFAULT (UUID()),
  template_key VARCHAR(100) NOT NULL UNIQUE,
  title VARCHAR(255) NOT NULL,
  body TEXT NOT NULL,
  payload_template JSON,
  push_type ENUM('ALERT', 'BACKGROUND', 'VOIP', 'LIVEACTIVITY') DEFAULT 'ALERT',
  priority TINYINT DEFAULT 10,
  is_active BOOLEAN DEFAULT TRUE,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  
  INDEX idx_template_key (template_key),
  INDEX idx_is_active (is_active)
);
```

## 3. 服务架构设计

### 3.1 模块结构
```
src/push-notifications/
├── push-notifications.module.ts
├── push-notifications.controller.ts
├── push-notifications.service.ts
├── apns.provider.ts
├── models/
│   ├── user-push-token.model.ts
│   ├── push-message.model.ts
│   └── push-template.model.ts
├── dto/
│   ├── register-device-token.dto.ts
│   ├── send-push-notification.dto.ts
│   ├── push-template.dto.ts
│   └── push-response.dto.ts
└── interfaces/
    ├── push-notification.interface.ts
    └── apns-config.interface.ts
```

### 3.2 核心服务类
1. **PushNotificationsService**: 主要业务逻辑服务
2. **ApnsProvider**: APNs连接和通信服务
3. **PushTokenService**: 推送令牌管理服务
4. **PushTemplateService**: 推送模板管理服务

## 4. API接口设计

### 4.1 推送令牌管理
```
POST /api/push-notifications/register-token
PUT /api/push-notifications/update-token
DELETE /api/push-notifications/unregister-token
```

### 4.2 推送消息发送
```
POST /api/push-notifications/send
POST /api/push-notifications/send-by-template
POST /api/push-notifications/send-batch
```

### 4.3 推送模板管理
```
GET /api/push-notifications/templates
POST /api/push-notifications/templates
PUT /api/push-notifications/templates/:id
DELETE /api/push-notifications/templates/:id
```

## 5. 配置要求

### 5.1 环境变量
```bash
# APNs配置
APNS_KEY_ID=your_key_id
APNS_TEAM_ID=your_team_id
APNS_KEY_PATH=path/to/APNsAuthKey_XXXXXXXXXX.p8
APNS_BUNDLE_ID=com.yourcompany.yourapp
APNS_ENVIRONMENT=production # or sandbox

# 推送服务配置
PUSH_RETRY_LIMIT=3
PUSH_REQUEST_TIMEOUT=5000
PUSH_HEARTBEAT=60000
```

### 5.2 APNs认证配置
- **Token-based认证** (推荐):
  - Key ID: 从Apple开发者账号获取
  - Team ID: 从Apple开发者账号获取
  - 私钥文件: .p8格式的私钥文件

- **Certificate-based认证**:
  - 证书文件: .pem格式的证书文件
  - 私钥文件: .pem格式的私钥文件

## 6. 推送消息类型

### 6.1 基础推送类型
- **ALERT**: 标准推送通知，显示警告、播放声音或更新应用图标徽章
- **BACKGROUND**: 静默推送，不显示用户界面
- **VOIP**: VoIP推送，用于实时通信
- **LIVEACTIVITY**: 实时活动推送

### 6.2 业务场景推送
- 训练提醒
- 饮食记录提醒
- 挑战进度通知
- 会员到期提醒
- 系统通知

## 7. 错误处理和重试机制

### 7.1 常见错误处理
- **Unregistered**: 设备令牌无效，从数据库中删除
- **BadDeviceToken**: 设备令牌格式错误，记录并标记为无效
- **DeviceTokenNotForTopic**: 设备令牌与Bundle ID不匹配
- **TooManyRequests**: 请求频率过高，实现退避重试
- **InternalServerError**: APNs服务器错误，实现重试机制

### 7.2 重试策略
- 指数退避算法
- 最大重试次数限制
- 不同错误类型的差异化处理

## 8. 安全考虑

### 8.1 数据安全
- 推送令牌加密存储
- 敏感信息脱敏日志
- API访问权限控制

### 8.2 隐私保护
- 用户推送偏好设置
- 推送内容审核机制
- 推送频率限制

## 9. 监控和日志

### 9.1 推送监控
- 推送成功率统计
- 推送延迟监控
- 错误率分析

### 9.2 日志记录
- 推送请求日志
- APNs响应日志
- 错误详情日志

## 10. 性能优化

### 10.1 连接管理
- HTTP/2连接池
- 连接复用
- 心跳保活

### 10.2 批量处理
- 批量推送优化
- 异步处理机制
- 队列管理

## 11. 测试策略

### 11.1 单元测试
- 服务层逻辑测试
- 数据模型测试
- 工具函数测试

### 11.2 集成测试
- APNs连接测试
- 推送流程测试
- 错误处理测试

### 11.3 端到端测试
- 沙盒环境测试
- 真机推送测试
- 性能压力测试

## 12. 部署和运维

### 12.1 环境配置
- 开发环境: 使用APNs沙盒环境
- 测试环境: 使用APNs沙盒环境
- 生产环境: 使用APNs生产环境

### 12.2 运维监控
- 推送服务健康检查
- 性能指标监控
- 告警机制设置