746 lines
19 KiB
Markdown
746 lines
19 KiB
Markdown
# 房内红包需求接口拆分
|
||
|
||
## 1. 结论
|
||
|
||
房内红包拆成两类通道：
|
||
|
||
- HTTP 接口：承载有状态业务，包括配置、发送、领取、详情、记录、退款后台操作；房间在线态使用语音房通用接口。
|
||
- IM 消息：承载实时 UI 触达，包括房内弹窗、延时红包同语区飘窗、倒计时结束强弹、侧边栏数量刷新。
|
||
|
||
本需求以产品文档为准：
|
||
|
||
- 红包类型：即时红包、延时红包。
|
||
- 发送成功立刻扣除金币。
|
||
- 发送者本人可以领取自己发出的红包。
|
||
- 红包有效领取时间为 24 小时，过期未领取金额退回发送者。
|
||
- 即时红包不触发同语区广播飘窗。
|
||
- 延时红包发送成功后触发同语区广播飘窗。
|
||
- 当前房间内无论即时还是延时，发送成功后都需要立刻弹出抢红包窗口。
|
||
|
||
现有历史文档中的 `2 小时退款` 不适用于本次新需求，应改为 24 小时。
|
||
|
||
## 2. 统一响应约定
|
||
|
||
现有 Go 网关成功响应会同时返回 `body` 和 `data`，客户端读取任意一个都可以。
|
||
|
||
成功响应：
|
||
|
||
```json
|
||
{
|
||
"status": true,
|
||
"errorCode": 0,
|
||
"errorMsg": "success",
|
||
"body": {},
|
||
"code": "success",
|
||
"message": "success",
|
||
"data": {},
|
||
"time": 1780000000000
|
||
}
|
||
```
|
||
|
||
错误响应：
|
||
|
||
```json
|
||
{
|
||
"status": false,
|
||
"errorCode": 409,
|
||
"errorCodeName": "voice_room_red_packet_expired",
|
||
"errorMsg": "red packet expired",
|
||
"body": null,
|
||
"code": "voice_room_red_packet_expired",
|
||
"message": "red packet expired",
|
||
"data": null,
|
||
"time": 1780000000000
|
||
}
|
||
```
|
||
|
||
接口文档下文只定义 `body/data` 中的业务字段。
|
||
|
||
## 3. 哪些需要使用 IM
|
||
|
||
| 场景 | IM key | 发送范围 | 使用 IM 的原因 |
|
||
| --- | --- | --- | --- |
|
||
| 红包创建后当前房间立刻弹窗 | `ROOM_RED_PACKET`，`event=CREATED`，`scope=ROOM` | 当前房间 IM 群 | 房内所有在线用户需要实时收到弹窗，不能依赖轮询 |
|
||
| 延时红包同语区飘窗引流 | `ROOM_RED_PACKET`，`event=CREATED`，`scope=REGION` | 发送者所在同语区 IM 群 | 首页和其他房间用户没有主动请求，现有区域飘屏能力通过语区 IM 群触达 |
|
||
| 延时红包倒计时结束强弹 | `ROOM_RED_PACKET`，`event=OPEN_DUE`，`scope=ROOM` | 当前房间 IM 群 | 用户可能提前关闭弹窗，到点必须再次强制弹出 |
|
||
| 红包抢完、过期、退款后刷新侧边栏 | `ROOM_RED_PACKET`，`event=STATUS_CHANGED`，`scope=ROOM` | 当前房间 IM 群 | 房内侧边栏红包数量需要实时减少 |
|
||
|
||
不使用 IM 的动作：
|
||
|
||
| 动作 | 原因 |
|
||
| --- | --- |
|
||
| 发送红包 | 需要鉴权、扣款、档位校验、日上限、幂等落库 |
|
||
| 抢红包 | 需要鉴权、并发防超卖、领取幂等、钱包入账 |
|
||
| 查询配置 | 普通读接口，礼物面板打开时请求即可 |
|
||
| 查询详情和记录 | 需要分页、权限和稳定数据 |
|
||
| 过期退款 | 服务端定时任务和后台补偿，不应由客户端 IM 触发 |
|
||
|
||
## 4. IM 消息格式
|
||
|
||
现有腾讯 IM 自定义消息通过 `TIMCustomElem.MsgContent.Data` 发送 JSON 字符串。业务层统一使用外层：
|
||
|
||
```json
|
||
{
|
||
"type": "ROOM_RED_PACKET",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
腾讯 IM 实际 payload：
|
||
|
||
```json
|
||
{
|
||
"MsgType": "TIMCustomElem",
|
||
"MsgContent": {
|
||
"Data": "{\"type\":\"ROOM_RED_PACKET\",\"data\":{...}}",
|
||
"Desc": "customBody",
|
||
"Sound": "dingdong.aiff"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.1 CREATED
|
||
|
||
当前房间弹窗和同语区飘窗都使用 `CREATED`，通过 `scope` 区分。
|
||
|
||
```json
|
||
{
|
||
"type": "ROOM_RED_PACKET",
|
||
"data": {
|
||
"event": "CREATED",
|
||
"scope": "ROOM",
|
||
"packetNo": "VRRP2026052712340001",
|
||
"packetId": "VRRP2026052712340001",
|
||
"roomId": "9001",
|
||
"regionCode": "AR",
|
||
"packetMode": "DELAYED",
|
||
"senderUserId": "10001",
|
||
"actualAccount": "10001",
|
||
"userNickname": "Tom",
|
||
"userAvatar": "https://example.com/avatar.png",
|
||
"totalAmount": 15000,
|
||
"totalCount": 5,
|
||
"remainCount": 5,
|
||
"status": "ACTIVE",
|
||
"delaySeconds": 300,
|
||
"claimStartTime": 1780000000000,
|
||
"expireTime": 1780086400000,
|
||
"serverTime": 1779999700000
|
||
}
|
||
}
|
||
```
|
||
|
||
字段说明：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `event` | string | 固定为 `CREATED` |
|
||
| `scope` | string | `ROOM` 表示房间弹窗，`REGION` 表示同语区飘窗 |
|
||
| `packetNo` | string | 红包唯一编号，接口参数使用该字段 |
|
||
| `packetId` | string | 兼容旧 Flutter 飘屏字段，值同 `packetNo` |
|
||
| `roomId` | string | 红包所属房间，点击飘窗进入该房间 |
|
||
| `regionCode` | string | 语区编码 |
|
||
| `packetMode` | string | `IMMEDIATE` 或 `DELAYED` |
|
||
| `senderUserId` | string | 发送者用户 ID |
|
||
| `actualAccount` | string | 发送者账号 |
|
||
| `userNickname` | string | 发送者昵称 |
|
||
| `userAvatar` | string | 发送者头像 |
|
||
| `totalAmount` | int64 | 红包总金币 |
|
||
| `totalCount` | int | 红包份数 |
|
||
| `remainCount` | int | 剩余可领份数 |
|
||
| `status` | string | 红包状态 |
|
||
| `delaySeconds` | int | 后台配置的延时秒数 |
|
||
| `claimStartTime` | int64 | 可领取开始时间，毫秒时间戳 |
|
||
| `expireTime` | int64 | 过期时间，毫秒时间戳，创建后 24 小时 |
|
||
| `serverTime` | int64 | 服务端当前时间，毫秒时间戳 |
|
||
|
||
发送规则：
|
||
|
||
- 即时红包：只发送 `scope=ROOM` 到当前房间 IM 群。
|
||
- 延时红包：发送 `scope=ROOM` 到当前房间 IM 群；同时发送 `scope=REGION` 到同语区 IM 群。
|
||
|
||
### 4.2 OPEN_DUE
|
||
|
||
延时红包倒计时结束后，服务端向当前房间发送强弹消息。
|
||
|
||
```json
|
||
{
|
||
"type": "ROOM_RED_PACKET",
|
||
"data": {
|
||
"event": "OPEN_DUE",
|
||
"scope": "ROOM",
|
||
"packetNo": "VRRP2026052712340001",
|
||
"packetId": "VRRP2026052712340001",
|
||
"roomId": "9001",
|
||
"packetMode": "DELAYED",
|
||
"claimStartTime": 1780000000000,
|
||
"expireTime": 1780086400000,
|
||
"serverTime": 1780000000000
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 STATUS_CHANGED
|
||
|
||
红包被抢完、过期、退款完成后，服务端向当前房间发送状态刷新消息。
|
||
|
||
```json
|
||
{
|
||
"type": "ROOM_RED_PACKET",
|
||
"data": {
|
||
"event": "STATUS_CHANGED",
|
||
"scope": "ROOM",
|
||
"packetNo": "VRRP2026052712340001",
|
||
"packetId": "VRRP2026052712340001",
|
||
"roomId": "9001",
|
||
"status": "EXPIRED",
|
||
"remainCount": 0,
|
||
"refundedAmount": 3000,
|
||
"serverTime": 1780086400000
|
||
}
|
||
}
|
||
```
|
||
|
||
客户端收到后刷新侧边栏未领取数量；如果当前展示的是该红包弹窗或详情页，同步刷新状态。
|
||
|
||
## 5. App HTTP 接口
|
||
|
||
### 5.1 获取当前用户语区 IM 群
|
||
|
||
```http
|
||
GET /app/region-im-group/current
|
||
```
|
||
|
||
兼容旧路径：
|
||
|
||
```http
|
||
GET /app/voice-room/red-packet/im-group
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"configured": true,
|
||
"sysOrigin": "LIKEI",
|
||
"regionCode": "AR",
|
||
"groupId": "@TGS#xxxx",
|
||
"groupName": "region-im-group-LIKEI-AR",
|
||
"status": "ACTIVE"
|
||
}
|
||
```
|
||
|
||
客户端处理：
|
||
|
||
- `configured=true` 且 `groupId` 非空时加入腾讯 IM 群。
|
||
- `joinGroup` 返回成功或已在群内都按成功处理。
|
||
- 区域变化时退出旧区域群并加入新区域群。
|
||
|
||
### 5.2 通用房间心跳
|
||
|
||
```http
|
||
POST /api/v1/rooms/heartbeat
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"room_id": "9001",
|
||
"command_id": "cmd_heartbeat_9001_10001_1780000000000"
|
||
}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"result": {
|
||
"ok": true
|
||
},
|
||
"user": {
|
||
"user_id": "10001",
|
||
"room_id": "9001",
|
||
"last_seen_at_ms": 1780000000000
|
||
},
|
||
"room": {}
|
||
}
|
||
```
|
||
|
||
用途：
|
||
|
||
- 这是语音房通用 presence 能力，不属于红包专用接口。
|
||
- 只刷新已经存在的业务 presence，不能替代进房 `JoinRoom`。
|
||
- 红包发送、红包领取、侧边栏有效红包查询都依赖该 presence 判断用户是否仍在当前房间。
|
||
- 用户不在房间、已离房、被踢或房间关闭时，心跳应失败，客户端应停止心跳并清理本地房间态。
|
||
|
||
客户端心跳间隔由房间模块统一配置，必须小于 room-service 的 presence stale 窗口。
|
||
|
||
### 5.3 通用离开房间
|
||
|
||
```http
|
||
POST /api/v1/rooms/leave
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"room_id": "9001",
|
||
"command_id": "cmd_leave_9001_10001_1780000000000"
|
||
}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"result": {
|
||
"ok": true
|
||
},
|
||
"room": {}
|
||
}
|
||
```
|
||
|
||
用途：
|
||
|
||
- 这是语音房通用离房接口，不属于红包专用接口。
|
||
- 主动关闭房间页、切换账号、被客户端确认退出时调用。
|
||
- 离房后 room-service 移除业务 presence，红包领取接口再校验该用户时应返回不在房间。
|
||
- 如果用户在麦上，离房流程同时释放麦位。
|
||
- LeaveRoom 后客户端必须停止房间心跳、退出 RTC 房、退出或忽略 IM 房间群消息。
|
||
|
||
### 5.4 红包配置
|
||
|
||
```http
|
||
GET /app/voice-room/red-packet/config
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"enabled": true,
|
||
"dailySendLimit": 10,
|
||
"todaySendCount": 1,
|
||
"delaySeconds": 300,
|
||
"expireSeconds": 86400,
|
||
"amountOptions": [15000, 30000, 70000, 100000],
|
||
"countOptions": [5, 10, 20, 50],
|
||
"ruleUrl": "https://example.com/red-packet-rule"
|
||
}
|
||
```
|
||
|
||
参数定义：
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| --- | --- | --- |
|
||
| `enabled` | bool | 红包功能开关 |
|
||
| `dailySendLimit` | int | 每日发送上限 |
|
||
| `todaySendCount` | int | 当前用户当天已发送数量 |
|
||
| `delaySeconds` | int | 延时红包等待秒数，后台全局唯一配置 |
|
||
| `expireSeconds` | int | 固定 86400 秒 |
|
||
| `amountOptions` | int64[] | 后台配置金额档位 |
|
||
| `countOptions` | int[] | 后台配置红包份数档位 |
|
||
| `ruleUrl` | string | 红包规则 H5 地址 |
|
||
|
||
### 5.5 发送红包
|
||
|
||
```http
|
||
POST /app/voice-room/red-packet/send
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"requestId": "client-unique-id",
|
||
"roomId": "9001",
|
||
"packetMode": "DELAYED",
|
||
"totalAmount": 15000,
|
||
"totalCount": 5
|
||
}
|
||
```
|
||
|
||
参数定义：
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
| --- | --- | --- | --- |
|
||
| `requestId` | string | 是 | 客户端幂等 ID，重复请求返回同一红包 |
|
||
| `roomId` | string | 是 | 当前房间 ID |
|
||
| `packetMode` | string | 是 | `IMMEDIATE` 或 `DELAYED` |
|
||
| `totalAmount` | int64 | 是 | 总金币，必须命中后台金额档位 |
|
||
| `totalCount` | int | 是 | 红包份数，必须命中后台份数档位 |
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"packetNo": "VRRP2026052712340001",
|
||
"roomId": "9001",
|
||
"packetMode": "DELAYED",
|
||
"totalAmount": 15000,
|
||
"totalCount": 5,
|
||
"remainAmount": 15000,
|
||
"remainCount": 5,
|
||
"claimStartTime": "2026-05-27T21:05:00+08:00",
|
||
"claimStartTimeMs": 1780000000000,
|
||
"expireTime": "2026-05-28T21:00:00+08:00",
|
||
"expireTimeMs": 1780086400000,
|
||
"status": "ACTIVE",
|
||
"balanceAfter": 100000
|
||
}
|
||
```
|
||
|
||
服务端逻辑：
|
||
|
||
1. 校验登录态、功能开关，并通过 room-service 通用 presence 校验发送者仍在 `roomId` 房间内。
|
||
2. 校验金额和份数档位。
|
||
3. 校验每日发送上限。
|
||
4. 校验余额并立刻扣金币。
|
||
5. 预拆随机份额，写红包主表和份额表。
|
||
6. 即时红包 `claimStartTime = createdAt`。
|
||
7. 延时红包 `claimStartTime = createdAt + delaySeconds`。
|
||
8. 所有红包 `expireTime = createdAt + 24h`。
|
||
9. 发送对应 IM 消息。
|
||
|
||
### 5.6 房间有效红包列表
|
||
|
||
```http
|
||
GET /app/voice-room/red-packet/active?roomId=9001
|
||
```
|
||
|
||
用途：
|
||
|
||
- 进入房间时初始化侧边栏红包数量。
|
||
- 用户关闭弹窗后，通过侧边栏图标重新唤起红包窗口。
|
||
- 收到 IM 状态变化后刷新列表。
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"roomId": "9001",
|
||
"unclaimedCount": 3,
|
||
"items": [
|
||
{
|
||
"packetNo": "VRRP2026052712340001",
|
||
"packetMode": "DELAYED",
|
||
"senderUserId": "10001",
|
||
"senderNickname": "Tom",
|
||
"senderAvatar": "https://example.com/avatar.png",
|
||
"totalAmount": 15000,
|
||
"totalCount": 5,
|
||
"remainCount": 5,
|
||
"claimStartTime": "2026-05-27T21:05:00+08:00",
|
||
"claimStartTimeMs": 1780000000000,
|
||
"expireTime": "2026-05-28T21:00:00+08:00",
|
||
"expireTimeMs": 1780086400000,
|
||
"status": "ACTIVE",
|
||
"currentUserClaimed": false,
|
||
"currentUserAmount": 0
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
`unclaimedCount` 统计当前用户未领取且未过期、未抢完的红包数量。
|
||
|
||
### 5.7 抢红包
|
||
|
||
```http
|
||
POST /app/voice-room/red-packet/claim
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"packetNo": "VRRP2026052712340001"
|
||
}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"packetNo": "VRRP2026052712340001",
|
||
"claimed": true,
|
||
"amount": 3000,
|
||
"remainCount": 4,
|
||
"totalCount": 5,
|
||
"claimTime": "2026-05-27T21:05:10+08:00",
|
||
"claimTimeMs": 1780000010000,
|
||
"status": "ACTIVE"
|
||
}
|
||
```
|
||
|
||
领取失败但业务可展示的情况通过错误码返回：
|
||
|
||
- `voice_room_red_packet_room_presence_required`：用户不在红包所属房间内，需要先进入房间。
|
||
- `voice_room_red_packet_not_started`：延时红包未到可领取时间。
|
||
- `voice_room_red_packet_expired`：红包已过期。
|
||
- `voice_room_red_packet_finished`：红包已抢完。
|
||
- `voice_room_region_not_match`：非同语区不可领取。
|
||
|
||
领取前校验：
|
||
|
||
- 抢红包接口不创建、不刷新房间 presence，只读取 room-service 当前 presence。
|
||
- 用户必须仍在 `packetNo` 对应的 `roomId` 房间内，否则返回 `voice_room_red_packet_room_presence_required`。
|
||
- 进入房间和离开房间仍由通用房间接口负责，不在红包接口里重复实现。
|
||
|
||
幂等要求：
|
||
|
||
- 同一用户重复领取同一红包，返回第一次领取结果。
|
||
- 钱包入账处理中，返回 `claim_processing`，客户端可重试或查详情。
|
||
|
||
### 5.8 红包详情
|
||
|
||
```http
|
||
GET /app/voice-room/red-packet/detail?packetNo=VRRP2026052712340001
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"packetNo": "VRRP2026052712340001",
|
||
"roomId": "9001",
|
||
"packetMode": "DELAYED",
|
||
"sendTime": "2026-05-27 21:00:00",
|
||
"sendTimeMs": 1779999700000,
|
||
"totalCount": 5,
|
||
"totalAmount": 15000,
|
||
"remainCount": 4,
|
||
"remainAmount": 12000,
|
||
"claimedCount": 1,
|
||
"claimedAmount": 3000,
|
||
"refundAmount": 0,
|
||
"claimStartTime": "2026-05-27T21:05:00+08:00",
|
||
"claimStartTimeMs": 1780000000000,
|
||
"expireTime": "2026-05-28T21:00:00+08:00",
|
||
"expireTimeMs": 1780086400000,
|
||
"status": "ACTIVE",
|
||
"sender": {
|
||
"userId": "10001",
|
||
"account": "10001",
|
||
"nickname": "Tom",
|
||
"avatar": "https://example.com/avatar.png"
|
||
},
|
||
"currentUserClaimed": true,
|
||
"currentUserAmount": 3000
|
||
}
|
||
```
|
||
|
||
### 5.9 领取记录列表
|
||
|
||
```http
|
||
GET /app/voice-room/red-packet/claim-records?packetNo=VRRP2026052712340001&cursor=&limit=20
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"packetNo": "VRRP2026052712340001",
|
||
"totalCount": 5,
|
||
"claimedCount": 1,
|
||
"claimedAmount": 3000,
|
||
"records": [
|
||
{
|
||
"id": "2052643780674195456",
|
||
"userId": "10002",
|
||
"account": "10002",
|
||
"nickname": "Jerry",
|
||
"avatar": "https://example.com/avatar2.png",
|
||
"amount": 3000,
|
||
"claimTime": "2026-05-27 21:05:10",
|
||
"claimTimeMs": 1780000010000
|
||
}
|
||
],
|
||
"nextCursor": "2052643780674195456",
|
||
"hasMore": false
|
||
}
|
||
```
|
||
|
||
### 5.10 发送记录列表
|
||
|
||
```http
|
||
GET /app/voice-room/red-packet/sent-records?cursor=&limit=20
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"records": [
|
||
{
|
||
"packetNo": "VRRP2026052712340001",
|
||
"roomId": "9001",
|
||
"packetMode": "DELAYED",
|
||
"sendTime": "2026-05-27 21:00:00",
|
||
"sendTimeMs": 1779999700000,
|
||
"totalCount": 5,
|
||
"totalAmount": 15000,
|
||
"refundAmount": 0,
|
||
"status": "ACTIVE"
|
||
}
|
||
],
|
||
"nextCursor": "VRRP2026052712340001",
|
||
"hasMore": false
|
||
}
|
||
```
|
||
|
||
列表页展示字段：
|
||
|
||
- 发送时间：`sendTime`
|
||
- 红包个数：`totalCount`
|
||
- 红包总金额：`totalAmount`
|
||
- 退回金额：`refundAmount`
|
||
|
||
## 6. 后台接口
|
||
|
||
### 6.1 查询配置
|
||
|
||
```http
|
||
GET /resident-activity/voice-room-red-packet/config
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"enabled": true,
|
||
"dailySendLimit": 10,
|
||
"delaySeconds": 300,
|
||
"expireSeconds": 86400,
|
||
"amountOptions": [15000, 30000, 70000, 100000],
|
||
"countOptions": [5, 10, 20, 50],
|
||
"ruleUrl": "https://example.com/red-packet-rule"
|
||
}
|
||
```
|
||
|
||
### 6.2 保存配置
|
||
|
||
```http
|
||
POST /resident-activity/voice-room-red-packet/config
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"enabled": true,
|
||
"dailySendLimit": 10,
|
||
"delaySeconds": 300,
|
||
"amountOptions": [15000, 30000, 70000, 100000],
|
||
"countOptions": [5, 10, 20, 50],
|
||
"ruleUrl": "https://example.com/red-packet-rule"
|
||
}
|
||
```
|
||
|
||
说明：
|
||
|
||
- `expireSeconds` 固定为 86400，不建议后台配置。
|
||
- `amountOptions` 和 `countOptions` 必须都是正整数数组。
|
||
- `totalAmount >= totalCount`，保证每份最小金额大于 0。
|
||
|
||
### 6.3 红包记录查询
|
||
|
||
```http
|
||
GET /resident-activity/voice-room-red-packet/records?sysOrigin=LIKEI&roomId=&senderUserId=&status=&startTime=&endTime=&page=1&pageSize=20
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"page": 1,
|
||
"pageSize": 20,
|
||
"total": 1,
|
||
"records": [
|
||
{
|
||
"packetNo": "VRRP2026052712340001",
|
||
"roomId": "9001",
|
||
"senderUserId": "10001",
|
||
"senderNickname": "Tom",
|
||
"packetMode": "DELAYED",
|
||
"totalAmount": 15000,
|
||
"totalCount": 5,
|
||
"claimedAmount": 3000,
|
||
"claimedCount": 1,
|
||
"refundAmount": 0,
|
||
"status": "ACTIVE",
|
||
"sendTime": "2026-05-27 21:00:00",
|
||
"expireTime": "2026-05-28 21:00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 6.4 退款重试
|
||
|
||
```http
|
||
POST /resident-activity/voice-room-red-packet/refund/retry
|
||
```
|
||
|
||
请求：
|
||
|
||
```json
|
||
{
|
||
"packetNo": "VRRP2026052712340001"
|
||
}
|
||
```
|
||
|
||
返回：
|
||
|
||
```json
|
||
{
|
||
"packetNo": "VRRP2026052712340001",
|
||
"refundAmount": 3000,
|
||
"refundStatus": "SUCCESS"
|
||
}
|
||
```
|
||
|
||
## 7. 错误码
|
||
|
||
| code | 场景 | 客户端处理 |
|
||
| --- | --- | --- |
|
||
| `voice_room_red_packet_disabled` | 功能关闭 | 隐藏入口或提示暂不可用 |
|
||
| `voice_room_red_packet_amount_invalid` | 金额不在后台档位 | 刷新配置 |
|
||
| `voice_room_red_packet_count_invalid` | 个数不在后台档位 | 刷新配置 |
|
||
| `voice_room_red_packet_daily_limit_exceeded` | 今日发送上限 | 提示今日发送次数已达上限 |
|
||
| `voice_room_red_packet_room_presence_required` | 用户不在当前房间在线态 | 提示需在房间内操作 |
|
||
| `voice_room_red_packet_insufficient_balance` | 余额不足 | 拉起充值弹窗 |
|
||
| `voice_room_region_missing` | 用户区域缺失 | 提示暂不可参与 |
|
||
| `voice_room_region_not_match` | 非同语区领取 | 提示非同语区不可领取 |
|
||
| `voice_room_red_packet_not_found` | 红包不存在 | 刷新列表 |
|
||
| `voice_room_red_packet_not_started` | 延时红包未到时间 | 展示倒计时 |
|
||
| `voice_room_red_packet_expired` | 红包已过期 | 提示已过期并刷新侧边栏 |
|
||
| `voice_room_red_packet_finished` | 红包已抢完 | 提示已抢完并刷新侧边栏 |
|
||
| `claim_processing` | 钱包入账处理中 | 展示处理中，可重试或查详情 |
|
||
| `voice_room_red_packet_wallet_deduct_failed` | 扣款失败 | 提示发送失败 |
|
||
| `voice_room_red_packet_wallet_income_failed` | 入账失败 | 提示领取处理中或稍后重试 |
|
||
| `voice_room_red_packet_refund_failed` | 退款失败 | 后台重试 |
|
||
|
||
## 8. 验证点
|
||
|
||
功能验证：
|
||
|
||
- 发送即时红包，当前房间用户收到 `ROOM_RED_PACKET CREATED scope=ROOM`，同语区群不收到飘窗。
|
||
- 发送延时红包，当前房间用户收到 `scope=ROOM` 弹窗，同语区用户收到 `scope=REGION` 飘窗。
|
||
- 延时红包未到 `claimStartTime` 领取返回 `voice_room_red_packet_not_started`。
|
||
- 延时红包到点后房间收到 `OPEN_DUE`，已关闭弹窗的用户被强弹。
|
||
- 发送者本人可以领取自己发送的红包。
|
||
- 同一用户重复领取同一红包返回同一领取结果。
|
||
- 并发领取不会超过 `totalAmount` 和 `totalCount`。
|
||
- 红包创建 24 小时后，未领取金额退回发送者。
|
||
- 领取成功、抢完、过期后房间侧边栏未领取数量实时减少。
|
||
|
||
接口验证：
|
||
|
||
- 所有成功接口同时返回 `body` 和 `data`。
|
||
- 所有失败接口 `status=false`，`body/data=null`，`code` 与 `errorCodeName` 一致。
|
||
- `requestId` 重复发送只生成一个红包。
|
||
- `packetNo + userId` 重复领取只生成一条领取记录。
|