feat: add jpush push handler

2026-09-05 17:06:59 +08:00
parent efbfb7556a
commit 9e290b76b3
10 changed files with 1715 additions and 2 deletions
@@ -446,6 +446,138 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | 消息过大 | `{"ctrl":{"id":"pub-1","code":413,"text":"message too large","params":{"reason":"MESSAGE_TOO_LARGE","max_size":4194304}}}` | 禁止重试，提示压缩或拆分 |
 | 断线 | WebSocket close | 指数退避重连，重新 `hi -> token login -> sub me -> sub topics`，按最后完整 `seq + 1` 增量拉取 |

+##### 0.5.4.9 极光离线 Push 与重连补偿
+
+离线 Push 只承担提醒和唤醒 App，不作为消息正文或业务状态真源。客户端收到极光 Push 后，必须重新登录 IM，通过 `topic + seq`、`call_id` 或系统通知 ID 拉取服务端状态。普通聊天、群 @、系统通知、好友/群审批、音视频来电都复用同一套 extras 分发协议。
+
+客户端侧要求：
+
+- App 集成 JPush SDK，初始化使用极光 `AppKey`，不接触 `MasterSecret`。
+- 登录 IM 后将极光 alias 绑定为当前 `user_id`，例如 `usr...`；同一用户多设备允许绑定同一个 alias。
+- SDK 返回 `registration_id` 后调用 `PUT /v1/im/devices/{device_id}/push-token` 上报，`provider` 固定传 `jpush`。
+- 点击 Push 后按 `extras.type` 跳转，再按服务端数据补偿，不能只凭 Push payload 渲染最终状态。
+
+服务端侧要求：
+
+- `jpush_master_secret` 只保存在后台配置 `im_jpush` 分组，IM Server 通过内部配置接口读取并调用极光 REST API。
+- 用户在线时优先 WebSocket 实时投递；用户离线、后台或不可投递时生成 Push 任务。
+- 万人大群实时 fanout 不靠 Push；离线只对需要提醒的成员生成极光 Push，客户端重连后按 Topic seq 拉取补偿。
+- Push payload 默认不带敏感正文，通知栏文案按用户隐私设置降级。
+
+极光 Push extras 统一格式：
+
+```json
+{
+  "type": "im_message",
+  "tenant_code": "default",
+  "topic": "p2p...",
+  "seq": "128",
+  "sender_id": "usr_sender",
+  "message_type": "text"
+}
+```
+
+| `extras.type` | 必填字段 | 客户端动作 |
+| --- | --- | --- |
+| `im_message` | `tenant_code,topic,seq` | 打开会话，按本地最后 seq 补齐消息并定位。 |
+| `group_mention` | `tenant_code,topic,seq,sender_id` | 打开群会话并定位被 @ 消息。 |
+| `call_invite` | `tenant_code,topic,seq,call_id,call_type,caller_id` | 打开来电页前先登录 IM 并确认通话仍为有效来电。 |
+| `call_missed` | `tenant_code,topic,call_id` | 打开通话记录或对应会话。 |
+| `system_notification` | `tenant_code,notification_id` | 打开系统消息列表并刷新详情。 |
+| `friend_request` | `tenant_code,request_id` | 打开新朋友列表并刷新未处理数。 |
+| `group_request` | `tenant_code,topic,request_id` | 打开群审批入口并刷新列表。 |
+
+普通离线消息极光 payload 示例：
+
+```json
+{
+  "platform": "all",
+  "audience": {
+    "alias": ["usr_target"]
+  },
+  "notification": {
+    "alert": "你收到一条新消息",
+    "android": {
+      "title": "MeetingIM",
+      "alert": "你收到一条新消息",
+      "extras": {
+        "type": "im_message",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "128"
+      }
+    },
+    "ios": {
+      "alert": {
+        "title": "MeetingIM",
+        "body": "你收到一条新消息"
+      },
+      "sound": "default",
+      "badge": "+1",
+      "extras": {
+        "type": "im_message",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "128"
+      }
+    }
+  },
+  "options": {
+    "time_to_live": 86400,
+    "apns_production": false,
+    "classification": 1
+  }
+}
+```
+
+音视频来电极光 payload 示例：
+
+```json
+{
+  "platform": "all",
+  "audience": {
+    "alias": ["usr_callee"]
+  },
+  "notification": {
+    "alert": "收到一通语音通话",
+    "android": {
+      "title": "语音通话",
+      "alert": "张三邀请你语音通话",
+      "extras": {
+        "type": "call_invite",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "30",
+        "call_id": "call_01K...",
+        "call_type": "audio",
+        "caller_id": "usr_caller"
+      }
+    },
+    "ios": {
+      "alert": {
+        "title": "语音通话",
+        "body": "张三邀请你语音通话"
+      },
+      "sound": "default",
+      "badge": "+1",
+      "extras": {
+        "type": "call_invite",
+        "tenant_code": "default",
+        "topic": "p2p...",
+        "seq": "30",
+        "call_id": "call_01K...",
+        "call_type": "audio",
+        "caller_id": "usr_caller"
+      }
+    }
+  },
+  "options": {
+    "time_to_live": 60,
+    "apns_production": false,
+    "classification": 1
+  }
+}
+```

 #### 0.5.5 Long Polling 与文件基础示例