.. _evaluation_trace:

实盘评测环境留痕指引
=================================================

当期货公司要求您先在评测环境完成穿透式监管留痕测试时，可以通过 TqSdk 显式切换到评测采集库完成登录、下单、撤单等测试流程，而不需要再手工替换 DLL 文件。

本文适用于以下场景：

* 期货公司客户经理明确要求您先做外接评测
* 您已经拿到该期货公司的评测账号、服务器信息或测试指引
* 您使用的是 Windows 64 位环境

.. note::

   TqSdk 安装包会同时携带生产采集库与评测采集库。只有在期货公司明确要求使用评测环境时，才需要按本文切换；默认情况下无需做任何额外设置。


使用前准备
-------------------------------------------------

开始前，请先确认以下事项：

1. 当前运行环境为 Windows 64 位。
2. 已安装支持该功能的依赖包，运行 ``pip install -U tqsdk_ctpse`` 确保 ``tqsdk_ctpse`` 版本 >= 1.1.0。
3. 已从期货公司获取评测环境所需信息，例如评测账号、密码、柜台地址或测试要求。
4. 已准备好需要执行的测试脚本，或者能够运行最小登录程序。


如何切换到评测采集库
-------------------------------------------------

TqSdk 通过环境变量 ``CTPSE_RUN_MODE`` 控制当前使用的采集库：

* ``PRODUCTION``: 生产采集库
* ``TEST``: 评测采集库

默认值为 ``PRODUCTION``。如果您需要在评测环境完成留痕，请在运行策略前把它设置为 ``TEST``。


方式一：在命令行中设置
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

如果您是通过命令行运行 Python 脚本，建议优先使用这种方式。

Windows ``cmd``::

  set CTPSE_RUN_MODE=TEST
  python your_strategy.py

Windows PowerShell::

  $env:CTPSE_RUN_MODE="TEST"
  python .\your_strategy.py

设置完成后，当前终端里启动的程序就会使用评测采集库。


方式二：在 Python 代码中设置
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

如果您希望把测试脚本单独保存，也可以在代码开头设置环境变量。请注意，建议在导入 ``tqsdk`` 之前完成设置。

.. code-block:: python

   import os

   os.environ["CTPSE_RUN_MODE"] = "TEST"

   from tqsdk import TqApi, TqAuth, TqAccount

   api = TqApi(
       account=TqAccount("期货公司", "评测账号", "评测密码"),
       auth=TqAuth("天勤账号", "天勤密码"),
   )

   print("登录成功，当前已使用评测采集库")

   api.close()

如果您已有现成的交易或测试脚本，通常只需要增加这一个环境变量设置，其余登录、下单、撤单代码不需要修改。


推荐测试流程
-------------------------------------------------

如果期货公司已经给出明确测试要求，请优先按对方要求执行。常见流程通常如下：

1. 切换 ``CTPSE_RUN_MODE=TEST``。
2. 使用评测账号登录。
3. 按期货公司要求完成留痕相关操作，例如登录、查询资金、下单、撤单、平仓等。
4. 保存测试结果或截图，并提交给期货公司客户经理确认。
5. 测试完成后恢复默认配置。

如果期货公司只要求您“完成评测”，但没有明确说明具体步骤，建议至少完成以下几个动作：

* 成功登录一次
* 查询一次账户或持仓
* 完成一次下单
* 完成一次撤单，或完成一次开仓和平仓


测试完成后如何恢复默认模式
-------------------------------------------------

测试结束后，清除环境变量即可恢复默认生产行为。

Windows ``cmd``::

  set CTPSE_RUN_MODE=

Windows PowerShell::

  Remove-Item Env:CTPSE_RUN_MODE

也可以直接关闭当前终端，并在新的终端窗口中重新运行程序。只要没有设置 ``CTPSE_RUN_MODE=TEST``，TqSdk 就会继续使用生产采集库。


常见问题
-------------------------------------------------

为什么还需要期货公司提供评测环境信息？
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

TqSdk 解决的是“如何切换评测采集库”的问题，但评测账号、服务器地址、测试要求仍然需要由期货公司提供。


为什么不再需要手工替换 DLL？
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

生产采集库和评测采集库会随安装包一起分发。您只需要切换环境变量，不需要再手工查找、复制或覆盖 DLL 文件。


正式交易前需要做什么？
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

完成评测后，请清除 ``CTPSE_RUN_MODE``，再使用正式环境账号运行程序。这样程序会恢复为默认的生产采集库模式。