# 农场模块 (Farm)

> **状态**: ✅ 已完成 - 农场模块开发已完成，包含完整的种植、收获、升级等功能

## 模块说明
农场模块是开心农场系统的核心模块，负责管理用户的农场、土地、房屋、种子和作物等核心游戏元素，实现种植、收获、升级等主要玩法。

## 目录结构
```
app/Module/Farm/
├── AdminControllers/        # 后台管理控制器
│   ├── Land/                # 土地相关控制器
│   ├── House/               # 房屋相关控制器
│   ├── Seed/                # 种子相关控制器
│   ├── Crop/                # 作物相关控制器
│   └── Helper/              # 控制器辅助类
├── Commands/                # 命令行工具
├── Databases/               # 数据库相关文件
│   └── createsql/           # 表创建SQL文件
├── Docs/                    # 详细文档目录
│   ├── README.md            # 文档索引
│   ├── 设计概述.md           # 模块整体设计
│   ├── 数据库设计.md         # 数据库表结构设计
│   ├── 模块接口.md           # 模块对外接口
│   ├── 土地系统.md           # 土地系统设计
│   ├── 房屋系统.md           # 房屋系统设计
│   ├── 种子与作物系统.md      # 种子与作物系统设计
│   ├── 神灵加持系统.md        # 神灵加持系统设计
│   ├── 枚举定义.md           # 枚举类型定义
├── Enums/                   # 枚举类型定义
├── Events/                  # 事件类
├── Logics/                  # 业务逻辑类
│   ├── Land/                # 土地相关逻辑
│   ├── House/               # 房屋相关逻辑
│   ├── Seed/                # 种子相关逻辑
│   └── Crop/                # 作物相关逻辑
├── Models/                  # 数据模型
├── Providers/               # 服务提供者
├── Repositorys/             # 数据仓库
├── Services/                # 开放服务类
└── README.md                # 模块文档
```

## 功能概述

### 1. 土地管理
- 土地类型：普通土地、红土地、黑土地、特殊土地（金/蓝/紫）
- 土地升级：普通→红土地→黑土地→特殊土地
- 土地状态：空闲、种植中、灾害、收获期、枯萎期
- 土地产出：基于土地类型、房屋等级和灾害情况计算产量

### 2. 房屋管理
- 房屋等级：共12级，注册默认1级
- 房屋升级：消耗材料升级房屋
- 房屋降级：N天不升级则降级
- 房屋效果：影响土地产出概率和特殊土地数量

### 3. 种子管理
- 种子类型：神秘种子、普通种子、巨化种子
- 种子属性：生长周期、产量范围、灾害抵抗
- 种子获取：商店购买、任务奖励、宝箱开启

### 4. 作物管理
- 生长周期：种子期→发芽期→生长期→成熟期→枯萎期
- 生长加速：使用化肥减少生长时间
- 灾害系统：干旱、虫害、杂草，影响产量
- 收获系统：计算最终产量并添加到用户物品

### 5. 神灵加持系统
- 加持类型：丰收之神、雨露之神、屠草之神、拭虫之神
- 加持效果：提高产量、防止灾害
- 加持获取：商店购买、任务奖励、活动奖励
- 加持管理：添加、查询、清理过期加持

## 数据表设计

### 1. 用户农场表 (farm_users)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| user_id | bigint | 用户ID |
| house_level | tinyint | 房屋等级 |
| last_upgrade_time | timestamp | 最后升级时间 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 2. 土地表 (farm_land_users)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| user_id | bigint | 用户ID |
| position | tinyint | 土地位置 |
| land_type | tinyint | 土地类型 |
| status | tinyint | 土地状态 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 3. 作物表 (farm_crops)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| land_id | bigint | 土地ID |
| seed_id | bigint | 种子ID |
| plant_time | timestamp | 种植时间 |
| growth_stage | tinyint | 生长阶段 |
| stage_end_time | timestamp | 阶段结束时间 |
| disasters | json | 灾害情况 |
| fertilized | boolean | 是否使用化肥 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 4. 种子表 (farm_seeds)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| name | varchar | 种子名称 |
| type | tinyint | 种子类型 |
| seed_time | int | 种子期时间(秒) |
| min_output | int | 最小产出 |
| max_output | int | 最大产出 |
| disaster_min_output | int | 有灾害时最小产出 |
| disaster_max_output | int | 有灾害时最大产出 |
| item_id | bigint | 对应的物品ID |
| disaster_resistance | json | 灾害抵抗 |
| display_attributes | json | 显示属性 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

**注意**：种子只配置种子期时间，其他阶段时间由果实生长周期配置决定。

### 5. 果实生长周期表 (farm_fruit_growth_cycles)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| fruit_item_id | bigint | 果实物品ID |
| sprout_time | int | 发芽期时间(秒) |
| growth_time | int | 成长期时间(秒) |
| fruit_time | int | 果实期时间(秒) |
| mature_time | int | 成熟期时间(秒，0表示无限) |
| wither_time | int | 枯萎期时间(秒，0表示无限) |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 6. 房屋等级配置表 (farm_house_configs)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| level | tinyint | 等级 |
| output_bonus | decimal | 产出加成 |
| special_land_limit | tinyint | 特殊土地上限 |
| upgrade_materials | json | 升级所需材料 |
| downgrade_days | int | 降级天数 |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 7. 收获记录表 (farm_harvest_logs)
| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | bigint | 主键ID |
| user_id | bigint | 用户ID |
| land_id | bigint | 土地ID |
| crop_id | bigint | 作物ID |
| seed_id | bigint | 种子ID |
| output_amount | int | 产出数量 |
| harvest_time | timestamp | 收获时间 |
| created_at | timestamp | 创建时间 |

### 8. 神灵加持表 (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 | 更新时间 |

## 核心服务

### 1. 土地服务 (LandService)
- 创建土地
- 升级土地
- 获取土地状态
- 处理土地灾害

### 2. 房屋服务 (HouseService)
- 升级房屋
- 计算房屋降级
- 获取房屋加成效果

### 3. 种子服务 (SeedService)
- 获取种子信息
- 计算种子生长时间
- 处理神秘种子随机逻辑

### 4. 作物服务 (CropService)
- 种植作物
- 处理作物生长
- 处理灾害影响
- 收获作物
- 计算产量

### 5. 神灵加持服务 (GodBuffService)
- 添加神灵加持
- 获取用户的神灵加持
- 检查用户是否有特定加持
- 清理过期加持

## 事件系统

### 发出的事件
- 作物种植事件 (CropPlanted)
- 作物收获事件 (CropHarvested)
- 土地升级事件 (LandUpgraded)
- 房屋升级事件 (HouseUpgraded)
- 灾害发生事件 (DisasterOccurred)

### 监听的事件
- 物品变更事件 (ItemChanged)
- 宠物技能使用事件 (PetSkillUsed)

## 与其他模块的交互

### GameItems模块
- 获取种子物品信息
- 添加收获物品到用户背包
- 消耗升级材料
- 检查用户物品库存
- 处理神秘种子转化
- 监听物品变更事件

物品模块集成的详细实现已融入各功能模块文档中，请参考相关文档的"与物品系统的交互"部分。

### Pet模块
- 获取宠物技能效果
- 处理宠物自动收菜、播种等功能
- 监听宠物技能使用事件



### User模块
- 获取用户信息
- 验证用户权限
- 用户注册时初始化农场

## 开发注意事项

1. **数据一致性**：所有涉及多个操作的功能都应使用数据库事务
2. **性能优化**：定时任务处理作物生长和灾害，避免实时计算
3. **扩展性考虑**：预留土地类型、种子类型的扩展空间
4. **安全验证**：所有操作前验证用户权限和数据有效性
5. **日志记录**：记录关键操作，便于问题排查和数据分析

## 开发文档

详细的开发文档请参考以下资源：
- [开发指南](Docs/开发指南.md) - 模块开发的快速入门指南
- [枚举定义](Docs/枚举定义.md) - 模块中使用的所有枚举类型定义
- [神灵加持系统](Docs/神灵加持系统.md) - 神灵加持系统的设计与实现
- [文档审查报告](Docs/文档审查报告.md) - 文档结构和内容的审查报告