期货量化限价挂单总漏状态：天勤 InsertOrderTask 用法
前言
趋势策略用TargetPosTask很省心，但有些场景必须限价挂单等待成交：例如固定价位补单、做市式报价、或要求「挂出去、未成再撤再挂」。手写insert_order+ 轮询order.status，容易漏撤单、漏部分成交、或在同一帧重复下单。
天勤TqSdk在tqsdk.lib里提供InsertOrderTask等任务类，把「挂单—等待—撤单」封装进与wait_update协作的模型。下面说明适用场景、最小用法、与主循环关系，具体 API 以当前文档为准。
一、什么情况下用手写报单链太累
- 限价单挂在盘口，要直到成交或超时撤单
- 部分成交后 remainder 如何处理要一致
- 同一策略里多处下单，状态变量散落
若只是「目标净仓 = 3」，优先TargetPosTask；限价挂单是执行层细节，再考虑InsertOrderTask。
二、任务类与 wait_update 的关系
TqSdk 推荐在while True: api.wait_update()里驱动。InsertOrderTask在每次wait_update后推进内部状态，你只需创建任务并在循环里调用其更新方法（以文档示例为准，常见模式如下）：
fromtqsdkimportTqApi,TqAuth,TqSimfromtqsdk.libimportInsertOrderTask api=TqApi(TqSim(),auth=TqAuth("账户","密码"))symbol="SHFE.rb2510"quote=api.get_quote(symbol)# 参数名、方向、开平以 reference/tqsdk.lib.rst 为准task=InsertOrderTask(api,symbol,direction="BUY",offset="OPEN",volume=1,limit_price=3500)whileTrue:api.wait_update()task.update()# 若文档为其他方法名，以文档为准iftask.is_finished():# 或文档中的完成判断print("order task done",task.order)breakapi.close()上线前在模拟盘对照文档核对：update/is_finished等名称随版本可能调整，以你安装的tqsdk为准。
三、与 insert_order 手写对比
| 方式 | 适合 |
|---|---|
insert_order一次 | 市价或立即关心下一帧状态 |
InsertOrderTask | 限价持续有效、需自动撤改 |
InsertOrderUntilAllTradedTask | 必须全部成交才继续（另文） |
手写时要自己对order.volume_left、order.status做状态机；任务类把常见路径封装，减少漏分支。
四、集成到策略主循环
不要把InsertOrderTask放在没有wait_update的代码路径里。典型结构：
- 信号层判定「需要挂限价单」
- 创建
InsertOrderTask，记录 task 引用 - 主循环每帧
task.update()，直到完成或超时 - 完成后再恢复信号逻辑或设
TargetPosTask
同一 symbol 避免同时多个未完成任务，否则撤单对象可能搞混。
五、注意边界
- 涨跌停、非交易时段报单会失败，任务类不替代时段过滤。
- 部分成交后策略总目标仓仍要对齐
position。 - 模拟与实盘撮合不同，限价挂单在
TqSim里先测行为。
总结
限价挂单反复漏撤单、漏部分成交，根因通常是手写insert_order却没有与wait_update同步的状态机。若策略目标是净仓、追价不紧，优先TargetPosTask；若必须「挂限价、等待、未成再撤再挂」，再考虑tqsdk.lib里的InsertOrderTask，在每次wait_update后调用文档规定的update（及完成判断），直到任务结束再恢复信号逻辑。
集成时注意：同一 symbol 避免多个未完成任务并行；涨跌停与非交易时段仍会拒单，任务类不替代时段过滤；部分成交后总仓位仍要对齐position。模拟与实盘撮合不同，限价排队行为须在TqSim或TqKq里先测「成交 / 撤单 / 超时」是否符合预期。
建议以本地reference/tqsdk.lib.rst官方示例为准跑通一轮（方法名随版本可能变化），再嵌入信号模块；上线前用日志记录每次 task 创建、完成、撤单原因，便于与客户端委托列表对照。
FAQ
1）和 TargetPosTask 能同时用吗？
可以，注意同一合约委托冲突，先完成挂单 task 再调目标仓。
2）超时怎么设？
以 lib 文档参数为准，无则外层计时器 + 主动 cancel。
3）多合约多个 task？
每个合约独立 task 实例，循环内逐个 update。
4）回测能用吗？
视回测撮合是否支持限价排队，需实测。
风险提示
本文用于程序化交易技术说明，不构成投资建议。