kknongchang_2506/app/Module/GameItems/README.cline-gemini25.md

GameItems 模块文档

模块概述

GameItems 模块是游戏内物品系统的核心，负责管理所有与物品相关的逻辑和数据。它旨在提供一个灵活、可扩展且功能完善的物品管理解决方案。

主要职责

该模块涵盖了以下核心功能领域：

• 物品基础属性管理:
  • 名称
  • 分类
  • 类型
  • 展示属性（如图标、描述等）
  • 数值属性（如攻击力、防御力、使用效果值等）
  • 其他自定义基础属性
• 物品获取与消耗: 定义和处理物品如何被玩家获得以及如何被消耗或使用。
• 物品库存管理: 跟踪玩家拥有的物品及其数量。
• 物品交易系统: （如果适用）支持玩家之间的物品交易或与 NPC 的交易。
• 宝箱类物品管理:
  • 定义宝箱内容物。
  • 实现宝箱开启机制，包括随机掉落逻辑。
• 物品过期时间管理:
  • 全局过期: 设定所有同类物品的统一过期时间点。
  • 物品有效期: 物品在获得后的一段时间内有效。
  • 用户特定过期: 为特定用户的特定物品设置单独的过期时间。

核心功能特点

1. 多物品宝箱系统:

   • 允许一个宝箱（或类似容器）在开启时同时掉落多种不同的物品。
   • 可以为宝箱中的每种物品配置：
     • 掉落数量范围（例如，掉落 1 到 5 个）
     • 掉落概率（例如，有 30% 的几率掉落）
   • 提供了高度可配置的掉落逻辑，以满足复杂的游戏设计需求。
   • 支持保底机制 (Pity System): 可配置在开启一定次数后必定获得指定的稀有物品，增加玩家的获得确定性。需要记录玩家针对特定宝箱或奖池的开启次数。

2. 灵活的过期机制:

   • 全局过期: 适用于活动物品或限时物品，到期后所有玩家的该物品将失效或移除。
   • 物品有效期: 物品在获得后的一段时间内有效，例如体验卡、临时增益道具。
   • 用户特定过期: 允许根据特定条件（如补偿、特殊奖励）为单个用户设置物品的过期时间。
   • 系统能自动处理过期物品的逻辑（如移除、状态变更）。

3. 完善的属性系统:

   • 使用灵活的键值对（Key-Value）结构来存储物品的各种属性。
   • 支持数值型、字符型、布尔型等多种数据类型的属性。
   • 易于扩展，可以方便地添加新的属性来支持复杂的物品效果和游戏机制（如装备词缀、宝石镶嵌、附魔效果等）。

4. 单独物品属性系统:

   • 允许基于一个“基础物品”（模板）创建出多个具有独立属性的“单独物品”实例。
   • 每个单独物品实例可以拥有自己独特的属性值（例如，两把相同的剑，但一把有 +10 攻击力，另一把有 +5 攻击力和 +5% 暴击率）。
   • 适用于需要精细管理每个物品个体差异的场景，如装备、宠物等。
   • 每个单独物品拥有唯一的实例 ID，便于追踪和管理。

5. 物品组管理:

   • 允许创建物品的逻辑分组，一个物品组可以包含多个基础物品。
   • 主要用于简化配置，例如在宝箱奖励配置中可以直接引用物品组，而不是列出组内所有物品。
   • 可以为物品组内的物品配置额外的属性，如在组内的权重或特殊掉落规则。

设计目标

• 高内聚，低耦合: 模块内部功能紧密相关，与其他模块的依赖尽可能减少。
• 可扩展性: 易于添加新的物品类型、属性和功能。
• 性能: 高效处理大量物品数据和相关操作。
• 可配置性: 游戏策划可以通过配置轻松调整物品属性、掉落、过期规则等。

数据库设计

为了支持上述功能，建议采用以下核心数据表结构：

1. game_item_bases (基础物品表): 存储物品的模板信息。

   • id: 主键
   • name: 物品名称
   • category_id: 物品分类 ID (外键关联分类表)
   • type: 物品类型 (例如：消耗品, 装备, 材料, 宝箱)
   • description: 物品描述
   • icon: 物品图标
   • stack_limit: 堆叠上限 (1 表示不可堆叠)
   • base_attributes: JSON/Text 存储基础属性 (如攻击力、防御力)
   • is_tradable: 是否可交易
   • is_sellable: 是否可出售
   • sell_price: 出售价格
   • global_expire_at: 全局过期时间 (NULL 表示永不过期)
   • created_at, updated_at

2. game_item_instances (单独物品实例表): 存储具有独立属性的物品实例 (针对“单独物品属性系统”)。

   • id: 主键 (唯一实例 ID)
   • base_item_id: 基础物品 ID (外键关联 game_item_bases)
   • owner_user_id: 所属用户 ID (外键关联用户表)
   • instance_attributes: JSON/Text 存储实例特定属性 (如强化等级, 随机词缀)
   • created_at, updated_at
   • expire_at: 特定过期时间 (NULL 表示遵循基础物品或永不过期)
   • status: 物品状态 (例如：在背包中, 已装备, 已锁定)

3. user_inventories (用户物品库存表): 存储用户拥有的可堆叠物品。

   • id: 主键
   • user_id: 用户 ID (外键关联用户表)
   • base_item_id: 基础物品 ID (外键关联 game_item_bases)
   • quantity: 拥有数量
   • created_at, updated_at
   • expire_at: 特定过期时间 (针对用户特定过期，优先级高于全局过期和有效期)

4. game_item_categories (物品分类表):

   • id: 主键
   • name: 物品分类名称 (例如：武器, 护甲, 药水)
   • parent_id: 父分类 ID (支持层级分类)
   • created_at, updated_at

5. game_item_groups (物品组表): 定义物品的逻辑分组。

   • id: 主键
   • name: 物品组名称
   • description: 物品组描述
   • created_at, updated_at

6. game_item_group_items (物品组包含物品表): 关联物品组和基础物品。

   • id: 主键
   • group_id: 物品组 ID (外键关联 game_item_groups)
   • base_item_id: 基础物品 ID (外键关联 game_item_bases)
   • weight: 在物品组内的权重 (用于随机抽取)
   • created_at, updated_at

7. game_chest_rewards (宝箱奖励配置表):

   • id: 主键
   • chest_base_item_id: 宝箱的基础物品 ID (外键关联 game_item_bases)
   • reward_base_item_id: 奖励的基础物品 ID (外键关联 game_item_bases, 如果直接奖励物品)
   • reward_group_id: 奖励物品组 ID (外键关联 game_item_groups, 如果奖励物品组)
   • min_quantity: 最小掉落数量
   • max_quantity: 最大掉落数量
   • probability: 掉落概率 (例如 0.3 表示 30%)
   • is_pity_reward: 布尔值, 标记此项是否为可通过保底获得的奖励之一 (可选, 简化逻辑)
   • created_at, updated_at

8. game_chest_pity_configs (宝箱保底配置表): 定义宝箱的保底规则。

   • id: 主键
   • chest_base_item_id: 宝箱的基础物品 ID (外键关联 game_item_bases)
   • pity_group_id: 保底组 ID (可选, 用于多个宝箱共享保底计数)
   • pity_threshold: 触发保底所需的尝试次数
   • guaranteed_reward_item_id: 保底必定获得的物品 ID (外键关联 game_item_bases)
   • guaranteed_reward_quantity: 保底物品数量
   • reset_on_trigger: 触发保底后是否重置计数器 (通常为 true)
   • description: 保底规则描述 (例如 "90抽小保底", "180抽大保底")
   • created_at, updated_at

9. user_chest_pity_progress (用户宝箱保底进度表): 跟踪用户针对特定保底规则的进度。

   • id: 主键
   • user_id: 用户 ID (外键关联用户表)
   • pity_config_id: 关联的保底配置 ID (外键关联 game_chest_pity_configs)
   • attempts_count: 当前累计尝试次数
   • created_at, updated_at

说明:

• 对于不可堆叠且具有独立属性的物品（如装备），主要使用 game_item_instances 表。owner_user_id 标识归属。
• 对于可堆叠的物品（如消耗品、材料），主要使用 user_inventories 表。
• 过期逻辑处理优先级：user_inventories.expire_at > game_item_instances.expire_at > game_item_bases.global_expire_at > 物品有效期（通常在获得时计算并存入 user_inventories 或 game_item_instances 的 expire_at 字段）。
• 属性存储建议使用 JSON 类型，便于灵活扩展。
• 宝箱开启时，根据 game_chest_pity_configs 中的配置，检查并更新 user_chest_pity_progress 表。当用户的 attempts_count 达到对应 pity_config_id 的 pity_threshold 时，强制发放 guaranteed_reward_item_id 指定的物品，并根据 reset_on_trigger 决定是否重置计数器。