期货：配置、合约与数据

期货策略与股票用同一套回测引擎，但账户、合约、开平仓和换月规则都不一样。本页讲账户、合约与数据；下单见开平仓与订单，换月见主力换月与排查。日线和分钟回测写法相同。

#一、运行配置与账户

运行前选择期货账户、日期区间、日线或分钟频率，并配置资金、手续费、保证金和滑点。策略通过 context.run_info 读取这些配置，不在代码里覆盖。

用 context.account = context.run_info.future_account 保存账户，再用 context.future_account_dict[context.account] 读取账户对象。初始化阶段设置参数、准备数据；从交易回调开始才读取资金和持仓。

策略参数只用数字、布尔值、字符串或字符串列表，例如合约列表、目标手数和窗口长度。行情缓存、订单登记表等运行状态在 initialize 中自己建立。

#二、合约代码

下单使用真实交割合约，例如 A2501.DCE。示例中的合约是历史回测用的代码，运行区间必须落在它有数据、可交易的期间；换到其他期间时选对应的真实合约。

品种代码（如 A）用于查主力；A_DOMINANT.DCE 这类连续代码用于研究行情。下单前要从主力映射取得对应的真实 symbol，不要把连续代码或交易所原始代码直接当成交割合约。

#三、最小策略

下面这份完整策略在取得有效行情、确认没有在途订单且没有持仓时，开 1 手多仓。它只用来理解流程，不含平仓信号。

from panda_backtest.api.api import buy_open, get_open_future_orders


def initialize(context):
    context.account = context.run_info.future_account
    context.symbol = "A2501.DCE"
    context.hands = 1
    context.sub_future_symbol([context.symbol])


def handle_data(context, data):
    bar = data[context.symbol]
    if bar is None or not (0 < bar.close < float("inf")):
        return
    account = context.future_account_dict.get(context.account)
    if account is None:
        raise ValueError("期货账户不存在")
    if get_open_future_orders(context.account, context.symbol):
        return
    position = account.positions[context.symbol]
    if position.buy_quantity == 0 and position.sell_quantity == 0:
        orders = buy_open(context.account, context.symbol, int(context.hands))
        for order in orders or []:
            print(f"订单={order.order_id} 状态={order.status} 信息={order.message}")


def on_future_trade_rtn(context, order):
    print(f"成交回报：{order.order_book_id} 累计={order.filled_quantity}手")


def future_order_cancel(context, order):
    print(f"撤单或拒单：{order.order_id} {order.message}")

#四、回调函数

回测可能在下单调用内部就完成撮合并触发回调，不要假定「下单函数返回以后才发生回报」。先建立缓存再下单；返回后只登记仍处于未完成状态的订单。

#五、交易日与自然日

主力映射、每日信号和日线数据都用 context.trade_date 对齐。get_next_count_date 的起始日期必须在已加载列表中，不能用它查询回测区间之前的预热日；区间外的前一交易日在初始化时用 panda_data.get_prev_trade_date 查询。

#六、读取当前行情

用 bar = data[symbol] 读取当前 Bar。data 不是普通字典，不要用 symbol in data 判断行情是否存在；拿到对象后检查价格：

def read_valid_close(data, symbol):
    bar = data[symbol]
    if bar is None or not (0 < bar.close < float("inf")):
        return None
    return float(bar.close)

日线、分钟都可以用以下字段。价格单位跟随品种报价单位（元/吨、元/克、指数点等）；价格 × 合约乘数 × 手数才是名义金额。

• 日期：统一用 context.trade_date。分钟行情的 trade_date 是 YYYYMMDD 字符串，date 是自然日整数，time 是 HHMMSS 整数；日线的 bar.trade_date 不保证总有有效值。比较日期前先统一成 YYYYMMDD 字符串。
• 扩展字段：成交额、持仓量以实际行情列为准，当前期货数据用 amount、open_interest，不要把 turnover、oi 的默认值当成有效数据。分钟行情缺结算价时可能以收盘价填充，不能据此还原实际结算。
• 盘口：分钟对象里有 bidprice1、askprice1 字段，但有字段不代表数据源提供了有效盘口；值为 0 或缺失时不能用来定价。

#七、查询历史行情和合约资料

先 import panda_data，平台提供数据访问环境，策略不自行登录或配置密钥。历史查询放在 initialize 或每日一次的 before_trading 中，把结果缓存给 handle_data 用。

• 行情和主力查询的起止日期用 YYYYMMDD，必须填写；期货日线单次区间不超过 5 年。symbol、underlying_symbol、fields 可以是单个字符串或列表。
• get_future_min 的可选参数 time_zone 是日内时间段过滤（如 ('10:00', '11:00')），不是时区。数据查询的 '1m' 与回测配置的 '1M' 大小写不同。
• 交易日历的 exchange 支持 'SH'、'HK'、'US'，不能把 .SHF 这类合约后缀传给它；中国市场用默认 'SH'，具体品种的夜盘和休市还要结合交易时点和有效行情判断。

下面的函数在初始化时预加载一个合约的日线和合约乘数：

import panda_data


def load_history_and_contract(context, symbol):
    start = context.run_info.start_date
    end = context.run_info.end_date
    daily = panda_data.get_future_daily(
        symbol=[symbol], start_date=start, end_date=end,
        fields=["symbol", "date", "close"],
    )
    detail = panda_data.get_future_detail_all(
        symbol=[symbol], date=start,
        fields=["symbol", "contract_multiplier"],
    )
    if daily is None or daily.empty:
        raise ValueError("所选合约在回测区间内没有日线数据")
    if detail is None or detail.empty:
        raise ValueError("缺少合约资料")
    if "contract_multiplier" not in detail.columns:
        raise ValueError("缺少合约乘数字段")
    multiplier = float(detail.iloc[0]["contract_multiplier"])
    if not (0 < multiplier < float("inf")):
        raise ValueError("合约乘数无效")
    return daily, multiplier

使用返回的表时注意：

• 历史表常用 symbol、date、open、high、low、close、volume 等列，它是 DataFrame，不能照搬当前 Bar 的全部字段名。amount 是成交额、open_interest 是持仓量；分钟表的 trading_date 是交易日期，minute、datetime 是时点。分钟表的 turnover 是换手率，不是成交额。
• 指定 fields 后，读取前检查必要列、空值和无穷值。全区间预加载只为减少查询，某一天的信号仍只能用那个时点已知的数据。
• 合约资料里 contract_multiplier 是合约乘数，margin_rate 是最低保证金率（小数），is_trading 表示查询日期是否可交易。资料中的保证金率不等于本次回测或真实账户最终使用的保证金率。
• 工作流若传入了因子数据，可以通过 context.df_factor 读取 DataFrame。它的列名、时间范围和频率由上游因子节点决定，在初始化时校验所需列，并按交易日和真实合约对齐。