lujiuyin/suixinkan_uikit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1b2637f0ee954b8424db6172a653e8ea5d74bc92
suixinkan_uikit/docs/后端消息推送格式.md
汉秋 1b2637f0ee fix: 推送点击仅按 type 路由到收款页或消息中心。 
对齐后端消息类型约定，去掉 route/uri 等兼容字段，并补充联调日志与单测。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-22 18:20:36 +08:00

427 lines
14 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 后端消息推送格式
## 1. 文档说明
- 本文整理后端经极光推送发送到 Android 和 iOS 的通知消息格式。
- 当前内容基于 2026-07-22 的 Android、iOS 实际收包日志、两端客户端现有解析逻辑，以及后端开发人员提供的 `PushMsg` 类型定义。
- 后端当前定义了 `1`～`12`、`100`、`999` 共 14 个业务消息类型；目前已取得 `type = 1`（付款成功）、`type = 2`（退款成功）和 `type = 6`（扫码成功）的完整收包样本。
- 本文描述的是推送协议，不是普通 HTTP 接口响应格式。
## 2. 统一业务结构
极光在 Android 和 iOS 上交付的原始结构不同，但当前消息都可以归一化为以下业务结构：
```json
{
"title": "通知标题",
"content": "通知正文",
"msg_id": 1858,
"type": 6,
"data": {
"order_type": 14
}
}
```
### 2.1 公共业务字段
| 字段 | 当前类型 | 说明 |
| --- | --- | --- |
| `title` | string | 通知标题。Android 为 `notificationTitle`，iOS 为 `aps.alert.title`。 |
| `content` | string | 通知正文。Android 为 `notificationContent`，iOS 为 `aps.alert.body`。 |
| `msg_id` | int | 后端业务消息 ID。它与极光消息 ID 不是同一个字段。 |
| `type` | int | 业务消息类型，是客户端业务分发的主要依据。 |
| `data` | object | 随消息类型变化的业务数据。 |
> “当前类型”表示现有样本中观察到的 JSON 类型。后端应保持字段类型稳定，避免同一个字段在不同推送中交替使用数字、字符串或 `null`。
## 3. Android 收包格式
Android 通过极光 `JPushMessageReceiver.onNotifyMessageArrived` 收到通知。标题、正文和附加字段分别由 SDK 提供，其中 `extras` 是 JSON 字符串：
```text
[onNotifyMessageArrived] msgId=<极光消息ID>, title=<标题>, content=<正文>, extras=<业务JSON字符串>
```
`extras` 的当前结构为：
```json
{
"data": {},
"msg_id": 0,
"type": 0
}
```
### 3.1 扫码成功原始日志
```text
[onNotifyMessageArrived] msgId=18103321643292031, title=扫码成功通知, content=扫码成功, extras={"data":{"order_type":14},"msg_id":1852,"type":6}
```
对应的 `extras`：
```json
{
"data": {
"order_type": 14
},
"msg_id": 1852,
"type": 6
}
```
### 3.2 付款成功原始日志
```text
[onNotifyMessageArrived] msgId=18103321644290274, title=付款成功通知, content=您的订单 #260722128005 已支付成功，支付金额 ¥0.01, extras={"data":{"order_amount":"0.01","order_number":"260722128005","order_type":14,"pay_time":1784711036,"remark":""},"msg_id":1853,"type":1}
```
对应的 `extras`：
```json
{
"data": {
"order_amount": "0.01",
"order_number": "260722128005",
"order_type": 14,
"pay_time": 1784711036,
"remark": ""
},
"msg_id": 1853,
"type": 1
}
```
### 3.3 退款成功原始日志
```text
[onNotifyMessageArrived] msgId=18103321800527159, title=退款成功通知, content=您的订单 #260722128002 已成功退款，退款金额 ¥0.01, extras={"data":{},"msg_id":1867,"type":2}
```
对应的 `extras`：
```json
{
"data": {},
"msg_id": 1867,
"type": 2
}
```
## 4. iOS 收包格式
iOS 通过 APNs/极光收到 `userInfo` 字典。与 Android 相比：
- 标题和正文位于 `aps.alert`。
- Android `extras` 中的 `msg_id`、`type`、`data` 在 iOS 中位于 payload 顶层。
- `_j_*` 为极光传输层内部字段，不应作为业务分发依据。
通用结构如下：
```json
{
"_j_business": 1,
"_j_data": "{\"data_msgtype\":1,\"push_type\":8,\"is_vip\":0}",
"_j_msgid": 18103321726881995,
"_j_uid": 86399144805,
"aps": {
"alert": {
"body": "通知正文",
"title": "通知标题"
},
"sound": "default"
},
"data": {},
"msg_id": 0,
"type": 0
}
```
> 原始日志中该内部字段显示为 `*j\_data*`。本文按极光其他内部字段的命名方式记为 `_j_data`；后续联调时应以设备收到的真实字典 key 为准。该字段目前不参与业务解析。
### 4.1 扫码成功 payload
```json
{
"_j_business": 1,
"_j_data": "{\"data_msgtype\":1,\"push_type\":8,\"is_vip\":0}",
"_j_msgid": 18103321726881995,
"_j_uid": 86399144805,
"aps": {
"alert": {
"body": "扫码成功",
"title": "扫码成功通知"
},
"sound": "default"
},
"data": {
"order_type": 14
},
"msg_id": 1858,
"type": 6
}
```
### 4.2 付款成功 payload
```json
{
"_j_business": 1,
"_j_data": "{\"data_msgtype\":1,\"push_type\":8,\"is_vip\":0}",
"_j_msgid": 18103321720587147,
"_j_uid": 86399144805,
"aps": {
"alert": {
"body": "您的订单 #260722128006 已支付成功，支付金额 ¥0.01",
"title": "付款成功通知"
},
"sound": "default"
},
"data": {
"order_amount": "0.01",
"order_number": "260722128006",
"order_type": 14,
"pay_time": 1784712671,
"remark": ""
},
"msg_id": 1856,
"type": 1
}
```
### 4.3 退款成功 payload
```json
{
"_j_business": 1,
"_j_data": "{\"data_msgtype\":1,\"push_type\":8,\"is_vip\":0}",
"_j_msgid": 18103321792603316,
"_j_uid": 86399144805,
"aps": {
"alert": {
"body": "您的订单 #260722128005 已成功退款，退款金额 ¥0.01",
"title": "退款成功通知"
},
"sound": "default"
},
"data": {},
"msg_id": 1862,
"type": 2
}
```
## 5. Android 与 iOS 字段对应关系
| 语义 | Android | iOS | 是否用于业务 |
| --- | --- | --- | --- |
| 极光消息 ID | SDK `message.msgId` | `_j_msgid` | 否，仅用于推送链路日志与排查 |
| 通知标题 | SDK `message.notificationTitle` | `aps.alert.title` | 是，用于展示 |
| 通知正文 | SDK `message.notificationContent` | `aps.alert.body` | 是，用于展示 |
| 后端业务消息 ID | `extras.msg_id` | 顶层 `msg_id` | 是 |
| 业务消息类型 | `extras.type` | 顶层 `type` | 是，作为业务分发主键 |
| 业务数据 | `extras.data` | 顶层 `data` | 是，结构由 `type` 决定 |
| 极光业务标记 | SDK 内部处理 | `_j_business` | 否 |
| 极光附加元数据 | SDK 内部处理 | `_j_data` | 否 |
| 极光用户 ID | SDK 内部处理 | `_j_uid` | 否 |
| APNs 展示配置 | 不适用 | `aps` | 仅 iOS 系统使用 |
### 5.1 两种消息 ID 不可混用
- `msgId` / `_j_msgid`：极光生成的传输层消息 ID，当前样本为 17 位数字。
- `msg_id`：后端生成的业务消息 ID，当前样本为 `1852`、`1853`、`1856`、`1858`。
- 客户端日志、去重或上报时必须明确需要哪一种 ID，不能仅用名称相近而互相替代。
- 极光消息 ID 已超过 JavaScript 可安全表示的整数范围；若需要经过 JavaScript、WebView 或其他只能安全处理 53 位整数的链路，应按字符串传递。
## 6. 消息类型清单
### 6.1 后端 `PushMsg` 完整类型定义
定义位置：后端 `PushMsg.php` 第 49 行附近。
| `type` | 消息类型 | 后端备注 | 当前收包样本 |
| ---: | --- | --- | --- |
| `1` | 付款成功通知 | 上文实际示例即为此类型 | Android、iOS 均已取得 |
| `2` | 退款成功通知 | — | Android、iOS 均已取得 |
| `3` | 下单成功通知 | App 无需推送，当前未使用 | 暂无 |
| `4` | 签到成功通知 | — | 暂无 |
| `5` | 付尾款成功通知 | — | 暂无 |
| `6` | 扫码成功通知 | — | Android、iOS 均已取得 |
| `7` | 付定金成功通知 | — | 暂无 |
| `8` | 订单核销成功通知 | — | 暂无 |
| `9` | 剪辑完成通知 | — | 暂无 |
| `10` | 修图完成通知 | — | 暂无 |
| `11` | 跟拍签到通知 | — | 暂无 |
| `12` | 剪辑师新任务通知 | 类型名称映射中漏配 | 暂无 |
| `100` | 用户登出通知 | 账号在其他设备登录 | 暂无 |
| `999` | 系统消息 | 当前未使用 | 暂无 |
后端特别说明：
- `type` 表示业务消息类型，不代表推送渠道。
- 推送渠道的取值另有定义：`1` 为极光推送，`2` 为微信小程序，`999` 为不推送。
- `type = 12` 虽然已经定义，但尚未加入后端 `MAP_TYPE_NAMES`。后端调用 `getTypeName(12)` 时会返回“未知消息类型”，需要后端补充映射。
- “暂无收包样本”只表示当前文档还没有该类型的完整 payload，不能据此认为该类型未启用。收到后应继续补充其标题、正文、`data` 字段和点击行为。
### 6.2 `type = 1`：付款成功
| 项目 | 当前值 |
| --- | --- |
| 标题示例 | `付款成功通知` |
| 正文示例 | `您的订单 #260722128006 已支付成功，支付金额 ¥0.01` |
| 客户端点击行为 | Android、iOS 均进入收款记录页 |
`data` 字段：
| 字段 | 类型 | 当前样本 | 说明 |
| --- | --- | --- | --- |
| `order_amount` | string | `"0.01"` | 支付金额。使用十进制字符串，避免浮点精度问题。 |
| `order_number` | string | `"260722128006"` | 业务订单号。 |
| `order_type` | int | `14` | 订单类型；当前值表示“摄影师跟拍线下扫码”。 |
| `pay_time` | int | `1784712671` | 支付时间。当前样本为 Unix 秒级时间戳；Android 现有代码同时兼容秒和毫秒。 |
| `remark` | string | `""` | 付款备注；没有备注时当前返回空字符串。 |
示例：
```json
{
"type": 1,
"msg_id": 1856,
"data": {
"order_amount": "0.01",
"order_number": "260722128006",
"order_type": 14,
"pay_time": 1784712671,
"remark": ""
}
}
```
### 6.3 `type = 2`：退款成功
| 项目 | 当前值 |
| --- | --- |
| 标题示例 | `退款成功通知` |
| 正文示例 | `您的订单 #260722128005 已成功退款，退款金额 ¥0.01` |
| 客户端点击行为 | Android、iOS 均进入消息中心 |
`data` 字段：
| 字段 | 类型 | 当前样本 | 说明 |
| --- | --- | --- | --- |
| — | object | `{}` | 当前 Android、iOS 样本均为空对象。 |
示例：
```json
{
"type": 2,
"msg_id": 1862,
"data": {}
}
```
> 当前订单号和退款金额只存在于展示正文中，没有以结构化字段放入 `data`。客户端如果需要可靠地刷新指定订单、展示退款详情或执行金额计算，应由后端在 `data` 中提供字段，不应解析自然语言正文。
### 6.4 `type = 6`：扫码成功
| 项目 | 当前值 |
| --- | --- |
| 标题示例 | `扫码成功通知` |
| 正文示例 | `扫码成功` |
| 客户端点击行为 | Android、iOS 均进入收款详情页 |
`data` 字段：
| 字段 | 类型 | 当前样本 | 说明 |
| --- | --- | --- | --- |
| `order_type` | int | `14` | 订单类型；`14` 在 Android 现有代码中表示“摄影师跟拍线下扫码”。 |
示例：
```json
{
"type": 6,
"msg_id": 1858,
"data": {
"order_type": 14
}
}
```
## 7. 客户端解析约定
1. Android、iOS 的通知点击路由只根据业务字段 `type` 判断，不读取标题、正文、`data`、`route`、`uri`、`action` 或极光内部字段决定页面。
2. `type = 1`：进入收款记录页。
3. `type = 6`：进入收款详情页。
4. 其他任意 `type`、缺少 `type`、类型无法解析或 payload 损坏：进入消息中心。
5. Android 从 `notificationExtras` 或厂商通道包装字段中提取 `type`；iOS 优先读取 payload 顶层 `type`，并兼容常见推送包装层中的 `type`。
6. `data` 仍可按消息类型用于页面内容刷新，但不参与通知点击路由。新增字段应保持向后兼容，客户端应忽略当前版本不认识的额外字段。
7. 金额继续使用字符串；时间戳建议统一为 Unix 秒级整数，并在协议中固定单位。
8. `remark` 等可空业务字段建议固定返回空字符串或明确约定 `null`，不要在多种表示之间切换。
## 8. 新增消息类型记录模板
后续收到新类型时，复制以下内容追加到“消息类型清单”：
````markdown
### 6.x `type = <类型值>`：<消息名称>
| 项目 | 当前值 |
| --- | --- |
| 首次发现日期 | `YYYY-MM-DD` |
| 标题示例 | `<title>` |
| 正文示例 | `<content>` |
| 客户端业务行为 | `<展示、刷新或跳转行为>` |
`data` 字段：
| 字段 | 类型 | 必有 | 说明 |
| --- | --- | --- | --- |
| `<field>` | `<type>` | `<是/否/待确认>` | `<说明>` |
Android `extras` 示例：
```json
{
"data": {},
"msg_id": 0,
"type": 0
}
```
iOS 业务字段示例：
```json
{
"data": {},
"msg_id": 0,
"type": 0
}
```
````
记录新类型时至少保留以下信息：
- Android 和 iOS 各一份原始收包日志。
- `type`、`msg_id` 和完整 `data`。
- 标题、正文以及消息点击后的期望页面。
- 每个字段的 JSON 类型、是否必有、空值表示方式和时间/金额单位。
- 同一业务事件在两端的字段是否一致。
## 9. 待后端确认项
| 项目 | 当前观察 | 需要确认 |
| --- | --- | --- |
| `msg_id` | 与极光消息 ID 不同 | 是否对应消息中心记录 ID，以及是否用于已读/送达状态上报 |
| `data` | `type = 1`、`2`、`6` 的样本中都存在；`type = 2` 为 `{}` | 所有业务推送是否保证存在；无业务字段时是否统一返回 `{}` |
| 退款成功的 `data` | 当前为空对象，订单号和退款金额只在正文中 | 是否补充 `order_number`、`refund_amount`、`refund_time`、`order_type` 等结构化字段 |
| 其他类型的 `data` | 后端已定义消息名称，但尚未提供 payload | 分别确认 `type = 3`～`5`、`7`～`12`、`100`、`999` 的字段结构、必填项及点击行为 |
| `pay_time` | 当前为秒级时间戳 | 后端是否统一保证使用 Unix 秒，且时区语义固定为 UTC 时间戳 |
| `remark` | 无备注时为空字符串 | 是否可能返回 `null` 或省略 |
| `order_type` | 当前为 `14` | 完整枚举和值含义由哪份接口文档维护 |
| 标题与正文 | 当前均存在 | 是否为所有通知消息的必有字段 |
| 推送渠道字段 | 后端已给出渠道取值 `1`、`2`、`999` | payload 或发送接口中对应字段的准确名称 |
| `type = 12` | `MAP_TYPE_NAMES` 中漏配 | 后端补充映射，避免 `getTypeName(12)` 返回“未知消息类型” |
| 新增 `type` | 当前定义维护在 `PushMsg.php` | 后端新增类型前是否可同步类型值、字段结构和客户端行为 |
Reference in New Issue View Git Blame Copy Permalink