joinquant 风控实战：on_event 函数捕获强行平仓事件

在期货及融资融券量化交易中，当账户保证金不足且未及时补足时，可能会触发系统的强行平仓（Forced Liquidation）。为了让量化策略能够实时响应此类风险事件并进行后续的风控逻辑处理（例如停止继续开仓、调整仓位管理或发出告警），joinquant 提供了 on_event 事件回调机制。

一、什么是 on_event 与 ForcedLiquidationEvent？

on_event(context, event) 是 joinquant 策略引擎中的可选事件回调函数。当账户中持仓的标的发生特定事件时，系统会自动调用该函数。

目前 on_event 支持以下两种事件类型：

1. DividendsEvent：分红送股事件
2. ForcedLiquidationEvent：强行平仓事件

ForcedLiquidationEvent 对象属性

当触发强行平仓时，传给 on_event 的 event 对象包含以下常用属性：

• name: 事件名称，固定为 'ForcedLiquidation'
• pindex: 发生强平的子账户索引（SubPortfolio index）
• security: 被强平的标的代码（例如 'RB1909.XSGE'）
• side: 仓位方向，'long'（多头）或 'short'（空头）
• amount: 被强平的数量

二、核心实现步骤

1. 定义 on_event 回调：在策略代码中声明 def on_event(context, event):。
2. 判断事件类型：建议使用 isinstance 或检查 event.name 来准确判断是否为强行平仓事件。
3. 执行风控逻辑：捕获强平信息后，记录日志、重置策略状态变量或暂停交易。

三、完整 Python 策略代码示例

以下为一个示范策略，展示如何在聚宽平台使用 on_event 监听强行平仓并在触发后止损限仓：

import jqdata

def initialize(context):
    # 1. 设置基准与真实价格模式
    set_benchmark('000300.XSHG')
    set_option('use_real_price', True)
    
    # 2. 设置期货账户（以期货为例，期货更容易触发保证金不足强平）
    init_cash = context.portfolio.starting_cash
    set_subportfolios([SubPortfolioConfig(cash=init_cash, type='futures')])
    
    # 全局标记：是否触发过强平
    g.is_liquidated = False
    g.security = 'RB1909.XSGE'
    
    # 订阅行情与定时任务
    run_daily(market_open, time='every_bar', reference_security='RB9999.XSGE')

def on_event(context, event):
    """
    事件回调函数，当发生分红或强平事件时自动触发
    """
    # 建议使用 event.name 或 isinstance 进行事件类型判断
    if getattr(event, 'name', '') == 'ForcedLiquidation':
        log.error("【风控告警】触发强行平仓事件！")
        log.error("标的: %s, 方向: %s, 数量: %s, 子账户索引: %s" % 
                  (event.security, event.side, event.amount, event.pindex))
        
        # 设置风控标记，停止后续开仓操作
        g.is_liquidated = True
        
        # 可以在此处添加撤销所有未完成订单的操作
        open_orders = get_open_orders()
        for order_id, order_obj in open_orders.items():
            cancel_order(order_obj)
            log.info("已撤销未完成订单: %s" % order_id)

def market_open(context):
    # 若已触发强平风控，不再进行开仓逻辑
    if g.is_liquidated:
        log.warn("策略处于强平风控状态，跳过开仓交易。")
        return
        
    # 正常的交易逻辑
    # 例如检查保证金安全比例
    if context.subportfolios[0].is_dangerous(0.2):
        log.warn("当前仓位保证金比率低于 20%，注意补缴保证金，避免被强平！")

四、注意事项与最佳实践

1. 避免死循环：在 on_event 函数内部不要编写可能二次引发强平或复杂同步阻塞的交易逻辑。
2. 未完成订单清理：收到强平通知后，建议调用 get_open_orders() 并配合 cancel_order() 清理挂单，防止挂单占用保证金。
3. 主动风控预防：除被动监听 ForcedLiquidationEvent 外，建议结合 context.subportfolios[i].is_dangerous(margin_rate) 函数主动预警并控制保证金比例，做到事前预防与事后捕获相结合。