物品分解系统文档

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

1. 系统概述

物品分解系统允许玩家将不需要的物品分解为其他有用的材料或资源。系统采用规则驱动的设计，支持灵活的分解配置和复杂的分解逻辑。

1.1 核心特性

规则驱动：通过配置分解规则来控制分解行为
多层匹配：支持物品级别、分类级别和通用规则
稀有度支持：根据物品稀有度应用不同的分解规则
优先级控制：多个规则匹配时按优先级选择
组系统集成：使用消耗组、奖励组和条件组统一管理
兼容性保证：向后兼容旧的分解结果配置

2. 数据库结构

2.1 分解规则表 (item_dismantle_rules)

字段名	类型	说明	功能
`id`	int	规则ID，主键	唯一标识分解规则
`name`	varchar(255)	规则名称	便于管理和识别的规则名称
`code`	varchar(100)	规则编码（唯一）	程序中引用的唯一标识符
`description`	text	规则描述	详细说明规则的用途和效果
`item_id`	int	物品ID	指定特定物品：当设置时，规则仅适用于该物品
`category_id`	int	分类ID	指定物品分类：当item_id为空时，规则适用于该分类下的所有物品
`consume_group_id`	int	消耗组ID	额外消耗：分解时需要额外消耗的资源（如分解工具、手续费等）
`reward_group_id`	int	奖励组ID	分解奖励：分解成功后获得的奖励（替代旧的分解结果表）
`condition_group_id`	int	条件组ID	使用条件：使用该分解规则需要满足的条件（如等级、技能等）
`min_rarity`	tinyint	最小适用稀有度	稀有度范围下限：规则适用的最低稀有度等级
`max_rarity`	tinyint	最大适用稀有度	稀有度范围上限：规则适用的最高稀有度等级
`priority`	int	规则优先级	匹配优先级：多个规则匹配时，优先级高的规则生效
`sort_order`	int	排序权重	显示排序：在管理界面中的显示顺序
`is_active`	tinyint	是否激活	规则开关：控制规则是否生效

2.2 分解结果表 (item_dismantle_results) - 兼容性保留

字段名	类型	说明
`rule_id`	int	分解规则ID
`result_item_id`	int	结果物品ID
`min_quantity`	int	最小数量
`max_quantity`	int	最大数量
`base_chance`	decimal(5,2)	基础获取概率
`rarity_factor`	decimal(5,2)	稀有度影响因子
`quality_factor`	decimal(5,2)	品质影响因子

3. 字段功能详解

3.1 item_id - 物品ID

功能：指定规则适用的特定物品

使用场景：

为特殊物品设置专门的分解规则
覆盖分类规则，为特定物品提供不同的分解效果
设置限定物品的分解条件

匹配优先级：最高（优先于分类规则和通用规则）

示例：

-- 为传说武器设置特殊分解规则
INSERT INTO item_dismantle_rules (name, item_id, reward_group_id, priority)
VALUES ('传说武器分解', 1001, 100, 100);

3.2 reward_group_id - 奖励组ID

功能：定义分解成功后获得的奖励

使用场景：

设置分解后获得的物品和数量
配置随机奖励和权重
支持多种奖励类型（物品、货币、经验等）

优势：

支持复杂的奖励逻辑
可复用奖励配置
统一的奖励管理

示例：

-- 奖励组：分解铁剑获得铁锭
-- 在game_reward_groups表中配置奖励组
-- 在game_reward_items表中配置具体奖励项

3.3 consume_group_id - 消耗组ID

功能：定义分解时需要额外消耗的资源

使用场景：

分解工具消耗（如分解锤、分解药水）
分解手续费（金币、积分等）
分解材料消耗（如催化剂）

特点：

可选字段，不设置则无额外消耗
支持多种消耗类型
消耗不足时分解失败

示例：

-- 消耗组：分解高级装备需要分解工具
-- 在game_consume_groups表中配置消耗组
-- 在game_consume_items表中配置具体消耗项

3.4 condition_group_id - 条件组ID

功能：定义使用分解规则需要满足的条件

使用场景：

等级限制（玩家等级、技能等级）
物品持有条件（需要拥有特定物品）
任务完成条件（完成特定任务）
时间限制（特定时间段内可用）

特点：

可选字段，不设置则无条件限制
支持复杂的条件逻辑
条件不满足时无法使用该规则

3.5 min_rarity & max_rarity - 稀有度范围

功能：定义规则适用的稀有度范围

⚠️ 当前问题：

分解规则表中有稀有度字段
但物品表(item_items)中没有rarity字段
导致稀有度匹配功能无法正常工作

期望功能：

根据物品稀有度选择合适的分解规则
不同稀有度的物品有不同的分解效果
支持稀有度范围匹配

需要修复：

在物品表中添加rarity字段
在分解规则匹配逻辑中加入稀有度判断

3.6 priority - 规则优先级

功能：控制多个规则匹配时的选择顺序

匹配逻辑：

数值越大，优先级越高
优先级相同时，按ID降序排列
只有最高优先级的规则会被应用

使用场景：

特殊事件期间的临时规则
VIP玩家的专属分解规则
节日活动的加成规则

4. 规则匹配算法

4.1 当前实现

private static function getDismantleRule(int $itemId): ?ItemDismantleRule
{
    $item = Item::find($itemId);
    if (!$item) return null;

    // 1. 优先查找特定物品规则
    $rule = ItemDismantleRule::where('item_id', $itemId)
        ->where('is_active', true)
        ->orderBy('priority', 'desc')
        ->first();

    if ($rule) return $rule;

    // 2. 查找分类规则
    $rule = ItemDismantleRule::where('category_id', $item->category_id)
        ->where('is_active', true)
        ->orderBy('priority', 'desc')
        ->first();

    return $rule;
}

4.2 期望实现（包含稀有度）

private static function getDismantleRule(int $itemId): ?ItemDismantleRule
{
    $item = Item::find($itemId);
    if (!$item) return null;

    $rarity = $item->rarity ?? 1; // 需要添加rarity字段

    // 1. 特定物品规则（包含稀有度匹配）
    $rule = ItemDismantleRule::where('item_id', $itemId)
        ->where('is_active', true)
        ->where('min_rarity', '<=', $rarity)
        ->where('max_rarity', '>=', $rarity)
        ->orderBy('priority', 'desc')
        ->first();

    if ($rule) return $rule;

    // 2. 分类规则（包含稀有度匹配）
    $rule = ItemDismantleRule::where('category_id', $item->category_id)
        ->whereNull('item_id')
        ->where('is_active', true)
        ->where('min_rarity', '<=', $rarity)
        ->where('max_rarity', '>=', $rarity)
        ->orderBy('priority', 'desc')
        ->first();

    // 3. 通用规则（稀有度匹配）
    if (!$rule) {
        $rule = ItemDismantleRule::whereNull('item_id')
            ->whereNull('category_id')
            ->where('is_active', true)
            ->where('min_rarity', '<=', $rarity)
            ->where('max_rarity', '>=', $rarity)
            ->orderBy('priority', 'desc')
            ->first();
    }

    return $rule;
}

5. 代码一致性检查

5.1 发现的问题

稀有度字段缺失：
- 分解规则表有min_rarity和max_rarity字段
- 物品表缺少rarity字段
- 导致稀有度匹配功能无法使用
规则匹配不完整：
- 当前只匹配item_id和category_id
- 没有稀有度匹配逻辑
- 没有通用规则支持
组系统集成不完整：
- 模型中定义了组关系
- 但在实际分解逻辑中可能未完全使用

5.2 建议修复

添加物品稀有度字段
完善规则匹配算法
确保组系统完全集成
添加详细的测试用例

6. 使用示例

6.1 基础分解规则

-- 创建木材分解规则
INSERT INTO item_dismantle_rules (
    name, code, description,
    category_id, reward_group_id,
    min_rarity, max_rarity, priority, is_active
) VALUES (
    '基础木材分解', 'basic_wood_dismantle', '分解基础木材获得木屑',
    1, 10, 1, 3, 10, 1
);

6.2 高级分解规则

-- 创建传说装备分解规则
INSERT INTO item_dismantle_rules (
    name, code, description,
    item_id, consume_group_id, reward_group_id, condition_group_id,
    min_rarity, max_rarity, priority, is_active
) VALUES (
    '传说装备分解', 'legendary_equipment_dismantle', '分解传说装备获得稀有材料',
    1001, 5, 20, 3, 5, 5, 100, 1
);

7. 代码修复状态

7.1 已修复的问题

✅ 规则匹配算法优化：
- 更新了DismantleService::getDismantleRule()方法
- 添加了稀有度匹配逻辑（从numeric_attributes中获取）
- 支持三层匹配：物品级别 → 分类级别 → 通用规则
✅ 组系统集成：
- 在模型中添加了组系统的关系方法
- 在业务逻辑中预留了组系统调用接口
- 临时注释了未实现的服务方法调用

7.2 待解决的问题

⚠️ 物品稀有度字段：
- 建议在物品表中添加专门的rarity字段
- 当前通过numeric_attributes获取稀有度是临时方案
⚠️ 服务层方法缺失：
- ConditionService::checkConditionGroup() 方法需要实现
- ConsumeService::checkConsumeGroup() 方法需要实现
- RewardService::generateRewards() 方法需要实现
⚠️ 数据库结构更新：
- 需要执行分解规则表的结构更新SQL
- 需要为现有数据添加默认的稀有度值

7.3 建议的修复步骤

步骤1：添加物品稀有度字段

-- 为物品表添加稀有度字段
ALTER TABLE `kku_item_items`
ADD COLUMN `rarity` tinyint DEFAULT 1 COMMENT '物品稀有度（1:普通, 2:优秀, 3:稀有, 4:史诗, 5:传说）'
AFTER `type`;

-- 添加索引
ALTER TABLE `kku_item_items`
ADD KEY `idx_rarity` (`rarity`);

步骤2：更新Item模型

// 在Item模型中添加rarity字段
protected $fillable = [
    // ... 其他字段
    'rarity',
];

protected $casts = [
    // ... 其他字段
    'rarity' => 'integer',
];

步骤3：实现缺失的服务方法

实现条件检查服务
实现消耗检查服务
实现奖励生成服务

步骤4：执行数据库更新

# 执行分解规则表结构更新
mysql -u username -p database_name < database/sql/update_item_dismantle_rules_for_groups.sql

8. 总结

物品分解系统设计合理，采用了灵活的规则驱动架构和现代的组系统。通过本次分析和修复：

8.1 系统优势

规则驱动：支持复杂的分解逻辑配置
多层匹配：物品 → 分类 → 通用的匹配策略
组系统集成：统一的消耗、奖励、条件管理
向后兼容：保留对旧系统的支持

8.2 当前状态

核心功能：✅ 基本分解功能正常
规则匹配：✅ 已优化并支持稀有度
组系统：⚠️ 部分集成，等待服务层实现
稀有度支持：⚠️ 临时方案，建议添加专门字段

8.3 推荐使用方式

当前可用：基于item_id和category_id的基础分解规则
稀有度匹配：通过numeric_attributes设置rarity值
组系统：等待服务层实现后可使用完整功能

系统整体架构优秀，只需要完善少数细节即可发挥完整功能。

物品分解系统.md 12 KB Verlauf Originalformat

物品分解系统文档

1. 系统概述

1.1 核心特性

2. 数据库结构

2.1 分解规则表 (item_dismantle_rules)

2.2 分解结果表 (item_dismantle_results) - 兼容性保留

3. 字段功能详解

3.1 item_id - 物品ID

3.2 reward_group_id - 奖励组ID

3.3 consume_group_id - 消耗组ID

3.4 condition_group_id - 条件组ID

3.5 min_rarity & max_rarity - 稀有度范围

3.6 priority - 规则优先级

4. 规则匹配算法

4.1 当前实现

4.2 期望实现（包含稀有度）

5. 代码一致性检查

5.1 发现的问题

5.2 建议修复

6. 使用示例

6.1 基础分解规则

6.2 高级分解规则

7. 代码修复状态

7.1 已修复的问题

7.2 待解决的问题

7.3 建议的修复步骤

步骤1：添加物品稀有度字段

步骤2：更新Item模型

步骤3：实现缺失的服务方法

步骤4：执行数据库更新

8. 总结

8.1 系统优势

8.2 当前状态

8.3 推荐使用方式

物品分解系统.md 12 KB

Verlauf Originalformat