kknongchang_2506/app/Module/Task/Docs/任务重置系统_new.md

任务重置系统

1. 概述

任务重置系统是任务模块的核心功能之一，负责根据预定义的规则和时间点重置特定类型的任务，使玩家可以重新完成这些任务并获取奖励。本文档详细描述了任务重置系统的设计、实现和使用方法。

2. 重置类型

任务模块支持以下几种重置类型：

2.1 每日重置（daily）

每日重置的任务会在每天的特定时间点（通常是凌晨0点）自动重置。

特点：

• 重置频率：每24小时一次
• 重置时间：通常为北京时间凌晨0点（可配置）
• 适用场景：日常任务、签到任务等

2.2 每周重置（weekly）

每周重置的任务会在每周的特定时间点（通常是周一凌晨0点）自动重置。

特点：

• 重置频率：每7天一次
• 重置时间：通常为北京时间周一凌晨0点（可配置）
• 适用场景：周常任务、周限制任务等

2.3 每月重置（monthly）

每月重置的任务会在每月的特定时间点（通常是1日凌晨0点）自动重置。

特点：

• 重置频率：每月一次
• 重置时间：通常为北京时间每月1日凌晨0点（可配置）
• 适用场景：月度任务、月限制任务等

2.4 不重置（none）

不重置的任务只能完成一次，永远不会重置。

特点：

• 重置频率：永不重置
• 适用场景：成就任务、一次性任务、主线任务等

3. 重置机制

3.1 重置内容

当任务重置时，以下内容会被重置：

1. 任务状态：将已完成或已领取奖励的任务状态重置为未接取或进行中
2. 任务进度：将任务的完成进度重置为0或初始值
3. 完成时间：清除任务的完成时间
4. 奖励领取状态：清除任务的奖励领取状态

3.2 重置条件

任务重置需要满足以下条件：

1. 任务类型匹配：任务的重置类型必须与当前执行的重置类型匹配
2. 任务状态符合：只有已完成或已领取奖励的任务才会被重置
3. 时间条件满足：当前时间必须达到或超过任务的下一次重置时间

3.3 重置流程

任务重置的基本流程如下：

1. 确定重置类型：根据当前执行的命令确定重置类型（daily、weekly、monthly）
2. 查找符合条件的任务：查找数据库中符合重置条件的任务
3. 记录重置前状态：记录任务重置前的状态，用于日志和回滚
4. 执行重置操作：更新任务状态、进度、完成时间和奖励领取状态
5. 记录重置日志：在task_reset_logs表中记录重置操作的详细信息
6. 触发重置事件：触发TaskResetEvent事件，通知其他模块任务已重置

4. 实现方式

4.1 数据库表

任务重置系统主要涉及以下数据库表：

1. task_tasks：存储任务的基本信息，包括重置类型（reset_type）
2. task_user_tasks：存储用户任务的状态和进度
3. task_user_progress：存储用户任务的详细进度
4. task_reset_logs：记录任务重置的历史记录

4.2 命令行工具

任务重置系统通过以下命令行工具实现自动重置：

4.2.1 每日重置命令

伪代码：

命令：task:reset-daily

功能：重置每日任务

执行流程：
1. 输出开始重置每日任务的提示信息
2. 调用任务重置服务的resetTasks方法，传入'daily'参数
3. 输出重置完成的提示信息，包括受影响的任务数量
4. 返回执行结果

4.2.2 每周重置命令

伪代码：

命令：task:reset-weekly

功能：重置每周任务

执行流程：
1. 输出开始重置每周任务的提示信息
2. 调用任务重置服务的resetTasks方法，传入'weekly'参数
3. 输出重置完成的提示信息，包括受影响的任务数量
4. 返回执行结果

4.2.3 每月重置命令

伪代码：

命令：task:reset-monthly

功能：重置每月任务

执行流程：
1. 输出开始重置每月任务的提示信息
2. 调用任务重置服务的resetTasks方法，传入'monthly'参数
3. 输出重置完成的提示信息，包括受影响的任务数量
4. 返回执行结果

4.3 服务类

任务重置系统的核心逻辑在TaskResetService服务类中实现：

伪代码：

方法：resetTasks(重置类型)

参数：
- 重置类型：daily, weekly, monthly

执行流程：
1. 开始数据库事务
2. 尝试执行以下操作：
   a. 查找符合条件的任务（重置类型匹配且处于激活状态）
   b. 获取任务ID列表
   c. 如果存在符合条件的任务：
      i. 查找用户任务（任务ID匹配且状态为已完成或已领取奖励）
      ii. 计算受影响的任务数量
      iii. 遍历用户任务，执行以下操作：
          - 重置任务状态为进行中
          - 重置任务进度为0
          - 清除完成时间和奖励领取时间
          - 保存更新后的用户任务
          - 重置任务的详细进度
      iv. 创建重置日志记录
      v. 触发任务重置事件
   d. 提交事务
   e. 返回重置结果（成功标志、重置类型、受影响的任务数量、受影响的任务ID列表）
3. 如果发生异常：
   a. 回滚事务
   b. 记录错误日志
   c. 返回失败结果

方法：checkResetNeeded()

功能：检查是否需要重置任务

执行流程：
1. 初始化需要重置的任务类型列表
2. 获取当前时间
3. 检查每日重置：
   a. 获取最后一次每日重置记录
   b. 如果不存在记录或距离上次重置已过去1天以上，将'daily'添加到需要重置的类型列表
4. 检查每周重置：
   a. 获取最后一次每周重置记录
   b. 如果不存在记录或距离上次重置已过去1周以上，将'weekly'添加到需要重置的类型列表
5. 检查每月重置：
   a. 获取最后一次每月重置记录
   b. 如果不存在记录或距离上次重置已过去1个月以上，将'monthly'添加到需要重置的类型列表
6. 返回需要重置的任务类型列表

4.4 事件类

任务重置系统定义了TaskResetEvent事件，用于通知其他模块任务已重置：

伪代码：

事件：TaskResetEvent

属性：
- 重置类型：daily, weekly, monthly
- 重置时间：重置操作执行的时间
- 受影响的任务ID列表：被重置的任务ID数组

构造函数：
1. 接收重置类型、重置时间和受影响的任务ID列表
2. 初始化事件属性

5. 定时任务配置

任务重置系统通过Laravel的调度器（Scheduler）实现定时重置：

伪代码：

定时任务配置：

1. 每日重置任务：
   - 命令：task:reset-daily
   - 执行时间：每天凌晨00:00

2. 每周重置任务：
   - 命令：task:reset-weekly
   - 执行时间：每周一凌晨00:00

3. 每月重置任务：
   - 命令：task:reset-monthly
   - 执行时间：每月1日凌晨00:00

6. 时区处理

任务重置系统需要考虑时区问题，确保在正确的时间点重置任务。系统默认使用北京时间（UTC+8）作为重置时间的基准。

伪代码：

时区设置：

1. 在应用服务提供者中设置默认时区：
   - 设置默认时区为Asia/Shanghai（北京时间）

2. 在重置逻辑中使用统一的时间获取方式：
   - 使用now()函数获取当前时间，确保时区一致

7. 重置日志

任务重置系统会在task_reset_logs表中记录每次重置的详细信息，包括重置类型、重置时间、受影响的任务ID列表和受影响的任务数量。

日志字段说明：

字段	类型	描述
id	int	主键
reset_type	varchar	重置类型（daily, weekly, monthly）
reset_time	timestamp	重置时间
affected_tasks	json	受影响的任务ID列表（JSON格式）
affected_count	int	受影响的任务数量
created_at	timestamp	创建时间

8. 手动重置

除了自动重置外，系统还支持手动重置任务，可以通过命令行工具或后台管理界面触发：

8.1 命令行手动重置

伪代码：

手动重置命令：

1. 重置每日任务：
   命令：php artisan task:reset-daily

2. 重置每周任务：
   命令：php artisan task:reset-weekly

3. 重置每月任务：
   命令：php artisan task:reset-monthly

8.2 后台管理界面手动重置

在后台管理界面中，管理员可以通过以下步骤手动重置任务：

1. 进入任务管理页面
2. 选择"任务重置"选项卡
3. 选择要重置的任务类型（每日、每周、每月）
4. 点击"执行重置"按钮
5. 确认重置操作
6. 系统执行重置并显示结果

9. 常见问题与解决方案

9.1 重置时间不准确

可能的原因：

• 服务器时区设置不正确
• 定时任务未按时执行

解决方案：

• 检查服务器时区设置
• 检查cron任务配置
• 使用监控工具监控定时任务执行情况

9.2 部分任务未重置

可能的原因：

• 任务的重置类型设置不正确
• 任务状态不符合重置条件

解决方案：

• 检查任务的重置类型设置
• 检查任务的状态
• 查看重置日志，确认重置操作是否成功执行

9.3 重置后数据不一致

可能的原因：

• 重置过程中发生异常
• 数据库事务未正确提交或回滚

解决方案：

• 检查错误日志
• 确保重置操作在事务中执行
• 实现数据一致性检查机制

10. 最佳实践

1. 使用事务：在重置操作中使用数据库事务，确保数据一致性
2. 记录详细日志：记录每次重置的详细信息，便于问题排查
3. 设置监控：监控重置任务的执行情况，及时发现并解决问题
4. 定期备份：定期备份任务数据，防止重置操作导致数据丢失
5. 渐进式重置：对于大量任务，采用分批重置的方式，避免系统负载过高
6. 用户通知：在任务重置后通知用户，提醒他们可以重新完成任务

11. 参考资料

• Laravel 调度器文档
• Laravel 事件系统文档
• 任务模块数据库设计
• 任务模块事件系统

12. 更新历史

日期	版本	更新内容
2023-06-15	1.0	初始版本
2023-06-17	1.1	移除具体代码实现，改用伪代码描述