消耗组系统

最后更新时间：2024年5月

1. 概述

消耗组系统是 Game 模块提供的一个用于管理和执行消耗操作的功能。它允许将多种不同类型的消耗（如物品、货币等）组合在一起，形成一个消耗组，然后统一执行消耗操作。这种设计使得游戏中的各种消耗操作更加灵活和可配置。

2. 系统架构

消耗组系统由以下几个部分组成：

2.1 数据模型

GameConsumeGroup: 消耗组模型，包含消耗组的基本信息，如名称、编码和描述。
GameConsumeItem: 消耗项模型，包含具体的消耗内容，如消耗类型、目标ID、数量等。

2.2 枚举类

CONSUME_TYPE: 消耗类型枚举，定义了支持的消耗类型，如物品、货币等。

2.3 服务类

ConsumeService: 消耗服务类，提供检查消耗条件和执行消耗的功能。

2.4 后台管理

GameConsumeGroupController: 消耗组管理控制器，用于在后台管理消耗组。
GameConsumeItemController: 消耗项管理控制器，用于在后台管理消耗项。

3. 数据库结构

3.1 消耗组表 (game_consume_groups)

字段名	类型	说明
id	int	主键
name	varchar	消耗组名称
code	varchar	消耗组编码（唯一）
description	text	消耗组描述
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

3.2 消耗项表 (game_consume_items)

字段名	类型	说明
id	int	主键
group_id	int	消耗组ID，外键关联game_consume_groups表
consume_type	tinyint	消耗类型（1:物品, 2:币种, 3:账户种类, 4:多账户种类）
target_id	int	目标ID（物品ID、货币ID、账户种类ID等，根据consume_type解释）
param1	int	参数1（根据consume_type不同含义，如物品的品质、货币的来源等）
param2	int	参数2（根据consume_type不同含义，如物品的绑定状态、货币的类型等）
quantity	int	数量
extra_data	json	额外数据（JSON格式，可存储特定消耗类型的额外参数，如多账户种类的ID列表）
created_at	timestamp	创建时间
updated_at	timestamp	更新时间

4. 使用方法

4.1 创建消耗组

在后台管理界面中，进入"消耗组管理"页面。
点击"新增"按钮，填写消耗组的名称、编码和描述，然后保存。
在消耗组详情页面，可以查看和管理该消耗组下的消耗项。

4.2 添加消耗项

在后台管理界面中，进入"消耗项管理"页面。
点击"新增"按钮，选择所属的消耗组，填写消耗类型、目标ID、数量等信息，然后保存。
根据不同的消耗类型，填写相应的参数和额外数据。

4.3 检查消耗条件

在代码中，可以使用 ConsumeService::checkConsume 方法检查用户是否满足消耗条件：

$result = ConsumeService::checkConsume($userId, 'consume_group_code');
if ($result['success']) {
    // 用户满足消耗条件
} else {
    // 用户不满足消耗条件，$result['message'] 包含错误信息
}

4.4 执行消耗

在代码中，可以使用 ConsumeService::executeConsume 方法执行消耗操作：

$result = ConsumeService::executeConsume($userId, 'consume_group_code', 'source', $sourceId);
if ($result['success']) {
    // 消耗执行成功
} else {
    // 消耗执行失败，$result['message'] 包含错误信息
}

4.5 测试消耗组功能

可以使用命令行工具测试消耗组功能：

php artisan game:test-consume {user_id} {consume_group} [--check]

参数说明：

user_id: 用户ID
consume_group: 消耗组编码或ID
--check: 可选参数，如果提供，则只检查不执行消耗

5. 消耗类型说明

5.1 物品消耗 (CONSUME_TYPE::ITEM)

target_id: 物品ID
param1: 物品品质（可选）
param2: 物品绑定状态（可选）
quantity: 消耗数量

5.2 货币消耗 (CONSUME_TYPE::CURRENCY)

target_id: 货币ID
param1: 货币来源（可选）
param2: 货币类型（可选）
quantity: 消耗数量

5.3 账户种类消耗 (CONSUME_TYPE::FUND_CONFIG)

target_id: 账户种类ID
param1: 预留参数（可选）
param2: 预留参数（可选）
quantity: 消耗数量

5.4 多账户种类消耗 (CONSUME_TYPE::FUND_CONFIGS)

target_id: 主账户种类ID（第一个消耗的账户）
param1: 预留参数（可选）
param2: 预留参数（可选）
quantity: 消耗数量
extra_data: JSON格式的额外数据，包含：
- fund_config_ids: 数组，包含额外的账户种类ID列表

多账户种类消耗说明：

系统会按照配置的顺序依次从各个账户中扣除资金
首先从 target_id 指定的主账户扣除
如果主账户余额不足，则依次从 extra_data.fund_config_ids 中的账户扣除
所有账户的总余额必须满足消耗需求
配置时应确保选择的账户种类具有等价值的资金

配置示例：

{
  "target_id": 1,
  "quantity": 1000,
  "extra_data": {
    "fund_config_ids": [2, 3, 4]
  }
}

这个配置表示：消耗1000单位资金，优先从账户种类1扣除，不足时依次从账户种类2、3、4扣除。

6. 注意事项

消耗组编码必须唯一，建议使用有意义的编码，如 upgrade_house_level_2。
执行消耗操作时，会先检查用户是否满足所有消耗条件，只有全部满足才会执行消耗。
执行消耗操作是在事务中进行的，如果任何一个消耗项执行失败，整个事务会回滚。
在添加消耗项时，请确保目标ID（如物品ID、货币ID）是有效的。

消耗组系统.md 5.8 KB História Raw