mirror of
https://github.com/openimsdk/open-im-server.git
synced 2026-07-06 11:41:10 +08:00
704 lines
15 KiB
Markdown
704 lines
15 KiB
Markdown
# RedPacket 后端接口说明
|
||
|
||
本文档按当前 `internal/api/redpacket.go` 与 `internal/rpc/redpacket/*` 实现整理。红包服务已经从独立 Gin 服务迁移为 OpenIM 标准 RPC 服务：
|
||
|
||
- HTTP 入口在 `internal/api` 网关，路由前缀为 `/redpacket`
|
||
- 网关通过 `pbredpacket.RedPacketClient` 调用 `internal/rpc/redpacket`
|
||
- RPC 服务使用 MongoDB 存储，通过 `pkg/common/storage/controller.RedPacketDatabase` 聚合 DAO
|
||
- 服务注册名为 `redPacket`，配置文件为 `config/openim-rpc-redpacket.yml`
|
||
|
||
## 1. 基础约定
|
||
|
||
### 1.1 Base URL
|
||
|
||
网关地址由 `openim-api` 部署决定，例如：
|
||
|
||
```text
|
||
http://127.0.0.1:10002
|
||
```
|
||
|
||
红包接口统一挂在：
|
||
|
||
```text
|
||
/redpacket
|
||
```
|
||
|
||
### 1.2 鉴权
|
||
|
||
当前 `internal/api/router.go` 的 `Whitelist` 未包含 `/redpacket/*`，因此所有红包 HTTP 接口默认都需要登录 token。
|
||
|
||
请求头：
|
||
|
||
```http
|
||
token: <OpenIM user token>
|
||
operationID: <request id>
|
||
```
|
||
|
||
RPC 层不信任请求体中的 `user_id`。当前登录用户统一从 `mcontext.GetOpUserID(ctx)` 读取。
|
||
|
||
### 1.3 请求字段命名
|
||
|
||
HTTP 请求建议使用 snake_case。网关使用 `a2r.ParseRequestNotCheck` 解析到 protobuf 请求对象。
|
||
|
||
示例：
|
||
|
||
- HTTP: `packet_id`
|
||
- protobuf Go 字段: `PacketID`
|
||
|
||
### 1.4 响应格式
|
||
|
||
网关使用 `apiresp.GinSuccess` / `apiresp.GinError` 包装响应。不同 OpenIM 版本的外层字段可能略有差异，下面示例重点展示 `data` 内容。
|
||
|
||
成功示意：
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
失败示意：
|
||
|
||
```json
|
||
{
|
||
"errCode": 1001,
|
||
"errMsg": "packet_id is required"
|
||
}
|
||
```
|
||
|
||
## 2. 接口总览
|
||
|
||
用户侧接口：
|
||
|
||
- `POST /redpacket/create_order`
|
||
- `POST /redpacket/created_callback`
|
||
- `POST /redpacket/detail`
|
||
- `POST /redpacket/issue_claim_sign`
|
||
- `POST /redpacket/claim_result`
|
||
- `POST /redpacket/wallet_bind/challenge`
|
||
- `POST /redpacket/wallet_bind/confirm`
|
||
- `POST /redpacket/wallet_bind/detail`
|
||
|
||
管理员接口：
|
||
|
||
- `POST /redpacket/admin/set_signer`
|
||
- `POST /redpacket/admin/set_token`
|
||
- `POST /redpacket/admin/set_expiry`
|
||
- `POST /redpacket/admin/set_allow_all_tokens`
|
||
- `POST /redpacket/admin/set_native_token_enabled`
|
||
- `POST /redpacket/admin/parse_tx_events`
|
||
|
||
## 3. 用户侧接口
|
||
|
||
### 3.1 创建红包业务单
|
||
|
||
```text
|
||
POST /redpacket/create_order
|
||
gRPC: CreateOrder(CreateOrderReq) returns (CreateOrderResp)
|
||
```
|
||
|
||
链上创建红包前调用，服务端创建一条 `PENDING` 业务记录并返回 `biz_id`。
|
||
|
||
请求示例：
|
||
|
||
```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"
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
- `chain_type`: 必填，当前支持 `EVM`、`TRON`
|
||
- `chain_id`: 可选；EVM client 可用时为空会使用配置的 chainID
|
||
- `contract_address`: 可选；EVM/TRON client 可用时为空会使用配置地址
|
||
- `creator_wallet`: 必填，发红包钱包地址
|
||
- `scope_type`: `GROUP`、`DIRECT`、`PUBLIC`；空值默认 `PUBLIC`
|
||
- `group_id`: `scope_type=GROUP` 时必填
|
||
- `receiver_user_id` / `receiver_user_ids`: `scope_type=DIRECT` 时至少一个非空
|
||
- `packet_type`: `0` 固定红包，`1` 拼手气红包，`2` 转账
|
||
- `total_amount`: 链上最小单位十进制字符串
|
||
- `total_shares`: 总份数
|
||
- `expiry_at`: Unix 秒；`0` 表示使用合约默认过期
|
||
|
||
成功响应 `data`：
|
||
|
||
```json
|
||
{
|
||
"biz_id": "f8a0f87e-d9cb-4d4a-8350-7bd43ab2e9a4"
|
||
}
|
||
```
|
||
|
||
服务端写入：
|
||
|
||
- collection: `red_packet`
|
||
- status: `PENDING`
|
||
- creatorUserID: 来自登录上下文，不来自请求体
|
||
|
||
### 3.2 创建交易回写
|
||
|
||
```text
|
||
POST /redpacket/created_callback
|
||
gRPC: CreatedCallback(CreatedCallbackReq) returns (CreatedCallbackResp)
|
||
```
|
||
|
||
链上创建交易确认后调用，用于把 `biz_id` 与链上 `packet_id` / `tx_hash` 绑定。
|
||
|
||
请求示例：
|
||
|
||
```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": []
|
||
}
|
||
```
|
||
|
||
成功响应 `data`：
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
服务端逻辑：
|
||
|
||
- `biz_id` 与 `tx_hash` 必填
|
||
- 如果链客户端可用，会解析交易 receipt 中的 `PacketCreated`
|
||
- 解析成功后校验 creator、packetType、token、amount、shares、expiry 是否与业务单一致
|
||
- 如果链客户端不可用或解析失败，但请求提供了 `packet_id`，会使用 fallback
|
||
- 成功后更新 `red_packet.status=ACTIVE`
|
||
|
||
### 3.3 查询红包详情
|
||
|
||
```text
|
||
POST /redpacket/detail
|
||
gRPC: GetDetail(GetDetailReq) returns (GetDetailResp)
|
||
```
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"packet_id": "10001"
|
||
}
|
||
```
|
||
|
||
成功响应 `data`：
|
||
|
||
```json
|
||
{
|
||
"record": {
|
||
"biz_id": "f8a0f87e-d9cb-4d4a-8350-7bd43ab2e9a4",
|
||
"chain_type": "EVM",
|
||
"packet_id": "10001",
|
||
"chain_id": 1,
|
||
"contract_address": "0xA1f42567559aBA5Ff0aac84cdE1AaF1F9DbB888F",
|
||
"creator_user_id": "u1001",
|
||
"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,
|
||
"claimed_amount": "123456789",
|
||
"claimed_shares": 1,
|
||
"expiry_at": 0,
|
||
"tx_hash": "0xabc123...",
|
||
"status": "ACTIVE",
|
||
"created_at": 1777000000,
|
||
"updated_at": 1777000060
|
||
},
|
||
"claims": [
|
||
{
|
||
"packet_id": "10001",
|
||
"user_id": "u2002",
|
||
"claimer_wallet": "0x3333333333333333333333333333333333333333",
|
||
"auth_nonce": "328840239847239847",
|
||
"claim_tx_hash": "0xdef456...",
|
||
"claimed_amount": "123456789",
|
||
"block_number": 1234567,
|
||
"status": "CONFIRMED",
|
||
"created_at": 1777000100,
|
||
"updated_at": 1777000100
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `created_at` / `updated_at` 为 Unix 秒
|
||
- `claims` 按 Mongo 查询返回，DAO 层按 `created_at desc` 排序
|
||
|
||
### 3.4 申请领取签名
|
||
|
||
```text
|
||
POST /redpacket/issue_claim_sign
|
||
gRPC: IssueClaimSign(IssueClaimSignReq) returns (IssueClaimSignResp)
|
||
```
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"packet_id": "10001",
|
||
"claimer": "0x3333333333333333333333333333333333333333",
|
||
"random_seed": "0"
|
||
}
|
||
```
|
||
|
||
成功响应 `data`：
|
||
|
||
```json
|
||
{
|
||
"auth_nonce": "328840239847239847",
|
||
"deadline": 1777012345,
|
||
"signature": "0x7b1e...a2",
|
||
"random_seed": "8888812345"
|
||
}
|
||
```
|
||
|
||
校验逻辑：
|
||
|
||
1. 当前用户必须存在：`mcontext.GetOpUserID(ctx) != ""`
|
||
2. `packet_id` 与 `claimer` 必填
|
||
3. 红包必须存在且 `status=ACTIVE`
|
||
4. 未过期、未退款
|
||
5. 当前用户与 `claimer` 钱包必须有 `ACTIVE` 绑定
|
||
6. 同一用户 / 同一钱包不能重复领取
|
||
7. 固定红包和拼手气红包要求 `group_id` 存在
|
||
8. 转账红包要求当前用户为 `receiver_user_id`
|
||
|
||
签名逻辑：
|
||
|
||
- EVM client 可用时调用 `getSignMessage(packetId, claimer, authNonce, randomSeed, deadline)` 获取 digest
|
||
- 使用 `chain.signerPrivateKey` 裸签 digest
|
||
- `v` 从 0/1 调整为 27/28
|
||
- 如果 signer 私钥未配置，当前代码会返回 placeholder 签名，仅适合本地调试
|
||
|
||
### 3.5 领取结果回写
|
||
|
||
```text
|
||
POST /redpacket/claim_result
|
||
gRPC: ClaimResult(ClaimResultReq) returns (ClaimResultResp)
|
||
```
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"packet_id": "10001",
|
||
"claimer": "0x3333333333333333333333333333333333333333",
|
||
"tx_hash": "0xdef456..."
|
||
}
|
||
```
|
||
|
||
成功响应 `data`：
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
服务端逻辑：
|
||
|
||
- 先保存一条 `PENDING` claim
|
||
- 若能立即解析 `PacketClaimed` 事件，则更新为 `CONFIRMED`
|
||
- 成功解析后会累计 `claimed_amount` / `claimed_shares`
|
||
- 红包领完时状态变为 `COMPLETED`
|
||
- 如果 receipt 暂不可用，保持 `PENDING`，等待 indexer 补偿
|
||
|
||
### 3.6 发起钱包绑定挑战
|
||
|
||
```text
|
||
POST /redpacket/wallet_bind/challenge
|
||
gRPC: IssueWalletBindChallenge(IssueWalletBindChallengeReq)
|
||
```
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"chain_type": "EVM",
|
||
"chain_id": 1,
|
||
"wallet_address": "0x3333333333333333333333333333333333333333",
|
||
"domain": "redpacket.example.com",
|
||
"uri": "https://redpacket.example.com/wallet-bind"
|
||
}
|
||
```
|
||
|
||
成功响应 `data`：
|
||
|
||
```json
|
||
{
|
||
"challenge_id": "1f7d9b0d-7b43-4d84-bb11-65f2ecf7e321",
|
||
"user_id": "u2002",
|
||
"chain_type": "EVM",
|
||
"chain_id": 1,
|
||
"wallet": "0x3333333333333333333333333333333333333333",
|
||
"protocol": "siwe-eip4361",
|
||
"sign_method": "personal_sign",
|
||
"nonce": "7b7d8d48-9db6-4e95-9daa-40e9517a2a85",
|
||
"message": "redpacket.example.com wants you to sign in with your Ethereum account:\n...",
|
||
"issued_at": "2026-04-30T03:00:00Z",
|
||
"expires_at": "2026-04-30T03:10:00Z"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- EVM 使用 `siwe-eip4361` + `personal_sign`
|
||
- TRON 使用 `tron-signmessagev2` + `signMessageV2`
|
||
- challenge 有效期为 10 分钟
|
||
|
||
### 3.7 确认钱包绑定
|
||
|
||
```text
|
||
POST /redpacket/wallet_bind/confirm
|
||
gRPC: ConfirmWalletBind(ConfirmWalletBindReq)
|
||
```
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"challenge_id": "1f7d9b0d-7b43-4d84-bb11-65f2ecf7e321",
|
||
"signature": "0x8f..."
|
||
}
|
||
```
|
||
|
||
成功响应 `data`：
|
||
|
||
```json
|
||
{
|
||
"user_id": "u2002",
|
||
"chain_type": "EVM",
|
||
"chain_id": 1,
|
||
"wallet_address": "0x3333333333333333333333333333333333333333",
|
||
"status": "ACTIVE",
|
||
"verified_at": "2026-04-30T03:01:00Z"
|
||
}
|
||
```
|
||
|
||
当前限制：
|
||
|
||
- EVM 验签已实现
|
||
- TRON 验签当前返回 `TRON wallet binding verification is not implemented yet`
|
||
|
||
### 3.8 查询钱包绑定
|
||
|
||
```text
|
||
POST /redpacket/wallet_bind/detail
|
||
gRPC: GetWalletBinding(GetWalletBindingReq)
|
||
```
|
||
|
||
请求示例：
|
||
|
||
```json
|
||
{
|
||
"chain_type": "EVM",
|
||
"wallet_address": "0x3333333333333333333333333333333333333333"
|
||
}
|
||
```
|
||
|
||
成功响应 `data`：
|
||
|
||
```json
|
||
{
|
||
"user_id": "u2002",
|
||
"chain_type": "EVM",
|
||
"chain_id": 1,
|
||
"wallet_address": "0x3333333333333333333333333333333333333333",
|
||
"status": "ACTIVE",
|
||
"challenge_id": "1f7d9b0d-7b43-4d84-bb11-65f2ecf7e321",
|
||
"verified_at": "2026-04-30T03:01:00Z"
|
||
}
|
||
```
|
||
|
||
## 4. 管理员接口
|
||
|
||
### 4.1 设置 signer
|
||
|
||
```text
|
||
POST /redpacket/admin/set_signer
|
||
gRPC: SetSigner(SetSignerReq)
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"signer_address": "0x4444444444444444444444444444444444444444"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"message": "signer address updated successfully"
|
||
}
|
||
```
|
||
|
||
### 4.2 设置 token 白名单
|
||
|
||
```text
|
||
POST /redpacket/admin/set_token
|
||
gRPC: SetToken(SetTokenReq)
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"token_address": "0x2222222222222222222222222222222222222222",
|
||
"allowed": true,
|
||
"min_amount": "1000000"
|
||
}
|
||
```
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"message": "token configuration updated"
|
||
}
|
||
```
|
||
|
||
### 4.3 设置默认过期时间
|
||
|
||
```text
|
||
POST /redpacket/admin/set_expiry
|
||
gRPC: SetExpiry(SetExpiryReq)
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"expiry_seconds": 86400
|
||
}
|
||
```
|
||
|
||
### 4.4 设置是否允许所有 token
|
||
|
||
```text
|
||
POST /redpacket/admin/set_allow_all_tokens
|
||
gRPC: SetAllowAllTokens(SetAllowAllTokensReq)
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"allow_all": false
|
||
}
|
||
```
|
||
|
||
### 4.5 设置原生币开关
|
||
|
||
```text
|
||
POST /redpacket/admin/set_native_token_enabled
|
||
gRPC: SetNativeTokenEnabled(SetNativeTokenEnabledReq)
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"enabled": true
|
||
}
|
||
```
|
||
|
||
### 4.6 解析交易事件
|
||
|
||
```text
|
||
POST /redpacket/admin/parse_tx_events
|
||
gRPC: ParseTxEvents(ParseTxEventsReq)
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"tx_hash": "0xabc123...",
|
||
"chain": "eth"
|
||
}
|
||
```
|
||
|
||
EVM 响应：
|
||
|
||
```json
|
||
{
|
||
"chain": "eth",
|
||
"tx_hash": "0xabc123...",
|
||
"events": [
|
||
{
|
||
"name": "PacketCreated",
|
||
"data": {
|
||
"packetId": "10001",
|
||
"creator": "0x1111111111111111111111111111111111111111"
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
TRON 当前响应：
|
||
|
||
```json
|
||
{
|
||
"chain": "tron",
|
||
"tx_hash": "7d9e...txid",
|
||
"note": "TRON event parsing not fully implemented in this version"
|
||
}
|
||
```
|
||
|
||
### 4.7 管理接口当前行为边界
|
||
|
||
- EVM admin 接口当前为 mock，仅记录日志并返回 message，不发链上交易。
|
||
- TRON admin 接口会调用 `SendAdminTransaction(...)` 尝试发链上交易。
|
||
- 管理接口目前没有单独管理员校验，默认只依赖 API 网关 token。生产建议补管理员鉴权与审计。
|
||
|
||
## 5. 业务状态
|
||
|
||
红包状态：
|
||
|
||
- `PENDING`: 已创建业务单，尚未确认链上创建
|
||
- `ACTIVE`: 链上创建已确认，可领取
|
||
- `COMPLETED`: 已领取完成
|
||
- `REFUNDED`: 已退款
|
||
|
||
领取状态：
|
||
|
||
- `PENDING`: 已提交领取 txHash，receipt 尚未解析或未确认
|
||
- `CONFIRMED`: 已解析 `PacketClaimed`
|
||
- `FAILED`: 预留失败状态，当前逻辑仅用于重复领取判断时放行失败记录
|
||
|
||
钱包绑定 challenge 状态：
|
||
|
||
- `PENDING`
|
||
- `VERIFIED`
|
||
- `FAILED`
|
||
- `EXPIRED`
|
||
|
||
钱包绑定状态：
|
||
|
||
- `ACTIVE`
|
||
|
||
## 6. 常见错误
|
||
|
||
- `op user id is empty`: 缺少 token 或 token 未正确注入上下文
|
||
- `unsupported chain_type`: `chain_type` 不是 `EVM` 或 `TRON`
|
||
- `packet_id is required`: 缺少红包链上 ID
|
||
- `wallet is not bound to user`: 当前用户未绑定该领取钱包
|
||
- `user already claimed`: 当前用户已领取
|
||
- `already claimed`: 当前钱包已领取
|
||
- `packet is not active`: 红包尚未激活或已经完成/退款
|
||
- `packet is expired`: 红包已过期
|
||
- `TRON wallet binding verification is not implemented yet`: 当前未实现 TRON 绑定验签
|
||
|
||
## 7. 前端推荐调用顺序
|
||
|
||
创建红包：
|
||
|
||
1. `POST /redpacket/create_order`
|
||
2. 钱包发起 `createFixedPacket/createRandomPacket/createTransfer`
|
||
3. 从 `PacketCreated` 解析 `packetId`
|
||
4. `POST /redpacket/created_callback`
|
||
5. `POST /redpacket/detail` 刷新状态
|
||
|
||
绑定钱包：
|
||
|
||
1. `POST /redpacket/wallet_bind/challenge`
|
||
2. 钱包按 `sign_method` 签名 `message`
|
||
3. `POST /redpacket/wallet_bind/confirm`
|
||
4. `POST /redpacket/wallet_bind/detail`
|
||
|
||
领取红包：
|
||
|
||
1. `POST /redpacket/detail`
|
||
2. `POST /redpacket/issue_claim_sign`
|
||
3. 钱包调用链上 `claim(packetId, authNonce, randomSeed, deadline, signature)`
|
||
4. 可选：`POST /redpacket/claim_result`
|
||
5. `POST /redpacket/detail` 刷新状态
|
||
|
||
## 8. 存储与索引
|
||
|
||
Mongo collections：
|
||
|
||
- `red_packet`
|
||
- `red_packet_claim`
|
||
- `red_packet_claim_auth`
|
||
- `red_packet_refund`
|
||
- `wallet_binding_challenge`
|
||
- `wallet_binding`
|
||
|
||
主要索引：
|
||
|
||
- `red_packet.biz_id` 唯一
|
||
- `red_packet.packet_id`
|
||
- `red_packet.group_id`
|
||
- `red_packet_claim.claim_tx_hash` 唯一
|
||
- `red_packet_claim.packet_id + user_id`
|
||
- `red_packet_claim.packet_id + claimer_wallet`
|
||
- `red_packet_claim_auth.auth_nonce` 唯一
|
||
- `wallet_binding_challenge.challenge_id` 唯一
|
||
- `wallet_binding.user_id + chain_type + wallet_address` 唯一
|
||
|
||
## 9. 配置文件
|
||
|
||
`config/openim-rpc-redpacket.yml`：
|
||
|
||
```yaml
|
||
rpc:
|
||
registerIP: ""
|
||
listenIP: 0.0.0.0
|
||
autoSetPorts: false
|
||
ports: [10560]
|
||
|
||
prometheus:
|
||
enable: false
|
||
ports: [12560]
|
||
|
||
chain:
|
||
rpcURL: ""
|
||
contractAddress: ""
|
||
chainID: 0
|
||
signerPrivateKey: ""
|
||
configAdminPrivateKey: ""
|
||
|
||
tron:
|
||
fullNodeURL: ""
|
||
contractBase58: ""
|
||
ownerBase58: ""
|
||
privateKeyHex: ""
|
||
feeLimit: 100000000
|
||
|
||
indexer:
|
||
pollInterval: 5
|
||
```
|
||
|
||
`chain.rpcURL` 为空时 EVM client 初始化会失败并降级；`tron.fullNodeURL` 为空时 TRON client 不启用。服务会继续启动。
|