删除doc文件
This commit is contained in:
tianfeng
parent
c077c563eb
commit
18209b32ae
@ -1,622 +0,0 @@
|
||||
# 🚀 语聊房火箭系统 - 完整需求文档
|
||||
|
||||
---
|
||||
|
||||
## 📋 文档信息
|
||||
|
||||
| 项目 | 内容 |
|
||||
|-----|------|
|
||||
| **文档名称** | 语聊房火箭系统需求文档 |
|
||||
| **版本** | 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自动重置，或手动调用重置方法
|
||||
|
||||
---
|
||||
|
||||
**祝开发顺利！🚀**
|
||||
Loading…
x
Reference in New Issue
Block a user