623 lines
13 KiB
Markdown
623 lines
13 KiB
Markdown
# 🚀 语聊房火箭系统 - 完整需求文档
|
||
|
||
---
|
||
|
||
## 📋 文档信息
|
||
|
||
| 项目 | 内容 |
|
||
|-----|------|
|
||
| **文档名称** | 语聊房火箭系统需求文档 |
|
||
| **版本** | v1.0 |
|
||
| **创建日期** | 2025-01-15 |
|
||
| **所属项目** | Likei Services |
|
||
| **所属模块** | rc-service-other |
|
||
| **项目路径** | D:\workspace\likei-services\rc-service\rc-service-other |
|
||
|
||
---
|
||
|
||
## 1. 业务需求
|
||
|
||
### 1.1 功能概述
|
||
|
||
语聊房火箭是一个房间级互动玩法，用户通过送礼积累火箭能量，达到阈值后自动发射并分发奖励。
|
||
|
||
### 1.2 核心规则
|
||
|
||
#### 能量积累规则
|
||
- **基础规则**：1金币礼物 = 1火箭能量点
|
||
- **幸运加成**：幸运礼物额外增加4%能量
|
||
- **实时累积**：每次送礼立即增加能量
|
||
|
||
#### 火箭等级系统
|
||
| 等级 | 能量阈值 | 说明 |
|
||
|-----|---------|------|
|
||
| Lv1 | 150,000 | 一级火箭 |
|
||
| Lv2 | 500,000 | 二级火箭 |
|
||
| Lv3 | 1,000,000 | 三级火箭 |
|
||
|
||
#### 发射机制
|
||
- 能量达到阈值自动触发发射
|
||
- 发射后进入"领取中"状态
|
||
- 领取有效期：1分钟
|
||
|
||
#### 奖励领取规则
|
||
- 房间内所有用户可领取
|
||
- 贡献者和普通用户奖励不同（配置待定）
|
||
- 每人限领一次
|
||
- 过期后自动重置
|
||
|
||
#### 每日重置
|
||
- 每天00:00重置火箭状态
|
||
- 历史记录保存到MongoDB
|
||
|
||
---
|
||
|
||
## 2. 技术架构
|
||
|
||
### 2.1 技术栈
|
||
|
||
| 组件 | 技术 |
|
||
|-----|------|
|
||
| **语言** | Java 17+ |
|
||
| **框架** | Spring Boot |
|
||
| **数据库** | MySQL + MongoDB |
|
||
| **缓存** | Redis |
|
||
| **架构模式** | DDD + CQRS |
|
||
|
||
### 2.2 数据库设计
|
||
|
||
#### MongoDB 集合
|
||
|
||
**room_rocket_status** - 火箭实时状态
|
||
```javascript
|
||
{
|
||
"_id": ObjectId,
|
||
"room_id": NumberLong,
|
||
"date": "2025-01-15",
|
||
"level": 1, // 1/2/3
|
||
"current_energy": NumberLong(85000),
|
||
"max_energy": NumberLong(150000),
|
||
"status": 1, // 1:CHARGING 2:LAUNCHED 3:CLAIMING
|
||
"contributors": [
|
||
{
|
||
"user_id": NumberLong,
|
||
"user_name": "张三",
|
||
"user_avatar": "https://...",
|
||
"energy": NumberLong(50000),
|
||
"contribution_rate": 58.82,
|
||
"gift_count": 125,
|
||
"first_contribute_time": ISODate,
|
||
"last_contribute_time": ISODate
|
||
}
|
||
],
|
||
"launch_time": ISODate,
|
||
"claim_expire_time": ISODate,
|
||
"claim_count": 0,
|
||
"created_at": ISODate,
|
||
"updated_at": ISODate
|
||
}
|
||
|
||
// 索引
|
||
db.room_rocket_status.createIndex({"room_id": 1, "date": 1}, {unique: true})
|
||
db.room_rocket_status.createIndex({"status": 1})
|
||
```
|
||
|
||
#### MySQL 表
|
||
|
||
**rocket_config** - 火箭配置表
|
||
```sql
|
||
CREATE TABLE `rocket_config` (
|
||
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
|
||
`level` TINYINT UNSIGNED NOT NULL COMMENT '等级 1/2/3',
|
||
`max_energy` BIGINT UNSIGNED NOT NULL COMMENT '最大能量值',
|
||
`reward_config` JSON DEFAULT NULL COMMENT '奖励配置(预留)',
|
||
`status` TINYINT UNSIGNED NOT NULL DEFAULT 1 COMMENT '状态',
|
||
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
`updated_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||
PRIMARY KEY (`id`),
|
||
UNIQUE KEY `uk_level` (`level`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
||
|
||
INSERT INTO `rocket_config` (`level`, `max_energy`) VALUES
|
||
(1, 150000),
|
||
(2, 500000),
|
||
(3, 1000000);
|
||
```
|
||
|
||
**rocket_reward_claim_log** - 奖励领取记录表
|
||
```sql
|
||
CREATE TABLE `rocket_reward_claim_log` (
|
||
`id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
|
||
`rocket_history_id` VARCHAR(32) NOT NULL COMMENT 'MongoDB _id',
|
||
`room_id` BIGINT UNSIGNED NOT NULL,
|
||
`user_id` BIGINT UNSIGNED NOT NULL,
|
||
`is_contributor` TINYINT UNSIGNED NOT NULL COMMENT '是否贡献者',
|
||
`reward_type` VARCHAR(32) NOT NULL COMMENT 'GOLD/DIAMOND/PROP',
|
||
`reward_amount` BIGINT UNSIGNED NOT NULL,
|
||
`claimed_at` DATETIME NOT NULL,
|
||
`created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
|
||
PRIMARY KEY (`id`),
|
||
UNIQUE KEY `uk_rocket_user` (`rocket_history_id`, `user_id`),
|
||
KEY `idx_room_id` (`room_id`),
|
||
KEY `idx_user_id` (`user_id`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
|
||
```
|
||
|
||
### 2.3 Redis 缓存设计
|
||
|
||
| Key | 类型 | TTL | 用途 |
|
||
|-----|------|-----|------|
|
||
| ROCKET:STATUS:{roomId} | String(JSON) | 24h | 状态缓存 |
|
||
| ROCKET:LOCK:{roomId} | String | 5s | 分布式锁 |
|
||
| ROCKET:CLAIMED:{historyId} | Set | 2min | 已领取用户 |
|
||
| ROCKET:CONFIG:{level} | String(JSON) | 1h | 配置缓存 |
|
||
|
||
---
|
||
|
||
## 3. 核心流程
|
||
|
||
### 3.1 能量积累流程
|
||
|
||
```
|
||
用户送礼 → GiftSendEvent
|
||
↓
|
||
RocketEnergyAddCmdExe
|
||
↓
|
||
1. 获取分布式锁 (Redis)
|
||
2. 查询火箭状态 (MongoDB)
|
||
3. 计算能量值 (普通/幸运)
|
||
4. 更新能量和贡献者
|
||
5. 检查等级提升
|
||
6. 保存状态
|
||
7. 判断是否达到发射条件
|
||
├─ 是 → 触发发射
|
||
└─ 否 → 推送能量更新
|
||
```
|
||
|
||
### 3.2 火箭发射流程
|
||
|
||
```
|
||
能量达到阈值
|
||
↓
|
||
RocketLaunchCmdExe
|
||
↓
|
||
1. 获取分布式锁
|
||
2. 校验状态和能量
|
||
3. 发射火箭 (status → LAUNCHED)
|
||
4. 设置领取过期时间 (+1分钟)
|
||
5. 进入领取状态 (status → CLAIMING)
|
||
6. 保存状态
|
||
7. 推送发射动画 (TODO: WebSocket)
|
||
8. 保存历史记录 (TODO)
|
||
```
|
||
|
||
### 3.3 奖励领取流程
|
||
|
||
```
|
||
用户点击领取
|
||
↓
|
||
RocketRewardClaimCmdExe
|
||
↓
|
||
1. 获取分布式锁
|
||
2. 校验领取资格
|
||
├─ 状态是否为CLAIMING
|
||
├─ 是否过期
|
||
└─ 是否重复领取
|
||
3. 判断是否贡献者
|
||
4. 计算奖励金额 (TODO: 配置)
|
||
5. 调用钱包服务发放 (TODO)
|
||
6. 记录领取日志 (MySQL)
|
||
7. 更新领取人数
|
||
8. 返回奖励详情
|
||
```
|
||
|
||
### 3.4 每日重置流程
|
||
|
||
```
|
||
定时任务 00:00
|
||
↓
|
||
RocketDailyResetTask
|
||
↓
|
||
1. 查询所有CHARGING状态火箭
|
||
2. 保存历史记录 (TODO)
|
||
3. 重置火箭状态
|
||
├─ level = 1
|
||
├─ current_energy = 0
|
||
├─ contributors = []
|
||
└─ date = 今天
|
||
4. 清除Redis缓存
|
||
```
|
||
|
||
---
|
||
|
||
## 4. API 接口设计
|
||
|
||
### 4.1 查询火箭状态
|
||
|
||
**接口**: `GET /api/rocket/status`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"roomId": 123456,
|
||
"currentUserId": 789 // 可选
|
||
}
|
||
```
|
||
|
||
**响应数据**:
|
||
```json
|
||
{
|
||
"roomId": 123456,
|
||
"date": "2025-01-15",
|
||
"level": 2,
|
||
"levelName": "二级火箭",
|
||
"currentEnergy": 350000,
|
||
"maxEnergy": 500000,
|
||
"energyPercent": 70.00,
|
||
"status": "CHARGING",
|
||
"statusDesc": "充能中",
|
||
"topContributors": [
|
||
{
|
||
"userId": 789,
|
||
"userName": "张三",
|
||
"userAvatar": "https://...",
|
||
"energy": 200000,
|
||
"contributionRate": 57.14,
|
||
"rank": 1,
|
||
"giftCount": 500
|
||
}
|
||
],
|
||
"totalContributors": 25,
|
||
"claimCount": 0,
|
||
"canClaim": false,
|
||
"hasClaimed": false,
|
||
"myContribution": 200000,
|
||
"myContributionRate": 57.14
|
||
}
|
||
```
|
||
|
||
### 4.2 领取奖励
|
||
|
||
**接口**: `POST /api/rocket/claim`
|
||
|
||
**请求参数**:
|
||
```json
|
||
{
|
||
"roomId": 123456,
|
||
"userId": 789,
|
||
"rocketHistoryId": "507f1f77bcf86cd799439011"
|
||
}
|
||
```
|
||
|
||
**响应数据**:
|
||
```json
|
||
{
|
||
"rewardType": "GOLD",
|
||
"rewardAmount": 1000,
|
||
"isContributor": true,
|
||
"contributionEnergy": 200000,
|
||
"contributionRate": 57.14,
|
||
"message": "恭喜您获得贡献者奖励！"
|
||
}
|
||
```
|
||
|
||
### 4.3 手动触发发射 (测试用)
|
||
|
||
**接口**: `POST /api/rocket/manual-launch`
|
||
|
||
**请求参数**:
|
||
```
|
||
roomId=123456
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 已实现文件清单
|
||
|
||
### 5.1 Domain 层
|
||
```
|
||
✅ RocketLevel.java - 等级枚举
|
||
✅ RocketStatusEnum.java - 状态枚举
|
||
✅ RocketContributor.java - 贡献者值对象
|
||
✅ RocketStatus.java - 火箭状态领域对象
|
||
✅ RocketStatusGateway.java - Gateway接口
|
||
```
|
||
|
||
### 5.2 Infrastructure 层
|
||
```
|
||
✅ RocketKeys.java - Redis Key枚举
|
||
✅ RocketStatusDocument.java - MongoDB文档
|
||
✅ RocketStatusRepository.java - MongoDB Repository
|
||
✅ RocketStatusGatewayImpl.java - Gateway实现
|
||
```
|
||
|
||
### 5.3 Client 层
|
||
```
|
||
✅ RocketEnergyAddCmd.java - 能量增加命令
|
||
✅ RocketRewardClaimCmd.java - 奖励领取命令
|
||
✅ RocketStatusQueryCmd.java - 状态查询命令
|
||
✅ RocketStatusCO.java - 状态客户端对象
|
||
✅ RocketContributorCO.java - 贡献者客户端对象
|
||
✅ RocketRewardCO.java - 奖励客户端对象
|
||
✅ RocketService.java - 服务接口
|
||
```
|
||
|
||
### 5.4 Application 层
|
||
```
|
||
✅ RocketEnergyAddCmdExe.java - 能量增加执行器
|
||
✅ RocketLaunchCmdExe.java - 火箭发射执行器
|
||
✅ RocketStatusQryExe.java - 状态查询执行器
|
||
✅ RocketRewardClaimCmdExe.java - 奖励领取执行器
|
||
✅ RocketServiceImpl.java - 服务实现
|
||
✅ RocketDailyResetTask.java - 每日重置任务
|
||
✅ RocketClaimExpireTask.java - 过期检查任务
|
||
```
|
||
|
||
### 5.5 Adapter 层
|
||
```
|
||
✅ RocketRestController.java - REST控制器
|
||
```
|
||
|
||
---
|
||
|
||
## 6. 待实现功能清单
|
||
|
||
### 6.1 高优先级 (P0)
|
||
|
||
#### 1. 礼物事件监听
|
||
**文件**: `GiftSendRocketListener.java`
|
||
**位置**: `other-application/src/.../app/listener/`
|
||
**功能**: 监听送礼事件，自动触发能量增加
|
||
```java
|
||
@EventListener
|
||
public void onGiftSend(GiftSendEvent event) {
|
||
RocketEnergyAddCmd cmd = new RocketEnergyAddCmd();
|
||
cmd.setRoomId(event.getRoomId());
|
||
cmd.setUserId(event.getUserId());
|
||
cmd.setGiftGoldValue(event.getGiftGoldValue());
|
||
cmd.setIsLucky(event.getIsLuckyGift());
|
||
cmd.setBizNo("GIFT_" + event.getGiftOrderId());
|
||
rocketService.addEnergy(cmd);
|
||
}
|
||
```
|
||
|
||
#### 2. MySQL 表创建
|
||
**执行SQL**:
|
||
- `rocket_config` 配置表
|
||
- `rocket_reward_claim_log` 领取记录表
|
||
|
||
#### 3. MongoDB 索引创建
|
||
```javascript
|
||
db.room_rocket_status.createIndex(
|
||
{"room_id": 1, "date": 1},
|
||
{unique: true, name: "uk_room_date"}
|
||
)
|
||
db.room_rocket_status.createIndex(
|
||
{"status": 1},
|
||
{name: "idx_status"}
|
||
)
|
||
```
|
||
|
||
#### 4. 奖励发放集成
|
||
**需要**: 调用 `wallet-inner-api`
|
||
**实现**: 在 `RocketRewardClaimCmdExe` 中补充
|
||
```java
|
||
// 注入 Feign Client
|
||
@Autowired
|
||
private WalletGoldClient walletGoldClient;
|
||
|
||
// 发放奖励
|
||
String bizNo = "ROCKET_" + rocketHistoryId + "_" + userId;
|
||
WalletReceiptReqDTO req = new WalletReceiptReqDTO();
|
||
req.setUserId(userId);
|
||
req.setAmount(rewardAmount);
|
||
req.setBizType(WalletBizType.ROCKET_REWARD);
|
||
req.setBizNo(bizNo);
|
||
walletGoldClient.income(req);
|
||
```
|
||
|
||
#### 5. 领取防重实现
|
||
**实现**: MySQL唯一索引 + Redis检查
|
||
```java
|
||
// 查询MySQL
|
||
boolean hasClaimed = rocketRewardLogGateway.existsByRocketAndUser(
|
||
rocketHistoryId, userId
|
||
);
|
||
if (hasClaimed) {
|
||
throw new RuntimeException("您已经领取过奖励了");
|
||
}
|
||
```
|
||
|
||
### 6.2 中优先级 (P1)
|
||
|
||
#### 6. 历史记录保存
|
||
**文件**: `RocketHistoryDocument.java` + `RocketHistoryRepository.java`
|
||
**功能**: 发射后保存完整历史
|
||
|
||
#### 7. WebSocket 推送
|
||
**功能**:
|
||
- 能量更新推送
|
||
- 发射动画推送
|
||
- 领取通知推送
|
||
|
||
#### 8. 奖励配置管理
|
||
**功能**: 后台配置各等级奖励规则
|
||
|
||
#### 9. 排行榜查询
|
||
**文件**: `RocketRankingQryExe.java`
|
||
**功能**: 查询贡献排行榜
|
||
|
||
### 6.3 低优先级 (P2)
|
||
|
||
#### 10. 管理后台接口
|
||
**功能**:
|
||
- 配置管理
|
||
- 数据统计
|
||
- 手动重置
|
||
|
||
#### 11. 数据统计报表
|
||
**功能**: 发射次数、领取人数等统计
|
||
|
||
#### 12. 监控告警
|
||
**功能**: 关键指标监控、异常告警
|
||
|
||
---
|
||
|
||
## 7. 测试用例
|
||
|
||
### 7.1 单元测试
|
||
|
||
```java
|
||
@Test
|
||
public void testEnergyAdd_Normal() {
|
||
// 正常送礼增加能量
|
||
}
|
||
|
||
@Test
|
||
public void testEnergyAdd_Lucky() {
|
||
// 幸运礼物增加能量
|
||
}
|
||
|
||
@Test
|
||
public void testRocketLaunch_AutoTrigger() {
|
||
// 能量满自动发射
|
||
}
|
||
|
||
@Test
|
||
public void testRewardClaim_Contributor() {
|
||
// 贡献者领取奖励
|
||
}
|
||
|
||
@Test
|
||
public void testRewardClaim_Duplicate() {
|
||
// 重复领取防重
|
||
}
|
||
```
|
||
|
||
### 7.2 集成测试场景
|
||
|
||
1. **完整流程**: 送礼 → 发射 → 领取
|
||
2. **并发送礼**: 100人同时送礼
|
||
3. **分布式锁**: 高并发下的锁测试
|
||
4. **过期重置**: 领取过期自动重置
|
||
|
||
---
|
||
|
||
## 8. 部署说明
|
||
|
||
### 8.1 环境要求
|
||
|
||
- MongoDB 4.4+
|
||
- MySQL 8.0+
|
||
- Redis 6.0+
|
||
|
||
### 8.2 配置示例
|
||
|
||
```yaml
|
||
# application.yml
|
||
spring:
|
||
data:
|
||
mongodb:
|
||
uri: mongodb://localhost:27017/likei
|
||
datasource:
|
||
url: jdbc:mysql://localhost:3306/likei
|
||
username: root
|
||
password: password
|
||
|
||
rocket:
|
||
enabled: true
|
||
lucky-bonus-rate: 0.04
|
||
claim-expire-seconds: 60
|
||
```
|
||
|
||
### 8.3 启动顺序
|
||
|
||
1. 启动 MongoDB
|
||
2. 启动 MySQL
|
||
3. 启动 Redis
|
||
4. 执行数据库初始化脚本
|
||
5. 启动应用
|
||
|
||
---
|
||
|
||
## 9. 注意事项
|
||
|
||
### 9.1 幂等性
|
||
- 能量增加使用 `bizNo` 防重
|
||
- 奖励领取使用 MySQL 唯一索引防重
|
||
|
||
### 9.2 并发控制
|
||
- 使用 Redis 分布式锁
|
||
- 锁粒度：房间级别
|
||
|
||
### 9.3 数据一致性
|
||
- MongoDB 保存实时状态
|
||
- MySQL 保存领取记录
|
||
- 通过业务逻辑保证一致性
|
||
|
||
### 9.4 性能优化
|
||
- 热点房间使用 Redis 缓存
|
||
- 批量查询贡献者
|
||
- 异步推送消息
|
||
|
||
---
|
||
d
|
||
## 10. 联系方式
|
||
|
||
**技术支持**: system
|
||
**文档维护**: Leo
|
||
**最后更新**: 2025-01-15
|
||
|
||
---
|
||
|
||
## 附录：快速上手指南
|
||
|
||
### A. 快速测试流程
|
||
|
||
1. **初始化数据库**
|
||
```sql
|
||
-- 执行 MySQL 建表语句
|
||
-- 插入火箭配置数据
|
||
```
|
||
|
||
2. **创建 MongoDB 索引**
|
||
```javascript
|
||
use likei
|
||
db.room_rocket_status.createIndex({"room_id": 1, "date": 1}, {unique: true})
|
||
```
|
||
|
||
3. **启动应用**
|
||
```bash
|
||
cd other-start
|
||
mvn spring-boot:run
|
||
```
|
||
|
||
4. **测试接口**
|
||
```bash
|
||
# 查询状态
|
||
curl "http://localhost:8080/api/rocket/status?roomId=123456"
|
||
|
||
# 手动发射 (测试用)
|
||
curl -X POST "http://localhost:8080/api/rocket/manual-launch?roomId=123456"
|
||
|
||
# 领取奖励
|
||
curl -X POST "http://localhost:8080/api/rocket/claim" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"roomId":123456,"userId":789,"rocketHistoryId":"xxx"}'
|
||
```
|
||
|
||
### B. 常见问题
|
||
|
||
**Q: 如何手动触发能量增加？**
|
||
A: 调用 `RocketService.addEnergy(cmd)` 或监听送礼事件
|
||
|
||
**Q: 如何查看当前火箭状态？**
|
||
A: 访问 MongoDB `room_rocket_status` 集合或调用查询接口
|
||
|
||
**Q: 如何重置火箭？**
|
||
A: 等待每日00:00自动重置，或手动调用重置方法
|
||
|
||
---
|
||
|
||
**祝开发顺利！🚀**
|