设计概述.md 18 KB
农场模块设计概述
1. 模块定位与目标
1.1 模块定位
农场模块是开心农场游戏的核心模块，整合了土地、房屋、种子和作物管理功能，为玩家提供完整的种植、收获和升级体验。它是游戏中最基础的玩法系统，也是与其他模块交互最频繁的模块之一。
1.2 设计目标
本模块旨在实现以下目标：
- 游戏性：提供直观、有趣的种植玩法，增强用户粘性
- 进度设计：建立合理的游戏进度和成长曲线，平衡游戏难度
- 多样性：支持多样化的种植策略和玩法，提高游戏深度
- 集成性：与其他模块（如物品、宠物）无缝集成，形成完整生态
- 稳定性：保证数据一致性和系统稳定性，提供可靠的游戏体验
2. 核心功能领域
2.1 土地系统
土地是种植作物的基础，不同类型的土地有不同的产出效果。土地系统包括：
- 土地类型管理（普通、红土、黑土、特殊土地）
- 土地状态管理（空闲、种植中、灾害、收获期、枯萎期）
- 土地升级机制
- 土地产出计算
2.2 房屋系统
房屋是用户农场的核心建筑，影响整体产出和可用特殊土地数量：
- 房屋等级管理（1-12级）
- 房屋升级与降级机制
- 房屋对产出的加成效果
- 特殊土地解锁条件
2.3 种子系统
种子是作物的来源，决定了作物的基本属性：
- 种子类型管理（普通、神秘、巨化）
- 种子属性配置（生长周期、产量范围、灾害抵抗）
- 神秘种子随机机制
2.4 作物系统
作物是玩家种植的核心对象，从种植到收获的全过程管理：
- 生长周期管理（种子期、发芽期、生长期、成熟期、枯萎期）
- 灾害系统（干旱、虫害、杂草）
- 化肥加速机制
- 产量计算与收获
3. 系统架构
3.1 架构概览
农场模块采用分层架构设计，遵循单一职责原则和依赖倒置原则，各层次职责明确，便于维护和扩展：
┌─────────────────────────────────────────────────────┐
│ 表现层 (Presentation) │
│ ┌─────────────────────────────────────────────┐ │
│ │ AdminControllers │ │
│ │ Land/ House/ Seed/ Crop/ Helper/ │ │
│ └─────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────┤
│ 服务层 (Service) │
│ ┌─────────────────────────────────────────────┐ │
│ │ FarmService LandService HouseService │ │
│ │ SeedService CropService │ │
│ └─────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────┤
│ 业务层 (Logic) │
│ ┌─────────────────────────────────────────────┐ │
│ │ Land/ House/ Seed/ Crop/ Disaster/ │ │
│ └─────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────┤
│ 数据层 (Data) │
│ ┌─────────────────┐ ┌─────────────────────┐ │
│ │ Models │ │ Repositorys │ │
│ └─────────────────┘ └─────────────────────┘ │
└─────────────────────────────────────────────────────┘
3.2 各层职责
3.2.1 表现层 (Presentation)
表现层负责与用户交互，包括后台管理界面和API接口：
- AdminControllers：后台管理控制器，提供管理界面
- Land/：土地管理控制器
- House/：房屋管理控制器
- Seed/：种子管理控制器
- Crop/：作物管理控制器
- Helper/：辅助类，如表格、表单构建器等
3.2.2 服务层 (Service)
服务层是模块对外的接口，提供高级功能，封装业务逻辑：
FarmService：整合服务，提供跨领域功能
public function initUserFarm(int $userId): bool; public function getFarmOverview(int $userId): array; public function processScheduledTasks(): array;LandService：土地相关服务
public function getUserLands(int $userId): array; public function upgradeLand(int $landId, int $targetType): bool;HouseService：房屋相关服务
public function getHouseInfo(int $userId): array; public function upgradeHouse(int $userId): bool;SeedService：种子相关服务
public function getSeedList(array $filters = []): array; public function processMysterySeeds(int $mysterySeedId): int;CropService：作物相关服务
public function plantCrop(int $landId, int $seedId): array; public function harvestCrop(int $cropId): array;
3.2.3 业务层 (Logic)
业务层处理具体的业务逻辑，实现核心算法：
Land/LandLogic：土地业务逻辑
public function calculateOutputBonus(FarmLand $land): float; public function canHaveMoreSpecialLand(int $userId, int $landType): bool;House/HouseLogic：房屋业务逻辑
public function calculateOutputBonus(int $houseLevel): float; public function shouldDowngrade(FarmUser $farmUser): bool;Seed/SeedLogic：种子业务逻辑
public function getRandomSeedId(int $mysterySeedId): int; public function getSeedGrowthTimes(FarmSeed $seed): array;Crop/CropLogic：作物业务逻辑
public function calculateOutput(FarmCrop $crop, FarmLand $land, int $houseLevel): int; public function updateGrowthStage(FarmCrop $crop): bool;Disaster/DisasterLogic：灾害业务逻辑
public function generateDisaster(FarmCrop $crop, FarmLand $land): ?array; public function calculateDisasterImpact(array $disasters): float;
3.2.4 数据层 (Data)
数据层定义数据结构和关系，负责数据的存取：
Models：数据模型，定义表结构和关系
- FarmUser：用户农场信息
- FarmLand：土地信息
- FarmCrop：作物信息
- FarmSeed：种子信息
- FarmHouseConfig：房屋配置
- FarmHarvestLog：收获记录
Repositorys：数据仓库，封装数据访问逻辑
- FarmUserRepository：用户农场数据仓库
- FarmLandRepository：土地数据仓库
- FarmCropRepository：作物数据仓库
- FarmSeedRepository：种子数据仓库
- FarmHouseConfigRepository：房屋配置数据仓库
- FarmHarvestLogRepository：收获记录数据仓库
3.3 依赖关系
模块内部依赖关系遵循依赖倒置原则：
- 表现层 依赖 服务层
- 服务层 依赖 业务层 和 数据层
- 业务层 依赖 数据层
外部模块依赖通过服务层接口实现：
- 其他模块通过 服务层 接口调用农场模块功能
- 农场模块通过依赖注入调用其他模块的服务
3.4 事件系统
农场模块使用事件系统实现模块间的松耦合通信：
发出的事件：
- CropPlantedEvent：作物种植事件
- CropHarvestedEvent：作物收获事件
- LandUpgradedEvent：土地升级事件
- HouseUpgradedEvent：房屋升级事件
- DisasterOccurredEvent：灾害发生事件
监听的事件：
- ItemChangedEvent：物品变更事件
- PetSkillUsedEvent：宠物技能使用事件
4. 关键流程
4.1 种植流程
- 用户选择空闲土地
- 选择要种植的种子
- 系统验证用户拥有该种子
- 创建作物记录，设置初始生长阶段
- 计算各阶段结束时间
- 消耗用户种子物品
- 触发作物种植事件
4.2 生长与灾害流程
- 定时任务检查作物生长状态
- 根据当前时间更新作物生长阶段
- 在适当阶段随机生成灾害
- 用户可使用道具或宠物技能处理灾害
- 灾害影响最终产量计算
4.3 收获流程
- 用户选择成熟作物收获
- 系统验证作物状态
- 计算最终产量（基础产量 × 土地加成 × 房屋加成 × (1 - 灾害减产)）
- 将收获物品添加到用户背包
- 记录收获日志
- 重置土地状态为空闲
- 触发作物收获事件
4.4 土地升级流程
- 用户选择要升级的土地
- 系统验证土地当前类型和用户等级
- 检查用户是否拥有足够的升级材料
- 消耗升级材料
- 更新土地类型
- 触发土地升级事件
4.5 房屋升级流程
- 用户选择升级房屋
- 系统验证当前房屋等级
- 检查用户是否拥有足够的升级材料
- 消耗升级材料
- 更新房屋等级和最后升级时间
- 触发房屋升级事件
5. 与其他模块的交互
农场模块作为核心玩法模块，需要与多个其他模块进行交互，形成完整的游戏生态系统。
5.1 与GameItems模块的交互
农场模块与物品模块的交互是最频繁的，主要包括：
- 种子物品管理：获取种子物品信息、消耗种子进行种植
- 收获物品管理：将收获的作物添加到用户背包
- 道具使用：使用化肥加速生长、使用工具处理灾害
- 材料消耗：升级土地和房屋时消耗材料物品
5.1.1 物品操作接口
农场模块需要调用物品模块的以下接口：
// 检查用户是否拥有足够的物品
$hasItem = $this->itemService->checkUserItem($userId, $itemId, $amount);
// 消耗用户物品
$result = $this->itemService->consumeUserItem($userId, $itemId, $amount, $reason);
// 添加物品到用户背包
$result = $this->itemService->addUserItem($userId, $itemId, $amount, $reason);
// 获取物品信息
$itemInfo = $this->itemService->getItemInfo($itemId);
详细的实现示例请参考各功能模块文档中的物品交互部分。
5.2 与Pet模块的交互
宠物可以辅助农场种植，主要交互包括：
- 自动操作：宠物可以自动收菜、播种、处理灾害等
- 属性加成：宠物可以提供产量加成、减少灾害概率等
- 技能效果：特殊宠物技能可能影响作物生长和产量
- 事件监听：农场模块监听宠物技能使用事件，执行相应操作
5.3 与User模块的交互
用户模块提供基础的用户信息和权限管理：
- 用户验证：验证用户身份和操作权限
- 用户初始化：新用户注册时初始化农场数据
- 用户状态：根据用户状态（如VIP等级）提供不同的农场特权
- 用户统计：记录用户的农场活动数据用于统计分析
5.4 与Task模块的交互
任务系统与农场活动紧密结合：
- 任务触发：种植、收获等农场活动可以触发或完成任务
- 任务奖励：完成任务可以获得种子、化肥等农场相关物品
- 成就系统：记录农场相关的成就，如首次种植、收获数量等
- 数据提供：向任务系统提供农场活动数据用于任务判定
5.5 与Team模块的交互
农场模块与团队模块的交互主要围绕收益分成和达人加成展开：
- 收益分成：作物收获时触发事件，团队模块计算并分配收益给推荐人
- 达人加成：达人等级影响农场产出，提高团队整体收益
- 团队任务：支持团队成员协同完成农场任务
- 直间推收益：实现"直间推播种收获贡献百分比农作物收益"的核心功能
- 事件驱动：通过事件机制实现模块间松耦合交互
5.5.1 收益分成流程
- 用户收获作物，获得原始收益
- 农场模块触发
CropHarvestedEvent事件 - 团队模块监听该事件，获取收益信息
- 团队模块查询用户的推荐关系
- 根据推荐关系和达人等级计算分成
- 将分成收益添加到推荐人账户
- 记录分成明细
5.5.2 达人加成应用
农场模块在计算作物最终产量时，会调用团队模块的接口获取达人加成：
// 计算最终产量
$finalOutput = $baseOutput * (1 + $landBonus) * (1 + $houseBonus) * (1 - $disasterImpact) * (1 + $talentBonus);
其中$talentBonus就是从团队模块获取的达人产出加成。
5.6 与其他可能的模块交互
- 商店模块：购买种子、工具、化肥等农场物品
- 社交模块：好友互访、赠送农产品等社交功能
- 活动模块：参与农场相关的限时活动
- 排行榜模块：农场产量、等级等排行榜数据
6. 扩展性考虑
6.1 土地类型扩展
预留特殊土地类型的扩展空间，支持未来添加新的土地类型。
6.2 种子类型扩展
设计灵活的种子属性系统，支持添加新的种子类型和属性。
6.3 灾害系统扩展
灾害系统设计为可扩展的，支持添加新的灾害类型和影响机制。
6.4 季节系统预留
预留季节系统的接入点，为未来可能的季节特性做准备。
7. 性能与安全考虑
7.1 性能优化
- 使用定时任务处理作物生长和灾害，避免实时计算
- 合理设计索引，优化查询性能
- 缓存热点数据，如种子配置、房屋配置等
7.2 安全措施
- 所有操作前验证用户权限和数据有效性
- 使用事务确保数据一致性
- 记录关键操作日志，便于审计和问题排查
- 防止刷单和作弊行为的检测机制
8. 未来规划
农场模块将按照以下规划分阶段实施，确保功能逐步完善，同时保持系统的稳定性。
8.1 短期规划（1-2个月）
核心功能实现：
- 基础种植系统：实现种子种植、作物生长和收获的基本流程
- 土地管理：实现土地状态管理和基础升级功能
- 房屋系统：实现房屋等级和产出加成效果
- 基本灾害系统：实现干旱、虫害、杂草三种基本灾害
- 物品模块集成：完成与物品模块的基础集成，实现种子消耗和收获产出
技术基础：
- 完成数据库表结构设计和创建
- 实现基础的服务层和业务层逻辑
- 开发后台管理界面，支持基础配置管理
- 建立单元测试框架，确保核心功能稳定
8.2 中期规划（3-6个月）
功能扩展：
- 种子系统扩展：添加更多种子类型和特性，如神秘种子、巨化种子
- 灾害系统完善：增加更多灾害类型，完善灾害生成和影响机制
- 化肥系统：实现多种化肥类型，提供不同的加速效果
- 产量平衡：优化产量计算公式，平衡游戏经济系统
- 宠物模块集成：实现与宠物模块的集成，支持宠物辅助农场功能
系统优化：
- 实现缓存机制，提高系统性能
- 完善事件系统，实现更灵活的模块间通信
- 增强数据统计和分析功能
- 优化后台管理界面，提供更丰富的配置选项
- 扩展测试覆盖率，确保系统稳定性
8.3 长期规划（6个月以上）
高级功能：
- 季节系统：实现四季变化，不同季节适合种植不同作物
- 特殊事件：添加丰收节、自然灾害等特殊事件
- 社交功能：开发好友互访、赠送农产品等社交功能
- 成就系统：实现农场相关的成就和奖励机制
- 农场装饰：允许玩家装饰自己的农场，提供视觉效果和属性加成
系统升级：
- 实现分布式架构，支持更大规模的用户访问
- 开发数据分析工具，优化游戏平衡性
- 建立完整的监控和报警系统
- 支持多语言和国际化
- 开发API文档和开发者工具，方便第三方集成
8.4 迭代计划
| 迭代 | 时间 | 主要目标 | 里程碑 |
|---|---|---|---|
| 1.0 | 第1-2周 | 数据库设计和基础架构 | 完成数据库表创建和模型定义 |
| 1.1 | 第3-4周 | 基础种植功能 | 实现种植和收获基本流程 |
| 1.2 | 第5-6周 | 土地和房屋系统 | 完成土地和房屋升级功能 |
| 1.3 | 第7-8周 | 物品模块集成 | 完成与物品模块的基础集成 |
| 2.0 | 第3个月 | 灾害系统和化肥系统 | 实现完整的灾害和化肥功能 |
| 2.1 | 第4个月 | 种子系统扩展 | 添加神秘种子和巨化种子 |
| 2.2 | 第5-6个月 | 宠物模块集成 | 实现宠物辅助农场功能 |
| 3.0 | 第7-8个月 | 季节系统 | 实现四季变化和季节特性 |
| 3.1 | 第9-10个月 | 社交功能 | 实现好友互访和社交功能 |
| 3.2 | 第11-12个月 | 农场装饰 | 实现农场装饰和视觉效果 |
9. 总结
农场模块作为开心农场游戏的核心玩法模块，通过土地、房屋、种子和作物系统的紧密结合，为玩家提供了丰富的种植体验。模块采用分层架构设计，各层职责明确，便于维护和扩展。通过与物品、宠物等模块的集成，形成了完整的游戏生态系统。
未来，农场模块将按照规划逐步完善功能，提升用户体验，同时保持系统的稳定性和可扩展性。通过持续的优化和创新，为玩家提供更加丰富和有趣的农场玩法。