kknongchang_2506/app/Module/Task/Docs/数据库设计.md

任务模块数据库设计

1. 数据库表概览

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

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

2. 表结构详细设计

2.1 任务分类表 (task_categories)

存储任务的分类信息，用于对任务进行分组和管理。

字段名	类型	允许空	默认值	说明
id	int	否	自增	主键
name	varchar(100)	否	-	分类名称
code	varchar(50)	否	-	分类编码（唯一）
description	varchar(255)	是	NULL	分类描述
sort_order	int	否	0	排序顺序
created_at	timestamp	是	NULL	创建时间
updated_at	timestamp	是	NULL	更新时间

索引：

• PRIMARY KEY (id)
• UNIQUE KEY idx_code (code)

2.2 任务定义表 (task_tasks)

存储任务的基本定义信息，包括任务名称、描述、奖励等。目标相关字段已拆分到任务达成条件表。

字段名	类型	允许空	默认值	说明
id	int	否	自增	主键
category_id	int	否	-	任务分类ID，外键关联task_categories表
name	varchar(100)	否	-	任务名称
description	varchar(500)	是	NULL	任务描述
type	varchar(20)	否	-	任务类型（daily, weekly, achievement, event, tutorial, team）
rewards	json	否	-	奖励内容（JSON格式）
prerequisite_tasks	json	是	NULL	前置任务ID（JSON格式）
level_required	int	否	0	所需等级
time_limit	int	是	NULL	时间限制（秒，NULL表示无限制）
reset_type	varchar(20)	否	'none'	重置类型（none, daily, weekly, monthly）
is_active	tinyint	否	1	是否激活（0:否, 1:是）
start_time	timestamp	是	NULL	开始时间（NULL表示立即开始）
end_time	timestamp	是	NULL	结束时间（NULL表示永不结束）
created_at	timestamp	是	NULL	创建时间
updated_at	timestamp	是	NULL	更新时间

索引：

• PRIMARY KEY (id)
• KEY idx_category (category_id)
• KEY idx_type (type)
• KEY idx_active_time (is_active, start_time, end_time)

2.3 用户任务关联表 (task_user_tasks)

存储用户与任务的关联信息，包括任务状态、进度、完成时间等。

字段名	类型	允许空	默认值	说明
id	int	否	自增	主键
user_id	int	否	-	用户ID
task_id	int	否	-	任务ID，外键关联task_tasks表
status	tinyint	否	0	状态（0:未接取, 1:进行中, 2:已完成, 3:已领取奖励, 4:已失败, 5:已过期）
progress	int	否	0	当前进度
completed_at	timestamp	是	NULL	完成时间
rewarded_at	timestamp	是	NULL	奖励发放时间
expire_at	timestamp	是	NULL	过期时间
created_at	timestamp	是	NULL	创建时间
updated_at	timestamp	是	NULL	更新时间

索引：

• PRIMARY KEY (id)
• UNIQUE KEY idx_user_task (user_id, task_id)
• KEY idx_user_status (user_id, status)
• KEY idx_task (task_id)
• KEY idx_expire (expire_at)

2.4 任务条件表 (task_conditions)

定义系统中所有可用的条件类型，每种条件类型对应一个处理器类，负责验证和更新该类型条件的进度。

字段名	类型	允许空	默认值	说明
id	int	否	自增	主键
code	varchar(50)	否	-	条件代码（唯一），如'login', 'plant', 'harvest'
name	varchar(100)	否	-	条件名称，如'登录游戏', '种植作物', '收获作物'
description	varchar(255)	是	NULL	条件描述
param_schema	json	是	NULL	参数模式，定义此条件需要的参数及其类型
handler_class	varchar(255)	是	NULL	处理此条件的类名
is_active	tinyint	否	1	是否激活（0:否, 1:是）
created_at	timestamp	是	NULL	创建时间
updated_at	timestamp	是	NULL	更新时间

索引：

• PRIMARY KEY (id)
• UNIQUE KEY idx_code (code)

2.5 任务达成条件表 (task_achievement_conditions)

关联任务和具体的条件，定义了完成任务需要满足的条件。一个任务可以有多个条件，通过这个表可以实现复杂的任务逻辑。条件分为两种类型：前置条件和进度条件。

字段名	类型	允许空	默认值	说明
id	int	否	自增	主键
task_id	int	否	-	任务ID，外键关联task_tasks表
condition_id	int	否	-	条件ID，外键关联task_conditions表
condition_type	varchar(20)	否	'progress'	条件类型（'prerequisite'=前置条件，'progress'=进度条件）
target_value	int	否	1	目标值，如需要完成的次数
params	json	是	NULL	条件参数，如特定物品ID、特定作物ID等
operator	varchar(10)	否	'='	运算符，如'=', '>=', '<='
sort_order	int	否	0	排序顺序，用于多条件任务
is_required	tinyint	否	1	是否必须满足此条件（0:否, 1:是）
created_at	timestamp	是	NULL	创建时间
updated_at	timestamp	是	NULL	更新时间

索引：

• PRIMARY KEY (id)
• KEY idx_task_id (task_id)
• KEY idx_condition_id (condition_id)
• KEY idx_task_condition (task_id, condition_id)
• KEY idx_condition_type (condition_type)

2.6 用户任务进度表 (task_user_progress)

存储用户任务的详细进度信息，关联到具体的任务达成条件。

字段名	类型	允许空	默认值	说明
id	int	否	自增	主键
user_id	int	否	-	用户ID
task_id	int	否	-	任务ID，外键关联task_tasks表
achievement_condition_id	int	否	-	达成条件ID，外键关联task_achievement_conditions表
current_value	int	否	0	当前值
last_update_time	timestamp	是	NULL	最后更新时间
created_at	timestamp	是	NULL	创建时间
updated_at	timestamp	是	NULL	更新时间

索引：

• PRIMARY KEY (id)
• UNIQUE KEY idx_user_task_condition (user_id, task_id, achievement_condition_id)
• KEY idx_user_task (user_id, task_id)
• KEY idx_achievement_condition (achievement_condition_id)

2.7 任务完成日志表 (task_completion_logs)

记录用户完成任务的详细信息，用于审计和数据分析。

字段名	类型	允许空	默认值	说明
id	int	否	自增	主键
user_id	int	否	-	用户ID
task_id	int	否	-	任务ID，外键关联task_tasks表
completed_at	timestamp	否	-	完成时间
time_spent	int	是	NULL	完成耗时（秒）
ip_address	varchar(45)	是	NULL	IP地址
device_info	varchar(255)	是	NULL	设备信息
created_at	timestamp	是	NULL	创建时间

索引：

• PRIMARY KEY (id)
• KEY idx_user (user_id)
• KEY idx_task (task_id)
• KEY idx_completed_at (completed_at)

2.8 任务奖励发放日志表 (task_reward_logs)

记录任务奖励的发放情况，包括奖励内容、发放时间等。

字段名	类型	允许空	默认值	说明
id	int	否	自增	主键
user_id	int	否	-	用户ID
task_id	int	否	-	任务ID，外键关联task_tasks表
user_task_id	int	否	-	用户任务ID，外键关联task_user_tasks表
rewards	json	否	-	奖励内容（JSON格式）
rewarded_at	timestamp	否	-	奖励发放时间
ip_address	varchar(45)	是	NULL	IP地址
device_info	varchar(255)	是	NULL	设备信息
created_at	timestamp	是	NULL	创建时间

索引：

• PRIMARY KEY (id)
• KEY idx_user (user_id)
• KEY idx_task (task_id)
• KEY idx_user_task (user_task_id)
• KEY idx_rewarded_at (rewarded_at)

2.9 任务重置日志表 (task_reset_logs)

记录任务重置的情况，包括重置类型、重置时间、影响的任务数等。

字段名	类型	允许空	默认值	说明
id	int	否	自增	主键
reset_type	varchar(20)	否	-	重置类型（daily, weekly, monthly）
reset_time	timestamp	否	-	重置时间
affected_tasks	json	是	NULL	受影响的任务ID列表（JSON格式）
affected_count	int	否	0	受影响的任务数量
created_at	timestamp	是	NULL	创建时间

索引：

• PRIMARY KEY (id)
• KEY idx_reset_type (reset_type)
• KEY idx_reset_time (reset_time)

3. 数据关系

3.1 主要关系图

task_categories 1 --< task_tasks
task_conditions 1 --< task_achievement_conditions
task_tasks 1 --< task_achievement_conditions
task_tasks 1 --< task_user_tasks
task_achievement_conditions 1 --< task_user_progress
task_user_tasks 1 --< task_completion_logs
task_user_tasks 1 --< task_reward_logs

3.2 关系说明

1. 一个任务分类可以包含多个任务
2. 一个条件类型可以用于多个任务达成条件
3. 一个任务可以有多个达成条件
4. 一个任务可以被多个用户接取
5. 一个任务达成条件可以有多个用户进度记录
6. 一个用户任务完成后会生成一条完成日志
7. 一个用户任务领取奖励后会生成一条奖励发放日志

4. JSON字段结构

4.1 条件参数模式 (param_schema)

{
  "properties": {
    "seed_ids": {
      "type": "array",
      "items": {"type": "integer"},
      "description": "指定种子ID列表"
    },
    "land_type": {
      "type": "integer",
      "description": "指定土地类型"
    },
    "min_level": {
      "type": "integer",
      "description": "最低等级要求"
    }
  }
}

4.2 奖励内容 (rewards)

{
  "items": [
    {"item_id": 1001, "quantity": 10},
    {"item_id": 1002, "quantity": 5}
  ],
  "experience": 100,
  "special_rewards": {
    "type": "unlock_feature",
    "feature_id": 3
  }
}

4.3 前置任务 (prerequisite_tasks)

{
  "required_tasks": [101, 102],     // 必须完成的任务ID
  "optional_tasks": [103, 104],     // 可选完成的任务ID
  "min_optional_count": 1           // 最少需要完成的可选任务数
}

5. 索引设计考虑

5.1 高频查询场景

1. 获取用户当前进行中的任务

   • 使用 idx_user_status 索引优化

2. 获取特定类型的可用任务

   • 使用 idx_type 和 idx_active_time 索引优化

3. 检查用户是否完成特定任务

   • 使用 idx_user_task 索引优化

4. 获取即将过期的任务

   • 使用 idx_expire 索引优化

5.2 写入优化

1. 任务进度更新是高频操作，使用 task_user_progress 表分担 task_user_tasks 表的写入压力

2. 日志表（task_completion_logs, task_reward_logs）可考虑按时间分区，提高写入性能

6. 数据迁移与升级策略

1. 使用Laravel迁移文件管理表结构
2. 版本化迁移文件，支持回滚
3. 大型结构变更时考虑分步迁移，减少对系统的影响

7. 条件处理器设计

每种条件类型都有一个对应的处理器类，负责验证和更新该类型条件的进度。

7.1 条件处理器接口

interface ConditionHandlerInterface
{
    /**
     * 验证事件是否满足条件
     *
     * @param array $event 事件数据
     * @param array $params 条件参数
     * @return bool
     */
    public function matches(array $event, array $params): bool;

    /**
     * 计算事件对条件进度的贡献值
     *
     * @param array $event 事件数据
     * @param array $params 条件参数
     * @return int
     */
    public function calculateProgress(array $event, array $params): int;

    /**
     * 检查条件是否已完成
     *
     * @param int $currentValue 当前值
     * @param int $targetValue 目标值
     * @param string $operator 运算符
     * @return bool
     */
    public function isCompleted(int $currentValue, int $targetValue, string $operator): bool;
}

7.2 基础条件处理器

abstract class BaseConditionHandler implements ConditionHandlerInterface
{
    /**
     * 检查条件是否已完成
     *
     * @param int $currentValue 当前值
     * @param int $targetValue 目标值
     * @param string $operator 运算符
     * @return bool
     */
    public function isCompleted(int $currentValue, int $targetValue, string $operator): bool
    {
        switch ($operator) {
            case '=':
                return $currentValue == $targetValue;
            case '>=':
                return $currentValue >= $targetValue;
            case '>':
                return $currentValue > $targetValue;
            case '<=':
                return $currentValue <= $targetValue;
            case '<':
                return $currentValue < $targetValue;
            default:
                return false;
        }
    }
}

8. 任务进度更新流程

8.1 事件触发

1. 用户执行操作（如登录、种植、收获等）
2. 系统触发相应的事件

8.2 条件匹配

1. 任务服务接收事件
2. 查找与事件相关的所有活跃任务的进度条件
3. 对每个条件，调用对应的处理器验证事件是否匹配

8.3 进度更新

1. 对于匹配的条件，计算进度贡献值
2. 更新用户任务进度表中的当前值
3. 检查条件是否已完成

8.4 任务完成检查

1. 当进度条件完成时，检查任务的所有必要的进度条件是否都已完成
2. 如果所有必要的进度条件都已完成，将任务标记为已完成
3. 触发任务完成事件

9. 前置条件与进度条件的区别

9.1 前置条件

前置条件是指用户必须满足才能接取任务的条件，但不计入任务的完成进度。前置条件的特点：

1. 检查时机：在用户接取任务时检查
2. 完成状态：只有“满足/不满足”两种状态，没有进度概念
3. 典型例子：
   • 用户等级要求（如“需要等级10级才能接取”）
   • 前置任务要求（如“需要完成任务A才能接取”）
   • 特定物品要求（如“需要拥有特定物品才能接取”）

9.2 进度条件

进度条件是指用户需要完成才能完成任务的条件，有明确的进度计算。进度条件的特点：

1. 进度跟踪：有明确的当前值和目标值
2. 动态更新：随着用户操作不断更新进度
3. 典型例子：
   • 种植作物（如“种植5次小麦”）
   • 收获作物（如“收获10个苹果”）
   • 使用物品（如“使用3次化肥”）

9.3 处理流程差异

1. 前置条件处理：

   • 在用户尝试接取任务时检查
   • 如果不满足，拒绝接取并返回原因
   • 不需要记录进度

2. 进度条件处理：

   • 接取任务后持续跟踪
   • 根据用户操作更新进度
   • 在用户任务进度表中记录当前值
   • 当所有必要的进度条件都满足时，完成任务

10. 任务示例

10.1 简单任务：每日登录

任务名称：每日登录
任务描述：今天登录游戏
任务类型：daily
条件：
  - 类型：login
  - 目标值：1
  - 参数：{}
  - 运算符：=
奖励：
  - 金币 x 100

10.2 多条件任务：农场管理

任务名称：农场管理大师
任务描述：种植3种不同作物，收获10次，升级1次土地
任务类型：weekly
条件：
  - 类型：plant
    目标值：3
    参数：{"seed_ids": [101, 102, 103, 104, 105]}
    运算符：>=
    是否必须：是
  - 类型：harvest
    目标值：10
    参数：{}
    运算符：>=
    是否必须：是
  - 类型：upgrade_land
    目标值：1
    参数：{}
    运算符：>=
    是否必须：是
奖励：
  - 高级化肥 x 3
  - 金币 x 500

10.3 带前置条件的任务示例

任务名称：高级农场主
任务描述：已经达到农场等级10级的玩家，可以尝试种植高级作物
任务类型：achievement
前置条件：
  - 类型：level_check
    目标值：10
    参数：{"level_type": "farm"}
    运算符：>=
    条件类型：prerequisite
  - 类型：task_completed
    目标值：1
    参数：{"task_ids": [101, 102]}
    运算符：>=
    条件类型：prerequisite
进度条件：
  - 类型：plant
    目标值：5
    参数：{"seed_ids": [201, 202]}
    运算符：>=
    条件类型：progress
    是否必须：是
  - 类型：harvest
    目标值：20
    参数：{"crop_ids": [301, 302]}
    运算符：>=
    条件类型：progress
    是否必须：是
奖励：
  - 稀有种子 x 1
  - 金币 x 1000

11. 数据维护

11.1 数据清理策略

1. 定期清理过期的用户任务数据（可设置保留期限）
2. 日志表数据可考虑归档处理
3. 使用软删除机制，避免直接删除重要数据

11.2 数据备份策略

1. 与系统整体备份策略保持一致
2. 关键操作前进行数据备份
3. 定期验证备份数据的完整性