566 lines
16 KiB
Markdown
566 lines
16 KiB
Markdown
# 红包接口文档
|
||
|
||
## 接口列表
|
||
|
||
### 1. 发送红包
|
||
|
||
**接口地址**: `POST /redpacket/send_redpacket`
|
||
|
||
**接口描述**: 在群聊中发送红包，发送用户默认为群主
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"groupID": "group123", // 群ID（必填，string）
|
||
"redPacketType": 1, // 红包类型（必填，int32）：1-普通红包（平均分配），2-拼手气红包（随机分配）
|
||
"totalAmount": 10000, // 总金额（必填，int64，单位：分）
|
||
"totalCount": 10, // 总个数（必填，int32）
|
||
"blessing": "恭喜发财" // 祝福语（可选，string）
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
- `groupID`: 群ID，必须是已存在的群
|
||
- `redPacketType`: 红包类型
|
||
- `1`: 普通红包，每个红包金额 = 总金额 / 总个数
|
||
- `2`: 拼手气红包，金额随机分配
|
||
- `totalAmount`: 总金额，单位：分（例如：10000 = 100元）
|
||
- `totalCount`: 红包总个数，必须大于0
|
||
- `blessing`: 祝福语，可选
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0, // 错误码，0表示成功
|
||
"errMsg": "", // 错误信息
|
||
"errDlt": "", // 错误详情
|
||
"data": {
|
||
"redPacketID": "rp_1234567890abcdef", // 红包ID（string）
|
||
"serverMsgID": "msg_1234567890abcdef", // 服务器消息ID（string）
|
||
"clientMsgID": "client_1234567890", // 客户端消息ID（string）
|
||
"sendTime": 1704067200000 // 发送时间戳（int64，毫秒）
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应说明**:
|
||
- `redPacketID`: 红包唯一标识，用于后续领取、查询等操作
|
||
- `serverMsgID`: 服务器生成的消息ID
|
||
- `clientMsgID`: 客户端消息ID
|
||
- `sendTime`: 发送时间戳（毫秒）
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误（金额、个数、类型等）
|
||
- `1002`: 群不存在
|
||
- `1003`: 群主不存在
|
||
- `1004`: 创建红包记录失败
|
||
- `1005`: 发送消息失败
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:10002/redpacket/send_redpacket \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"groupID": "group123",
|
||
"redPacketType": 1,
|
||
"totalAmount": 10000,
|
||
"totalCount": 10,
|
||
"blessing": "恭喜发财"
|
||
}'
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"redPacketID": "rp_1234567890abcdef",
|
||
"serverMsgID": "msg_1234567890abcdef",
|
||
"clientMsgID": "client_1234567890",
|
||
"sendTime": 1704067200000
|
||
}
|
||
}
|
||
```
|
||
|
||
## 业务规则
|
||
|
||
1. **发送用户**: 自动使用群主作为发送用户，无需在请求中指定
|
||
2. **红包类型**:
|
||
- 普通红包（type=1）: 每个红包金额 = 总金额 / 总个数（向下取整，最后一个红包包含余数）
|
||
- 拼手气红包（type=2）: 金额随机分配，保证最后一个红包能领完剩余金额
|
||
3. **过期时间**: 红包默认24小时后过期
|
||
4. **红包状态**:
|
||
- `0`: 进行中（可领取）
|
||
- `1`: 已领完
|
||
- `2`: 已过期
|
||
5. **消息类型**: 红包消息使用自定义消息类型 `110`（`constant.Custom`），通过 `description` 字段标识二级类型为 `"redpacket"`
|
||
|
||
## 数据库记录
|
||
|
||
发送红包时会自动创建以下数据库记录：
|
||
|
||
**red_packets 表**:
|
||
- 记录红包基本信息（金额、个数、类型等）
|
||
- 记录红包状态和剩余信息
|
||
- 记录过期时间
|
||
|
||
**消息记录**:
|
||
- 在群聊中发送一条红包消息
|
||
- 消息内容包含红包ID和基本信息
|
||
- 群成员可以看到红包消息
|
||
|
||
## 注意事项
|
||
|
||
1. 只支持群聊，不支持单聊
|
||
2. 发送用户固定为群主，不能指定其他用户
|
||
3. 红包金额单位是"分"，不是"元"
|
||
4. 红包个数必须大于0
|
||
5. 总金额必须大于0
|
||
6. 红包类型只能是1或2
|
||
|
||
### 2. 领取红包
|
||
|
||
**接口地址**: `POST /redpacket/receive`
|
||
|
||
**接口描述**: 领取红包，支持普通红包和拼手气红包
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"redPacketID": "rp_1234567890abcdef" // 红包ID（必填，string）
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
- `redPacketID`: 红包ID，从发送红包接口的响应中获取
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0, // 错误码，0表示成功
|
||
"errMsg": "", // 错误信息
|
||
"errDlt": "", // 错误详情
|
||
"data": {
|
||
"redPacketID": "rp_1234567890abcdef", // 红包ID（string）
|
||
"amount": 1000, // 领取金额（int64，单位：分）
|
||
"isLucky": false // 是否为手气最佳（bool，仅拼手气红包有效）
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应说明**:
|
||
- `redPacketID`: 红包ID
|
||
- `amount`: 领取到的金额，单位：分
|
||
- `isLucky`: 是否为手气最佳，仅拼手气红包有效
|
||
- `true`: 是手气最佳（领取金额最大）
|
||
- `false`: 不是手气最佳
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误（红包ID为空）
|
||
- `1004`: 红包不存在（RecordNotFoundError）
|
||
- `1801`: 红包已被领完（RedPacketFinishedError）
|
||
- `1802`: 红包已过期（RedPacketExpiredError）
|
||
- `1803`: 用户已领取过该红包（RedPacketAlreadyReceivedError）
|
||
- `500`: 服务器内部错误（Redis队列操作失败等）
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:10002/redpacket/receive \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"redPacketID": "rp_1234567890abcdef"
|
||
}'
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"redPacketID": "rp_1234567890abcdef",
|
||
"amount": 1000,
|
||
"isLucky": false
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务规则**:
|
||
|
||
1. **领取限制**:
|
||
- 每个用户只能领取一次
|
||
- 红包必须处于"进行中"状态
|
||
- 红包不能已过期
|
||
- 红包不能已被领完
|
||
|
||
2. **金额分配**:
|
||
- **普通红包（type=1）**: 金额 = 剩余金额 / 剩余个数（向下取整，最后一个包含余数）
|
||
- **拼手气红包（type=2）**: 从Redis队列中获取预分配的随机金额
|
||
|
||
3. **手气最佳判断**:
|
||
- 仅拼手气红包有效
|
||
- 领取金额最大的用户被标记为手气最佳
|
||
- 如果有多个相同最大金额，第一个领取的会被标记为手气最佳
|
||
|
||
4. **消息更新**:
|
||
- 领取红包后，客户端下次拉取消息时会自动看到已领取状态
|
||
- 消息同步时会动态填充领取信息（`IsReceived` 和 `ReceiveInfo`）
|
||
|
||
5. **原子操作**:
|
||
- 领取操作是原子的，确保并发安全
|
||
- 使用数据库事务保证数据一致性
|
||
|
||
### 3. 查询红包列表（后台管理接口）
|
||
|
||
**接口地址**: `POST /redpacket/get_redpackets_by_group`
|
||
|
||
**接口描述**: 根据群ID查询红包列表，支持查询所有红包或指定群的红包
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"groupID": "group123", // 群ID（选填，string），不填或为空则查询所有红包
|
||
"pagination": {
|
||
"pageNumber": 1, // 页码（选填，int32），从1开始，默认1
|
||
"showNumber": 20 // 每页数量（选填，int32），默认20
|
||
}
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
- `groupID`: 群ID，选填
|
||
- 如果为空或不传，则查询所有红包
|
||
- 如果指定群ID，则只查询该群的红包
|
||
- `pagination`: 分页参数，选填
|
||
- `pageNumber`: 页码，从1开始，默认1
|
||
- `showNumber`: 每页数量，默认20
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"total": 100, // 总数（int64）
|
||
"redPackets": [ // 红包列表（array）
|
||
{
|
||
"redPacketID": "rp_1234567890abcdef", // 红包ID（string）
|
||
"sendUserID": "user123", // 发送者ID（string）
|
||
"groupID": "group123", // 群ID（string）
|
||
"groupName": "测试群", // 群名称（string）
|
||
"redPacketType": 1, // 红包类型（int32）：1-普通红包，2-拼手气红包
|
||
"totalAmount": 10000, // 总金额（int64，单位：分）
|
||
"totalCount": 10, // 总个数（int32）
|
||
"remainAmount": 5000, // 剩余金额（int64，单位：分）
|
||
"remainCount": 5, // 剩余个数（int32）
|
||
"blessing": "恭喜发财", // 祝福语（string）
|
||
"status": 0, // 状态（int32）：0-进行中，1-已领完，2-已过期
|
||
"expireTime": 1704153600000, // 过期时间戳（int64，毫秒）
|
||
"createTime": 1704067200000 // 创建时间戳（int64，毫秒）
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应说明**:
|
||
- `total`: 符合条件的红包总数
|
||
- `redPackets`: 红包列表，按创建时间倒序排列
|
||
- 每个红包包含完整的信息：ID、发送者、群ID、群名称、类型、金额、个数、剩余信息、状态等
|
||
- `groupName`: 群名称，通过批量查询群信息获取，如果群不存在或查询失败则为空字符串
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误
|
||
- `500`: 服务器内部错误
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
# 查询所有红包
|
||
curl -X POST http://localhost:10002/redpacket/get_redpackets_by_group \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 20
|
||
}
|
||
}'
|
||
|
||
# 查询指定群的红包
|
||
curl -X POST http://localhost:10002/redpacket/get_redpackets_by_group \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"groupID": "group123",
|
||
"pagination": {
|
||
"pageNumber": 1,
|
||
"showNumber": 20
|
||
}
|
||
}'
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"total": 100,
|
||
"redPackets": [
|
||
{
|
||
"redPacketID": "rp_1234567890abcdef",
|
||
"sendUserID": "user123",
|
||
"groupID": "group123",
|
||
"groupName": "测试群",
|
||
"redPacketType": 1,
|
||
"totalAmount": 10000,
|
||
"totalCount": 10,
|
||
"remainAmount": 5000,
|
||
"remainCount": 5,
|
||
"blessing": "恭喜发财",
|
||
"status": 0,
|
||
"expireTime": 1704153600000,
|
||
"createTime": 1704067200000
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4. 查询红包领取情况（后台管理接口）
|
||
|
||
**接口地址**: `POST /redpacket/get_receive_info`
|
||
|
||
**接口描述**: 查询指定红包的领取情况，包括所有领取记录和详细信息
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"redPacketID": "rp_1234567890abcdef" // 红包ID（必填，string）
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
- `redPacketID`: 红包ID，必填
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"redPacketID": "rp_1234567890abcdef", // 红包ID（string）
|
||
"totalAmount": 10000, // 总金额（int64，单位：分）
|
||
"totalCount": 10, // 总个数（int32）
|
||
"remainAmount": 5000, // 剩余金额（int64，单位：分）
|
||
"remainCount": 5, // 剩余个数（int32）
|
||
"status": 0, // 状态（int32）：0-进行中，1-已领完，2-已过期
|
||
"receives": [ // 领取记录列表（array）
|
||
{
|
||
"receiveID": "rec_1234567890", // 领取记录ID（string）
|
||
"receiveUserID": "user456", // 领取者ID（string）
|
||
"amount": 1000, // 领取金额（int64，单位：分）
|
||
"receiveTime": 1704070800000, // 领取时间戳（int64，毫秒）
|
||
"isLucky": false // 是否为手气最佳（bool，仅拼手气红包有效）
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应说明**:
|
||
- `redPacketID`: 红包ID
|
||
- `totalAmount`: 红包总金额
|
||
- `totalCount`: 红包总个数
|
||
- `remainAmount`: 剩余金额
|
||
- `remainCount`: 剩余个数
|
||
- `status`: 红包状态
|
||
- `receives`: 领取记录列表，按领取时间正序排列
|
||
- `receiveID`: 领取记录ID
|
||
- `receiveUserID`: 领取者用户ID
|
||
- `amount`: 领取的金额
|
||
- `receiveTime`: 领取时间戳
|
||
- `isLucky`: 是否为手气最佳（仅拼手气红包有效）
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误（红包ID为空）
|
||
- `1004`: 红包不存在
|
||
- `500`: 服务器内部错误
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:10002/redpacket/get_receive_info \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"redPacketID": "rp_1234567890abcdef"
|
||
}'
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"redPacketID": "rp_1234567890abcdef",
|
||
"totalAmount": 10000,
|
||
"totalCount": 10,
|
||
"remainAmount": 5000,
|
||
"remainCount": 5,
|
||
"status": 0,
|
||
"receives": [
|
||
{
|
||
"receiveID": "rec_1234567890",
|
||
"receiveUserID": "user456",
|
||
"amount": 1000,
|
||
"receiveTime": 1704070800000,
|
||
"isLucky": false
|
||
},
|
||
{
|
||
"receiveID": "rec_1234567891",
|
||
"receiveUserID": "user789",
|
||
"amount": 2000,
|
||
"receiveTime": 1704071400000,
|
||
"isLucky": true
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5. 暂停红包（后台管理接口）
|
||
|
||
**接口地址**: `POST /redpacket/pause`
|
||
|
||
**接口描述**: 暂停红包，清空Redis队列，使红包无法继续被领取（仅对拼手气红包有效）
|
||
|
||
**请求参数**:
|
||
|
||
```json
|
||
{
|
||
"redPacketID": "rp_1234567890abcdef" // 红包ID（必填，string）
|
||
}
|
||
```
|
||
|
||
**参数说明**:
|
||
- `redPacketID`: 红包ID，必填
|
||
|
||
**响应参数**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"redPacketID": "rp_1234567890abcdef" // 红包ID（string）
|
||
}
|
||
}
|
||
```
|
||
|
||
**响应说明**:
|
||
- `redPacketID`: 红包ID
|
||
|
||
**错误码**:
|
||
- `0`: 成功
|
||
- `1001`: 参数错误（红包ID为空）
|
||
- `1004`: 红包不存在
|
||
- `500`: 服务器内部错误（Redis操作失败等）
|
||
|
||
**请求示例**:
|
||
|
||
```bash
|
||
curl -X POST http://localhost:10002/redpacket/pause \
|
||
-H "Content-Type: application/json" \
|
||
-H "token: your_token" \
|
||
-d '{
|
||
"redPacketID": "rp_1234567890abcdef"
|
||
}'
|
||
```
|
||
|
||
**响应示例**:
|
||
|
||
```json
|
||
{
|
||
"errCode": 0,
|
||
"errMsg": "",
|
||
"errDlt": "",
|
||
"data": {
|
||
"redPacketID": "rp_1234567890abcdef"
|
||
}
|
||
}
|
||
```
|
||
|
||
**业务规则**:
|
||
|
||
1. **暂停操作**:
|
||
- 清空该红包在Redis中的队列（`redpacket:queue:{redPacketID}`）
|
||
- 清空后，后续领取请求会因队列为空而失败（返回 `1801: red packet has been finished`）
|
||
- 已领取的记录不受影响，只是无法继续领取
|
||
|
||
2. **红包类型**:
|
||
- **拼手气红包（type=2）**: 会清空Redis队列
|
||
- **普通红包（type=1）**: 没有Redis队列，直接返回成功
|
||
|
||
3. **注意事项**:
|
||
- 暂停操作不可逆，清空后的Redis队列无法恢复
|
||
- 暂停后，红包状态不会自动更新，但实际已无法领取
|
||
- 建议在暂停后手动更新红包状态为"已领完"或"已过期"
|
||
|
||
## 接口汇总
|
||
|
||
| 接口路径 | 方法 | 描述 | 类型 |
|
||
|---------|------|------|------|
|
||
| `/redpacket/send_redpacket` | POST | 发送红包 | 用户接口 |
|
||
| `/redpacket/receive` | POST | 领取红包 | 用户接口 |
|
||
| `/redpacket/get_redpackets_by_group` | POST | 查询红包列表 | 后台管理接口 |
|
||
| `/redpacket/get_receive_info` | POST | 查询红包领取情况 | 后台管理接口 |
|
||
| `/redpacket/pause` | POST | 暂停红包 | 后台管理接口 |
|
||
|
||
## 错误码汇总
|
||
|
||
| 错误码 | 说明 | 适用接口 |
|
||
|--------|------|----------|
|
||
| `0` | 成功 | 所有接口 |
|
||
| `1001` | 参数错误 | 所有接口 |
|
||
| `1004` | 记录不存在 | 领取、查询、暂停接口 |
|
||
| `1801` | 红包已被领完 | 领取接口 |
|
||
| `1802` | 红包已过期 | 领取接口 |
|
||
| `1803` | 用户已领取过该红包 | 领取接口 |
|
||
| `500` | 服务器内部错误 | 所有接口 |
|
||
|
||
## 客户端消息结构
|
||
|
||
客户端收到的红包消息结构请参考：[红包消息结构文档](./redpacket-message-structure.md)
|
||
|