商店系统 (ShopAPI)

ShopAPI 由 shop_plugin 插件提供，负责管理商品定义、用户库存以及物品的消耗。

async def register_item(self, owner_plugin: str, item_id: str, name: str, description: str, price: int, daily_limit: int = 0)

用于插件向商店注册一个可供出售的商品。

• 参数:
  • owner_plugin (str): 注册该物品的插件名称。
  • item_id (str): 物品的唯一英文ID。
  • name (str): 物品的显示名称。
  • description (str): 物品的功能描述。
  • price (int): 物品的售价。
  • daily_limit (int): (可选) 每日限购数量，0 表示不限制。默认为 0。
• 返回: 无。

async def get_item_details(self, identifier: str) -> Optional[Dict[str, Any]]

根据物品的ID或名称获取其详细信息。

• 参数:
  • identifier (str): 物品的唯一英文ID或中文名称。
• 返回: dict 或 None - 成功时返回包含商品所有属性的字典，如果找不到则返回 None。

async def get_user_inventory(self, user_id: str) -> list

获取指定用户的整个背包（物品列表）。

• 参数:
  • user_id (str): 用户的唯一ID。
• 返回: list - 一个由字典组成的列表，每个字典代表用户拥有的一个物品。

async def has_item(self, user_id: str, item_id: str) -> bool

检查用户是否拥有至少一个指定的物品。

• 参数:
  • user_id (str): 用户的唯一ID。
  • item_id (str): 要检查的物品的唯一ID。
• 返回: bool - 如果用户拥有该物品，返回 True，否则返回 False。

async def consume_item(self, user_id: str, item_id: str, quantity: int = 1) -> bool

消耗（移除）用户背包中的指定物品。

• 参数:
  • user_id (str): 用户的唯一ID。
  • item_id (str): 要消耗的物品的唯一ID。
  • quantity (int): (可选) 要消耗的数量，默认为 1。
• 返回: bool - 如果用户拥有足够数量的物品并成功消耗，返回 True。如果物品数量不足，返回 False。

async def get_today_purchase_count(self, user_id: str, item_id: str) -> int

[新增] 查询用户今日已购买某限购商品的数量。

• 参数:
  • user_id (str): 用户的唯一ID。
  • item_id (str): 限购商品的唯一ID。
• 返回: int - 用户今天已购买该商品的数量。

async def log_purchase(self, user_id: str, item_id: str, quantity: int)

[新增] 记录用户的购买行为，用于限购统计。当其他插件通过非商店途径（如直接调用economy_api.add_coins）让用户获得限购商品时，应调用此API来消耗额度。

• 参数:
  • user_id (str): 用户的唯一ID。
  • item_id (str): 限购商品的唯一ID。
  • quantity (int): 购买的数量。
• 返回: 无。