新增冒险系统(成功, 编写任务文件)

.tasks/2025-10-29_2_complete-adventure-game.md

@@ -0,0 +1,222 @@
+# 背景
+文件名：2025-10-29_2_complete-adventure-game.md
+创建于：2025-10-29_17:31:02
+创建者：admin
+主分支：main
+任务分支：main
+Yolo模式：Off
+
+# 任务描述
+完善冒险游戏的 `_perform_adventure` 函数，实现冒险系统的时间管理和奖励发放功能。完成后将冒险系统关联到炼金游戏检测中，并将该游戏注册到指令系统中。
+
+## 核心需求
+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` 函数中添加冒险系统帮助信息
+- 原因：实现冒险系统完整功能，包括时间管理、奖励发放、游戏互斥和系统集成
+- 阻碍因素：无
+- 状态：成功
+
+# 详细实施记录
+
+## 文件修改清单
+
+### 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')` 查询状态
+  - 如果存在状态：
+    * 计算剩余时间
+    * 如果已完成：自动删除状态，允许继续
+    * 如果未完成：返回错误消息，显示剩余时间（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` 和 `.冒险` 指令正常工作
+- ✅ 帮助信息：显示在全局帮助中
+
+## 代码质量
+- ✅ 所有语法检查通过
+- ✅ 错误处理完善（参数验证、状态异常处理）
+- ✅ 日志记录完整
+- ✅ 代码风格一致
+- ✅ 不了解释清晰
+
+## 集成完成
+- ✅ 指令解析器：已注册指令映射
+- ✅ 路由处理器：已添加游戏处理分支
+- ✅ 帮助系统：已添加帮助信息
+- ✅ 游戏互斥：已集成到炼金系统
+
+**实施与计划完全匹配**
+
+所有功能已按计划完成，冒险系统已完整集成到WPS Bot Game系统中。
+