房屋系统设计文档

1. 系统概述

房屋系统是农场模块的核心组件之一，代表玩家在农场中的主要建筑。房屋等级影响土地产出、特殊土地数量和其他游戏机制，是玩家进度的重要指标。

2. 房屋等级

2.1 等级范围

房屋共有12个等级，从1级（初始）到12级（最高）。

2.2 等级属性

等级	产出加成	特殊土地上限	降级天数	升级材料
1	0%	0	不降级	木材x20
2	5%	0	7天	木材x30, 石材x10
3	10%	0	7天	木材x40, 石材x20
4	15%	0	7天	木材x50, 石材x30, 钢材x5
5	20%	0	7天	木材x60, 石材x40, 钢材x10
6	25%	0	7天	木材x70, 石材x50, 钢材x15
7	30%	2	7天	木材x80, 石材x60, 钢材x20, 钻石x5
8	35%	4	7天	木材x90, 石材x70, 钢材x25, 钻石x10
9	40%	6	7天	木材x100, 石材x80, 钢材x30, 钻石x15
10	45%	8	7天	木材x120, 石材x90, 钢材x35, 钻石x20
11	50%	10	7天	木材x140, 石材x100, 钢材x40, 钻石x25
12	60%	12	不降级	木材x160, 石材x120, 钢材x50, 钻石x30

3. 房屋功能

3.1 产出加成

房屋等级提供全局产出加成，影响所有土地的作物产量：

最终产量 = 基础产量 × (1 + 土地加成) × (1 + 房屋加成) × (1 - 灾害减产)

3.2 特殊土地解锁

房屋等级决定玩家可以拥有的特殊土地（金/蓝/紫）数量：

7级以下：不能拥有特殊土地
7级及以上：每升1级增加2块特殊土地上限

3.3 降级机制

为了鼓励玩家持续活跃，房屋设有降级机制：

如果玩家超过配置的天数（通常为7天）没有升级房屋，房屋将降1级
1级和12级房屋不会降级

4. 数据结构

4.1 用户农场表 (farm_users)

字段名	类型	说明
id	bigint	主键ID
user_id	bigint	用户ID
house_level	tinyint	房屋等级
last_upgrade_time	timestamp	最后升级时间
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

4.2 房屋等级配置表 (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	更新时间

4.3 升级材料JSON结构

{
  "materials": [
    {"item_id": 1001, "amount": 20},  // 木材x20
    {"item_id": 1002, "amount": 10}   // 石材x10
  ]
}

4.4 索引设计

主键索引：id
唯一索引：user_id（确保每个用户只有一条农场记录）
普通索引：house_level（加速查询特定等级的用户）
普通索引：last_upgrade_time（用于降级检查）

5. 核心功能

5.1 创建用户农场

/**
 * 为新用户创建农场记录
 *
 * @param int $userId 用户ID
 * @return FarmUser 创建的农场对象
 */
public function createFarmUser(int $userId): FarmUser

5.2 升级房屋

/**
 * 升级用户房屋
 *
 * @param int $userId 用户ID
 * @return bool 升级是否成功
 * @throws InsufficientMaterialsException 材料不足异常
 * @throws MaxLevelReachedException 已达最高等级异常
 */
public function upgradeHouse(int $userId): bool

5.3 获取房屋信息

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

5.4 检查并处理房屋降级

/**
 * 检查并处理房屋降级
 * 此方法应由定时任务调用
 *
 * @return int 处理的降级数量
 */
public function processHouseDowngrade(): int

6. 业务逻辑

6.1 房屋产出加成计算

/**
 * 计算房屋的产出加成
 *
 * @param int $houseLevel 房屋等级
 * @return float 产出加成系数
 */
public function calculateOutputBonus(int $houseLevel): float

6.2 特殊土地上限计算

/**
 * 计算特殊土地上限
 *
 * @param int $houseLevel 房屋等级
 * @return int 特殊土地上限
 */
public function getSpecialLandLimit(int $houseLevel): int

6.3 升级材料验证

/**
 * 验证用户是否拥有足够的升级材料
 *
 * @param int $userId 用户ID
 * @param int $targetLevel 目标等级
 * @return bool 是否拥有足够材料
 */
public function hasEnoughUpgradeMaterials(int $userId, int $targetLevel): bool

6.4 降级条件检查

/**
 * 检查用户房屋是否需要降级
 *
 * @param FarmUser $farmUser 用户农场对象
 * @return bool 是否需要降级
 */
public function shouldDowngrade(FarmUser $farmUser): bool

7. 前端交互

7.1 房屋展示

前端应展示房屋的以下信息：

当前等级（通过不同的视觉效果区分）
产出加成百分比
特殊土地上限
距离降级的剩余天数
下一级所需材料

7.2 房屋操作

前端应提供以下房屋操作：

升级：消耗材料升级房屋
查看详情：查看房屋各项属性详情
查看升级历史：查看房屋升级记录

8. 与其他系统的交互

8.1 与土地系统的交互

房屋等级限制特殊土地的数量
房屋等级影响土地的整体产出

8.2 与物品系统的交互

8.2.1 基本交互

升级房屋消耗物品系统中的材料
房屋升级可能触发物品奖励

8.2.2 房屋升级示例

房屋升级时需要消耗对应的材料物品：

/**
 * 升级用户房屋
 */
public function upgradeHouse(int $userId): bool
{
    return DB::transaction(function () use ($userId) {
        // 获取用户农场信息
        $farmUser = $this->farmUserRepository->findByUserId($userId);
        if (!$farmUser) {
            throw new FarmUserNotFoundException("用户农场信息不存在");
        }

        $currentLevel = $farmUser->house_level;
        $nextLevel = $currentLevel + 1;

        // 验证是否已达最高等级
        if ($currentLevel >= 12) {
            throw new MaxLevelReachedException("房屋已达最高等级");
        }

        // 获取升级所需材料
        $houseConfig = $this->houseConfigRepository->findByLevel($nextLevel);
        $materials = json_decode($houseConfig->upgrade_materials, true)['materials'];

        // 检查用户是否拥有足够的材料
        foreach ($materials as $material) {
            $hasItem = $this->itemService->checkUserItem(
                $userId,
                $material['item_id'],
                $material['amount']
            );
            if (!$hasItem) {
                throw new InsufficientMaterialsException("材料不足");
            }
        }

        // 消耗材料
        foreach ($materials as $material) {
            $this->itemService->consumeUserItem(
                $userId,
                $material['item_id'],
                $material['amount'],
                "升级房屋"
            );
        }

        // 更新房屋等级和最后升级时间
        $this->farmUserRepository->update($farmUser->id, [
            'house_level' => $nextLevel,
            'last_upgrade_time' => now()
        ]);

        // 触发房屋升级事件
        event(new HouseUpgradedEvent($userId, $currentLevel, $nextLevel));

        return true;
    });
}

8.2.3 获取升级材料示例

/**
 * 获取房屋升级所需材料
 */
public function getHouseUpgradeMaterials(int $userId): array
{
    // 获取用户当前房屋等级
    $farmUser = $this->farmUserRepository->findByUserId($userId);
    if (!$farmUser) {
        throw new FarmUserNotFoundException("用户农场信息不存在");
    }

    $currentLevel = $farmUser->house_level;
    $nextLevel = $currentLevel + 1;

    // 验证是否已达最高等级
    if ($currentLevel >= 12) {
        return [
            'can_upgrade' => false,
            'reason' => '房屋已达最高等级',
            'materials' => []
        ];
    }

    // 获取下一级房屋配置
    $houseConfig = $this->houseConfigRepository->findByLevel($nextLevel);
    $materials = json_decode($houseConfig->upgrade_materials, true)['materials'];

    // 检查用户拥有的材料数量
    $materialStatus = [];
    foreach ($materials as $material) {
        $itemInfo = $this->itemService->getItemInfo($material['item_id']);
        $userAmount = $this->itemService->getUserItemAmount($userId, $material['item_id']);

        $materialStatus[] = [
            'item_id' => $material['item_id'],
            'name' => $itemInfo['name'],
            'icon' => $itemInfo['icon'],
            'required' => $material['amount'],
            'owned' => $userAmount,
            'sufficient' => $userAmount >= $material['amount']
        ];
    }

    return [
        'can_upgrade' => true,
        'current_level' => $currentLevel,
        'next_level' => $nextLevel,
        'materials' => $materialStatus
    ];
}

8.3 与任务系统的交互

房屋升级可能是任务完成条件
达到特定房屋等级可能解锁新任务

9. 扩展性考虑

9.1 房屋外观

未来可以添加房屋外观系统，允许玩家自定义房屋样式，提供视觉效果和可能的额外属性加成。

9.2 房屋功能扩展

随着游戏发展，可以为房屋添加更多功能：

仓库功能：增加物品存储上限
加工功能：解锁物品加工能力
社交功能：允许好友参观和互动

9.3 房屋特殊效果

可以为不同等级的房屋添加特殊效果：

灾害抵抗：减少农场灾害发生概率
生长加速：作物生长速度提升
特殊产出：有几率获得额外产出

10. 实现注意事项

10.1 数据一致性

使用事务确保房屋升级和材料消耗的原子性
定期检查用户房屋等级与特殊土地数量的一致性

10.2 性能考虑

缓存房屋配置数据，避免频繁查询数据库
降级检查应使用批处理方式，避免单次处理过多数据

10.3 安全措施

验证所有房屋操作的合法性
记录关键操作日志，便于审计和问题排查
防止刷单和作弊行为的检测机制

房屋系统.md 10 KB History Raw