1

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

@@ -2,21 +2,31 @@
 
 ## 1. 数据库表概览
 
-任务模块包含以下核心数据表：
+任务模块包含以下核心数据表，按功能分为三个部分：
+
+### 1.1 任务定义相关表
 
 1. **task_categories** - 任务分类表
 2. **task_tasks** - 任务定义表
 3. **task_conditions** - 任务条件表
 4. **task_achievement_conditions** - 任务达成条件表
+
+### 1.2 任务完成相关表
+
 5. **task_user_tasks** - 用户任务关联表
 6. **task_user_progress** - 用户任务进度表
+
+### 1.3 日志记录相关表
+
 7. **task_completion_logs** - 任务完成日志表
 8. **task_reward_logs** - 任务奖励发放日志表
 9. **task_reset_logs** - 任务重置日志表
 
 ## 2. 表结构详细设计
 
-### 2.1 任务分类表 (task_categories)
+## 2.1 任务定义相关表
+
+### 2.1.1 任务分类表 (task_categories)
 
 存储任务的分类信息，用于对任务进行分组和管理。
 
@@ -34,7 +44,7 @@
 - PRIMARY KEY (`id`)
 - UNIQUE KEY `idx_code` (`code`)
 
-### 2.2 任务定义表 (task_tasks)
+### 2.1.2 任务定义表 (task_tasks)
 
 存储任务的基本定义信息，包括任务名称、描述、奖励等。目标相关字段已拆分到任务达成条件表。
 
@@ -62,31 +72,7 @@
 - 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)
+### 2.1.3 任务条件表 (task_conditions)
 
 定义系统中所有可用的条件类型，每种条件类型对应一个处理器类，负责验证和更新该类型条件的进度。
 
@@ -106,7 +92,7 @@
 - PRIMARY KEY (`id`)
 - UNIQUE KEY `idx_code` (`code`)
 
-### 2.5 任务达成条件表 (task_achievement_conditions)
+### 2.1.4 任务达成条件表 (task_achievement_conditions)
 
 关联任务和具体的条件，定义了完成任务需要满足的条件。一个任务可以有多个条件，通过这个表可以实现复杂的任务逻辑。条件分为两种类型：前置条件和进度条件。
 
@@ -131,7 +117,33 @@
 - KEY `idx_task_condition` (`task_id`, `condition_id`)
 - KEY `idx_condition_type` (`condition_type`)
 
-### 2.6 用户任务进度表 (task_user_progress)
+## 2.2 任务完成相关表
+
+### 2.2.1 用户任务关联表 (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.2.2 用户任务进度表 (task_user_progress)
 
 存储用户任务的详细进度信息，关联到具体的任务达成条件。
 
@@ -152,7 +164,9 @@
 - KEY `idx_user_task` (`user_id`, `task_id`)
 - KEY `idx_achievement_condition` (`achievement_condition_id`)
 
-### 2.7 任务完成日志表 (task_completion_logs)
+## 2.3 日志记录相关表
+
+### 2.3.1 任务完成日志表 (task_completion_logs)
 
 记录用户完成任务的详细信息，用于审计和数据分析。
 
@@ -173,7 +187,7 @@
 - KEY `idx_task` (`task_id`)
 - KEY `idx_completed_at` (`completed_at`)
 
-### 2.8 任务奖励发放日志表 (task_reward_logs)
+### 2.3.2 任务奖励发放日志表 (task_reward_logs)
 
 记录任务奖励的发放情况，包括奖励内容、发放时间等。
 
@@ -196,7 +210,7 @@
 - KEY `idx_user_task` (`user_task_id`)
 - KEY `idx_rewarded_at` (`rewarded_at`)
 
-### 2.9 任务重置日志表 (task_reset_logs)
+### 2.3.3 任务重置日志表 (task_reset_logs)
 
 记录任务重置的情况，包括重置类型、重置时间、影响的任务数等。
 
@@ -316,11 +330,63 @@ task_user_tasks 1 --< task_reward_logs
 2. 版本化迁移文件，支持回滚
 3. 大型结构变更时考虑分步迁移，减少对系统的影响
 
-## 7. 条件处理器设计
+## 7. 任务定义相关设计
+
+### 7.1 前置条件与进度条件的区别
+
+#### 7.1.1 前置条件
+
+前置条件是指用户必须满足才能接取任务的条件，但不计入任务的完成进度。前置条件的特点：
+
+1. **检查时机**：在用户接取任务时检查
+2. **完成状态**：只有“满足/不满足”两种状态，没有进度概念
+3. **典型例子**：
+   - 用户等级要求（如“需要等级10级才能接取”）
+   - 前置任务要求（如“需要完成任务A才能接取”）
+   - 特定物品要求（如“需要拥有特定物品才能接取”）
+
+#### 7.1.2 进度条件
+
+进度条件是指用户需要完成才能完成任务的条件，有明确的进度计算。进度条件的特点：
+
+1. **进度跟踪**：有明确的当前值和目标值
+2. **动态更新**：随着用户操作不断更新进度
+3. **典型例子**：
+   - 种植作物（如“种植5次小麦”）
+   - 收获作物（如“收获10个苹果”）
+   - 使用物品（如“使用3次化肥”）
+
+#### 7.1.3 处理流程差异
+
+1. **前置条件处理**：
+   - 在用户尝试接取任务时检查
+   - 如果不满足，拒绝接取并返回原因
+   - 不需要记录进度
+
+2. **进度条件处理**：
+   - 接取任务后持续跟踪
+   - 根据用户操作更新进度
+   - 在用户任务进度表中记录当前值
+   - 当所有必要的进度条件都满足时，完成任务
+
+### 7.2 任务类型设计
+
+任务模块支持多种任务类型，每种类型有不同的特性和重置规则：
+
+1. **日常任务（daily）**：每天重置，通常是简单的日常活动
+2. **每周任务（weekly）**：每周重置，通常难度较高，奖励也更丰厚
+3. **成就任务（achievement）**：不重置，只能完成一次，通常是长期目标
+4. **活动任务（event）**：与特定活动关联，有明确的开始和结束时间
+5. **教程任务（tutorial）**：新手引导任务，帮助用户学习游戏机制
+6. **团队任务（team）**：需要多个用户合作完成的任务
+
+## 8. 任务完成相关设计
+
+### 8.1 条件处理器设计
 
 每种条件类型都有一个对应的处理器类，负责验证和更新该类型条件的进度。
 
-### 7.1 条件处理器接口
+#### 8.1.1 条件处理器接口
 
 ```php
 interface ConditionHandlerInterface
@@ -355,7 +421,7 @@ interface ConditionHandlerInterface
 }
 ```
 
-### 7.2 基础条件处理器
+#### 8.1.2 基础条件处理器
 
 ```php
 abstract class BaseConditionHandler implements ConditionHandlerInterface
@@ -388,71 +454,42 @@ abstract class BaseConditionHandler implements ConditionHandlerInterface
 }
 ```
 
-## 8. 任务进度更新流程
+### 8.2 任务进度更新流程
 
-### 8.1 事件触发
+#### 8.2.1 事件触发
 
 1. 用户执行操作（如登录、种植、收获等）
 2. 系统触发相应的事件
 
-### 8.2 条件匹配
+#### 8.2.2 条件匹配
 
 1. 任务服务接收事件
 2. 查找与事件相关的所有活跃任务的进度条件
 3. 对每个条件，调用对应的处理器验证事件是否匹配
 
-### 8.3 进度更新
+#### 8.2.3 进度更新
 
 1. 对于匹配的条件，计算进度贡献值
 2. 更新用户任务进度表中的当前值
 3. 检查条件是否已完成
 
-### 8.4 任务完成检查
+#### 8.2.4 任务完成检查
 
 1. 当进度条件完成时，检查任务的所有必要的进度条件是否都已完成
 2. 如果所有必要的进度条件都已完成，将任务标记为已完成
 3. 触发任务完成事件
 
-## 9. 前置条件与进度条件的区别
-
-### 9.1 前置条件
-
-前置条件是指用户必须满足才能接取任务的条件，但不计入任务的完成进度。前置条件的特点：
-
-1. **检查时机**：在用户接取任务时检查
-2. **完成状态**：只有“满足/不满足”两种状态，没有进度概念
-3. **典型例子**：
-   - 用户等级要求（如“需要等级10级才能接取”）
-   - 前置任务要求（如“需要完成任务A才能接取”）
-   - 特定物品要求（如“需要拥有特定物品才能接取”）
-
-### 9.2 进度条件
-
-进度条件是指用户需要完成才能完成任务的条件，有明确的进度计算。进度条件的特点：
-
-1. **进度跟踪**：有明确的当前值和目标值
-2. **动态更新**：随着用户操作不断更新进度
-3. **典型例子**：
-   - 种植作物（如“种植5次小麦”）
-   - 收获作物（如“收获10个苹果”）
-   - 使用物品（如“使用3次化肥”）
+### 8.3 任务奖励领取流程
 
-### 9.3 处理流程差异
+1. 用户完成任务后，可以领取奖励
+2. 系统验证任务是否已完成且奖励未领取
+3. 发放奖励到用户账户
+4. 更新任务状态为已领取奖励
+5. 记录奖励发放日志
 
-1. **前置条件处理**：
-   - 在用户尝试接取任务时检查
-   - 如果不满足，拒绝接取并返回原因
-   - 不需要记录进度
-
-2. **进度条件处理**：
-   - 接取任务后持续跟踪
-   - 根据用户操作更新进度
-   - 在用户任务进度表中记录当前值
-   - 当所有必要的进度条件都满足时，完成任务
+## 9. 任务示例
 
-## 10. 任务示例
-
-### 10.1 简单任务：每日登录
+### 9.1 简单任务：每日登录
 
 ```
 任务名称：每日登录
@@ -467,7 +504,7 @@ abstract class BaseConditionHandler implements ConditionHandlerInterface
   - 金币 x 100
 ```
 
-### 10.2 多条件任务：农场管理
+### 9.2 多条件任务：农场管理
 
 ```
 任务名称：农场管理大师
@@ -494,7 +531,7 @@ abstract class BaseConditionHandler implements ConditionHandlerInterface
   - 金币 x 500
 ```
 
-### 10.3 带前置条件的任务示例
+### 9.3 带前置条件的任务示例
 
 ```
 任务名称：高级农场主
@@ -529,15 +566,29 @@ abstract class BaseConditionHandler implements ConditionHandlerInterface
   - 金币 x 1000
 ```
 
-## 11. 数据维护
+## 10. 日志记录相关设计
+
+### 10.1 日志记录目的
+
+1. **审计追踪**：记录用户任务完成和奖励领取的详细信息，便于后续审计和问题排查
+2. **数据分析**：为游戏运营提供数据支持，分析用户行为和任务完成情况
+3. **安全保障**：防止奖励重复发放，记录关键操作的IP和设备信息
+
+### 10.2 日志记录策略
+
+1. **完成日志**：记录任务完成的时间、耗时等信息
+2. **奖励日志**：记录奖励发放的详细内容和时间
+3. **重置日志**：记录系统定期重置任务的情况
+
+### 10.3 日志数据维护
 
-### 11.1 数据清理策略
+#### 10.3.1 数据清理策略
 
 1. 定期清理过期的用户任务数据（可设置保留期限）
 2. 日志表数据可考虑归档处理
 3. 使用软删除机制，避免直接删除重要数据
 
-### 11.2 数据备份策略
+#### 10.3.2 数据备份策略
 
 1. 与系统整体备份策略保持一致
 2. 关键操作前进行数据备份