一句话结论：真实券商接入分阶段——今天只做只读 Adapter 骨架：能查资金/持仓/订单、能 sync，但 submit_order/ cancel_order代码层阻断；默认模式仍是 simulated，不能误开真实交易。

新增内容：broker mode（simulated/ real_readonly/ real_trading）、RealBrokerConfig、RealBrokerReadOnlyAdapter；只读调用交易方法抛出 BrokerReadOnlyError。

模块：live/broker.py；测试覆盖只读返回与交易阻断。

边界：real_trading仅预留名称，未实现真实下单；敏感凭证不进仓库。

承接 Day 123：日终流程已走统一券商接口 + SimulatedBroker；本篇搭真实券商接入位置，先读清楚再决定要不要动。

工程代码：https://github.com/xuyafei/quant_strategy

前面两篇，我们已经完成了两个关键动作：

第 46 篇：定义统一券商接口
第 47 篇：让日终纸面交易跑在统一券商接口上

这意味着我们的工程里已经有了一个“交易插座”。

日终流程可以把订单计划交给这个插座。

现在的问题是：

下一步是不是直接接真实券商，然后开始下单？

我觉得还不能。

今天这一步要做的是：

真实券商 Adapter 骨架，但只读。

本系列代码仓库：

https://github.com/xuyafei/quant_strategy

一、为什么不能直接真实下单

从工程上看，我们已经越来越接近实盘：

股票池管理
真实股票池回测
目标权重
订单计划
订单预检查
纸面交易
账户状态持久化
日终脚本
每日调度
统一券商接口
模拟券商执行

但真实券商不是一个普通模块。

它连接的是账户和资金。

只要下单接口一打开，代码里的一个边界错误、一个单位错误、一个股票代码格式错误，都可能变成真实交易。

比如：

100 股和 100 手混淆
可用持仓和总持仓混淆
现金余额和可用资金混淆
撤单状态和废单状态混淆
代码后缀不一致
订单状态映射错误
重复运行导致重复下单

这些问题在回测里可能只是一个 bug。

但在真实交易里，就是实际损失。

所以我觉得真实券商接入应该分阶段：

只读查询
-> 人工确认下单
-> 小资金白名单下单
-> 自动实盘

今天只做第一步。

二、什么是只读 Adapter

只读 Adapter 的意思是：

它可以做：

查资金
查持仓
查订单
同步状态

但不能做：

提交订单
撤单

也就是说，它可以让系统看到真实账户，但不能让系统动真实账户。

这一步的意义很大。

因为接入真实券商后，第一件事不是交易，而是确认这些问题：

真实资金字段能不能正确读取？
总资产和可用资金是否一致？
持仓股票代码是否和策略代码格式一致？
总持仓和可用持仓是否区分正确？
订单状态能不能映射成统一状态？
券商返回的字段有没有缺失？
同步时间是否可靠？

只有这些读数稳定之后，才值得讨论真实下单。

三、这次新增了什么

这次主要还是在：

live/broker.py

新增了几类内容。

1. broker mode

现在工程里定义了三种券商模式：

simulated
real_readonly
real_trading

它们分别代表：

simulated      模拟券商，不连接真实券商
real_readonly  真实券商只读，只查不下单
real_trading   真实交易模式，后续预留

当前默认仍然是：

simulated

这很重要。

默认模式不能有真实交易能力。

2. RealBrokerConfig

新增了：

RealBrokerConfig

它只存放非敏感配置：

provider
account_id
mode

比如：

provider = qmt
account_id = demo
mode = real_readonly

注意，这里不存密码、Token、交易密钥。

真实账户的敏感信息后面应该通过环境变量、本机配置文件或券商客户端安全机制处理，不能写进仓库。

3. RealBrokerReadOnlyAdapter

新增了：

RealBrokerReadOnlyAdapter

它实现统一券商接口里的查询方法：

sync()
get_account()
get_cash()
get_positions()
get_orders()

同时，它明确阻断交易方法：

submit_order()
cancel_order()

如果调用这两个方法，会抛出：

BrokerReadOnlyError

也就是从代码层面防止误下单。

四、为什么只读 Adapter 也要写测试

有人可能会觉得，只读类这么简单，有必要测试吗？

我觉得很有必要。

因为它是安全边界。

这次测试覆盖了三件事：

只读 adapter 能返回账户、持仓快照
只读 adapter 会阻断 submit_order
只读 adapter 会阻断 cancel_order

尤其是后两条。

如果某天我们改代码时不小心让只读 adapter 能下单了，测试应该立刻失败。

量化工程里，不只是收益逻辑需要测试。

安全边界更需要测试。

五、它和上一篇有什么区别

第 123 篇做的是：

日终纸面交易 -> 统一券商接口 -> SimulatedBroker

也就是让主流程开始走统一接口。

本篇做的是：

真实券商只读 Adapter 骨架

它不是给日终交易新增一个真实下单模式。

而是先把真实券商未来要接入的位置搭出来，并且明确：

当前只能读
不能交易

这两个动作一个偏“流程接入”，一个偏“真实券商安全边界”。

六、为什么不把 real_trading 一起做了

因为太早了。

真实下单至少还要补几层东西：

真实券商 API 字段映射
订单状态映射
成交回报同步
下单前二次确认
白名单股票
单日最大下单金额
单笔最大下单金额
重复下单保护
盘后对账
异常通知
人工停止开关

如果这些都没有，直接开放 real_trading是不负责任的。

所以今天虽然定义了 real_trading这个模式名称，但没有实现真实交易能力。

它只是一个后续阶段的目标。

七、当前工程做到哪里了

现在这条实盘链路大概是：

研究回测
-> 目标权重
-> 订单计划
-> 订单预检查
-> 日终纸面交易
-> 统一券商接口
-> 模拟券商
-> 真实券商只读骨架

这意味着我们已经不再只是做一个策略回测脚本。

我们在慢慢补齐一个真实系统该有的结构：

策略层
组合层
风控层
订单层
执行接口层
账户状态层
日报与审计层

但现在仍然没有真实下单。

这点必须反复强调。

八、下一步应该做什么

下一步有两个方向。

第一，继续往真实券商只读走：

选择具体券商
实现真实 sync()
读取真实资金
读取真实持仓
读取真实订单
把券商字段映射成 BrokerAccount / BrokerPosition / BrokerOrder

第二，补实盘安全保护：

交易白名单
单笔金额上限
单日金额上限
人工确认文件
只读 / 模拟 / 真实模式隔离
重复下单保护

我更倾向于先做安全保护，再做具体券商 API。

原因很简单：

券商 API 接起来之后，如果没有保护层，会很危险。

九、小结

第 124 篇做的不是“接上真实券商并开始交易”。

它做的是：

真实券商接入前的只读安全骨架。

这一步看起来克制，但很重要。

因为从今天开始，我们的工程已经开始认真面对真实账户这个问题了。

真实账户接入的第一原则不是“先下单试试”。

而是：

先读清楚，再决定要不要动。