逻辑盘管理使用说明 & xs_opend Python API

使用说明

xs_opend 是先胜内部逻辑盘交易 SDK。它封装的是交易接口与逻辑盘账本，不封装富途行情策略接口。

如果策略需要行情、K 线、盘口、实时快照等能力，请继续使用富途官方 OpenD 行情 API。生产上建议：行情由富途 OpenD 提供，交易提交与逻辑账本由 xs_opend 提供，账本状态由常驻 worker 更新。

重要 1.1.1 版本开始，推荐架构是：策略下单，worker 接收富途订单推送并维护账本，OMS 只负责展示与人工操作入口。

一、业务概念

逻辑盘是在一个富途 A 股模拟盘之上拆分出来的内部账本。多个策略可以共用同一个富途模拟账户，但在先胜数据库里分别拥有独立的现金、持仓、订单、成交、盈亏与资金流水。

二、新版架构

1. worker 负责账本更新

生产推荐只让 worker 持续维护账本。worker 运行后会做几件事：

• 监听富途 TradeOrderHandlerBase 订单推送。
• 把富途原始状态归一为先胜内部状态，例如 SUBMITTED、PART_FILLED、FILLED、CANCELLED、REJECTED。
• 按推送里的累计成交数量计算增量成交，更新现金、持仓、冻结和成交流水。
• 定时刷新持仓现价、昨收、个股今日涨跌。
• 定时同步真实盘资产，例如当前资产、基准资产、可分配额度。
• 低频全量同步活动订单，防止偶发漏推送。

2. 策略程序负责下单和读取本地状态

策略程序通过 xs_place_order() 提交订单，然后通过 xs_get_order_list()、xs_get_position_list()、xs_get_funds() 读取数据库中的本地账本。

策略程序不应该高频调用 xs_sync() 轮询富途订单。这个接口会触发富途 order_list_query(refresh_cache=True)，容易打满富途限频，尤其是多个策略同时运行时。

三、OMS 页面使用说明

1. 线上/测试环境

• 线上环境连接生产库 xianshengweb_product，逻辑盘 ID 通常以 LSIM 开头。
• 测试环境连接测试库 xianshengweb_copy_dev，逻辑盘 ID 通常以 TEST 开头。
• 本机地址 localhost、127.0.0.1、192.168.* 默认识别为测试环境。
• 线上域名 oms.* 默认识别为线上环境。

2. ！！！测试库与生产库完全隔离

排查环境问题时，先确认三件事：OMS 当前 URL、Python SDK 的 dsn、worker 启动命令里的 --dsn 是否指向同一个环境。

3. OpenD 账户

OpenD 账户代表真实富途模拟盘。创建时需要维护账户名称、OpenD host、OpenD port、市场、可选 futu_acc_id。一个 worker 通常只负责同步一个真实盘及其下属逻辑盘。

4. 逻辑盘

逻辑盘是策略运行的最小账本单位。创建时填写名称、初始资金、运行时间 RUN AT、策略注释。策略注释用于复盘，不参与交易逻辑。

5. 账本服务

账本服务页面用于查看 worker 是否在线、最近心跳、订单推送时间、全量同步时间、价格刷新时间、队列深度和处理日志。测试环境下会按浏览器本地用户标识区分不同电脑上的 worker。

四、资金与账本规则

1. 真实盘额度

真实盘已分配 = sum(ACTIVE 逻辑盘 total_deposit)

真实盘可分配 = base_assets
            - sum(所有逻辑盘 total_deposit)
            + sum(DELETED 逻辑盘 released_on_deleted)

逻辑盘运行期间的持仓涨跌不影响真实盘可分配额度。只有删除逻辑盘时，最终释放现金会通过 released_on_deleted 回到真实盘可分配额度。

2. 冻结规则

3. 持仓字段

五、Python 接入准备

1. 安装 SDK

SDK 以 wheel 包发布。当前建议安装最新 xs_opend-1.1.1-py3-none-any.whl。公司共享目录示例：

python3 -m venv ~/.xs-opend-worker
~/.xs-opend-worker/bin/python -m pip install -U '/Volumes/990PRO_RAID1/pyShares/先胜api/xs_opend-1.1.1-py3-none-any.whl'

不要直接用系统 python3 -m pip install 安装到系统 Python。macOS 新版 Python 可能出现 externally-managed-environment，固定虚拟环境可以避免不同电脑上 python3 与 pip 指向不同解释器。

2. ！！！运行环境

3. 导入方式

from xs_opend import XsOpenDClient, XsRejectError, XsOpenDError

旧源码路径导入如 from xs_OpenD.xs_opend import ... 只适合直接运行源码目录，不适合作为生产策略的标准写法。生产以 wheel 安装后的 from xs_opend import ... 为准。

六、账本服务 worker

1. 启动命令

OMS 的“账本服务”页面可以按当前环境、用户标识、真实盘、同步间隔生成启动命令。命令本质类似：

~/.xs-opend-worker/bin/python -m xs_opend.worker \
  --dsn 'postgresql://xsquant_user:***@192.168.2.1:5432/xianshengweb_product?sslmode=disable&gssencmode=disable&connect_timeout=10&options=-c%20TimeZone%3DAsia%2FShanghai' \
  --env-tag production \
  --worker-id p000-broker-3-worker \
  --client-id p000 \
  --client-label p000 \
  --broker-account-id 3 \
  --full-sync-interval 300 \
  --price-sync-interval 10 \
  --heartbeat-interval 5 \
  --push-queue-maxsize 10000 \
  --snapshot-batch-size 200 \
  --snapshot-batch-sleep 0.35

Docker 部署时请使用 python -m xs_opend.worker。注意不要写成 python -m -m xs_opend.worker。

2. 日志事件

3. 限频与缓存

• worker 处理订单推送不调用富途查询接口，只按推送快照更新账本。
• 全量同步按真实盘合并查询。一个真实盘下多个逻辑盘，不会每个逻辑盘各查一次富途订单。
• 没有活动订单时，全量同步不会查富途订单，所以日志出现 真实盘订单查询 0 次 是合理的。
• 资产、持仓、订单、成交查询在 Broker 层使用 refresh_cache=True，避免读到富途端缓存旧值。
• 快照接口 get_market_snapshot 没有 refresh_cache 参数，worker 通过 snapshot_batch_size 和 snapshot_batch_sleep 控制批量与节奏。
• 不要让策略用 xs_sync() 高频轮询订单状态，否则会和 worker 的兜底同步叠加，快速触发富途限频。

七、Client 初始化

client = XsOpenDClient(
    dsn=None,
    logic_account_id=None,
    host="host.docker.internal",
    port=11111,
    futu_acc_id=None,
    dry_run=False,
    broker=None,
    config_path=None,
    auto_sync=False,
)

1. 参数说明

2. 运行模式

八、Python API 详解

order = client.xs_place_order(
    code="SZ.000001",
    qty=300,
    price=11.00,
    trd_side="BUY",
    order_type="LIMIT",
    remark="strategy_alpha_buy_001",
)

client.xs_cancel_order("XSO-7DF1C6ACF1664095A765")

funds = client.xs_get_funds()

positions = client.xs_get_position_list()

orders = client.xs_get_order_list()

deals = client.xs_get_deal_list()

result = client.xs_sync()

client.xs_sync_position_prices_from_broker()

九、推荐代码

1. 本机测试逻辑盘

from xs_opend import XsOpenDClient

TEST_DSN = (
    "postgresql://xsquant_user:xianshengQuant2025@192.168.2.1:5432/"
    "xianshengweb_copy_dev?sslmode=disable&gssencmode=disable&connect_timeout=10"
)

with XsOpenDClient(
    dsn=TEST_DSN,
    logic_account_id="TEST-20260609-0017",
    host="127.0.0.1",
    port=11111,
) as client:
    print(client.xs_get_funds())
    print(client.xs_get_position_list())

2. 生产策略下单

from xs_opend import XsOpenDClient, XsRejectError

LOGIC_ID = "LSIM-20260610-0018"

try:
    with XsOpenDClient(logic_account_id=LOGIC_ID) as client:
        order = client.xs_place_order(
            code="SZ.002910",
            qty=500,
            price=9.20,
            trd_side="BUY",
            order_type="LIMIT",
            remark="morning_signal",
        )
        print("下单成功:", order["logic_order_id"], order.get("futu_order_id"))
except XsRejectError as exc:
    print("逻辑盘拒单:", exc)

3. 等待订单结果的正确方式

下单后用本地订单表判断状态，等待 worker 推送更新。不要在循环里调用 xs_sync()。

import time
from xs_opend import XsOpenDClient

TERMINAL = {"FILLED", "CANCELLED", "REJECTED"}

with XsOpenDClient(logic_account_id="LSIM-20260610-0018") as client:
    order = client.xs_place_order(
        code="SZ.002910",
        qty=500,
        price=9.20,
        trd_side="BUY",
        order_type="LIMIT",
        remark="wait_local_order_status",
    )
    logic_order_id = order["logic_order_id"]

    for _ in range(120):
        orders = client.xs_get_order_list()
        current = next((o for o in orders if o["logic_order_id"] == logic_order_id), None)
        if current:
            print(current["status"], current.get("dealt_qty"), current.get("dealt_avg_price"))
            if current["status"] in TERMINAL:
                break
        time.sleep(0.5)

4. 反例：高频 xs_sync

# 不推荐：这会不断调用富途 order_list_query，容易限频
while True:
    client.xs_sync()
    time.sleep(0.4)

十、常见问题

1. 不传 logic_account_id 会怎样？

进入直连模式，直接操作富途模拟盘，不写先胜逻辑盘表。正式策略不要这样运行。

2. 为什么 logic account not found？

常见原因是环境库不一致。例如策略默认连接生产库，但传入的是测试库里的 TEST-... 逻辑盘。测试逻辑盘请显式传测试 DSN。

3. 为什么 worker 日志里“真实盘订单查询 0 次”？

如果当前没有活动订单，worker 全量同步不会查富途订单。这是为了减少限频消耗，是正常行为。

4. 为什么成交后可用数量比持仓数量少？

通常是存在活动卖单冻结了股票。查看订单列表中是否有 SUBMITTED 或 PART_FILLED 的卖单。若存在异常长期 PENDING_SUBMIT 且没有富途订单号，需要人工排查或修复。

5. 富途模拟盘手续费怎么处理？

富途模拟盘 API 不提供稳定的订单费用明细。逻辑盘当前主要基于成交价和成交数量维护账本；如需更真实成本，应在先胜内部增加可配置费率模型。

6. 可以用市价单吗？

不可以。xs_place_order() 当前只允许 LIMIT。需要快速成交时，请用激进限价模拟。

7. OMS 会自己更新账本吗？

新版架构中，OMS 主要展示数据库状态。账本更新主要由 worker 完成。OMS 的刷新按钮用于重新读取展示数据，不应该承担核心账本维护职责。