mirror of
https://github.com/openimsdk/open-im-server.git
synced 2026-07-06 03:31:08 +08:00
386 lines
9.5 KiB
Markdown
386 lines
9.5 KiB
Markdown
# RedPacket 前端对接文档
|
||
|
||
本文档面向前端 / 网关 / App 对接方，说明红包创建、领取和钱包绑定的真实接入方式，重点覆盖：
|
||
|
||
- 如何把当前登录用户传递给红包服务
|
||
- 如何创建红包（业务单 + 链上创建 + 回写激活）
|
||
- 如何绑定钱包
|
||
- 如何申请领取签名
|
||
- 前端何时发链、何时回写后端
|
||
|
||
## 1. 总体原则
|
||
|
||
红包服务已经切换为 RPC 上下文取当前用户 ID：
|
||
|
||
- 前端不再把 `user_id` 当作可信业务参数传给红包服务
|
||
- 红包服务从请求上下文里的 `opUserID` 获取当前登录用户
|
||
- 上下文通常由网关或鉴权中间件根据 `token` 解析后注入
|
||
|
||
这意味着对接时必须满足一个前提：
|
||
|
||
- 请求进入红包服务前，网关已经完成 token 解析
|
||
- 并且把当前登录用户写入上下文中的 `opUserID`
|
||
|
||
如果没有这一层，红包服务会返回：
|
||
|
||
```json
|
||
{
|
||
"code": 403,
|
||
"message": "op user id missing in context"
|
||
}
|
||
```
|
||
|
||
## 2. 钱包绑定流程
|
||
|
||
### 2.1 流程图
|
||
|
||
```text
|
||
前端 -> 红包服务: POST /api/redpacket/wallet-bind/challenge
|
||
红包服务 -> 前端: challenge_id + message + sign_method
|
||
前端 -> 钱包: 对 message 签名
|
||
前端 -> 红包服务: POST /api/redpacket/wallet-bind/confirm
|
||
红包服务 -> 前端: 绑定成功
|
||
```
|
||
|
||
### 2.2 发起挑战
|
||
|
||
请求：
|
||
|
||
```http
|
||
POST /api/redpacket/wallet-bind/challenge
|
||
token: <user token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"chain_type": "EVM",
|
||
"chain_id": 1,
|
||
"wallet_address": "0x3333333333333333333333333333333333333333",
|
||
"domain": "redpacket.example.com",
|
||
"uri": "https://redpacket.example.com/wallet-bind"
|
||
}
|
||
```
|
||
|
||
返回里最关键的是：
|
||
|
||
- `challenge_id`
|
||
- `message`
|
||
- `sign_method`
|
||
|
||
前端要做的是：
|
||
|
||
- 按 `sign_method` 调钱包签名
|
||
- 当前 EVM 实现使用的是 `personal_sign`
|
||
|
||
### 2.3 确认绑定
|
||
|
||
请求：
|
||
|
||
```http
|
||
POST /api/redpacket/wallet-bind/confirm
|
||
token: <user token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"challenge_id": "1f7d9b0d-7b43-4d84-bb11-65f2ecf7e321",
|
||
"signature": "0x8f..."
|
||
}
|
||
```
|
||
|
||
成功后代表：
|
||
|
||
- 当前登录用户
|
||
- 当前链类型
|
||
- 当前钱包地址
|
||
|
||
已经在后端建立了有效绑定关系。
|
||
|
||
## 3. 创建红包流程
|
||
|
||
### 4.1 流程图
|
||
|
||
```text
|
||
前端 -> 红包服务: POST /api/redpacket/create-order
|
||
红包服务 -> 前端: biz_id (状态 PENDING)
|
||
前端 -> 钱包/链上: createFixedPacket/createRandomPacket/createTransfer
|
||
链上 -> 前端: tx_hash + packet_id(从事件或回执解析)
|
||
前端 -> 红包服务: POST /api/redpacket/created-callback
|
||
红包服务 -> 红包服务: 校验创建参数并激活红包
|
||
红包服务 -> 前端: 回写成功 (状态 ACTIVE)
|
||
前端 -> 红包服务: POST /api/redpacket/detail (可选)
|
||
```
|
||
|
||
### 3.2 创建业务单（发链前必调）
|
||
|
||
请求：
|
||
|
||
```http
|
||
POST /api/redpacket/create-order
|
||
token: <user token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"chain_type": "EVM",
|
||
"chain_id": 1,
|
||
"contract_address": "0xA1f42567559aBA5Ff0aac84cdE1AaF1F9DbB888F",
|
||
"creator_wallet": "0x1111111111111111111111111111111111111111",
|
||
"group_id": "g001",
|
||
"scope_type": "GROUP",
|
||
"receiver_user_id": "",
|
||
"receiver_user_ids": [],
|
||
"packet_type": 1,
|
||
"token": "0x2222222222222222222222222222222222222222",
|
||
"total_amount": "1000000000000000000",
|
||
"total_shares": 10,
|
||
"expiry_at": 0,
|
||
"remark": "happy new year"
|
||
}
|
||
```
|
||
|
||
关键说明：
|
||
|
||
- 不需要传 `user_id`，创建人从上下文 `opUserID` 取
|
||
- `total_amount` 必须是链上最小单位十进制字符串（例如 wei）
|
||
- `packet_type`: `0` 固定红包，`1` 拼手气红包，`2` 转账
|
||
- `scope_type=GROUP` 时必须传 `group_id`
|
||
- `scope_type=DIRECT` 时必须传 `receiver_user_id` 或 `receiver_user_ids`
|
||
|
||
成功响应里最关键的是：
|
||
|
||
- `biz_id`: 业务红包单号（后续回写必须带上）
|
||
|
||
### 3.3 链上创建红包
|
||
|
||
前端拿到 `biz_id` 后，再调用链上创建方法：
|
||
|
||
- 固定红包：`createFixedPacket(...)`
|
||
- 拼手气红包：`createRandomPacket(...)`
|
||
- 转账红包：`createTransfer(...)`
|
||
|
||
链上交易成功后，前端需要得到：
|
||
|
||
- `tx_hash`
|
||
- `packet_id`（优先从 `PacketCreated` 事件解析）
|
||
|
||
### 3.4 创建回写（激活红包）
|
||
|
||
请求：
|
||
|
||
```http
|
||
POST /api/redpacket/created-callback
|
||
token: <user token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"biz_id": "f8a0f87e-d9cb-4d4a-8350-7bd43ab2e9a4",
|
||
"tx_hash": "0xabc123...",
|
||
"packet_id": "10001",
|
||
"group_id": "g001",
|
||
"scope_type": "GROUP",
|
||
"receiver_user_id": "",
|
||
"receiver_user_ids": []
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `biz_id`、`tx_hash` 必填
|
||
- 推荐传 `packet_id`（可减少后端 fallback 分支）
|
||
- 回写成功后红包状态从 `PENDING` 变为 `ACTIVE`
|
||
- 回写后可调 `/api/redpacket/detail` 刷新页面状态
|
||
|
||
### 3.5 创建流程常见坑
|
||
|
||
- 先发链再 `create_order`：会导致回写阶段缺少有效 `biz_id`
|
||
- `create_order` 的 `creator_wallet` 与实际发链钱包不一致：可能被后端校验拦截
|
||
- 未调用 `created_callback`：红包会一直停留在 `PENDING`，领取侧会失败
|
||
|
||
## 4. 领取签名流程
|
||
|
||
### 3.1 流程图
|
||
|
||
```text
|
||
前端 -> 红包服务: POST /api/redpacket/claim-sign
|
||
红包服务 -> 红包服务: 校验当前用户、钱包绑定、领取资格
|
||
红包服务 -> 合约: getSignMessage(packetId, claimer, authNonce, randomSeed, deadline)
|
||
红包服务 -> 前端: auth_nonce + random_seed + deadline + signature
|
||
前端 -> 钱包/链上: claim(packetId, authNonce, randomSeed, deadline, signature)
|
||
前端 -> 红包服务: POST /api/redpacket/claim-result (可选)
|
||
链监听器 -> 红包服务: 最终确认领取结果
|
||
```
|
||
|
||
### 4.2 申请领取签名
|
||
|
||
请求：
|
||
|
||
```http
|
||
POST /api/redpacket/claim-sign
|
||
token: <user token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"packet_id": "10001",
|
||
"claimer": "0x3333333333333333333333333333333333333333",
|
||
"random_seed": "0"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `claimer` 必须是这次真正发链的地址
|
||
- `random_seed` 可省略或传 `0`
|
||
- 不需要传 `user_id`
|
||
|
||
后端会自动完成这些校验：
|
||
|
||
1. 当前登录用户存在
|
||
2. 红包存在且仍可领取
|
||
3. 当前登录用户与 `claimer` 已绑定
|
||
4. 当前用户在该红包下未领取过
|
||
5. 当前钱包在该红包下未领取过
|
||
6. 群红包 / 转账红包的附加业务限制通过
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "ok",
|
||
"data": {
|
||
"auth_nonce": "328840239847239847",
|
||
"deadline": 1777012345,
|
||
"signature": "0x7b1e...a2",
|
||
"random_seed": "8888812345"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 前端拿到响应后要做什么
|
||
|
||
前端必须原样把这些参数传给链上：
|
||
|
||
```text
|
||
claim(packetId, authNonce, randomSeed, deadline, signature)
|
||
```
|
||
|
||
对应关系：
|
||
|
||
- `packetId` -> 前端当前红包 ID
|
||
- `authNonce` -> 响应里的 `auth_nonce`
|
||
- `randomSeed` -> 响应里的 `random_seed`
|
||
- `deadline` -> 响应里的 `deadline`
|
||
- `signature` -> 响应里的 `signature`
|
||
|
||
注意：
|
||
|
||
- 不要自己改 `auth_nonce`
|
||
- 不要重新算摘要
|
||
- 不要对摘要再次做 `signMessage`
|
||
- 后端返回的 `signature` 已经是最终可上链签名
|
||
|
||
## 5. 领取结果回写
|
||
|
||
`claim-result` 是可选的，主要作用是让业务侧尽快看到一条 `PENDING` 领取记录。
|
||
|
||
请求：
|
||
|
||
```http
|
||
POST /api/redpacket/claim-result
|
||
token: <user token>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
```json
|
||
{
|
||
"packet_id": "10001",
|
||
"claimer": "0x3333333333333333333333333333333333333333",
|
||
"tx_hash": "0xdef456..."
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- 不需要传 `user_id`
|
||
- 当前登录用户仍然从上下文中取
|
||
- 如果后端当前能立刻解析 receipt，会把记录补成 `CONFIRMED`
|
||
- 如果不能，会先记成 `PENDING`
|
||
- 最终仍以链监听器为准
|
||
|
||
## 6. 前端推荐调用顺序
|
||
|
||
### 6.1 创建红包
|
||
|
||
1. 用户登录业务系统
|
||
2. 前端请求 `/api/redpacket/create-order`
|
||
3. 拿到 `biz_id` 后，钱包调用链上创建红包方法
|
||
4. 从交易回执/事件拿到 `tx_hash`、`packet_id`
|
||
5. 前端请求 `/api/redpacket/created-callback`
|
||
6. 前端请求 `/api/redpacket/detail` 刷新状态（确认 `ACTIVE`）
|
||
|
||
### 6.2 首次使用钱包领取
|
||
|
||
1. 用户登录业务系统
|
||
2. 前端请求 `/api/redpacket/wallet-bind/challenge`
|
||
3. 钱包对 `message` 签名
|
||
4. 前端请求 `/api/redpacket/wallet-bind/confirm`
|
||
5. 绑定成功后再进入领取流程
|
||
|
||
### 6.3 正常领取
|
||
|
||
1. 前端拿到红包 `packet_id`
|
||
2. 用户连接钱包，得到本次 `claimer` 地址
|
||
3. 前端请求 `/api/redpacket/claim-sign`
|
||
4. 拿到 `auth_nonce + random_seed + deadline + signature`
|
||
5. 前端调用链上 `claim(...)`
|
||
6. 前端可选请求 `/api/redpacket/claim-result`
|
||
7. 页面轮询详情页或等待业务侧状态同步
|
||
|
||
## 7. 常见错误和排查
|
||
|
||
### 7.1 `op user id missing in context`
|
||
|
||
原因：
|
||
|
||
- 网关没有解析 token
|
||
- 网关没有把 `opUserID` 注入上下文
|
||
- 直接绕过网关调用了红包服务
|
||
|
||
### 7.2 `wallet is not bound to user`
|
||
|
||
原因：
|
||
|
||
- 当前钱包还没绑定
|
||
- 当前钱包绑定的是别的业务用户
|
||
- 链类型不一致
|
||
|
||
### 7.3 `already claimed`
|
||
|
||
原因：
|
||
|
||
- 同一个钱包地址已经领过该红包
|
||
|
||
### 7.4 `user already claimed`
|
||
|
||
原因：
|
||
|
||
- 同一个业务用户已经领取过该红包
|
||
- 即使换钱包地址，也会被后端拦截
|
||
|
||
## 8. 后端接口与代码位置
|
||
|
||
- 接口契约文档：
|
||
[backend-api.md](/Users/panda/aiCode/red_packet/open-im-server-origin/cmd/openim-rpc/openim-rpc-redpacket/backend-api.md)
|
||
- 领取签名核心逻辑：
|
||
[redpacket.go](/Users/panda/aiCode/red_packet/open-im-server-origin/cmd/openim-rpc/openim-rpc-redpacket/internal/service/redpacket.go)
|
||
- 用户上下文提取：
|
||
[user.go](/Users/panda/aiCode/red_packet/open-im-server-origin/cmd/openim-rpc/openim-rpc-redpacket/internal/authctx/user.go)
|