外观
常见问题
先按安装说明核对 Python 环境与已安装版本，再看完整异常链和实际运行配置。已有结果时，summary 提供实际区间，backtest_settings 提供常用生效设置。定位问题不需要查看框架源码；保留可复现的输入、配置和错误信息即可。
数据与区间
| 现象 | 定位与处理 |
|---|---|
| 基准净值缺日期，或曲线期初日历缺失 | 数据须覆盖首日前一交易日和全部回测交易日，不能把首日净值改成 1 来绕过检查，见期初契约 |
框架数据不存在或已被消费 | 每次回测重新注册同一 bundle，不能复用已消费的 key；注册与运行须在同一进程。见 注册契约 |
| 请求的日期范围被缩短 | 查看加载范围、交易日历及 summary.start_date/end_date；预热按实际信号窗口和前置行情需求确定，见加载区间 |
| 基准报可用区间或缺行情错误 | 确认标的通过正确参数加载，基准有回测首日前一交易日及首日行情；非指数还需后复权收盘，不靠增加订阅解决 |
无任何日线、HFQ 无数据或基础信息缺标的 | 检查代码、asset_type、etf_codes 和实际数据覆盖；缺失属于必要输入，不能用空策略掩盖 |
| 分钟数据存在无日线对应的交易日 | 按代码和日期核实日线缺口与分钟时间；修正数据范围或明确数据处理口径，不能静默丢弃整日 |
| 分钟回调触发但目标行情为 NaN | 股票基金使用固定事件网格；期货可能由其他相关合约触发。检查目标时间戳是否确有 bar；外部挂载时确认接收了新 bundle |
| 涨跌停没有限制成交 | 检查 price_limit；股票基金局部缺行时告警且不校验，期货普通委托缺少必要价格时报错；系统移仓采用独立的结算价模型 |
| 后复权因子与价格跳变不一致 | 核实同一标的、日期的不复权价、HFQ 和现金分红；不手工重复注入折算来消除错误 |
| 昨收、复权或停牌历史不符预期 | 先区分 bar 与快照昨收、日线后复权字段和无 bar 的停牌语义，见 价格口径 |
| 国债曲线为零或风险指标无效 | 分别核对 include_yield_curve 与 base.use_risk_free_rate，见 无风险利率 |
| 期货日线预热导致加载过多分钟 | 用 history_start 提前加载日线，start/end 保持分钟执行范围，见分钟加载 |
策略与订单
| 现象 | 定位与处理 |
|---|---|
下单返回 None、0 order quantity | 检查数量取整、可平量与价格；不是所有创建失败都会抛异常 |
| 下单有返回值但仓位未变 | 查看 status/message/filled_quantity；活动订单不等于成交，见 订单回读 |
| 资金不足或实际成交量偏少 | 核对手续费、滑点、可用现金和成交量上限，再决定是否采用 资金缩量；不要只关闭风控 |
| 竞价单在后续时点成交 | 竞价阶段结束后的余单继续参与普通 BAR 撮合；仅开盘成交的策略应逐笔撮合后立即撤销余单，不能等下一 BAR 回调或次日再撤 |
No market data、未上市或不可交易 | 检查加载范围、上市日期及当日行情；code in bar_dict 只证明订阅，不证明有数据 |
sellable 不存在，或账户键 stock 不存在 | get_position 使用 closable，账户字典使用 STOCK，见 账户与持仓 |
| 初始持仓未生效 | base.init_positions 使用 "代码:数量" 字符串，不传字典；见 配置 |
| 日线取分钟历史、算法单或分钟快照报错 | 核对 API 能力与时间边界；挂载分钟不等于启用全部上游 API |
| smart 调仓在分钟或 scheduler 报错 | 仅支持竞价与日线 handle_bar，还需核对调仓估值价，见 智能调仓 |
| ST 恒 False、行业为空 | 本数据源未提供这些查询；所需因子或成分数据在策略准备层通过 seeddata 查询 |
| 期货没有手续费或保证金配置 | 显式设置固定 futures_commission 和按结算价盯市；费用不继承股票设置，见期货配置 |
| 盘中系列路由与当日 mapping 不同 | 分钟使用前日结算目标，当日 mapping 用于日终移仓；这是路由模型的约定 |
| 夜盘成交日期与持仓日期不同 | 成交按自然 datetime 排序，日切和今昨仓按 trading_date，不能用自然日期判定平今 |
输出与优化
| 现象 | 定位与处理 |
|---|---|
没有 pkl 或返回值缺少 sys_analyser | 检查分析器是否启用、是否配置 output_file 及父目录是否存在；见 分析器 |
| pkl 有数据但 HTML 导出失败 | 保留 pkl，按完整异常定位后单独 重新导出，不必重跑回测 |
| 成交或持仓表缺列 | 无成交或持仓时可能为空表；先判断是否为空，再选择列，不视作回测必然失败 |
| 日内有交易，但持仓和保证金图为零 | 这些表是日终快照；日内清仓后为零是正常结果，盘中峰值须另外记录 |
| 优化第二组任务报 bundle 已消费 | 在优化回调内为每轮回测注册数据，见优化回调 |
并行 pickle 或 __main__ 错误 | 将回调定义在可导入模块，数据经 shared 传入；见 并行与续跑 |
| worker 异常退出 / BrokenExecutor | 查看首个异常及进程退出原因；确认内存不足时减少 worker 或单任务数据量，不能只凭该异常认定 OOM |
| 优化报日志文件限制 | 删除优化配置中的 extra.log_file，由入口管理日志或使用控制台 |
| 续跑未命中 | 确认检查点目录、运行身份及参数一致；仅成功任务缓存 |
需要复现时，用短区间和少量标的保留触发条件。策略回调通过 logger.info 记录信号时间、下单量、实际成交量和现金；调试日志可用 extra.log_level="debug"。不先运行完整大回测来定位局部错误。