kknongchang_2506/app/Module/Task

任务模块

开心农场系统 - 任务系统，管理游戏内各类任务的创建、分配、完成和奖励发放

目录

1. 模块概述
2. 核心功能
3. 架构设计
4. 数据结构
5. API接口
6. 与其他模块集成
7. 部署与配置
8. 开发指南
9. 常见问题

1. 模块概述

任务模块是开心农场系统的核心功能模块之一，负责管理游戏中的各类任务，包括日常任务、成就任务、活动任务等。该模块提供任务的创建、分配、进度跟踪、完成验证和奖励发放等功能，通过任务系统引导玩家体验游戏内容，提高用户活跃度和留存率。

2. 核心功能

• 多类型任务管理：支持日常、周常、成就、活动、新手引导、团队等多种任务类型
• 任务进度跟踪：自动跟踪玩家的任务进度，支持多种任务目标类型
• 任务奖励系统：支持多种奖励类型，与物品系统无缝集成
• 任务重置机制：支持不同周期的任务重置（每日、每周、每月），采用被动重置机制
• 任务通知：任务状态变更通知，任务过期提醒等

3. 架构设计

任务模块采用分层架构设计，遵循"服务是对外的，Logic是内部的"原则：

app/Module/Task/
├── AdminControllers/        # 后台管理控制器
│   ├── Helper/              # 控制器辅助类
│   ├── Actions/             # 控制器动作类
│   └── LazyRenderable/      # 懒加载渲染类
├── Commands/                # 命令行工具
├── Controllers/             # 前端API控制器
├── Databases/               # 数据库相关文件
│   └── GenerateSql/         # 数据库创建脚本
├── Dtos/                    # 数据传输对象
├── Enums/                   # 枚举类型定义
├── Events/                  # 事件类
├── Exceptions/              # 异常类
├── Listeners/               # 事件监听器
├── Logics/                  # 业务逻辑类
├── Models/                  # 数据模型
├── Providers/               # 服务提供者
├── Repositorys/             # 数据仓库
├── Services/                # 服务类
└── Docs/                    # 模块文档

4. 数据结构

任务模块包含以下核心数据表：

1. task_categories - 任务分类表
2. task_tasks - 任务定义表
3. task_user_tasks - 用户任务关联表
4. task_user_progress - 用户任务进度表
5. task_completion_logs - 任务完成日志表
6. task_reward_logs - 任务奖励发放日志表
7. task_reset_logs - 任务重置日志表

详细的数据库设计请参考 数据库设计文档。

5. API接口

任务模块提供以下主要API接口：

• 获取任务列表 - GET /api/task/list
• 获取任务详情 - GET /api/task/detail
• 接取任务 - POST /api/task/accept
• 放弃任务 - POST /api/task/abandon
• 完成任务 - POST /api/task/complete
• 领取任务奖励 - POST /api/task/claim-reward
• 获取任务进度 - GET /api/task/progress

详细的API接口设计请参考 API接口设计文档。

6. 与其他模块集成

任务模块与以下模块进行集成：

• 用户模块：获取用户信息，验证用户等级和权限
• 物品模块：发放任务奖励，验证物品使用情况
• 农场模块：监听种植、收获等事件，更新任务进度
• 团队模块：任务完成后计算团队收益，支持团队任务
• 宠物模块：监听宠物相关事件，更新任务进度
• 通知模块：发送任务相关通知

详细的集成方式请参考 与其他模块集成文档。

7. 部署与配置

7.1 安装步骤

1. 确保已安装Laravel框架和相关依赖
2. 将任务模块代码复制到项目的app/Module/Task目录下
3. 执行数据库迁移：php artisan migrate
4. 注册服务提供者：在config/app.php中添加App\Module\Task\Providers\TaskServiceProvider::class
5. 发布配置文件：php artisan vendor:publish --tag=task-config

7.2 配置选项

任务模块的主要配置选项位于config/task.php文件中：

• reset_time - 任务重置时间配置
• notification_enabled - 是否启用任务通知
• expiration_reminder_hours - 任务过期提醒时间（小时）
• log_retention_days - 日志保留天数

7.3 命令行工具

任务模块提供以下命令行工具：

• php artisan task:reset-check - 任务重置检查命令，用于诊断任务重置状态
• php artisan task:check-progress - 检查任务进度命令，自动完成满足条件的任务
• php artisan task:clean-expired - 清理过期任务命令，清理已过期和超时的任务

8. 开发指南

8.1 添加新任务类型

1. 在TASK_TYPE枚举中添加新的任务类型
2. 在TaskService中实现相应的验证和处理逻辑
3. 在后台管理界面添加新任务类型的配置选项

8.2 添加新目标类型

1. 在TARGET_TYPE枚举中添加新的目标类型
2. 创建相应的事件监听器，监听相关事件
3. 在TaskConditionService::updateProgressCondition方法中添加新目标类型的处理逻辑

8.3 自定义任务奖励

1. 在REWARD_TYPE枚举中添加新的奖励类型
2. 在TaskRewardService中添加新奖励类型的处理方法
3. 更新前端界面，显示新的奖励类型

8.4 任务重置机制

任务模块采用被动重置机制，其工作原理如下：

1. 当用户访问或使用任务时，系统会检查任务是否需要重置
2. 重置检查由TaskProgressService::checkAndResetTask方法实现
3. 如果任务需要重置，系统会自动重置任务状态和进度
4. 重置记录会保存在task_reset_logs表中

这种机制相比于主动重置（定时任务）的优点是：

• 减少系统资源消耗，只在需要时才重置
• 避免大量任务同时重置导致的性能问题
• 更灵活的重置时间控制，不受定时任务执行时间的限制

9. 常见问题

9.1 任务进度不更新

可能的原因：

• 事件未正确触发或监听
• 任务目标参数配置错误
• 用户任务状态不正确

解决方案：

• 检查事件监听器是否正确注册
• 验证任务目标参数是否匹配
• 检查用户任务状态是否为"进行中"

9.2 任务奖励发放失败

可能的原因：

• 物品模块接口调用失败
• 数据库事务回滚
• 奖励配置错误

解决方案：

• 检查物品模块日志
• 验证奖励JSON格式是否正确
• 确保数据库连接稳定

9.3 任务重置未生效

可能的原因：

• 重置类型配置错误
• 任务状态不正确
• 下次重置时间计算错误
• 被动重置检查逻辑异常

解决方案：

• 使用 php artisan task:reset-check 命令诊断重置状态
• 验证任务的重置类型设置
• 检查任务的下次重置时间是否正确
• 确保系统时区设置正确