经济系统 (EconomyAPI)

EconomyAPI 由 astrbot_plugin_sign 插件提供，负责管理用户的金币余额和相关数据。

1. 查询指定用户的金币余额

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

• 参数:
  • user_id (str): 用户的唯一ID。
• 返回: int - 用户的金币数量。如果用户不存在，返回 0。可以返回负数。

async def add_coins(self, user_id: str, amount: int, reason: str) -> bool

为指定用户增加或减少金币。此版本支持负数金币（欠款），即使余额不足，扣款操作也会成功并导致余额变为负数。

• 参数:
  • user_id (str): 用户的唯一ID。
  • amount (int): 要变动的数量。正数为增加，负数为减少。
  • reason (str): 本次金币变动的原因，将用于记录日志。
• 返回: bool - 操作是否成功。除非传入的 amount 格式错误，否则通常返回 True。

async def set_coins(self, user_id: str, amount: int, reason: str) -> bool

[慎用] 直接将用户的金币设置为一个特定值。出于安全考虑，此方法禁止直接将用户金币设置为负数。

• 参数:
  • user_id (str): 用户的唯一ID。
  • amount (int): 要设定的目标金额，必须大于等于 0。
  • reason (str): 操作原因。
• 返回: bool - 操作是否成功。

async def get_user_profile(self, user_id: str) -> Optional[dict]

获取用户的公开签到信息。

• 参数:
  • user_id (str): 用户的唯一ID。
• 返回: dict 或 None。成功时返回包含用户信息的字典（如 user_id, nickname, coins, total_days 等），用户不存在则返回 None。

async def get_ranking(self, limit: int = 10) -> list

获取金币排行榜。

• 参数:
  • limit (int): (可选) 希望获取的榜单长度，默认为 10。
• 返回: list - 一个由字典组成的列表，每个字典代表一位榜上的用户。

async def get_coin_history(self, user_id: str, limit: int = 5) -> list

获取指定用户最近的金币变动历史。

• 参数:
  • user_id (str): 用户的唯一ID。
  • limit (int): (可选) 希望获取的记录条数，默认为 5。
• 返回: list - 一个由字典组成的列表，每个字典代表一条金币变动记录。