richard/plates-server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1fe969aa97c9cae64c6744f9045ac2a8ebadd136
plates-server/docs/ios-push-notification-design.md
richarjiang 305a969912 feat: 支持 push
2025-10-11 17:38:04 +08:00

6.9 KiB
Raw Blame History

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)

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)

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)

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 环境变量

# 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 运维监控

  • 推送服务健康检查
  • 性能指标监控
  • 告警机制设置