股票市场 (StockMarketAPI)

StockMarketAPI 由模拟炒股插件提供，用于与其他系统（如虚拟产业）进行交互，管理股票的生命周期和价格。

async def register_stock(self, ticker: str, company_name: str, initial_price: float, total_shares: int, owner_id: str) -> bool

注册一支新的股票到市场 (通常由公司IPO时调用)。

• 参数:
  • ticker (str): 股票代码 (如 "APPL")。
  • company_name (str): 公司名称。
  • initial_price (float): 初始发行价。
  • total_shares (int): 总股本。
  • owner_id (str): 公司所有者的用户ID。
• 返回: bool - 注册是否成功。

async def delist_stock(self, ticker: str) -> bool

当公司破产或倒闭时，将其从市场退市。

• 参数:
  • ticker (str): 股票代码。
• 返回: bool - 操作是否成功。

async def is_ticker_available(self, ticker: str) -> bool

检查一个股票代码是否可用（未被注册）。

• 参数:
  • ticker (str): 股票代码。
• 返回: bool - 如果可用返回 True，否则 False。

async def set_intrinsic_value(self, ticker: str, value: float)

[关键接口] 设置或更新一只股票的内在价值（基本面价值）。此价值是股价的“锚”，股价会围绕它波动。通常由公司插件在公司升级、资产变动后调用。

• 参数:
  • ticker (str): 股票代码。
  • value (float): 新的内在价值。
• 返回: 无。

async def get_stock_price(self, ticker: str) -> Optional[float]

获取指定股票的当前市场价格。

• 参数:
  • ticker (str): 股票代码。
• 返回: float 或 None - 股票的当前价格，如果股票不存在则返回 None。

async def get_market_cap(self, ticker: str) -> Optional[float]

获取指定股票的总市值（当前价格 * 总股本）。

• 参数:
  • ticker (str): 股票代码。
• 返回: float 或 None - 股票的总市值，如果股票不存在则返回 None。

async def report_earnings(self, ticker: str, performance_modifier: float)

上报公司的业绩表现，用于驱动股价大幅波动（如财报季）。

• 参数:
  • ticker (str): 股票代码。
  • performance_modifier (float): 业绩修正因子，正数大利好，负数大利空。
• 返回: 无。

async def report_event(self, ticker: str, price_impact_percentage: float)

上报一个能即时影响股价的随机事件（如公司被攻击、政策变动等）。

• 参数:
  • ticker (str): 股票代码。
  • price_impact_percentage (float): 价格影响百分比，例如 0.1 表示上涨10%，-0.05 表示下跌5%。
• 返回: 无。

async def get_user_total_asset(self, user_id: str) -> Dict[str, Any]

获取单个用户的详细总资产信息（包含现金和股票持仓）。

• 参数:
  • user_id (str): 用户的唯一ID。
• 返回: dict - 包含用户资产详情的字典。
• 注意: total_assets 才是总资产的键名。

async def get_total_asset_ranking(self, limit: int = 10) -> List[Dict[str, Any]]

获取总资产（现金+股票）排行榜。

• 参数:
  • limit (int): (可选) 榜单长度，默认为 10。
• 返回: list - 包含用户资产排名的字典列表。
• 注意: total_assets 才是总资产的键名。