货币与账户概念使用指南

1. 概述

在系统中，我们有三个核心概念：

币种（Currency）：指货币的种类，如美元、人民币等，由 FundCurrencyModel 表示
账户种类（Fund Config）：指资金的不同用途或状态，如可用账户、冻结账户，由 FundConfigModel 表示
用户账户（Fund）：用户实际持有的资金账户，由 FundModel 表示

本文档旨在明确这些概念的正确使用方式，避免混淆。

2. 枚举定义

2.1 消耗类型枚举（CONSUME_TYPE）

enum CONSUME_TYPE: int
{
    /**
     * 物品消耗
     * 消耗用户背包中的物品
     */
    case ITEM = 1;

    /**
     * 账户种类消耗
     * 消耗用户特定账户种类的资金
     * 注意：这里的target_id指向fund_config表的id（账户种类ID）
     */
    case FUND_CONFIG = 2;

    /**
     * 币种消耗
     * 消耗用户特定币种的资金
     * 注意：这里的target_id指向fund_currency表的id（币种ID）
     */
    case CURRENCY = 3;
}

2.2 奖励类型枚举（REWARD_TYPE）

enum REWARD_TYPE: int
{
    /**
     * 物品奖励
     * 奖励用户背包中的物品
     */
    case ITEM = 1;

    /**
     * 账户种类奖励
     * 奖励用户特定账户种类的资金
     * 注意：这里的target_id指向fund_config表的id（账户种类ID）
     */
    case FUND_CONFIG = 2;

    /**
     * 宠物经验奖励
     */
    case PET_EXP = 3;

    /**
     * 宠物体力奖励
     */
    case PET_ENERGY = 4;

    /**
     * 币种奖励
     * 奖励用户特定币种的资金
     * 注意：这里的target_id指向fund_currency表的id（币种ID）
     */
    case CURRENCY = 5;

    /**
     * 其他奖励
     */
    case OTHER = 99;
}

3. 正确使用方式

3.1 消耗账户种类资金

当需要消耗用户特定账户种类的资金时，应使用 CONSUME_TYPE::FUND_CONFIG：

// 创建消耗项
$consumeItem = new GameConsumeItem();
$consumeItem->consume_type = CONSUME_TYPE::FUND_CONFIG->value;
$consumeItem->target_id = $fundConfigId; // 账户种类ID，来自fund_config表
$consumeItem->quantity = $amount;

// 检查消耗
$result = ConsumeService::checkConsumeItem($userId, $consumeItem);

// 执行消耗
$result = ConsumeService::executeConsumeItem($userId, $consumeItem, $source, $sourceId);

3.2 消耗币种资金

当需要消耗用户特定币种的资金（可能涉及多个账户）时，应使用 CONSUME_TYPE::CURRENCY：

// 创建消耗项
$consumeItem = new GameConsumeItem();
$consumeItem->consume_type = CONSUME_TYPE::CURRENCY->value;
$consumeItem->target_id = $currencyId; // 币种ID，来自fund_currency表
$consumeItem->quantity = $amount;

// 检查消耗
$result = ConsumeService::checkConsumeItem($userId, $consumeItem);

// 执行消耗
$result = ConsumeService::executeConsumeItem($userId, $consumeItem, $source, $sourceId);

3.3 奖励账户种类资金

当需要奖励用户特定账户种类的资金时，应使用 REWARD_TYPE::FUND_CONFIG：

// 创建奖励项
$rewardItem = new GameRewardItem();
$rewardItem->reward_type = REWARD_TYPE::FUND_CONFIG->value;
$rewardItem->target_id = $fundConfigId; // 账户种类ID，来自fund_config表
$rewardItem->quantity = $amount;

// 发放奖励
$result = RewardService::grantReward($userId, $rewardItem, $source, $sourceId);

3.4 奖励币种资金

当需要奖励用户特定币种的资金时，应使用 REWARD_TYPE::CURRENCY：

// 创建奖励项
$rewardItem = new GameRewardItem();
$rewardItem->reward_type = REWARD_TYPE::CURRENCY->value;
$rewardItem->target_id = $currencyId; // 币种ID，来自fund_currency表
$rewardItem->quantity = $amount;

// 发放奖励
$result = RewardService::grantReward($userId, $rewardItem, $source, $sourceId);

4. 常见错误

4.1 混淆账户种类ID和币种ID

错误示例：

// 错误：使用币种ID作为账户种类消耗的target_id
$consumeItem->consume_type = CONSUME_TYPE::FUND_CONFIG->value;
$consumeItem->target_id = $currencyId; // 错误！应该使用账户种类ID

正确示例：

// 正确：使用账户种类ID作为账户种类消耗的target_id
$consumeItem->consume_type = CONSUME_TYPE::FUND_CONFIG->value;
$consumeItem->target_id = $fundConfigId; // 正确！使用账户种类ID

4.2 混淆消耗类型