kknongchang_2506/app/Module/Farm

农场模块 (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	最大产出
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	成长期时间(秒)
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模块

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

Team模块

• 触发作物收获事件，用于团队收益分成
• 获取达人等级信息，影响农场产出
• 实现直间推播种收获贡献百分比农作物收益
• 支持团队任务和团队协作种植
• 详细实现请参考与团队模块集成文档

User模块

• 获取用户信息
• 验证用户权限
• 用户注册时初始化农场

开发注意事项

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

开发文档

详细的开发文档请参考以下资源：

• 开发指南 - 模块开发的快速入门指南
• 枚举定义 - 模块中使用的所有枚举类型定义
• 神灵加持系统 - 神灵加持系统的设计与实现
• 文档审查报告 - 文档结构和内容的审查报告