🔍
项目文档/架构设计/集成模式/交易连接器集成/富途证券集成

富途证券集成

📎 引用文件

本文引用的文件 - agent/src/trading/connectors/futu/sdk.py - agent/src/trading/connectors/futu/profiles.py - agent/src/trading/connectors/futu/__init__.py - agent/backtest/loaders/futu.py - agent/tests/test_futu_loader.py - agent/src/config/env_schema.py

目录

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与可靠性
  8. 故障排查指南
  9. 结论
  10. 附录

简介

本文件面向需要在本地部署并集成富途 OpenD 的开发者，系统性说明富途连接方式、安全认证机制、多市场（港股、美股、A股）交易能力、订单管理、成交回报与持仓管理流程，以及实时行情订阅、历史数据获取和账户信息查询的实现方案。文档同时覆盖本地客户端部署、网络连接管理与异常处理策略，帮助读者在模拟盘与实盘环境之间安全切换。

项目结构

围绕富途集成的关键代码分布在以下模块： - 连接器层：通过官方 futu-api SDK 封装对本地 OpenD 的连接与读写操作，提供账户、持仓、订单、报价、历史K线等只读能力，并在受控条件下支持下单/撤单。 - 回测数据加载器：基于 futu-api 拉取港股与A股的OHLCV数据，支持分页、缓存与标准化输出。 - 配置与环境变量：集中定义富途主机、端口、交易密码MD5等环境变量，并提供持久化配置文件路径。 - 预置交易画像：内置纸盘/实盘只读/可下单等多类 profile，自动区分 SIMULATE/REAL 环境并做身份守卫。

graph TB A["应用/工具调用"] --> B["Futu 连接器<br/>sdk.py"] B --> C["OpenD 网关<br/>127.0.0.1:11111"] B --> D["futu-api SDK"] D --> E["富途服务器"] A --> F["回测数据加载器<br/>backtest/loaders/futu.py"] F --> C F --> D G["配置与环境变量<br/>env_schema.py"] --> B G --> F

图表来源 - agent/src/trading/connectors/futu/sdk.py:1-25 - agent/backtest/loaders/futu.py:106-139 - agent/src/config/env_schema.py:164-165

章节来源 - agent/src/trading/connectors/futu/sdk.py:1-25 - agent/backtest/loaders/futu.py:106-139 - agent/src/config/env_schema.py:164-165

核心组件

章节来源 - agent/src/trading/connectors/futu/sdk.py:71-158 - agent/src/trading/connectors/futu/profiles.py:14-80 - agent/backtest/loaders/futu.py:106-139

架构总览

富途集成采用“本地 OpenD 网关 + SDK”的安全模式： - 本地 OpenD 运行在用户机器上，持有富途登录态；应用仅通过本地 TCP 与 OpenD 通信，不接触富途凭证。 - 每次连接前进行端口探测，若网关不可达则快速失败，避免SDK堆栈暴露。 - 账户选择依据 trd_env 匹配 profile 的环境，确保纸盘/实盘隔离。 - 实盘下单需要解锁交易上下文，使用交易密码的 MD5 作为口令，且必须来自受信任的环境变量。

sequenceDiagram participant App as "应用" participant Conn as "连接器(sdk.py)" participant Gate as "OpenD 网关" participant SDK as "futu-api SDK" participant Broker as "富途服务器" App->>Conn : 请求账户/行情/订单/下单 Conn->>Gate : 检查端口可达性 alt 不可达 Conn-->>App : 返回错误提示启动OpenD else 可达 Conn->>SDK : 创建 OpenQuoteContext/OpenSecTradeContext SDK->>Broker : 鉴权与业务调用 Broker-->>SDK : 返回结果 SDK-->>Conn : (ret_code, data) Conn-->>App : 标准化结果或错误信封 end

图表来源 - agent/src/trading/connectors/futu/sdk.py:664-703 - agent/src/trading/connectors/futu/sdk.py:223-272

详细组件分析

连接器与账户/持仓/订单/行情/历史

flowchart TD Start(["开始"]) --> ResolveAcc["解析账户ID<br/>trd_env匹配"] ResolveAcc --> EnvCheck{"环境=纸盘/实盘?"} EnvCheck --> |纸盘| ReadOps["读取账户/持仓/订单/报价/历史"] EnvCheck --> |实盘| Unlock{"是否需要解锁交易上下文?"} Unlock --> |是| UnlockPwd["读取交易密码MD5并解锁"] Unlock --> |否| ReadOps UnlockPwd --> ReadOps ReadOps --> End(["结束"])

图表来源 - agent/src/trading/connectors/futu/sdk.py:275-393 - agent/src/trading/connectors/futu/sdk.py:617-643

章节来源 - agent/src/trading/connectors/futu/sdk.py:275-393 - agent/src/trading/connectors/futu/sdk.py:617-643

订单管理与成交回报

sequenceDiagram participant Client as "调用方" participant Order as "place_order/cancel_order" participant TradeCtx as "交易上下文" participant Futu as "富途API" Client->>Order : 传入symbol/side/quantity/order_type/limit_price Order->>Order : 参数校验与类型转换 Order->>TradeCtx : 打开交易上下文 Order->>TradeCtx : 解析账户ID(trd_env) alt 实盘 Order->>TradeCtx : unlock_trade(password_md5) end Order->>Futu : place_order / modify_order(CANCEL) Futu-->>Order : 返回ret_code与数据 Order-->>Client : 标准化结果或错误信封

图表来源 - agent/src/trading/connectors/futu/sdk.py:407-539 - agent/src/trading/connectors/futu/sdk.py:542-614

章节来源 - agent/src/trading/connectors/futu/sdk.py:407-539 - agent/src/trading/connectors/futu/sdk.py:542-614

多市场交易能力（港股、美股、A股）

章节来源 - agent/src/trading/connectors/futu/sdk.py:71-93 - agent/backtest/loaders/futu.py:39-55

期权交易与融资融券

[本节为概念性说明，不直接分析具体文件]

实时行情订阅、历史数据与账户查询

章节来源 - agent/src/trading/connectors/futu/sdk.py:336-393 - agent/backtest/loaders/futu.py:140-253

本地客户端部署、网络连接管理与异常处理

章节来源 - agent/src/trading/connectors/futu/sdk.py:664-679 - agent/src/trading/connectors/futu/sdk.py:712-753

依赖关系分析

graph LR Env["环境变量/配置文件<br/>env_schema.py"] --> Conn["连接器<br/>sdk.py"] Env --> Loader["数据加载器<br/>loaders/futu.py"] Conn --> SDK["futu-api SDK"] Loader --> SDK SDK --> OpenD["OpenD 网关"] OpenD --> Broker["富途服务器"]

图表来源 - agent/src/config/env_schema.py:164-165 - agent/src/config/env_schema.py:294-294 - agent/src/trading/connectors/futu/sdk.py:656-703 - agent/backtest/loaders/futu.py:118-139

章节来源 - agent/src/config/env_schema.py:164-165 - agent/src/config/env_schema.py:294-294 - agent/src/trading/connectors/futu/sdk.py:656-703 - agent/backtest/loaders/futu.py:118-139

性能与可靠性

章节来源 - agent/backtest/loaders/futu.py:176-253 - agent/src/trading/connectors/futu/sdk.py:664-679

故障排查指南

章节来源 - agent/src/trading/connectors/futu/sdk.py:223-272 - agent/src/trading/connectors/futu/sdk.py:617-643 - agent/src/trading/connectors/futu/sdk.py:712-753

结论

本集成通过本地 OpenD 网关与官方 SDK 实现了安全、可控的富途接入，覆盖港股、美股、A股的多市场数据与交易能力。连接器提供账户、持仓、订单、行情与历史数据的标准化接口，并在纸盘/实盘间进行严格隔离。数据加载器支持高效的历史数据拉取与缓存。整体设计强调失败关闭、错误透明与可观测性，适合在生产环境中稳健运行。

[本节为总结性内容，不直接分析具体文件]

附录

环境变量与配置

章节来源 - agent/src/config/env_schema.py:164-165 - agent/src/config/env_schema.py:294-294

测试要点

章节来源 - agent/tests/test_futu_loader.py:81-124 - agent/tests/test_futu_loader.py:167-206 - agent/tests/test_futu_loader.py:226-333

← 其他券商平台集成 连接器架构设计 →