208 lines
5.5 KiB
Markdown
208 lines
5.5 KiB
Markdown
# 房间红包功能开发完成清单
|
||
|
||
## ✅ 已完成文件列表
|
||
|
||
### 1. Domain层（11个文件）
|
||
- ✅ RoomRedPacketType.java - 红包类型枚举
|
||
- ✅ RoomRedPacketStatus.java - 红包状态枚举
|
||
- ✅ RoomRedPacketSourceType.java - 红包来源类型枚举
|
||
- ✅ RoomRedPacketRefundStatus.java - 退款状态枚举
|
||
- ✅ RoomRedPacket.java - 红包领域对象
|
||
- ✅ RoomRedPacketRecord.java - 红包记录领域对象
|
||
- ✅ RoomRedPacketGateway.java - 红包网关接口
|
||
- ✅ RoomRedPacketRecordGateway.java - 红包记录网关接口
|
||
|
||
### 2. Infrastructure层（13个文件）
|
||
- ✅ RoomRedPacketEntity.java - 红包实体
|
||
- ✅ RoomRedPacketRecordEntity.java - 红包记录实体
|
||
- ✅ RoomRedPacketDAO.java - 红包DAO接口
|
||
- ✅ RoomRedPacketRecordDAO.java - 红包记录DAO接口
|
||
- ✅ RoomRedPacketDAO.xml - MyBatis映射文件
|
||
- ✅ RoomRedPacketRecordDAO.xml - MyBatis映射文件
|
||
- ✅ RoomRedPacketConvertor.java - 基础设施转换器
|
||
- ✅ RoomRedPacketGatewayImpl.java - 红包网关实现
|
||
- ✅ RoomRedPacketRecordGatewayImpl.java - 红包记录网关实现
|
||
- ✅ RoomRedPacketKeys.java - Redis Key枚举
|
||
- ✅ RoomRedPacketCacheService.java - Redis缓存服务接口
|
||
- ✅ RoomRedPacketCacheServiceImpl.java - Redis缓存服务实现
|
||
|
||
### 3. Client层（10个文件）
|
||
- ✅ SendRoomRedPacketCmd.java - 发红包命令
|
||
- ✅ GrabRoomRedPacketCmd.java - 抢红包命令
|
||
- ✅ QueryRoomRedPacketListCmd.java - 查询列表命令
|
||
- ✅ QueryRoomRedPacketDetailCmd.java - 查询详情命令
|
||
- ✅ RoomRedPacketCO.java - 红包CO
|
||
- ✅ RoomRedPacketDetailCO.java - 红包详情CO
|
||
- ✅ RoomRedPacketRecordCO.java - 红包记录CO
|
||
- ✅ GrabRoomRedPacketResultCO.java - 抢红包结果CO
|
||
- ✅ RoomRedPacketService.java - 服务接口
|
||
|
||
### 4. Application层（6个文件）
|
||
- ✅ RoomRedPacketAppConvertor.java - 应用层转换器
|
||
- ✅ SendRoomRedPacketCmdExe.java - 发红包执行器
|
||
- ✅ GrabRoomRedPacketCmdExe.java - 抢红包执行器（高并发核心）
|
||
- ✅ QueryRoomRedPacketListQryExe.java - 查询列表执行器
|
||
- ✅ QueryRoomRedPacketDetailQryExe.java - 查询详情执行器
|
||
- ✅ RoomRedPacketServiceImpl.java - 服务实现
|
||
|
||
### 5. Adapter层（1个文件）
|
||
- ✅ RoomRedPacketRestController.java - REST控制器
|
||
|
||
### 6. Scheduler层（1个文件）
|
||
- ✅ RoomRedPacketExpireTask.java - 过期退款定时任务
|
||
|
||
### 7. 错误码
|
||
- ✅ OtherErrorCode.java - 已添加红包相关错误码（3260-3271）
|
||
|
||
### 8. 数据库SQL
|
||
- ✅ room_red_packet_tables.sql - 数据库建表SQL
|
||
|
||
---
|
||
|
||
## 📊 统计
|
||
- **总文件数**: 42个
|
||
- **代码行数**: 约3500+行
|
||
- **涉及模块**: 7个层级
|
||
|
||
---
|
||
|
||
## 🚀 API接口清单
|
||
|
||
### 1. 发送红包
|
||
```
|
||
POST /api/room/red-packet/send
|
||
```
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"roomId": 123456,
|
||
"packetType": 1, // 1-固定金额 2-拼手气
|
||
"totalAmount": 1000, // 总金额（金币数量）
|
||
"totalCount": 10, // 红包个数
|
||
"expireMinutes": 3 // 过期分钟数：1/3/5
|
||
}
|
||
```
|
||
|
||
### 2. 抢红包
|
||
```
|
||
POST /api/room/red-packet/grab
|
||
```
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"packetId": "uuid-string"
|
||
}
|
||
```
|
||
|
||
### 3. 查询房间红包列表
|
||
```
|
||
GET /api/room/red-packet/list?roomId=123456&limit=20
|
||
```
|
||
|
||
### 4. 查询红包详情
|
||
```
|
||
GET /api/room/red-packet/detail?packetId=uuid-string
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 配置说明
|
||
|
||
### 1. Redis Key前缀
|
||
所有Redis Key使用前缀 `ROOM:RED_PACKET:`
|
||
|
||
### 2. 错误码范围
|
||
红包相关错误码：3260-3279
|
||
|
||
### 3. 定时任务
|
||
- **过期退款任务**: 每分钟执行一次 (cron = "0 * * * * ?")
|
||
|
||
---
|
||
|
||
## ⚠️ 待完成事项
|
||
|
||
### 1. 钱包服务GoldOrigin枚举
|
||
需要在钱包服务的 `GoldOrigin` 枚举中添加以下事件类型：
|
||
```java
|
||
// 在 wallet-inner-model 的 GoldOrigin 枚举中添加
|
||
RED_PACKET_SEND("red_packet_send", "发红包"),
|
||
RED_PACKET_GRAB("red_packet_grab", "抢红包"),
|
||
RED_PACKET_REFUND("red_packet_refund", "红包退款"),
|
||
```
|
||
|
||
### 2. IM推送集成
|
||
发红包时，如果金额>=10000，需要触发全服IM推送。代码中已预留TODO位置：
|
||
```java
|
||
// SendRoomRedPacketCmdExe.java 第94行
|
||
// TODO: 调用IM服务触发全服推送
|
||
```
|
||
|
||
### 3. WebSocket房间推送
|
||
抢红包成功后，需要通过WebSocket推送消息到房间内其他用户。可选实现。
|
||
|
||
### 4. 用户信息补充
|
||
在查询接口中，需要补充用户昵称和头像信息。建议调用user服务批量查询。
|
||
|
||
### 5. 房间权限校验
|
||
发红包和抢红包前，需要校验用户是否在房间内。建议调用live服务校验。
|
||
|
||
---
|
||
|
||
## 📝 注意事项
|
||
|
||
### 1. 高并发保护
|
||
- Redis防重标记
|
||
- Lua脚本原子扣减
|
||
- 异步写库提高响应速度
|
||
|
||
### 2. 幂等性保证
|
||
- 发红包：使用packetId作为bizNo
|
||
- 抢红包：使用recordId作为bizNo
|
||
- 退款：使用packetId_refund作为bizNo
|
||
|
||
### 3. 数据一致性
|
||
- 异步写库失败会记录日志
|
||
- 可扩展异常日志表进行补偿
|
||
|
||
### 4. 性能优化
|
||
- Redis缓存红包主数据
|
||
- 拼手气金额预生成
|
||
- 查询接口可加缓存
|
||
|
||
---
|
||
|
||
## 🧪 测试建议
|
||
|
||
### 1. 单元测试
|
||
- 固定金额红包发送
|
||
- 拼手气红包发送
|
||
- 高并发抢红包（多线程）
|
||
- 过期退款
|
||
|
||
### 2. 压力测试
|
||
- 100人同时抢1个红包
|
||
- 1000QPS发红包
|
||
- Redis性能测试
|
||
|
||
### 3. 异常测试
|
||
- 余额不足
|
||
- 重复领取
|
||
- 红包过期
|
||
- 异步失败补偿
|
||
|
||
---
|
||
|
||
## 📦 部署步骤
|
||
|
||
1. 执行数据库SQL建表
|
||
2. 确保Redis服务正常
|
||
3. 在钱包服务添加GoldOrigin枚举
|
||
4. 重启other服务
|
||
5. 验证接口可用性
|
||
|
||
---
|
||
|
||
**开发完成时间**: 2025-11-25
|
||
**开发者**: Leo
|
||
**状态**: ✅ 核心功能完成，待集成测试
|