feat: 支持 push
This commit is contained in:
richarjiang
265
docs/ios-push-notification-design.md
Normal file
265
docs/ios-push-notification-design.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# 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 运维监控
|
||||
- 推送服务健康检查
|
||||
- 性能指标监控
|
||||
- 告警机制设置
|
||||
Reference in New Issue
Block a user