260 lines
11 KiB
Markdown
260 lines
11 KiB
Markdown
# 背景
|
||
文件名：2025-10-29_2_complete-adventure-game.md
|
||
创建于：2025-10-29_17:31:02
|
||
创建者：admin
|
||
主分支：main
|
||
任务分支：main
|
||
Yolo模式：Off
|
||
|
||
# 任务描述
|
||
完善冒险游戏的 `_perform_adventure` 函数，实现冒险系统的时间管理和奖励发放功能。完成后将冒险系统关联到炼金游戏检测中，并将该游戏注册到指令系统中。
|
||
|
||
## 关联影响
|
||
本次更新同时也修改了炼金系统（`games/alchemy.py`），添加了冒险状态检测功能，实现游戏互斥机制。由于炼金系统开发时没有创建独立的任务文件，本次修改记录在本任务文件中。如需追踪炼金系统的完整变更历史，可参考本任务文件的"炼金游戏集成"部分。
|
||
|
||
## 核心需求
|
||
1. 完善 `_perform_adventure` 函数，实现三种状态处理：
|
||
- 检查用户是否已有未完成的冒险
|
||
- 如果冒险已完成，发放奖励并清除状态
|
||
- 如果没有冒险状态，开始新的冒险
|
||
2. 修复 `_draw_prize` 函数，支持三元组奖品池结构
|
||
3. 在炼金游戏中添加冒险状态检测，阻止冒险期间进行炼金
|
||
4. 在指令解析器中注册冒险指令（`.adventure` 和 `.冒险`）
|
||
5. 在路由处理器中注册冒险游戏
|
||
6. 在帮助系统中添加冒险游戏的帮助信息
|
||
|
||
# 项目概览
|
||
|
||
## 项目结构
|
||
```
|
||
WPSBotGame/
|
||
├── games/
|
||
│ ├── adventure.py # 冒险系统游戏（本次修改）
|
||
│ ├── alchemy.py # 炼金系统游戏（添加冒险检测）
|
||
│ └── base.py # 游戏基类（添加帮助信息）
|
||
├── routers/
|
||
│ └── callback.py # Callback路由处理（注册冒险游戏）
|
||
└── utils/
|
||
└── parser.py # 指令解析（注册冒险指令）
|
||
```
|
||
|
||
# 分析
|
||
|
||
## 当前状态
|
||
1. `games/adventure.py` 中 `_perform_adventure` 函数只有框架，所有逻辑都是 `if False: pass`
|
||
2. `_draw_prize` 函数期望4元组奖品池，但实际奖品池是3元组 `(权重, 倍率, 描述)`
|
||
3. 炼金游戏中没有检测用户是否在冒险中
|
||
4. 指令系统未注册冒险游戏
|
||
5. 帮助系统未包含冒险游戏说明
|
||
|
||
## 关键技术点
|
||
1. **状态管理**：使用 `game_states` 表存储冒险状态，使用 `chat_id=0` 作为用户级标识
|
||
2. **时间计算**：使用 Unix 时间戳计算冒险开始和结束时间，以分钟为单位
|
||
3. **奖品池结构**：修复为支持三元组格式 `(权重, 倍率, 描述)`
|
||
4. **游戏互斥**：冒险期间禁止炼金操作
|
||
5. **指令注册**：完整集成到指令解析和路由系统
|
||
|
||
# 提议的解决方案
|
||
|
||
## 方案概述
|
||
1. **完善冒险核心逻辑**：
|
||
- 使用 `game_states` 表存储状态：`{'start_time': timestamp, 'cost_time': minutes}`
|
||
- 实现三种情况的状态判断和处理
|
||
- 时间计算：`end_time = start_time + cost_time * 60`
|
||
2. **修复奖品池处理**：
|
||
- 修改 `_draw_prize` 支持三元组：`(权重, 倍率, 描述)`
|
||
- 返回格式：`{'value': 倍率, 'description': 描述}`
|
||
3. **炼金游戏集成**：
|
||
- 在 `_perform_alchemy` 开始时检查冒险状态
|
||
- 冒险进行中时阻止操作并显示剩余时间
|
||
- 冒险已完成时自动清理状态
|
||
4. **系统注册**：
|
||
- 在 `parser.py` 中添加指令映射
|
||
- 在 `callback.py` 中添加游戏处理器
|
||
- 在 `base.py` 中添加帮助信息
|
||
|
||
# 任务进度
|
||
|
||
## 2025-10-29_17:31:02
|
||
- 已修改：
|
||
- games/adventure.py（完善 `_perform_adventure` 函数，修复 `_draw_prize` 函数，添加 time 导入）
|
||
- games/alchemy.py（添加冒险状态检测，添加 time 导入）
|
||
- utils/parser.py（添加 `.adventure` 和 `.冒险` 指令映射）
|
||
- routers/callback.py（添加冒险游戏处理分支）
|
||
- games/base.py（在帮助系统中添加冒险游戏说明）
|
||
- 更改：
|
||
1. **冒险系统核心功能**：
|
||
- 添加 `import time` 模块
|
||
- 修改 `handle` 方法传递 `chat_id` 参数
|
||
- 完善 `_perform_adventure` 方法，实现完整的状态管理逻辑：
|
||
* 参数验证：确保 `cost_time >= 1`
|
||
* 状态查询：使用 `chat_id=0` 查询用户级冒险状态
|
||
* 未完成冒险：计算并显示剩余时间（分钟和秒）
|
||
* 已完成冒险：发放奖励（倍率 × 消耗时间），清除状态
|
||
* 新冒险：创建状态并保存，显示预计完成时间
|
||
- 修复 `_draw_prize` 方法支持三元组奖品池
|
||
2. **炼金游戏集成**：
|
||
- 添加 `import time` 模块
|
||
- 在 `_perform_alchemy` 方法开始处添加冒险状态检测
|
||
- 冒险进行中时返回错误提示并显示剩余时间
|
||
- 冒险已完成时自动清理状态，允许继续炼金
|
||
3. **指令系统注册**：
|
||
- 在 `utils/parser.py` 的 `COMMAND_MAP` 中添加 `.adventure` 和 `.冒险` 映射
|
||
- 在 `routers/callback.py` 的 `handle_command` 函数中添加冒险游戏处理分支
|
||
4. **帮助系统更新**：
|
||
- 在 `games/base.py` 的 `get_help_message` 函数中添加冒险系统帮助信息
|
||
- 原因：实现冒险系统完整功能，包括时间管理、奖励发放、游戏互斥和系统集成
|
||
- 阻碍因素：无
|
||
- 状态：成功
|
||
|
||
## 2025-10-30_00:00:00
|
||
- 已修改：
|
||
- games/adventure.py（新增放弃指令分支，新增 `_abandon_adventure`，更新帮助）
|
||
- games/base.py（在全局帮助中添加放弃用法）
|
||
- 更改：
|
||
1. 新增冒险放弃功能：
|
||
- 支持指令：`.adventure abandon`、`.adventure 放弃`
|
||
- 结算规则：最低倍率 × 已冒险分钟（向下取整，至少1分钟）
|
||
- 发放奖励后删除状态
|
||
2. 帮助信息更新：
|
||
- 本地帮助与全局帮助均加入放弃用法说明
|
||
- 原因：允许用户在冒险过程中主动放弃并按最低倍率获得奖励
|
||
- 阻碍因素：无
|
||
- 状态：成功
|
||
|
||
## 2025-10-31_10:27:59
|
||
- 已修改：
|
||
- games/alchemy.py（修复冒险任务完成后自动删除状态导致奖励丢失的bug）
|
||
- 更改：
|
||
1. **Bug修复**：修复冒险任务完成后奖励丢失问题
|
||
- **问题**：在 `_perform_alchemy` 中，当检测到冒险任务已完成时，代码会自动删除冒险状态（`self.db.delete_game_state`），但没有发放奖励，导致用户奖励丢失
|
||
- **修复**：移除自动删除逻辑，改为提示用户先使用 `.adventure` 回收奖励
|
||
- **修改前**：冒险完成后自动删除状态，允许炼金（导致奖励丢失）
|
||
- **修改后**：冒险完成后提示用户先回收奖励，不允许炼金，确保奖励只能通过 `.adventure` 命令回收
|
||
2. **行为变更**：
|
||
- 冒险进行中：提示剩余时间，不允许炼金（保持不变）
|
||
- 冒险已完成：提示先回收奖励，不允许炼金（修复后）
|
||
- 用户使用 `.adventure`：发放奖励并删除状态（保持不变）
|
||
- 状态已删除：可以正常炼金（保持不变）
|
||
- 原因：修复冒险任务完成后自动删除状态导致奖励丢失的严重bug，确保用户必须先主动回收奖励才能继续其他操作
|
||
- 阻碍因素：无
|
||
- 状态：成功
|
||
|
||
# 详细实施记录
|
||
|
||
## 文件修改清单
|
||
|
||
### 1. games/adventure.py
|
||
- **添加导入**：`import time`
|
||
- **修改方法签名**：
|
||
- `handle`：传递 `chat_id` 给 `_perform_adventure`
|
||
- `_perform_adventure`：添加 `chat_id` 参数，改为 `async`
|
||
- **完善 `_perform_adventure` 逻辑**：
|
||
- 参数验证：`cost_time >= 1`
|
||
- 使用 `get_game_state(0, user_id, 'adventure')` 查询状态
|
||
- 实现三种状态处理：
|
||
1. 未完成：计算剩余时间，格式化显示（X分Y秒）
|
||
2. 已完成：执行抽奖，发放奖励（倍率 × 消耗时间），删除状态
|
||
3. 新冒险：创建状态数据，保存到数据库，计算预计完成时间
|
||
- 异常处理：捕获状态数据异常，自动清理损坏状态
|
||
- **修复 `_draw_prize` 方法**：
|
||
- 修改循环：`for weight, multiplier, description in prize_pool:`
|
||
- 返回值：`{'value': multiplier, 'description': description}`
|
||
- 兜底返回：使用 `prize_pool[0][1]` 和 `prize_pool[0][2]`
|
||
|
||
### 2. games/alchemy.py
|
||
- **添加导入**：`import time`
|
||
- **在 `_perform_alchemy` 中添加冒险检测**：
|
||
- 使用 `get_game_state(0, user_id, 'adventure')` 查询状态
|
||
- 如果存在状态：
|
||
* 计算剩余时间
|
||
* 如果已完成：提示用户先使用 `.adventure` 回收奖励，不允许炼金（2025-10-31修复：避免奖励丢失，移除自动删除逻辑）
|
||
* 如果未完成：返回错误消息，显示剩余时间（X分Y秒）
|
||
- 异常处理：捕获状态数据异常，自动清理损坏状态
|
||
|
||
### 3. utils/parser.py
|
||
- **在 `COMMAND_MAP` 中添加**：
|
||
```python
|
||
# 冒险系统
|
||
'.adventure': 'adventure',
|
||
'.冒险': 'adventure',
|
||
```
|
||
|
||
### 4. routers/callback.py
|
||
- **在 `handle_command` 函数中添加**：
|
||
```python
|
||
# 冒险系统
|
||
if game_type == 'adventure':
|
||
from games.adventure import AdventureGame
|
||
game = AdventureGame()
|
||
return await game.handle(command, chat_id, user_id)
|
||
```
|
||
|
||
### 5. games/base.py
|
||
- **在 `get_help_message` 函数中添加**：
|
||
```markdown
|
||
### ⚡️ 冒险系统
|
||
- `.adventure` - 消耗1分钟进行冒险
|
||
- `.冒险` - 消耗1分钟进行冒险
|
||
- `.adventure 5` - 消耗5分钟进行冒险
|
||
- `.adventure help` - 查看冒险帮助
|
||
```
|
||
|
||
## 关键实现细节
|
||
|
||
### 状态数据结构
|
||
```python
|
||
state_data = {
|
||
'start_time': int(time.time()), # Unix时间戳（秒）
|
||
'cost_time': 5 # 消耗时间（分钟）
|
||
}
|
||
```
|
||
|
||
### 时间计算逻辑
|
||
- 开始时间：`start_time = int(time.time())`
|
||
- 结束时间：`end_time = start_time + cost_time * 60`
|
||
- 剩余时间：`remaining_seconds = end_time - current_time`
|
||
- 剩余时间显示：`remaining_minutes = remaining_seconds // 60`，`remaining_secs = remaining_seconds % 60`
|
||
|
||
### 奖励计算
|
||
- 抽奖获取倍率：`reward = self._draw_prize(prize_pool)`
|
||
- 奖励积分：`reward_points = int(reward['value'] * cost_time)`
|
||
- 发放奖励：`self.db.add_points(user_id, reward_points, "adventure", "冒险奖励")`
|
||
|
||
### 游戏互斥机制
|
||
- 炼金前检查：查询冒险状态
|
||
- 如果冒险进行中：返回错误，显示剩余时间
|
||
- 如果冒险已完成：提示用户先使用 `.adventure` 回收奖励，不允许炼金（修复后：确保奖励不会丢失）
|
||
- 状态异常：自动清理，允许继续操作
|
||
|
||
# 最终审查
|
||
|
||
## 功能验证
|
||
- ✅ 冒险开始：用户可以指定时间（分钟）开始冒险
|
||
- ✅ 冒险进行中：显示剩余时间，阻止重复开始
|
||
- ✅ 冒险完成：自动发放奖励，清除状态
|
||
- ✅ 时间计算：正确计算剩余时间和完成时间
|
||
- ✅ 奖励发放：根据倍率和消耗时间计算奖励积分
|
||
- ✅ 游戏互斥：冒险期间阻止炼金操作
|
||
- ✅ 指令注册：`.adventure` 和 `.冒险` 指令正常工作
|
||
- ✅ 帮助信息：显示在全局帮助中
|
||
- ✅ 冒险放弃：`.adventure abandon` / `.adventure 放弃` 按最低倍率结算已冒险分钟并清理状态
|
||
|
||
## 代码质量
|
||
- ✅ 所有语法检查通过
|
||
- ✅ 错误处理完善（参数验证、状态异常处理）
|
||
- ✅ 日志记录完整
|
||
- ✅ 代码风格一致
|
||
- ✅ 不了解释清晰
|
||
|
||
## 集成完成
|
||
- ✅ 指令解析器：已注册指令映射
|
||
- ✅ 路由处理器：已添加游戏处理分支
|
||
- ✅ 帮助系统：已添加帮助信息
|
||
- ✅ 游戏互斥：已集成到炼金系统
|
||
|
||
**实施与计划完全匹配**
|
||
|
||
所有功能已按计划完成，冒险系统已完整集成到WPS Bot Game系统中。
|
||
|