# 任务模块

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

## 目录

1. [模块概述](#1-模块概述)
2. [核心功能](#2-核心功能)
3. [架构设计](#3-架构设计)
4. [数据结构](#4-数据结构)
5. [API接口](#5-api接口)
6. [与其他模块集成](#6-与其他模块集成)
7. [部署与配置](#7-部署与配置)
8. [开发指南](#8-开发指南)
9. [常见问题](#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** - 任务重置日志表

详细的数据库设计请参考 [数据库设计文档](./Docs/数据库设计.md)。

## 5. API接口（废弃，没有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接口设计文档](./Docs/API接口设计.md)。

## 6. 与其他模块集成

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

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

详细的集成方式请参考 [与其他模块集成文档](./Docs/与其他模块集成.md)。

## 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` 命令诊断重置状态
- 验证任务的重置类型设置
- 检查任务的下次重置时间是否正确
- 确保系统时区设置正确