# 奖励组系统 - 独立概率模式使用示例

## 需求实现

您的需求：**随机三种物品，A 10% 1-10个 未命中没有；B 30% 5-20个 未命中没有；C 必中 10-50个**

## 数据库配置示例

### 1. 创建奖励组

```sql
-- 创建奖励组
INSERT INTO `kku_game_reward_groups` (
    `name`, 
    `code`, 
    `description`, 
    `is_random`, 
    `random_count`, 
    `reward_mode`
) VALUES (
    '随机三种物品奖励', 
    'random_three_items', 
    '随机三种物品，A 10% 1-10个，B 30% 5-20个，C 必中 10-50个', 
    0,  -- 不使用传统随机模式
    0,  -- 不限制数量
    2   -- 使用独立概率模式
);
```

### 2. 创建奖励项

```sql
-- 假设奖励组ID为1，物品A的ID为1001，物品B的ID为1002，物品C的ID为1003

-- 物品A：10%概率，1-10个，未命中没有
INSERT INTO `kku_game_reward_items` (
    `group_id`, 
    `reward_type`, 
    `target_id`, 
    `param1`, 
    `param2`, 
    `quantity`,           -- 不使用，因为有数量范围
    `weight`,             -- 不使用，因为使用概率
    `probability`,        -- 10%概率
    `min_quantity`,       -- 最小1个
    `max_quantity`,       -- 最大10个
    `is_guaranteed`       -- 非必中
) VALUES (
    1,                    -- 奖励组ID
    1,                    -- 物品奖励类型
    1001,                 -- 物品A的ID
    0,                    -- 参数1（可选）
    0,                    -- 参数2（可选）
    1,                    -- 默认数量（不使用）
    0,                    -- 权重（不使用）
    10.00,                -- 10%概率
    1,                    -- 最小1个
    10,                   -- 最大10个
    0                     -- 非必中
);

-- 物品B：30%概率，5-20个，未命中没有
INSERT INTO `kku_game_reward_items` (
    `group_id`, 
    `reward_type`, 
    `target_id`, 
    `param1`, 
    `param2`, 
    `quantity`, 
    `weight`, 
    `probability`, 
    `min_quantity`, 
    `max_quantity`, 
    `is_guaranteed`
) VALUES (
    1,                    -- 奖励组ID
    1,                    -- 物品奖励类型
    1002,                 -- 物品B的ID
    0,                    -- 参数1（可选）
    0,                    -- 参数2（可选）
    1,                    -- 默认数量（不使用）
    0,                    -- 权重（不使用）
    30.00,                -- 30%概率
    5,                    -- 最小5个
    20,                   -- 最大20个
    0                     -- 非必中
);

-- 物品C：必中，10-50个
INSERT INTO `kku_game_reward_items` (
    `group_id`, 
    `reward_type`, 
    `target_id`, 
    `param1`, 
    `param2`, 
    `quantity`, 
    `weight`, 
    `probability`, 
    `min_quantity`, 
    `max_quantity`, 
    `is_guaranteed`
) VALUES (
    1,                    -- 奖励组ID
    1,                    -- 物品奖励类型
    1003,                 -- 物品C的ID
    0,                    -- 参数1（可选）
    0,                    -- 参数2（可选）
    1,                    -- 默认数量（不使用）
    0,                    -- 权重（不使用）
    100.00,               -- 100%概率（可选，因为is_guaranteed=1）
    10,                   -- 最小10个
    50,                   -- 最大50个
    1                     -- 必中
);
```

## 代码使用示例

### 1. 发放奖励

```php
use App\Module\Game\Services\RewardService;

// 发放奖励
$result = RewardService::grantReward(
    userId: 1001,
    groupIdOrCode: 'random_three_items',
    sourceType: 'test',
    sourceId: 1
);

if ($result->isSuccess()) {
    echo "奖励发放成功！\n";
    
    $rewardItems = $result->getRewardItems();
    foreach ($rewardItems as $item) {
        echo "获得奖励：物品ID {$item->targetId} x{$item->quantity}\n";
    }
} else {
    echo "发放失败：" . $result->getMessage() . "\n";
}
```

### 2. 可能的结果示例

#### 情况1：全部命中
```
奖励发放成功！
获得奖励：物品ID 1001 x7     // 物品A，10%概率命中，随机得到7个
获得奖励：物品ID 1002 x15    // 物品B，30%概率命中，随机得到15个
获得奖励：物品ID 1003 x32    // 物品C，必中，随机得到32个
```

#### 情况2：部分命中
```
奖励发放成功！
获得奖励：物品ID 1003 x28    // 只有物品C必中，A和B都未命中
```

#### 情况3：A和C命中
```
奖励发放成功！
获得奖励：物品ID 1001 x3     // 物品A命中，得到3个
获得奖励：物品ID 1003 x45    // 物品C必中，得到45个
```

## 系统特性

### 1. 独立概率判断
- 每个奖励项独立进行概率判断
- 物品A有10%概率获得，90%概率不获得
- 物品B有30%概率获得，70%概率不获得
- 物品C必中（100%概率）

### 2. 数量范围随机
- 命中后，数量在指定范围内随机
- 物品A：1-10个随机
- 物品B：5-20个随机
- 物品C：10-50个随机

### 3. 未命中没有
- 如果概率判断未命中，该奖励项不会出现在结果中
- 实现了"未命中没有"的需求

## 概率计算说明

### 各种结果的概率

- **只获得C**：0.9 × 0.7 × 1 = 63%
- **获得A和C**：0.1 × 0.7 × 1 = 7%
- **获得B和C**：0.9 × 0.3 × 1 = 27%
- **获得A、B、C**：0.1 × 0.3 × 1 = 3%

### 期望获得物品数量

- **物品A**：10% × (1+10)/2 = 0.55个
- **物品B**：30% × (5+20)/2 = 3.75个
- **物品C**：100% × (10+50)/2 = 30个

## 扩展使用

### 1. 添加更多奖励类型

```sql
-- 添加货币奖励：50%概率，100-500金币
INSERT INTO `kku_game_reward_items` (
    `group_id`, `reward_type`, `target_id`, 
    `probability`, `min_quantity`, `max_quantity`, `is_guaranteed`
) VALUES (
    1, 2, 1, -- 货币类型，货币ID为1
    50.00, 100, 500, 0
);
```

### 2. 调整概率

```sql
-- 将物品A的概率从10%调整为15%
UPDATE `kku_game_reward_items` 
SET `probability` = 15.00 
WHERE `group_id` = 1 AND `target_id` = 1001;
```

### 3. 调整数量范围

```sql
-- 将物品B的数量范围从5-20调整为8-25
UPDATE `kku_game_reward_items` 
SET `min_quantity` = 8, `max_quantity` = 25 
WHERE `group_id` = 1 AND `target_id` = 1002;
```

## 总结

通过独立概率模式，奖励组系统完全可以实现您的需求：

✅ **支持独立概率判断**：每个物品独立计算是否获得
✅ **支持数量范围**：命中后在指定范围内随机数量
✅ **支持未命中没有**：未命中的物品不会出现在结果中
✅ **支持必中物品**：通过is_guaranteed字段实现
✅ **灵活配置**：可以随时调整概率和数量范围

这种设计既满足了您的具体需求，又保持了系统的灵活性和扩展性。