# 农场模块枚举定义

## 1. 概述

本文档定义了农场模块中使用的所有枚举类型，包括土地类型、土地状态、种子类型、作物生长阶段和灾害类型等。这些枚举类型在模块的各个部分都有使用，是理解模块功能的重要基础。

## 2. 土地相关枚举

### 2.1 土地类型 (LAND_TYPE)

土地类型枚举定义了农场中可能的土地类型，不同类型的土地有不同的产出加成和灾害抵抗能力。

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

enum LAND_TYPE: int {
    case NORMAL = 1;     // 普通土地
    case RED = 2;        // 红土地
    case BLACK = 3;      // 黑土地
    case GOLD = 4;       // 金色特殊土地
    case BLUE = 5;       // 蓝色特殊土地
    case PURPLE = 6;     // 紫色特殊土地
}
```

> 注：土地类型的属性（产量加成、灾害抵抗等）现在存储在 farm_land_types 表中，可通过后台配置修改。详细设计请参考 [土地配置表设计](土地配置表设计.md) 文档。

#### 土地类型属性表

下表为默认配置，实际值以数据库配置为准：

| 土地类型 | 值 | 产量加成 | 灾害抵抗 | 解锁条件 | 升级材料 |
|---------|---|---------|---------|---------|---------|
| 普通土地 | 1 | 0% | 0% | 默认 | - |
| 红土地 | 2 | +10% | +5% | 任意等级 | 木材x10 |
| 黑土地 | 3 | +25% | +10% | 任意等级 | 石材x10 |
| 金色特殊土地 | 4 | +50% | +15% | 房屋7级+ | 钢材x10+钻石x5 |
| 蓝色特殊土地 | 5 | +40% | +25% | 房屋7级+ | 钢材x10+钻石x5 |
| 紫色特殊土地 | 6 | +60% | +10% | 房屋7级+ | 钢材x10+钻石x5 |

### 2.2 土地状态 (LAND_STATUS)

土地状态枚举定义了土地可能的状态，影响土地上可以执行的操作。

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

enum LAND_STATUS: int {
    case EMPTY = 0;      // 空闲
    case PLANTED = 1;    // 种植中
    case DISASTER = 2;   // 灾害
    case HARVESTABLE = 3; // 可收获
    case WITHERED = 4;   // 枯萎
}
```

#### 土地状态说明

| 土地状态 | 值 | 说明 | 可执行操作 |
|---------|---|------|----------|
| 空闲 | 0 | 土地上没有作物 | 种植、升级 |
| 种植中 | 1 | 土地上有正在生长的作物 | 使用化肥、查看 |
| 灾害 | 2 | 土地上的作物遭遇灾害 | 处理灾害、查看 |
| 可收获 | 3 | 土地上的作物已成熟，可以收获 | 收获、查看 |
| 枯萎 | 4 | 土地上的作物已枯萎 | 铲除、查看 |

## 3. 种子与作物相关枚举

### 3.1 种子类型 (SEED_TYPE)

种子类型枚举定义了农场中可能的种子类型，不同类型的种子有不同的特性。

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

enum SEED_TYPE: int {
    case NORMAL = 1;     // 普通种子
    case MYSTERY = 2;    // 神秘种子
    case GIANT = 3;      // 巨化种子
}
```

#### 种子类型说明

| 种子类型 | 值 | 说明 | 特性 |
|---------|---|------|------|
| 普通种子 | 1 | 常规种子，有固定的生长周期和产量 | 产量正常 |
| 神秘种子 | 2 | 种植时随机转化为其他种子 | 90%概率转化为普通种子，10%概率转化为巨化种子 |
| 巨化种子 | 3 | 普通种子的强化版本 | 产量是普通种子的1.5倍 |

### 3.2 作物生长阶段 (CROP_GROWTH_STAGE)

作物生长阶段枚举定义了作物从种植到收获的各个阶段。

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

enum CROP_GROWTH_STAGE: int {
    case SEED = 1;       // 种子期
    case SPROUT = 2;     // 发芽期
    case GROWING = 3;    // 生长期
    case MATURE = 4;     // 成熟期
    case WITHERED = 5;   // 枯萎期
}
```

#### 生长阶段说明

| 生长阶段 | 值 | 持续时间 | 可用化肥 | 灾害概率 | 状态转换 |
|---------|---|---------|---------|---------|---------|
| 种子期 | 1 | 种子配置 | 是 | 低 | 自动进入发芽期 |
| 发芽期 | 2 | 种子配置 | 是 | 中 | 自动进入生长期 |
| 生长期 | 3 | 种子配置 | 是 | 高 | 自动进入成熟期 |
| 成熟期 | 4 | 24小时 | 否 | 无 | 超时进入枯萎期 |
| 枯萎期 | 5 | 永久 | 否 | 无 | 需手动铲除 |

## 4. 灾害相关枚举

### 4.1 灾害类型 (DISASTER_TYPE)

灾害类型枚举定义了可能影响作物生长的灾害类型。

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

enum DISASTER_TYPE: int {
    case DROUGHT = 1;    // 干旱
    case PEST = 2;       // 虫害
    case WEED = 3;       // 杂草
}
```

#### 灾害类型说明

| 灾害类型 | 值 | 减产比例 | 处理道具 | 处理效果 |
|---------|---|---------|---------|---------|
| 干旱 | 1 | 5% | 洒水壶 | 完全消除 |
| 虫害 | 2 | 5% | 杀虫剂 | 完全消除 |
| 杂草 | 3 | 5% | 除草剂 | 完全消除 |

## 5. 其他枚举

### 5.1 升级类型 (UPGRADE_TYPE)

升级类型枚举定义了农场中可能的升级类型，用于记录升级日志。

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

enum UPGRADE_TYPE: int {
    case LAND = 1;       // 土地升级
    case HOUSE = 2;      // 房屋升级
}
```

### 5.2 化肥类型 (FERTILIZER_TYPE)

化肥类型枚举定义了可用的化肥类型，不同类型的化肥有不同的加速效果。

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

enum FERTILIZER_TYPE: int {
    case NORMAL = 1;     // 普通化肥
    case ADVANCED = 2;   // 高级化肥
}
```

### 5.3 神灵加持类型 (GOD_BUFF_TYPE)

神灵加持类型枚举定义了可用的神灵加持类型，不同类型的加持提供不同的游戏优势。

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

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

#### 神灵加持类型说明

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

#### 化肥类型说明

| 化肥类型 | 值 | 加速效果 | 物品ID |
|---------|---|---------|-------|
| 普通化肥 | 1 | 减少当前阶段1小时生长时间 | 2001 |
| 高级化肥 | 2 | 减少当前阶段3小时生长时间 | 2002 |

## 6. 枚举使用示例

### 6.1 土地类型判断

```php
// 判断土地是否为特殊土地（旧版本，硬编码）
public function isSpecialLandType_old(int $landType): bool
{
    return in_array($landType, [
        LAND_TYPE::GOLD,
        LAND_TYPE::BLUE,
        LAND_TYPE::PURPLE
    ]);
}

// 判断土地是否为特殊土地（新版本，使用数据库配置）
public function isSpecialLandType(int $landType): bool
{
    // 从数据库中获取土地类型配置
    $landTypeConfig = $this->landTypeRepository->find($landType);

    if (!$landTypeConfig) {
        return false;
    }

    return (bool)$landTypeConfig->is_special;
}
```

### 6.2 土地状态更新

```php
// 更新土地状态
public function updateLandStatus(int $landId, int $status): bool
{
    // 验证状态有效性
    if (!in_array($status, [
        LAND_STATUS::EMPTY,
        LAND_STATUS::PLANTED,
        LAND_STATUS::DISASTER,
        LAND_STATUS::HARVESTABLE,
        LAND_STATUS::WITHERED
    ])) {
        throw new InvalidStatusException("无效的土地状态");
    }

    // 更新土地状态
    return $this->landRepository->update($landId, [
        'status' => $status
    ]);
}
```

### 6.3 作物生长阶段更新

```php
// 更新作物生长阶段
public function updateCropGrowthStage(FarmCrop $crop, int $newStage): bool
{
    // 验证生长阶段有效性
    if (!in_array($newStage, [
        CROP_GROWTH_STAGE::SEED,
        CROP_GROWTH_STAGE::SPROUT,
        CROP_GROWTH_STAGE::GROWING,
        CROP_GROWTH_STAGE::MATURE,
        CROP_GROWTH_STAGE::WITHERED
    ])) {
        throw new InvalidGrowthStageException("无效的生长阶段");
    }

    // 计算阶段结束时间
    $stageEndTime = $this->calculateStageEndTime($crop, $newStage);

    // 更新作物生长阶段
    return $this->cropRepository->update($crop->id, [
        'growth_stage' => $newStage,
        'stage_end_time' => $stageEndTime
    ]);
}
```

### 6.4 灾害处理

```php
// 处理灾害
public function handleDisaster(int $cropId, int $disasterType, int $toolId): bool
{
    // 验证灾害类型有效性
    if (!in_array($disasterType, [
        DISASTER_TYPE::DROUGHT,
        DISASTER_TYPE::PEST,
        DISASTER_TYPE::WEED
    ])) {
        throw new InvalidDisasterTypeException("无效的灾害类型");
    }

    // 验证工具与灾害类型匹配
    if (!$this->isToolMatchDisaster($toolId, $disasterType)) {
        throw new InvalidToolException("该工具不能处理此类灾害");
    }

    // 处理灾害
    // ...

    return true;
}
```

## 7. 枚举扩展指南

如需添加新的枚举值，请按照以下步骤操作：

1. 在对应的枚举类中添加新的枚举值
2. 更新相关的业务逻辑，处理新的枚举值
3. 更新前端展示逻辑，显示新的枚举值
4. 更新文档，说明新的枚举值的含义和用法

例如，添加新的土地类型：

```php
// 在LAND_TYPE枚举中添加新的土地类型
enum LAND_TYPE: int {
    case NORMAL = 1;     // 普通土地
    case RED = 2;        // 红土地
    case BLACK = 3;      // 黑土地
    case GOLD = 4;       // 金色特殊土地
    case BLUE = 5;       // 蓝色特殊土地
    case PURPLE = 6;     // 紫色特殊土地
    case DIAMOND = 7;    // 钻石土地（新增）
}
```

然后更新相关的业务逻辑：

```php
// 在LandLogic中添加新土地类型的产出加成计算
public function calculateOutputBonus(FarmLand $land): float
{
    switch ($land->land_type) {
        case LAND_TYPE::NORMAL:
            return 0.0;
        case LAND_TYPE::RED:
            return 0.1;
        case LAND_TYPE::BLACK:
            return 0.25;
        case LAND_TYPE::GOLD:
            return 0.5;
        case LAND_TYPE::BLUE:
            return 0.4;
        case LAND_TYPE::PURPLE:
            return 0.6;
        case LAND_TYPE::DIAMOND:  // 新增
            return 0.8;
        default:
            return 0.0;
    }
}
```

## 8. 总结

本文档定义了农场模块中使用的所有枚举类型，包括土地类型、土地状态、种子类型、作物生长阶段和灾害类型等。这些枚举类型是模块功能的重要基础，理解这些枚举类型有助于理解模块的整体功能和业务逻辑。

在开发过程中，应该严格按照枚举定义使用这些类型，避免使用魔法数字，以提高代码的可读性和可维护性。如需添加新的枚举值，请按照枚举扩展指南进行操作，确保相关的业务逻辑和文档都得到更新。