kknongchang_2506/app/Module/Farm/Docs/模块接口.md

农场模块接口文档

1. 概述

本文档描述了农场模块对外提供的服务接口，包括土地管理、房屋管理、种子与作物管理等功能。这些接口供其他模块调用，实现跨模块功能集成。

2. 服务类列表

农场模块对外提供以下主要服务类：

1. FarmService - 农场综合服务，提供跨领域功能
2. LandService - 土地相关服务
3. HouseService - 房屋相关服务
4. CropService - 作物相关服务
5. SeedService - 种子相关服务

3. FarmService 接口

3.1 初始化用户农场

/**
 * 初始化新用户的农场
 * 创建农场记录和初始土地
 * 
 * @param int $userId 用户ID
 * @return bool 初始化是否成功
 */
public function initUserFarm(int $userId): bool;

3.2 获取用户农场概览

/**
 * 获取用户农场概览信息
 * 包括房屋等级、土地数量、作物数量等
 * 
 * @param int $userId 用户ID
 * @return array 农场概览信息
 */
public function getFarmOverview(int $userId): array;

3.3 获取用户农场详情

/**
 * 获取用户农场详细信息
 * 包括房屋信息、所有土地和作物详情
 * 
 * @param int $userId 用户ID
 * @return array 农场详细信息
 */
public function getFarmDetails(int $userId): array;

3.4 检查并处理定时任务

/**
 * 检查并处理农场相关的定时任务
 * 包括作物生长、灾害生成、房屋降级等
 * 
 * @return array 处理结果统计
 */
public function processScheduledTasks(): array;

4. LandService 接口

4.1 获取用户土地列表

/**
 * 获取用户的所有土地
 * 
 * @param int $userId 用户ID
 * @return array 土地列表
 */
public function getUserLands(int $userId): array;

4.2 获取土地详情

/**
 * 获取土地详细信息
 * 包括当前种植的作物和状态
 * 
 * @param int $landId 土地ID
 * @return array 土地详情
 */
public function getLandDetail(int $landId): array;

4.3 升级土地

/**
 * 升级土地
 * 
 * @param int $landId 土地ID
 * @param int $targetType 目标土地类型
 * @return bool 升级是否成功
 * @throws Exception 升级失败时抛出异常
 */
public function upgradeLand(int $landId, int $targetType): bool;

4.4 检查特殊土地限制

/**
 * 检查用户是否可以拥有更多特殊土地
 * 
 * @param int $userId 用户ID
 * @param int $landType 目标土地类型
 * @return bool 是否可以拥有
 */
public function canHaveMoreSpecialLand(int $userId, int $landType): bool;

5. HouseService 接口

5.1 获取用户房屋信息

/**
 * 获取用户房屋信息
 * 
 * @param int $userId 用户ID
 * @return array 房屋信息
 */
public function getHouseInfo(int $userId): array;

5.2 升级房屋

/**
 * 升级用户房屋
 * 
 * @param int $userId 用户ID
 * @return bool 升级是否成功
 * @throws Exception 升级失败时抛出异常
 */
public function upgradeHouse(int $userId): bool;

5.3 获取房屋升级所需材料

/**
 * 获取房屋升级所需材料
 * 
 * @param int $userId 用户ID
 * @return array 升级所需材料
 */
public function getHouseUpgradeMaterials(int $userId): array;

5.4 检查并处理房屋降级

/**
 * 检查并处理房屋降级
 * 
 * @param int $userId 用户ID
 * @return bool 是否发生降级
 */
public function checkAndProcessHouseDowngrade(int $userId): bool;

6. CropService 接口

6.1 种植作物

/**
 * 在指定土地上种植作物
 * 
 * @param int $landId 土地ID
 * @param int $seedId 种子ID
 * @return array 种植结果
 * @throws Exception 种植失败时抛出异常
 */
public function plantCrop(int $landId, int $seedId): array;

6.2 使用化肥

/**
 * 对作物使用化肥
 * 
 * @param int $cropId 作物ID
 * @param int $fertilizerId 化肥物品ID
 * @return bool 使用是否成功
 * @throws Exception 使用失败时抛出异常
 */
public function useFertilizer(int $cropId, int $fertilizerId): bool;

6.3 处理灾害

/**
 * 处理作物灾害
 * 
 * @param int $cropId 作物ID
 * @param int $disasterType 灾害类型
 * @param int $toolId 处理工具物品ID
 * @return bool 处理是否成功
 * @throws Exception 处理失败时抛出异常
 */
public function handleDisaster(int $cropId, int $disasterType, int $toolId): bool;

6.4 收获作物

/**
 * 收获作物
 * 
 * @param int $cropId 作物ID
 * @return array 收获结果，包括产出数量
 * @throws Exception 收获失败时抛出异常
 */
public function harvestCrop(int $cropId): array;

6.5 铲除作物

/**
 * 铲除作物
 * 
 * @param int $cropId 作物ID
 * @return bool 铲除是否成功
 * @throws Exception 铲除失败时抛出异常
 */
public function removeCrop(int $cropId): bool;

6.6 获取作物状态

/**
 * 获取作物状态
 * 
 * @param int $cropId 作物ID
 * @return array 作物状态信息
 */
public function getCropStatus(int $cropId): array;

7. SeedService 接口

7.1 获取种子列表

/**
 * 获取所有种子列表
 * 
 * @param array $filters 过滤条件
 * @return array 种子列表
 */
public function getSeedList(array $filters = []): array;

7.2 获取种子详情

/**
 * 获取种子详细信息
 * 
 * @param int $seedId 种子ID
 * @return array 种子详情
 */
public function getSeedDetail(int $seedId): array;

7.3 处理神秘种子

/**
 * 处理神秘种子的随机转化
 * 
 * @param int $mysterySeedId 神秘种子ID
 * @return int 转化后的种子ID
 */
public function processMysterySeeds(int $mysterySeedId): int;

7.4 获取用户种子库存

/**
 * 获取用户的种子库存
 * 
 * @param int $userId 用户ID
 * @return array 种子库存列表
 */
public function getUserSeedInventory(int $userId): array;

8. 事件系统

农场模块通过事件系统与其他模块进行松耦合通信。

8.1 发出的事件

8.1.1 作物种植事件

/**
 * 作物种植事件
 * 
 * @param int $userId 用户ID
 * @param int $landId 土地ID
 * @param int $seedId 种子ID
 * @param int $cropId 作物ID
 */
class CropPlantedEvent

8.1.2 作物收获事件

/**
 * 作物收获事件
 * 
 * @param int $userId 用户ID
 * @param int $landId 土地ID
 * @param int $cropId 作物ID
 * @param int $seedId 种子ID
 * @param int $outputAmount 产出数量
 */
class CropHarvestedEvent

8.1.3 土地升级事件

/**
 * 土地升级事件
 * 
 * @param int $userId 用户ID
 * @param int $landId 土地ID
 * @param int $oldType 旧土地类型
 * @param int $newType 新土地类型
 */
class LandUpgradedEvent

8.1.4 房屋升级事件

/**
 * 房屋升级事件
 * 
 * @param int $userId 用户ID
 * @param int $oldLevel 旧等级
 * @param int $newLevel 新等级
 */
class HouseUpgradedEvent

8.1.5 灾害发生事件

/**
 * 灾害发生事件
 * 
 * @param int $userId 用户ID
 * @param int $cropId 作物ID
 * @param int $disasterType 灾害类型
 */
class DisasterOccurredEvent

8.2 监听的事件

8.2.1 物品变更事件

/**
 * 物品变更事件监听器
 * 用于处理物品变更对农场的影响
 */
class ItemChangedListener

8.2.2 宠物技能使用事件

/**
 * 宠物技能使用事件监听器
 * 用于处理宠物技能对农场的影响
 */
class PetSkillUsedListener

9. 错误处理

所有服务方法在遇到错误时会抛出异常，异常类型包括：

1. FarmException - 农场模块基础异常
2. LandException - 土地相关异常
3. HouseException - 房屋相关异常
4. CropException - 作物相关异常
5. SeedException - 种子相关异常

调用方需要捕获这些异常并进行适当处理。

10. 使用示例

10.1 初始化用户农场

try {
    $farmService = app(FarmService::class);
    $result = $farmService->initUserFarm($userId);
    if ($result) {
        // 初始化成功
    }
} catch (FarmException $e) {
    // 处理异常
}

10.2 种植作物

try {
    $cropService = app(CropService::class);
    $result = $cropService->plantCrop($landId, $seedId);
    // 处理种植结果
} catch (CropException $e) {
    // 处理异常
}

10.3 收获作物

try {
    $cropService = app(CropService::class);
    $result = $cropService->harvestCrop($cropId);
    // 处理收获结果
} catch (CropException $e) {
    // 处理异常
}

10.4 升级房屋

try {
    $houseService = app(HouseService::class);
    $result = $houseService->upgradeHouse($userId);
    if ($result) {
        // 升级成功
    }
} catch (HouseException $e) {
    // 处理异常
}

11. 注意事项

1. 事务处理：所有涉及多个操作的方法内部都使用了数据库事务，确保数据一致性。
2. 权限验证：所有方法都会验证操作的合法性，如用户是否拥有指定的土地等。
3. 并发控制：关键操作使用了锁机制，防止并发操作导致的数据不一致。
4. 性能考虑：批量操作和定时任务设计考虑了性能因素，避免单次处理过多数据。
5. 扩展性：接口设计预留了扩展空间，支持未来添加新功能。