ptrade 平台期货交易下单指南：buy_open、sell_close 与平今仓逻辑解析

在 ptrade 量化平台中进行期货策略开发时，正确处理下单接口以及**平今仓（平当前交易日开仓）与平昨仓（平历史交易日开仓）**的逻辑至关重要，特别是针对上海期货交易所（XSGE）等有严格平今平昨区分的交易所。

一、 ptrade 期货下单核心接口概览

ptrade 提供了四个专门用于期货交易的下单函数：

1. 多头开仓：buy_open(contract, amount, limit_price=None)
2. 多头平仓：sell_close(contract, amount, limit_price=None, close_today=False)
3. 空头开仓：sell_open(contract, amount, limit_price=None)
4. 空头平仓：buy_close(contract, amount, limit_price=None, close_today=False)

参数说明：

• contract: 期货合约代码（例如 'CU2112.XSGE'）。
• amount: 交易数量，必须为正整数（手）。
• limit_price: 限价价格，若不传则默认以行情快照最新价或当前分钟最新价报单。
• close_today: 是否仅平今仓，默认为 False。

二、 如何区分平今仓与平昨仓？

在 ptrade 中，平今仓与平昨仓的核心区别在于平仓接口（sell_close 和 buy_close）中的 close_today 参数设置以及交易所规则：

1. 优先平昨仓（默认设置 close_today=False）

• 当 close_today=False 时，系统会优先平掉历史持仓（昨仓），如果昨仓数量不足，剩余部分会自动平掉当日持仓（今仓）。
• 该设置适用于大部分不需要区分平今平昨的交易所（如大商所、郑商所、中金所）。

2. 仅平今仓（close_today=True）

• 当 close_today=True 时，系统只平掉当日开仓的持仓（今仓）。
• 注意：close_today=True 仅对上海期货交易所（XSGE）及上海国际能源交易中心（INE）生效。如果在其他交易所（如中金所、大商所）设置 close_today=True，ptrade 系统会发出警告并自动强行转换为 close_today=False。
• 若委托平今仓数量大于实际拥有的今仓数量，系统会自动将委托数量调整为当前实际今仓数量。

三、 实战代码示例

以下示例展示了如何在 ptrade 中实现双均线策略，并结合持仓判断对上期所合约进行平今仓与平昨仓的操作：

def initialize(context):
    # 设置期货合约标的（上期所沪铜合约）
    g.security = 'CU2112.XSGE'
    set_universe(g.security)
    # 设置保证金比例与手续费（回测环境有效）
    set_margin_rate('CU', 0.08)
    set_future_commission('CU', 0.00004)

def handle_data(context, data):
    contract = g.security
    # 获取持仓对象
    position = get_position(contract)
    
    # 获取多头与空头的今仓/昨仓信息
    long_today_amount = position.today_long_amount  # 多头今仓
    short_today_amount = position.today_short_amount # 空头今仓
    long_total_amount = position.long_amount         # 多头总持仓
    short_total_amount = position.short_amount       # 空头总持仓
    
    # 获取历史价格计算均线
    df = get_history(10, '1d', 'close', contract, include=False)
    ma5 = df['close'][-5:].mean()
    ma10 = df['close'][-10:].mean()
    
    # 交易逻辑：五日均线上穿十日均线，平空开多
    if ma5 > ma10:
        # 1. 若有空头持仓，先平空仓
        if short_total_amount > 0:
            # 如果存在空头今仓，优先平今仓
            if short_today_amount > 0:
                buy_close(contract, short_today_amount, close_today=True)
                log.info("上期所合约：平空头今仓 %s 手" % short_today_amount)
            # 剩余昨仓进行优先平昨
            left_short_yesterday = short_total_amount - short_today_amount
            if left_short_yesterday > 0:
                buy_close(contract, left_short_yesterday, close_today=False)
                log.info("上期所合约：平空头昨仓 %s 手" % left_short_yesterday)
                
        # 2. 买入开多仓
        if long_total_amount == 0:
            buy_open(contract, 1)
            log.info("多头开仓 1 手")
            
    # 交易逻辑：五日均线下穿十日均线，平多开空
    elif ma5 < ma10:
        # 1. 若有多头持仓，先平多仓
        if long_total_amount > 0:
            # 如果存在多头今仓，优先平今仓
            if long_today_amount > 0:
                sell_close(contract, long_today_amount, close_today=True)
                log.info("上期所合约：平多头今仓 %s 手" % long_today_amount)
            # 剩余昨仓平昨
            left_long_yesterday = long_total_amount - long_today_amount
            if left_long_yesterday > 0:
                sell_close(contract, left_long_yesterday, close_today=False)
                log.info("上期所合约：平多头昨仓 %s 手" % left_long_yesterday)
                
        # 2. 卖出开空仓
        if short_total_amount == 0:
            sell_open(contract, 1)
            log.info("空头开仓 1 手")

四、 期货交易注意事项

1. 每一跳价格精度：在传入 limit_price 时，请务必参考对应品种的最小变动价位（如铜为 10元/吨），否则可能导致报单失败。
2. 未完成订单处理：根据交易所规则，所有未完成的挂单会在每日收盘时由系统自动取消。
3. 持仓字段：获取持仓今仓/昨仓可使用 Position 对象的 today_long_amount（多头今仓）和 today_short_amount（空头今仓）属性进行精准判断。