# GameItems 游戏物品模块

> 游戏物品系统 - 综合管理游戏内所有物品的生命周期

## 目录

1. [模块概述](#1-模块概述)
2. [目录结构](#2-目录结构)
3. [架构设计](#3-架构设计)
4. [核心服务](#4-核心服务)
5. [数据模型](#5-数据模型)
6. [业务逻辑](#6-业务逻辑)
7. [使用示例](#7-使用示例)
8. [最佳实践](#8-最佳实践)

## 1. 模块概述

### 1.1 功能与目的

GameItems模块是游戏核心系统之一，负责管理游戏内所有物品的完整生命周期，包括创建、获取、使用、交易、过期和销毁。该模块为游戏内经济系统和玩家进度提供基础支持，是连接多个游戏子系统的核心组件。

### 1.2 主要功能

- **物品基础属性管理**：名称、描述、图标、类型等
- **物品获取与消耗逻辑**：添加物品到用户背包、消耗物品
- **物品库存管理**：堆叠、数量限制、过期处理
- **物品交易系统**：玩家间交易、商店交易
- **特殊物品效果**：使用效果、装备效果
- **宝箱系统**：宝箱配置、开启机制、保底机制
- **物品过期管理**：全局过期和用户特定过期
- **物品合成系统**：配方、材料、成功率
- **物品分解系统**：分解规则、结果计算
- **物品绑定机制**：绑定类型、交易限制

### 1.3 核心特点

- **多物品宝箱系统**：支持一个宝箱同时掉落多种物品，可配置数量范围和概率
- **保底机制**：支持在开启一定次数后必定获得指定物品
- **灵活的过期机制**：支持全局过期和用户特定过期
- **物品属性扩展**：支持通过JSON格式存储的键值对属性，实现复杂效果
- **物品分类与组**：支持物品分类和物品组，便于管理和配置

## 2. 目录结构

```
app/Module/GameItems/
├── AdminControllers/        # 后台管理控制器
│   ├── Helper/              # 控制器辅助类
│   ├── Actions/             # 控制器动作类
│   └── LazyRenderable/      # 懒加载渲染类
├── Commands/                # 命令行工具
├── Casts/                   # 自定义类型转换器
├── Databases/               # 数据库相关文件
│   └── create.sql           # 数据库创建脚本
├── Enums/                   # 枚举类型定义
├── Events/                  # 事件类
├── Exceptions/              # 异常类
├── Logics/                  # 业务逻辑类
├── Models/                  # 数据模型
├── Providers/               # 服务提供者
├── Repositorys/             # 数据仓库
├── Services/                # 服务类
└── README.md                # 模块文档
```

### 2.1 主要目录说明

- **AdminControllers/**: 包含所有后台管理界面的控制器，用于物品、宝箱、配方等的管理
  - **Helper/**: 控制器辅助类，如表单、表格、筛选器等帮助类
  - **Actions/**: 控制器动作类，如复制、导出等操作
  - **LazyRenderable/**: 懒加载渲染类，用于异步加载数据
- **Commands/**: 命令行工具，如数据导入导出、配置生成等
- **Casts/**: 自定义类型转换器，用于处理JSON属性等特殊字段
- **Enums/**: 定义模块中使用的所有枚举类型，如物品类型、交易类型等
- **Events/**: 定义模块触发的事件，用于模块间的松耦合通信
- **Exceptions/**: 自定义异常类，用于处理业务异常
- **Logics/**: 业务逻辑类，处理具体的业务规则，内部使用
- **Models/**: 数据模型，定义数据结构和关系
- **Providers/**: 服务提供者，用于注册服务和事件
- **Repositorys/**: 数据仓库，封装数据库操作
- **Services/**: 服务类，对外提供功能接口

## 3. 架构设计

### 3.1 模块架构

GameItems模块采用分层架构设计，遵循"服务是对外的，Logic是内部的"原则：

- **Models层**：数据模型，定义数据结构和关系
- **Logics层**：业务逻辑，处理具体的业务规则
- **Services层**：服务接口，对外提供功能，调用Logics层处理业务
- **Controllers层**：控制器，处理HTTP请求，调用Services层
- **Repositories层**：数据访问层，封装数据库操作

### 2.2 核心类关系

```
Services
  ├── ItemService - 物品基础服务
  ├── ChestService - 宝箱服务
  ├── CraftService - 合成服务
  └── DismantleService - 分解服务

Logics
  ├── Item - 物品逻辑
  ├── PityTime - 保底计数逻辑
  ├── ItemInstance - 物品实例逻辑
  ├── UserRecipe - 用户配方逻辑
  ├── Recipe - 配方逻辑
  ├── UserOutputCounter - 用户产出计数逻辑
  └── Group - 物品组逻辑

Models
  ├── Item - 物品基础信息
  ├── ItemCategory - 物品分类
  ├── ItemInstance - 物品实例（单独属性物品）
  ├── ItemUser - 用户物品关联
  ├── ItemGroup - 物品组
  ├── ItemGroupItem - 物品组内容
  ├── ItemChestConfig - 宝箱配置（新系统）
  ├── ItemPityTime - 宝箱保底计数
  ├── ItemChestOpenLog - 宝箱开启记录
  ├── ItemRecipe - 物品合成配方
  ├── ItemRecipeMaterial - 合成配方材料
  ├── ItemUserRecipe - 用户配方解锁状态
  ├── ItemCraftLog - 物品合成记录
  ├── ItemDismantleRule - 物品分解规则
  ├── ItemDismantleLog - 物品分解记录
  ├── ItemOutputLimit - 物品产出限制
  ├── ItemUserOutputCounter - 用户产出计数
  └── ItemTransactionLog - 物品交易记录
```

### 2.3 设计原则

1. **单一职责原则**：每个类只负责一个功能领域
2. **关注点分离**：模型只负责数据结构，业务逻辑由Logic类处理
3. **依赖注入**：通过构造函数注入依赖，提高可测试性
4. **事务完整性**：所有涉及多个操作的功能都使用数据库事务确保原子性
5. **日志记录**：关键操作都有详细的日志记录，便于追踪和分析

## 3. 数据结构

### 3.1 核心表结构

| 表名 | 主要功能 | 关键字段 |
|------|---------|---------|
| item_items | 统一属性物品定义 | id, name, type, is_unique, attributes |
| item_categories | 物品分类管理 | id, name, code, parent_id |
| item_instances | 单独属性物品实例 | id, item_id, attributes, is_bound |
| item_users | 用户物品关联 | user_id, item_id, instance_id, quantity |
| item_groups | 物品组定义 | id, name, code |
| item_group_items | 物品组内容 | group_id, item_id, weight |
| item_chest_configs | 宝箱配置（新系统） | item_id, consume_group_id, reward_group_id, condition_group_id |
| item_pity_times | 用户宝箱保底计数 | user_id, chest_id, chest_content_id, current_count |
| item_chest_open_logs | 宝箱开启记录 | user_id, chest_id, result_items, pity_triggered |
| item_recipes | 合成配方定义 | id, result_item_id, success_rate |
| item_recipe_materials | 配方材料需求 | recipe_id, item_id, quantity |
| item_user_recipes | 用户配方解锁状态 | user_id, recipe_id, is_unlocked |
| item_craft_logs | 物品合成记录 | user_id, recipe_id, is_success |
| item_dismantle_rules | 物品分解规则 | item_id/category_id, priority |
| item_dismantle_logs | 物品分解记录 | user_id, item_id, results |
| item_output_limits | 物品产出限制 | item_id, limit_type, max_quantity |
| item_user_output_counters | 用户产出计数 | user_id, limit_id, current_count |
| item_transaction_logs | 物品交易记录 | user_id, item_id, quantity, transaction_type |

### 3.2 关键字段说明

#### 3.2.1 物品类型 (item_items.type)

物品类型决定了物品的基本行为和使用方式：

- 1: 可使用物品 - 直接消耗获得效果
- 2: 可装备物品 - 装备后提供属性加成
- 3: 可合成物品 - 可用于合成其他物品
- 4: 任务物品 - 用于完成任务
- 5: 宝箱物品 - 可开启获得其他物品
- 6: 货币物品 - 用于交易和购买

#### 3.2.2 物品属性 (display_attributes, numeric_attributes)

物品属性以JSON格式存储，分为两类：

- **display_attributes**: 用于界面展示的属性，如图标、描述、外观等
- **numeric_attributes**: 用于游戏逻辑计算的属性，如攻击力、防御力、使用效果等

#### 3.2.3 交易类型 (item_transaction_logs.transaction_type)

记录物品流转的类型：

- 1: 获取 - 玩家获得物品
- 2: 消耗 - 玩家消耗物品
- 3: 交易获得 - 通过交易获得物品
- 4: 交易失去 - 通过交易失去物品
- 5: 过期失效 - 物品过期被移除

## 4. 核心功能

### 4.1 物品管理

#### 4.1.1 添加物品到用户背包

```php
// 添加统一属性物品
$result = $itemService->addItem($userId, $itemId, $quantity, [
    'source_type' => 'quest_reward',
    'source_id' => $questId,
]);

// 添加单独属性物品
$result = $itemService->addItem($userId, $itemId, 1, [
    'source_type' => 'chest_open',
    'source_id' => $chestId,
    'display_attributes' => ['color' => 'red', 'size' => 'large'],
    'numeric_attributes' => ['attack' => 100, 'defense' => 50],
]);
```

#### 4.1.2 消耗用户物品

```php
// 消耗统一属性物品
$result = $itemService->consumeItem($userId, $itemId, null, $quantity, [
    'source_type' => 'item_use',
    'details' => ['effect_id' => 123],
]);

// 消耗单独属性物品
$result = $itemService->consumeItem($userId, $itemId, $instanceId, 1, [
    'source_type' => 'equipment_upgrade',
    'details' => ['upgrade_id' => 456],
]);
```

#### 4.1.3 获取用户物品列表

```php
// 获取所有物品
$items = $itemService->getUserItems($userId);

// 获取特定类型的物品
$items = $itemService->getUserItems($userId, [
    'type' => 2, // 装备类物品
    'category_id' => 5, // 特定分类
]);
```

### 4.2 宝箱系统

#### 4.2.1 开启宝箱

```php
// 开启宝箱
$result = $chestService->openChest($userId, $chestId, $quantity, [
    'ip_address' => $request->ip(),
    'device_info' => $request->userAgent(),
]);

// 结果示例
[
    'success' => true,
    'chest_id' => 123,
    'quantity' => 1,
    'results' => [
        [
            [
                'item_id' => 456,
                'quantity' => 2,
                'is_pity' => false,
            ],
            [
                'item_id' => 789,
                'quantity' => 1,
                'is_pity' => true,
            ]
        ]
    ],
    'pity_triggered' => true,
    'log_id' => 10001,
]
```

#### 4.2.2 获取宝箱内容预览

```php
// 获取宝箱内容预览
$preview = $chestService->getChestContentPreview($chestId);
```

### 4.3 物品合成系统

#### 4.3.1 合成物品

```php
// 合成物品
$result = $craftService->craftItem($userId, $recipeId, [
    'ip_address' => $request->ip(),
    'device_info' => $request->userAgent(),
]);
```

#### 4.3.2 获取用户可合成配方列表

```php
// 获取用户可合成配方列表
$recipes = $craftService->getUserAvailableRecipes($userId);
```

### 4.4 物品分解系统

#### 4.4.1 分解物品

```php
// 分解物品
$result = $dismantleService->dismantleItem($userId, $itemId, $instanceId, $quantity, [
    'ip_address' => $request->ip(),
    'device_info' => $request->userAgent(),
]);
```

#### 4.4.2 获取物品分解预览

```php
// 获取物品分解预览
$preview = $dismantleService->getDismantlePreview($userId, $itemId, $instanceId);
```

## 4. 核心服务

### 4.1 ItemService

物品基础服务，负责物品的基本操作。

#### 主要方法

```php
/**
 * 获取用户物品列表
 *
 * @param int $userId 用户ID
 * @param array $filters 过滤条件
 * @param bool $includeExpired 是否包含已过期物品
 * @return Collection
 */
public function getUserItems(int $userId, array $filters = [], bool $includeExpired = false): Collection;

/**
 * 添加物品到用户背包
 *
 * @param int $userId 用户ID
 * @param int $itemId 物品ID
 * @param int $quantity 数量
 * @param array $options 选项
 * @return array 添加结果
 */
public function addItem(int $userId, int $itemId, int $quantity, array $options = []): array;

/**
 * 消耗用户物品
 *
 * @param int $userId 用户ID
 * @param int $itemId 物品ID
 * @param int|null $instanceId 物品实例ID（单独属性物品）
 * @param int $quantity 数量
 * @param array $options 选项
 * @return array 消耗结果
 */
public function consumeItem(int $userId, int $itemId, ?int $instanceId, int $quantity, array $options = []): array;

/**
 * 检查用户物品数量
 *
 * @param int $userId 用户ID
 * @param int $itemId 物品ID
 * @param int|null $instanceId 物品实例ID（单独属性物品）
 * @return int 物品数量
 */
public function getItemQuantity(int $userId, int $itemId, ?int $instanceId = null): int;

/**
 * 检查物品是否过期
 *
 * @param int $itemId 物品ID
 * @param int|null $instanceId 物品实例ID
 * @return bool 是否过期
 */
public function isItemExpired(int $itemId, ?int $instanceId = null): bool;
```

### 4.2 ChestService

宝箱服务，负责宝箱开启和内容管理。

#### 主要方法

```php
/**
 * 开启宝箱
 *
 * @param int $userId 用户ID
 * @param int $chestId 宝箱ID
 * @param int $quantity 开启数量
 * @param array $options 选项
 * @return array 开启结果
 */
public function openChest(int $userId, int $chestId, int $quantity = 1, array $options = []): array;

/**
 * 获取宝箱内容预览
 *
 * @param int $chestId 宝箱ID
 * @return array 宝箱内容预览
 */
public function getChestContentPreview(int $chestId): array;
```

### 4.3 CraftService

合成服务，负责物品合成和配方管理。

#### 主要方法

```php
/**
 * 合成物品
 *
 * @param int $userId 用户ID
 * @param int $recipeId 配方ID
 * @param array $options 选项
 * @return array 合成结果
 */
public function craftItem(int $userId, int $recipeId, array $options = []): array;

/**
 * 获取用户可合成配方列表
 *
 * @param int $userId 用户ID
 * @param array $filters 过滤条件
 * @return Collection 配方列表
 */
public function getUserAvailableRecipes(int $userId, array $filters = []): Collection;

/**
 * 解锁用户配方
 *
 * @param int $userId 用户ID
 * @param int $recipeId 配方ID
 * @return bool 是否成功
 */
public function unlockRecipe(int $userId, int $recipeId): bool;
```

### 4.4 DismantleService

分解服务，负责物品分解和规则管理。

#### 主要方法

```php
/**
 * 分解物品
 *
 * @param int $userId 用户ID
 * @param int $itemId 物品ID
 * @param int|null $instanceId 物品实例ID
 * @param int $quantity 数量
 * @param array $options 选项
 * @return array 分解结果
 */
public function dismantleItem(int $userId, int $itemId, ?int $instanceId, int $quantity, array $options = []): array;

/**
 * 获取物品分解预览
 *
 * @param int $userId 用户ID
 * @param int $itemId 物品ID
 * @param int|null $instanceId 物品实例ID
 * @return array 分解预览
 */
public function getDismantlePreview(int $userId, int $itemId, ?int $instanceId): array;
```

## 5. 数据模型

### 5.1 核心模型

#### 5.1.1 Item

物品基础信息模型，定义物品的基本属性。

```php
/**
 * 物品基础信息
 *
 * field start
 * @property   int  $id  物品ID，主键
 * @property   string  $name  物品名称
 * @property   string  $description  物品描述
 * @property   int  $category_id  物品分类ID，外键关联kku_item_categories表
 * @property   int  $type  物品类型（1:可使用, 2:可装备, 3:可合成, 4:可交任务, 5:可开启...）
 * @property   int  $is_unique  是否是单独属性物品（0:否，默认, 1:是）
 * @property   int  $max_stack  最大堆叠数量
 * @property   int  $sell_price  出售价格
 * @property   int  $tradable  是否可交易（0:不可交易, 1:可交易，默认）
 * @property   int  $dismantlable  是否可分解（0:不可分解, 1:可分解，默认）
 * @property   int  $default_expire_seconds  玩家获取物品后的默认有效秒数（0表示永久有效）
 * @property   object|array  $display_attributes  展示属性，以JSON格式存储键值对，用于界面展示和描述的属性
 * @property   object|array  $numeric_attributes  数值属性，以JSON格式存储键值对，用于计算和游戏逻辑的属性
 * @property   string  $global_expire_at  物品全局过期时间（可为空）
 * @property   \Carbon\Carbon  $created_at  创建时间
 * @property   \Carbon\Carbon  $updated_at  更新时间
 * field end
 */
class Item extends ModelCore
{
    // 模型实现...
}
```

#### 5.1.2 ItemChestConfig

宝箱配置模型（新系统），使用消耗组/奖励组/条件组来定义宝箱的开启消耗和产出。

```php
/**
 * 宝箱配置（新系统）
 *
 * field start
 * @property   int  $id  记录ID，主键
 * @property   int  $item_id  宝箱物品ID，外键关联kku_item_items表
 * @property   int  $consume_group_id  消耗组ID，外键关联kku_game_consume_groups表（可为空）
 * @property   int  $reward_group_id  奖励组ID，外键关联kku_game_reward_groups表
 * @property   int  $condition_group_id  条件组ID，外键关联kku_game_condition_groups表（可为空）
 * @property   bool  $is_active  是否激活（0:否, 1:是）
 * @property   \Carbon\Carbon  $created_at  创建时间
 * @property   \Carbon\Carbon  $updated_at  更新时间
 * field end
 */
class ItemChestConfig extends ModelCore
{
    // 模型实现...
}
```

#### 5.1.3 ItemUser

用户物品关联模型，记录用户拥有的物品。

```php
/**
 * 用户物品关联
 *
 * field start
 * @property   int  $id  记录ID，主键
 * @property   int  $user_id  用户ID
 * @property   int  $item_id  统一属性物品ID，外键关联kku_item_items表
 * @property   int  $instance_id  单独属性物品ID，外键关联kku_item_instances表（可为空）
 * @property   int  $quantity  数量（对于单独属性物品，该值始终为1）
 * @property   string  $expire_at  用户物品过期时间（可为空）
 * @property   \Carbon\Carbon  $created_at  获取时间
 * @property   \Carbon\Carbon  $updated_at  更新时间
 * field end
 */
class ItemUser extends ModelCore
{
    // 模型实现...
}
```

### 5.2 模型关系

模型之间的关系定义如下：

- **Item** 与 **ItemCategory** 是多对一关系
- **Item** 与 **ItemInstance** 是一对多关系
- **Item** 与 **ItemUser** 是一对多关系
- **ItemInstance** 与 **ItemUser** 是一对多关系
- **Item** 与 **ItemChestConfig** 是一对一关系（作为宝箱）
- **ItemGroup** 与 **ItemGroupItem** 是一对多关系
- **ItemRecipe** 与 **ItemRecipeMaterial** 是一对多关系
- **ItemRecipe** 与 **ItemUserRecipe** 是一对多关系

## 6. 业务逻辑

### 6.1 Logics层

Logics层包含所有业务逻辑处理类，负责具体的业务规则实现。这些类不直接对外提供服务，而是由Services层调用。

#### 6.1.1 Item

物品逻辑类，处理物品相关的业务逻辑。

```php
/**
 * 物品逻辑类
 */
class Item
{
    /**
     * 判断物品是否为宝箱
     *
     * @param ItemModel $item 物品模型
     * @return bool
     */
    public function isChest(ItemModel $item): bool;

    /**
     * 检查物品是否已过期（全局过期）
     *
     * @param ItemModel $item 物品模型
     * @return bool
     */
    public function isExpired(ItemModel $item): bool;
}
```

#### 6.1.2 PityTime

保底计数逻辑类，处理宝箱保底机制相关的业务逻辑。

```php
/**
 * 宝箱保底计数逻辑类
 */
class PityTime
{
    /**
     * 增加保底计数
     *
     * @param ItemPityTime $pityTime 保底计数模型
     * @param int $count 增加的数量，默认为1
     * @return bool
     */
    public function incrementCount(ItemPityTime $pityTime, int $count = 1): bool;

    /**
     * 重置保底计数
     *
     * @param ItemPityTime $pityTime 保底计数模型
     * @return bool
     */
    public function resetCount(ItemPityTime $pityTime): bool;
}
```

### 6.2 业务流程

#### 6.2.1 宝箱开启流程

1. 用户请求开启宝箱
2. 验证用户是否拥有足够数量的宝箱
3. 获取宝箱内容配置
4. 获取用户保底计数
5. 计算每个内容的调整后权重
6. 检查是否有达到保底次数的内容
7. 随机选择掉落内容
8. 消耗宝箱物品
9. 添加获得的物品到用户背包
10. 更新保底计数
11. 记录宝箱开启日志
12. 返回开启结果

#### 6.2.2 物品合成流程

1. 用户请求合成物品
2. 验证用户是否已解锁该配方
3. 检查用户是否在冷却时间内
4. 获取配方所需材料
5. 检查用户是否拥有足够的材料
6. 消耗材料
7. 计算合成成功率
8. 随机决定是否成功
9. 如果成功，添加产物到用户背包
10. 更新用户配方使用记录
11. 记录合成日志
12. 返回合成结果

## 7. 使用示例

### 7.1 在其他模块中使用物品服务

```php
// 在任务完成后添加奖励物品
public function completeQuest(int $userId, int $questId)
{
    // 获取任务信息
    $quest = $this->questRepository->find($questId);

    // 验证任务是否可完成
    if (!$this->questService->canComplete($userId, $questId)) {
        throw new QuestCannotCompleteException("任务无法完成");
    }

    // 开始事务
    DB::beginTransaction();
    try {
        // 标记任务完成
        $this->questService->markAsCompleted($userId, $questId);

        // 添加奖励物品
        foreach ($quest->rewards as $reward) {
            $this->itemService->addItem(
                $userId,
                $reward['item_id'],
                $reward['quantity'],
                [
                    'source_type' => 'quest_reward',
                    'source_id' => $questId,
                    'details' => ['quest_name' => $quest->name],
                ]
            );
        }

        DB::commit();
        return ['success' => true, 'message' => '任务完成，奖励已发放'];
    } catch (Exception $e) {
        DB::rollBack();
        throw $e;
    }
}
```

### 6.2 实现宝箱开启功能

```php
// 在控制器中实现宝箱开启功能
public function openChest(Request $request, int $chestId)
{
    // 验证请求
    $validated = $request->validate([
        'quantity' => 'required|integer|min:1|max:10',
    ]);

    try {
        // 获取当前用户ID
        $userId = Auth::id();

        // 开启宝箱
        $result = $this->chestService->openChest(
            $userId,
            $chestId,
            $validated['quantity'],
            [
                'ip_address' => $request->ip(),
                'device_info' => $request->userAgent(),
            ]
        );

        return response()->json([
            'success' => true,
            'data' => $result,
        ]);
    } catch (Exception $e) {
        return response()->json([
            'success' => false,
            'message' => $e->getMessage(),
        ], 400);
    }
}
```

### 6.3 实现物品合成功能

```php
// 在控制器中实现物品合成功能
public function craftItem(Request $request, int $recipeId)
{
    try {
        // 获取当前用户ID
        $userId = Auth::id();

        // 合成物品
        $result = $this->craftService->craftItem(
            $userId,
            $recipeId,
            [
                'ip_address' => $request->ip(),
                'device_info' => $request->userAgent(),
            ]
        );

        return response()->json([
            'success' => true,
            'data' => $result,
        ]);
    } catch (Exception $e) {
        return response()->json([
            'success' => false,
            'message' => $e->getMessage(),
        ], 400);
    }
}
```

## 8. 最佳实践

### 8.1 开发规范

1. **模型中不包含业务逻辑**：所有业务逻辑都应放在Logics层中
2. **服务类是对外的门面**：其他模块只能通过Services层访问GameItems模块功能
3. **使用依赖注入**：通过构造函数注入依赖，提高可测试性
4. **使用事务确保数据一致性**：所有涉及多个操作的功能都应使用数据库事务
5. **记录关键操作日志**：所有物品获取和消耗操作都应记录日志

### 8.2 扩展指南

#### 8.2.1 添加新的物品类型

1. 在 `Enums/ITEM_TYPE.php` 中添加新的类型常量
2. 在 `Models/Item.php` 中添加相关的关联方法（如果需要）
3. 在 `Logics/Item.php` 中添加处理新类型的逻辑方法
4. 在 `Services/ItemService.php` 中添加对外提供的服务方法

#### 8.2.2 添加新的宝箱机制

1. 在 `Models/ItemChestContent.php` 中添加新的字段（如果需要）
2. 在 `Logics/ChestContent.php` 中添加新机制的逻辑方法
3. 在 `Services/ChestService.php` 中修改 `openChest` 方法以支持新机制

### 8.3 性能优化建议

1. **使用批量操作**：对于大量物品操作，使用批量插入和更新
2. **合理使用索引**：为频繁查询的字段创建索引
3. **缓存热点数据**：缓存物品基础信息、配方等不常变化的数据
4. **分页加载**：用户物品列表使用分页加载，避免一次加载过多数据
5. **延迟加载**：使用延迟加载关联数据，避免N+1查询问题

### 7.2 安全考虑

1. **事务完整性**：所有涉及多个操作的功能都使用数据库事务
2. **日志记录**：记录所有物品获取和消耗操作，便于追踪和审计
3. **输入验证**：严格验证所有输入参数，防止恶意请求
4. **并发控制**：使用锁机制防止并发操作导致的数据不一致
5. **权限检查**：确保用户只能操作自己的物品

### 7.3 代码规范

1. **遵循单一职责原则**：每个类只负责一个功能领域
2. **使用依赖注入**：通过构造函数注入依赖，提高可测试性
3. **编写单元测试**：为核心功能编写单元测试，确保代码质量
4. **使用类型提示**：使用PHP类型提示增强代码可读性和安全性
5. **编写详细注释**：为公共方法编写详细的PHPDoc注释

### 7.4 常见问题解决

1. **物品数量不足**：在消耗物品前先检查数量是否足够
2. **宝箱概率问题**：使用权重系统而非直接概率，确保总和为100%
3. **保底机制实现**：使用计数器记录未获得次数，达到阈值时强制获得
4. **过期物品处理**：定期清理过期物品，避免数据库膨胀
5. **并发操作冲突**：使用悲观锁或乐观锁解决并发操作问题