288 lines
8.3 KiB
Markdown
288 lines
8.3 KiB
Markdown
# iOS远程推送功能实施计划
|
||
|
||
## 项目概述
|
||
|
||
本文档详细描述了在现有NestJS项目中实现iOS远程推送功能的完整实施计划。该功能将使用Apple官方APNs服务，通过@parse/node-apn库与Apple推送服务进行通信。
|
||
|
||
## 技术选型
|
||
|
||
### 核心技术栈
|
||
- **推送服务**: Apple官方APNs (Apple Push Notification service)
|
||
- **Node.js库**: @parse/node-apn (Trust Score: 9.8，支持HTTP/2)
|
||
- **认证方式**: Token-based authentication (推荐)
|
||
- **数据库**: MySQL (与现有项目保持一致)
|
||
|
||
### 依赖包
|
||
```json
|
||
{
|
||
"@parse/node-apn": "^5.0.0",
|
||
"uuid": "^11.1.0" // 已存在
|
||
}
|
||
```
|
||
|
||
## 实施阶段
|
||
|
||
### 第一阶段：基础设施搭建
|
||
1. **创建推送模块结构**
|
||
- 创建`src/push-notifications/`目录
|
||
- 设置模块、控制器、服务的基础结构
|
||
|
||
2. **数据库设计与实现**
|
||
- 创建推送令牌表 (t_user_push_tokens)
|
||
- 创建推送消息表 (t_push_messages)
|
||
- 创建推送模板表 (t_push_templates)
|
||
- 编写数据库迁移脚本
|
||
|
||
3. **APNs连接配置**
|
||
- 配置APNs认证信息
|
||
- 实现APNs Provider服务
|
||
- 设置连接池和错误处理
|
||
|
||
### 第二阶段：核心功能实现
|
||
1. **推送令牌管理**
|
||
- 实现设备令牌注册/更新/注销
|
||
- 令牌有效性验证
|
||
- 无效令牌清理机制
|
||
|
||
2. **推送消息发送**
|
||
- 实现单个推送发送
|
||
- 实现批量推送发送
|
||
- 实现静默推送发送
|
||
|
||
3. **推送模板系统**
|
||
- 模板创建/更新/删除
|
||
- 模板渲染引擎
|
||
- 动态数据绑定
|
||
|
||
### 第三阶段：API接口开发
|
||
1. **推送令牌管理API**
|
||
- POST /api/push-notifications/register-token
|
||
- PUT /api/push-notifications/update-token
|
||
- DELETE /api/push-notifications/unregister-token
|
||
|
||
2. **推送消息发送API**
|
||
- POST /api/push-notifications/send
|
||
- POST /api/push-notifications/send-by-template
|
||
- POST /api/push-notifications/send-batch
|
||
|
||
3. **推送模板管理API**
|
||
- GET /api/push-notifications/templates
|
||
- POST /api/push-notifications/templates
|
||
- PUT /api/push-notifications/templates/:id
|
||
- DELETE /api/push-notifications/templates/:id
|
||
|
||
### 第四阶段：优化与监控
|
||
1. **性能优化**
|
||
- 连接池管理
|
||
- 批量处理优化
|
||
- 缓存策略实现
|
||
|
||
2. **错误处理与重试**
|
||
- APNs错误分类处理
|
||
- 指数退避重试机制
|
||
- 无效令牌自动清理
|
||
|
||
3. **日志与监控**
|
||
- 推送状态日志记录
|
||
- 性能指标监控
|
||
- 错误率统计
|
||
|
||
## 文件结构
|
||
|
||
```
|
||
src/push-notifications/
|
||
├── push-notifications.module.ts
|
||
├── push-notifications.controller.ts
|
||
├── push-notifications.service.ts
|
||
├── apns.provider.ts
|
||
├── push-token.service.ts
|
||
├── push-template.service.ts
|
||
├── push-message.service.ts
|
||
├── models/
|
||
│ ├── user-push-token.model.ts
|
||
│ ├── push-message.model.ts
|
||
│ └── push-template.model.ts
|
||
├── dto/
|
||
│ ├── register-device-token.dto.ts
|
||
│ ├── update-device-token.dto.ts
|
||
│ ├── send-push-notification.dto.ts
|
||
│ ├── send-push-by-template.dto.ts
|
||
│ ├── create-push-template.dto.ts
|
||
│ ├── update-push-template.dto.ts
|
||
│ └── push-response.dto.ts
|
||
├── interfaces/
|
||
│ ├── push-notification.interface.ts
|
||
│ ├── apns-config.interface.ts
|
||
│ └── push-stats.interface.ts
|
||
└── enums/
|
||
├── device-type.enum.ts
|
||
├── push-type.enum.ts
|
||
└── push-message-status.enum.ts
|
||
```
|
||
|
||
## 环境配置
|
||
|
||
### 环境变量
|
||
```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
|
||
PUSH_BATCH_SIZE=100
|
||
```
|
||
|
||
### APNs认证文件
|
||
- 需要从Apple开发者账号下载.p8格式的私钥文件
|
||
- 将私钥文件安全地存储在服务器上
|
||
|
||
## 数据库表结构
|
||
|
||
### 推送令牌表 (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)
|
||
);
|
||
```
|
||
|
||
### 推送消息表 (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)
|
||
);
|
||
```
|
||
|
||
### 推送模板表 (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)
|
||
);
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 1. 注册设备令牌
|
||
```typescript
|
||
// iOS客户端获取设备令牌后，调用此API
|
||
POST /api/push-notifications/register-token
|
||
{
|
||
"deviceToken": "a9d0ed10e9cfd022a61cb08753f49c5a0b0dfb383697bf9f9d750a1003da19c7",
|
||
"deviceType": "IOS",
|
||
"appVersion": "1.0.0",
|
||
"osVersion": "iOS 15.0",
|
||
"deviceName": "iPhone 13"
|
||
}
|
||
```
|
||
|
||
### 2. 发送推送通知
|
||
```typescript
|
||
// 在业务服务中调用推送服务
|
||
await this.pushNotificationsService.sendNotification({
|
||
userIds: ['user_123'],
|
||
title: '训练提醒',
|
||
body: '您今天的普拉提训练还未完成，快来打卡吧！',
|
||
payload: {
|
||
type: 'training_reminder',
|
||
trainingId: 'training_123'
|
||
}
|
||
});
|
||
```
|
||
|
||
### 3. 使用模板发送推送
|
||
```typescript
|
||
// 使用预定义模板发送推送
|
||
await this.pushNotificationsService.sendNotificationByTemplate(
|
||
'user_123',
|
||
'training_reminder',
|
||
{
|
||
userName: '张三',
|
||
trainingName: '核心力量训练'
|
||
}
|
||
);
|
||
```
|
||
|
||
## 预期收益
|
||
|
||
1. **用户体验提升**: 及时推送训练提醒、饮食记录等重要信息
|
||
2. **用户粘性增强**: 通过个性化推送提高用户活跃度
|
||
3. **业务目标达成**: 支持各种业务场景的推送需求
|
||
4. **技术架构完善**: 建立可扩展的推送服务架构
|
||
|
||
## 风险评估
|
||
|
||
### 技术风险
|
||
- **APNs连接稳定性**: 通过连接池和重试机制降低风险
|
||
- **推送令牌管理**: 实现自动清理和验证机制
|
||
- **性能瓶颈**: 通过批量处理和缓存优化解决
|
||
|
||
### 业务风险
|
||
- **用户隐私**: 严格遵守数据保护法规
|
||
- **推送频率**: 实现推送频率限制避免骚扰用户
|
||
- **内容审核**: 建立推送内容审核机制
|
||
|
||
## 后续扩展
|
||
|
||
1. **多平台支持**: 扩展Android推送功能
|
||
2. **推送策略**: 实现智能推送时机和内容优化
|
||
3. **数据分析**: 推送效果分析和用户行为追踪
|
||
4. **A/B测试**: 推送内容和策略的A/B测试功能
|
||
|
||
## 总结
|
||
|
||
本实施计划提供了一个完整的iOS远程推送功能解决方案，包括技术选型、架构设计、实施步骤和使用示例。该方案具有良好的可扩展性和维护性，能够满足当前业务需求并为未来扩展留有空间。
|
||
|
||
实施完成后，您将拥有一个功能完整、性能优良的推送服务系统，可以通过简单的API调用来发送各种类型的推送通知，提升用户体验和业务指标。 |