# 神灵加持系统

## 1. 概述

神灵加持系统是农场模块的特殊buff机制，为玩家提供临时的游戏优势。玩家可以通过特定途径获得不同类型的神灵加持，这些加持可以提高产量、防止灾害等，为玩家的农场经营提供帮助。

## 2. 神灵加持类型

### 2.1 加持类型定义

农场模块定义了四种神灵加持类型：

```php
namespace App\Module\Farm\Enums;

enum GOD_BUFF_TYPE: int {
    case HARVEST = 1;    // 丰收之神
    case RAIN = 2;       // 雨露之神
    case WEED = 3;       // 屠草之神
    case PEST = 4;       // 拭虫之神
}
```

### 2.2 加持效果说明

| 加持类型 | 值 | 效果描述 | 应用场景 |
|---------|---|---------|---------|
| 丰收之神 | 1 | 确保收获时获得最高产量 | 收获作物时直接使用种子的最大产量值 |
| 雨露之神 | 2 | 防止干旱灾害 | 生成灾害时不会生成干旱类型的灾害 |
| 屠草之神 | 3 | 防止杂草灾害 | 生成灾害时不会生成杂草类型的灾害 |
| 拭虫之神 | 4 | 防止虫害灾害 | 生成灾害时不会生成虫害类型的灾害 |

## 3. 数据结构

### 3.1 神灵加持表 (farm_god_buffs)

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| user_id | bigint | 用户ID |
| buff_type | tinyint | 加持类型:1丰收之神,2雨露之神,3屠草之神,4拭虫之神 |
| expire_time | timestamp | 过期时间 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

```sql
CREATE TABLE `farm_god_buffs` (
  `id` bigint(20) unsigned NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `user_id` bigint(20) NOT NULL COMMENT '用户ID',
  `buff_type` tinyint(3) unsigned NOT NULL COMMENT 'buff类型:1丰收之神,2雨露之神,3屠草之神,4拭虫之神',
  `expire_time` timestamp NOT NULL COMMENT '过期时间',
  `created_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at` timestamp NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_expire_time` (`expire_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='神灵加持表';
```

### 3.2 索引设计

- 主键索引：`id`
- 普通索引：`user_id`（加速查询用户的所有加持）
- 普通索引：`expire_time`（加速查询过期的加持）

## 4. 核心功能

### 4.1 添加神灵加持

```php
/**
 * 添加神灵加持
 * 
 * @param int $userId 用户ID
 * @param int $buffType 加持类型
 * @param int $durationHours 持续时间(小时)
 * @return bool 是否添加成功
 */
public function addGodBuff(int $userId, int $buffType, int $durationHours): bool
{
    // 验证加持类型
    if (!in_array($buffType, [
        GOD_BUFF_TYPE::HARVEST,
        GOD_BUFF_TYPE::RAIN,
        GOD_BUFF_TYPE::WEED,
        GOD_BUFF_TYPE::PEST
    ])) {
        throw new InvalidBuffTypeException("无效的加持类型");
    }
    
    // 计算过期时间
    $expireTime = now()->addHours($durationHours);
    
    // 添加或更新加持记录
    return $this->godBuffRepository->addOrUpdateBuff($userId, $buffType, $expireTime);
}
```

### 4.2 获取用户的神灵加持

```php
/**
 * 获取用户的所有有效神灵加持
 * 
 * @param int $userId 用户ID
 * @return array 加持列表
 */
public function getUserActiveBuffs(int $userId): array
{
    return $this->godBuffRepository->getUserActiveBuffs($userId);
}
```

### 4.3 检查用户是否有特定加持

```php
/**
 * 检查用户是否有特定类型的有效加持
 * 
 * @param int $userId 用户ID
 * @param int $buffType 加持类型
 * @return bool 是否有效
 */
public function hasActiveBuff(int $userId, int $buffType): bool
{
    return $this->godBuffRepository->hasActiveBuff($userId, $buffType);
}
```

### 4.4 清理过期加持

```php
/**
 * 清理过期的神灵加持
 * 此方法应由定时任务调用
 * 
 * @return int 清理的记录数
 */
public function cleanExpiredBuffs(): int
{
    return $this->godBuffRepository->cleanExpiredBuffs();
}
```

## 5. 业务逻辑实现

### 5.1 灾害生成时应用神灵加持

在生成灾害的逻辑中，检查用户是否有对应的神灵加持：

```php
/**
 * 为作物生成灾害
 */
public function generateDisaster(FarmCrop $crop): ?array
{
    $userId = $crop->user_id;
    
    // 检查用户是否有神灵加持
    $godBuffs = $this->godBuffRepository->getUserActiveBuffs($userId);
    
    // 如果有雨露之神加持，不生成干旱灾害
    if ($this->hasGodBuff($godBuffs, GOD_BUFF_TYPE::RAIN)) {
        $disasterTypes = [DISASTER_TYPE::PEST, DISASTER_TYPE::WEED];
    } 
    // 如果有屠草之神加持，不生成杂草灾害
    else if ($this->hasGodBuff($godBuffs, GOD_BUFF_TYPE::WEED)) {
        $disasterTypes = [DISASTER_TYPE::DROUGHT, DISASTER_TYPE::PEST];
    }
    // 如果有拭虫之神加持，不生成虫害灾害
    else if ($this->hasGodBuff($godBuffs, GOD_BUFF_TYPE::PEST)) {
        $disasterTypes = [DISASTER_TYPE::DROUGHT, DISASTER_TYPE::WEED];
    }
    else {
        $disasterTypes = [DISASTER_TYPE::DROUGHT, DISASTER_TYPE::PEST, DISASTER_TYPE::WEED];
    }
    
    // 随机选择一种灾害类型
    if (empty($disasterTypes)) {
        return null;
    }
    
    $disasterType = $disasterTypes[array_rand($disasterTypes)];
    
    // 生成灾害
    // ...
    
    return $disaster;
}
```

### 5.2 收获作物时应用丰收之神加持

在收获作物的逻辑中，检查用户是否有丰收之神加持：

```php
/**
 * 计算作物的最终产量
 */
public function calculateOutput(FarmCrop $crop, FarmLand $land, int $houseLevel): int
{
    // 获取种子配置
    $seedConfig = $this->seedRepository->find($crop->seed_id);
    
    // 检查用户是否有丰收之神加持
    $hasHarvestBuff = $this->godBuffRepository->hasActiveBuff($crop->user_id, GOD_BUFF_TYPE::HARVEST);
    
    // 如果有丰收之神加持，直接使用最大产量
    if ($hasHarvestBuff) {
        $baseOutput = $seedConfig->max_output;
    } else {
        // 随机生成基础产量
        $baseOutput = rand($seedConfig->min_output, $seedConfig->max_output);
    }
    
    // 计算土地加成
    $landBonus = $this->landLogic->calculateOutputBonus($land);
    
    // 计算房屋加成
    $houseBonus = $this->houseLogic->calculateOutputBonus($houseLevel);
    
    // 计算灾害减产
    $disasterImpact = $this->disasterLogic->calculateDisasterImpact($crop->disasters);
    
    // 计算最终产量
    $finalOutput = $baseOutput * (1 + $landBonus) * (1 + $houseBonus) * (1 - $disasterImpact);
    
    // 应用产量限制
    $finalOutput = max(1000, min($finalOutput, 3000));
    
    return (int)$finalOutput;
}
```

## 6. 获取神灵加持的途径

玩家可以通过以下途径获得神灵加持：

1. **商店购买**：在游戏商店中购买神灵加持道具
2. **任务奖励**：完成特定任务获得神灵加持
3. **活动奖励**：参与游戏活动获得神灵加持
4. **宝箱开启**：开启宝箱有几率获得神灵加持
5. **VIP特权**：VIP玩家可以定期获得神灵加持

## 7. 前端交互

### 7.1 神灵加持展示

前端应展示用户当前拥有的神灵加持，包括：
- 加持类型（图标和名称）
- 剩余时间
- 效果说明

### 7.2 使用神灵加持

前端应提供使用神灵加持的界面，允许玩家：
- 查看可用的神灵加持道具
- 选择要使用的加持类型
- 确认使用并查看效果

## 8. 扩展性考虑

### 8.1 新加持类型

系统设计预留了添加新加持类型的可能性，只需：
1. 在GOD_BUFF_TYPE枚举中添加新类型
2. 在相应的业务逻辑中添加新类型的处理
3. 更新前端展示逻辑

### 8.2 加持效果增强

可以为神灵加持添加等级系统，不同等级的加持提供不同强度的效果：
- 初级丰收之神：确保80%的最大产量
- 中级丰收之神：确保90%的最大产量
- 高级丰收之神：确保100%的最大产量

### 8.3 加持组合效果

可以设计多种加持同时生效时的组合效果：
- 丰收之神+雨露之神：额外增加10%的产量
- 屠草之神+拭虫之神：额外增加作物生长速度

## 9. 总结

神灵加持系统为农场模块提供了一种临时增益机制，通过不同类型的加持，玩家可以获得产量提升、灾害防护等游戏优势。系统设计灵活，易于扩展，可以根据游戏需求添加新的加持类型和效果。

通过合理使用神灵加持，玩家可以更有效地管理自己的农场，提高游戏体验和策略性。