物品合成系统文档

最后更新时间：2025年5月29日

1. 系统概述

物品合成系统是一个混合架构的系统，同时支持传统的材料表模式和新的组系统模式：

1.1 双重架构设计

传统模式（当前主要使用）

ItemRecipeMaterial：通过材料表定义合成所需的具体材料
直接字段：使用result_item_id、coin_cost、level_required等字段
JSON配置：使用unlock_condition等JSON字段存储复杂条件

组系统模式（预留扩展）

消耗组：通过consume_group_id管理合成时需要消耗的材料和资源
奖励组：通过reward_group_id管理合成成功后获得的奖励
条件组：通过condition_group_id管理解锁配方需要满足的条件

1.2 系统特点

向后兼容：保留传统字段，确保现有功能正常运行
渐进升级：可以逐步迁移到组系统，无需一次性重构
灵活配置：支持复杂的合成逻辑和条件判断

2. 数据库结构

2.1 核心表结构

2.1.1 item_recipes（合成配方表）

字段名	类型	说明	使用状态
`id`	int	配方ID，主键	✅ 使用中
`name`	varchar(255)	配方名称	✅ 使用中
`code`	varchar(100)	配方编码（唯一）	✅ 使用中
`description`	text	配方描述	✅ 使用中
`consume_group_id`	int	消耗组ID	⚠️ 预留字段
`reward_group_id`	int	奖励组ID	⚠️ 预留字段
`condition_group_id`	int	条件组ID	⚠️ 预留字段
`result_item_id`	int	产出物品ID	✅ 使用中
`result_min_quantity`	int	最小产出数量	✅ 使用中
`result_max_quantity`	int	最大产出数量	✅ 使用中
`success_rate`	decimal(5,2)	成功率（百分比）	✅ 使用中
`coin_cost`	json	货币成本	✅ 使用中
`level_required`	int	所需等级	✅ 使用中
`is_default_unlocked`	tinyint	是否默认解锁	✅ 使用中
`unlock_condition`	json	解锁条件	✅ 使用中
`cooldown_seconds`	int	冷却时间（秒）	✅ 使用中
`category_id`	int	配方分类ID	✅ 使用中
`sort_order`	int	排序权重	✅ 使用中
`is_active`	tinyint	是否激活	✅ 使用中

2.1.2 item_recipe_materials（配方材料表）

字段名	类型	说明
`id`	int	记录ID，主键
`recipe_id`	int	配方ID
`item_id`	int	材料物品ID
`quantity`	int	所需数量
`is_consumed`	tinyint	是否消耗（0:不消耗, 1:消耗）

2.1.3 item_user_recipes（用户配方解锁状态表）

字段名	类型	说明
`id`	int	记录ID，主键
`user_id`	int	用户ID
`recipe_id`	int	配方ID
`is_unlocked`	tinyint	是否已解锁
`unlock_time`	timestamp	解锁时间
`last_craft_time`	timestamp	最后合成时间
`craft_count`	int	合成次数

2.1.4 item_craft_logs（合成记录表）

字段名	类型	说明
`id`	int	记录ID，主键
`user_id`	int	用户ID
`recipe_id`	int	配方ID
`materials`	json	消耗的材料
`result_item_id`	int	获得的物品ID
`result_instance_id`	int	获得的单独属性物品ID
`result_quantity`	int	获得的物品数量
`is_success`	tinyint	是否成功
`craft_time`	timestamp	合成时间
`ip_address`	varchar(100)	操作IP地址
`device_info`	text	设备信息

2.2 数据模型关系

核心模型

ItemRecipe：合成配方模型，包含配方的基本信息
ItemRecipeMaterial：配方材料模型，定义合成所需的具体材料
ItemUserRecipe：用户配方解锁状态模型
ItemCraftLog：合成记录模型，记录所有合成操作

组系统模型（预留）

GameConsumeGroup：消耗组，定义合成时需要消耗的资源
GameRewardGroup：奖励组，定义合成成功后获得的奖励
GameConditionGroup：条件组，定义解锁配方的条件

3. 系统架构

3.1 服务层架构

3.1.1 CraftService（合成服务）

位置：app/Module/GameItems/Services/CraftService.php
功能：对外提供合成相关的服务接口
主要方法：
- craftItem() - 合成物品
- getUserAvailableRecipes() - 获取用户可合成配方列表
- unlockRecipe() - 解锁配方

3.1.2 逻辑层

Recipe Logic：app/Module/GameItems/Logics/Recipe.php - 配方相关逻辑
UserRecipe Logic：app/Module/GameItems/Logics/UserRecipe.php - 用户配方逻辑
Item Logic：app/Module/GameItems/Logics/Item.php - 物品操作逻辑

3.2 当前实现模式

3.2.1 传统材料表模式（主要使用）

创建配方步骤：

创建配方记录：在item_recipes表中创建配方
添加材料需求：在item_recipe_materials表中定义所需材料
设置产出物品：通过result_item_id等字段定义产出
配置解锁条件：通过level_required、unlock_condition等字段

配方验证流程：

检查配方状态：配方是否激活（is_active）
检查解锁状态：用户是否已解锁该配方
检查等级要求：用户等级是否满足level_required
检查冷却时间：是否在冷却期内
检查材料充足：是否有足够的材料和货币

合成执行流程：

验证配方：执行上述验证流程
消耗材料：扣除item_recipe_materials定义的材料
消耗货币：扣除coin_cost定义的货币
判断成功率：根据success_rate判断是否成功
发放奖励：如果成功，发放result_item_id定义的物品
记录日志：在item_craft_logs表中记录操作

3.2.2 组系统模式（预留扩展）

预留字段：

consume_group_id - 消耗组ID
reward_group_id - 奖励组ID
condition_group_id - 条件组ID

模型关系：

// ItemRecipe模型中已定义的关系
public function consumeGroup(): BelongsTo
public function rewardGroup(): BelongsTo
public function conditionGroup(): BelongsTo

使用方式：

// 检查条件组（代码中已预留）
if ($this->condition_group_id && $this->conditionGroup) {
    $conditionService = app(\App\Module\Game\Services\ConditionService::class);
    $conditionResult = $conditionService->checkConditionGroup($userId, $this->condition_group_id);
}

4. 代码使用示例

4.1 合成物品

use App\Module\GameItems\Services\CraftService;

// 合成物品
$result = CraftService::craftItem(
    userId: 1001,
    recipeId: 1,
    options: [
        'quantity' => 1,
        'ip_address' => '127.0.0.1',
        'device_info' => 'Web Browser'
    ]
);

if ($result) {
    echo "合成成功！";
    // $result 包含合成结果信息
} else {
    echo "合成失败！";
}

4.2 获取用户可合成配方

// 获取用户可合成的配方列表
$recipes = CraftService::getUserAvailableRecipes(
    userId: 1001,
    filters: [
        'category_id' => 1  // 可选：按分类过滤
    ]
);

foreach ($recipes as $recipe) {
    echo "配方：{$recipe->name}，成功率：{$recipe->success_rate}%\n";
}

4.3 检查配方是否可合成

$recipe = ItemRecipe::find(1);
$canCraft = $recipe->canCraftByUser(1001);

if ($canCraft['can_craft']) {
    echo "可以合成";
} else {
    echo "不能合成：" . $canCraft['reason'];
}

5. 配置示例

5.1 简单配方示例

木板制作配方：

-- 1. 创建配方
INSERT INTO item_recipes (
    name, code, description,
    result_item_id, result_min_quantity, result_max_quantity,
    success_rate, level_required, is_default_unlocked,
    cooldown_seconds, is_active
) VALUES (
    '木板制作', 'craft_wooden_plank', '将木材制作成木板',
    1002, 4, 4,  -- 产出4个木板（物品ID 1002）
    100.00, 1, 1,  -- 100%成功率，1级解锁，默认解锁
    0, 1  -- 无冷却，激活状态
);

-- 2. 添加材料需求
INSERT INTO item_recipe_materials (
    recipe_id, item_id, quantity, is_consumed
) VALUES (
    1, 1001, 1, 1  -- 需要1个木材（物品ID 1001），消耗
);

5.2 复杂配方示例

高级装备制作：

-- 1. 创建配方
INSERT INTO item_recipes (
    name, code, description,
    result_item_id, result_min_quantity, result_max_quantity,
    success_rate, coin_cost, level_required, is_default_unlocked,
    unlock_condition, cooldown_seconds, is_active
) VALUES (
    '高级装备制作', 'craft_advanced_equipment', '制作高级装备',
    2001, 1, 1,  -- 产出1个高级装备
    80.00, '{"gold": 100}', 20, 0,  -- 80%成功率，消耗100金币，20级要求，非默认解锁
    '{"skills": ["blacksmith"]}', 3600, 1  -- 需要铁匠技能，1小时冷却
);

-- 2. 添加材料需求
INSERT INTO item_recipe_materials (recipe_id, item_id, quantity, is_consumed) VALUES
(2, 1003, 5, 1),  -- 5个铁锭
(2, 1004, 2, 1);  -- 2个宝石

6. 系统特点

6.1 当前优势

成熟稳定：传统材料表模式经过充分测试，稳定可靠
功能完整：支持复杂的合成逻辑和条件判断
性能良好：直接查询，无额外的组系统开销
易于理解：数据结构清晰，便于开发和维护

6.2 扩展能力

向后兼容：保留所有传统字段，确保现有功能不受影响
渐进升级：可以逐步迁移到组系统，无需一次性重构
双重支持：同时支持传统模式和组系统模式
灵活配置：支持JSON格式的复杂条件配置

6.3 日志记录

完整记录：记录所有合成操作，包括成功和失败
详细信息：记录消耗的材料、获得的物品、操作时间等
追踪能力：支持IP地址和设备信息记录
数据分析：便于进行合成数据分析和游戏平衡调整

7. 代码一致性检查结果

7.1 ✅ 实际实现与预期一致的部分

数据库结构：表结构与模型定义完全一致
服务层架构：CraftService提供完整的合成服务
业务逻辑：合成流程、验证逻辑、日志记录等功能完整
模型关系：各模型之间的关系定义正确

7.2 ⚠️ 发现的架构特点

混合架构：同时保留传统字段和组系统字段
预留扩展：组系统相关代码已预留，但主要使用传统模式
向后兼容：确保现有功能不受影响的设计

7.3 📊 系统评估

功能完整度：⭐⭐⭐⭐⭐ (5/5) - 功能完整，逻辑清晰
代码质量：⭐⭐⭐⭐⭐ (5/5) - 代码结构良好，注释完善
扩展性：⭐⭐⭐⭐⭐ (5/5) - 预留组系统扩展，架构灵活
稳定性：⭐⭐⭐⭐⭐ (5/5) - 传统模式成熟稳定

8. 总结

物品合成系统采用了智能的混合架构设计，既保持了传统材料表模式的稳定性和性能，又为未来的组系统升级预留了完整的扩展能力。这种设计体现了优秀的软件架构思维：

渐进式演进：不破坏现有功能的前提下预留扩展空间
向后兼容：确保系统升级不影响现有业务
架构前瞻性：为未来的功能扩展做好准备

物品合成系统.md 11 KB History Raw