big-qmt/docs/AUDIT_AND_REMEDIATION.md

big-qmt 项目审计与整改建议

• 审计日期：2026-08-28
• 审计范围：服务端 api/、客户端 py-client/
• 审计方式：静态代码检查、调用链核对、只读语法编译
• 当前状态：仅供人工确认，尚未实施代码整改

一、总体结论

当前版本不建议直接进入实盘运行。

服务端存在文件编码导致的启动级错误，且所有 QMT 调用和大对象序列化都在 Tornado 主线程同步执行。客户端的持仓管理、止盈、补仓、撤单和下单确认链存在多处必现错误或状态不一致风险。

建议按以下顺序处理：

1. 恢复服务端和客户端的基本可运行性。
2. 修复交易安全相关的订单确认、撤单和持仓数据模型。
3. 为止盈、补仓、订单状态机建立测试。
4. 在确认 QMT 线程约束后优化服务端响应速度。
5. 最后进行结构简化和重复代码清理。

---

二、P0：启动及交易安全问题

2.1 服务端文件编码不一致，程序无法正常编译

位置：api/QMT_API.py:1

现状：

# -*- coding: gbk -*-

文件实际内容包含 UTF-8 字节，只读编译时报错：

SyntaxError: 'gbk' codec can't decode byte ...

影响：服务端可能在载入阶段直接退出，所有 API 不可用。

解决方案：

如果运行环境强制要求 GBK，则必须把整个文件真实转换为 GBK，不能只修改声明。

验收标准：

• 中文日志和错误响应无乱码。

2.2 客户端持仓对象被错误当成字典和二元组使用

位置：py-client/strategy/trend/positions.py:32-40

现状：client.positions() 返回 list[Position]，但代码同时使用：

for idx, pos in positions:
code = pos["stock_code"]
avg_price = pos.get("avg_price", 0)

行情结果同样是 Tick dataclass，却使用字典的 .get()。

影响：进入持仓管理后必然抛出 TypeError 或 AttributeError，止盈和补仓完全无法执行。

解决方案：

全项目统一使用 SDK dataclass + slots，不再混用原始字典。

验收标准：

• 使用真实 Position、Tick 对象执行一轮不抛异常。

2.3 handle_profit 调用参数和函数签名不一致

位置：

• 调用：py-client/strategy/trend/positions.py:58
• 定义：py-client/strategy/trend/positions.py:73

影响：修复持仓遍历后，下一步仍会立即触发 TypeError。

解决方案： 删除未使用的 open_price、strategy_name 或把它们纳入统一模型。

推荐接口：

def handle_profit(
    runtime: Runtime,
    position: Position,
    tick: Tick,
    pnl_rate: float,
) -> ProfitDecision:
    ...

验收标准：

• 静态类型检查能够发现参数数量错误。
• ARMED、RAISED、STEADY、RETREAT 四种状态都有测试。

2.4 补仓流程存在多处必现错误

位置：py-client/strategy/trend/positions.py:118-159

问题包括：

• StateItem 被当成字典调用 .get()。
• orders.busy() 多传入一个 run 参数。
• 某些分支只返回 False，调用方却解包两个值。
• 使用不存在的 run.state.STATUS_ING。
• state.added_num = +1 每次都赋值为 1，并非累加。
• LOSS_TIERS[added_num] 可能数组越界。
• 下单后没有扣减本轮剩余预算，多持仓可能超额补仓。

解决方案：

1. 所有 StateItem 字段改为属性访问。
2. orders.busy(code, "BUY") 使用正确签名。
3. 所有返回分支统一返回结构，推荐使用 dataclass + slots：

@dataclass(frozen=True)
class TradeDecision:
    submitted: bool
    message: str = ""
    reserved_cash: float = 0.0

4. 使用模块常量 STATUS_ING，或把状态定义成 Enum。
5. 补仓次数使用 state.added_num += 1。
6. 当 added_num >= len(LOSS_TIERS) 时明确禁止继续补仓。
7. RunOnce 创建本轮 remaining_cash，每次成功提交补仓后立即扣减。

验收标准：

• 第 0、1、2 次补仓边界均有测试。
• 超过最大补仓次数不会抛异常或继续下单。

2.5 止盈跟踪器每轮重建，无法形成跨轮回撤

位置：py-client/strategy/trend/positions.py:31

影响：每轮都会清空最高盈利网格，止盈状态无法从 ARMED/RAISED 演进至 RETREAT。

解决方案：

1. GridTrailingTracker 应作为 Runtime 字段，在策略启动时只创建一次。
2. 检查是否有定时清理的功能

验收标准：

• 连续输入 2.1%、3.1%、2.9% 能产生 ARMED、RAISED、RETREAT。
• 相同股票不同账户的峰值互不污染。
• 清仓后重新建仓不会继承旧峰值。

2.6 “取消过期订单”只查询可撤状态，没有执行撤单

位置：

• 客户端：py-client/strategy/trend/order.py:74-88
• 服务端：api/QMT_API.py:962-969

影响：过期订单一直保留，订单锁可能长期阻止新交易。

解决方案：

方案 A，推荐：新增按真实委托号撤单接口。

POST /api/order/cancel_by_id
body: {order_id, account_type}

服务端先执行 can_cancel_order()，可撤时调用真正的 cancel()，并返回撤单请求结果。

验收标准：

• 暂时不做验证，后期验证

2.7 低现金资金闸同时跳过卖出管理

位置：py-client/strategy/trend/boot.py:126-134

影响：可用资金不足时直接结束整轮流程，持仓止盈和风险退出也被禁止。

解决方案：

把“是否允许新开仓/补仓”和“是否允许卖出”拆成不同条件。

验收标准：

• 可用现金低于阈值时不开仓、可补仓。
• 同一情况下满足止盈条件的持仓仍然能够提交卖单。

2.9 客户端订单标签未真正传给 QMT

位置：

• 客户端发送：py-client/sdk/trade.py:10-18
• 服务端丢弃：api/QMT_API.py:663

现状：客户端发送 strategyName，服务端调用 passorder() 时却硬编码为 qmt。

解决方案：

1. 统一：strategy_name 为信号的key,m_strRemark为本地业务订单号。
2. 同时修改QMT_API.py

验收标准：

• 下单后在 QMT 委托明细中可以看到客户端标签。
• 能从本地订单 ID 追踪到真实委托号和最终成交。

---

三、P1：服务端响应速度整改

验收标准：

• 一轮策略账户查询由三次以上 QMT 调用下降为一次快照调用。
• 下单后下一次快照不会返回过期的订单状态。

3.3 大量使用 dir() 和 getattr() 反射序列化

位置：

• api/QMT_API.py:920-930
• api/QMT_API.py:943-950
• api/QMT_API.py:979-1031
• api/QMT_API.py:1454-1473

影响：对每个对象遍历全部属性、捕获异常并转字符串，CPU 开销大，返回字段也不稳定。

解决方案：

1. 为订单、成交、资产、持仓等类型定义固定字段映射。
2. 只返回客户端实际使用的字段。
3. 使用统一的轻量转换函数，不在每个 Handler 复制反射循环。
4. 对未知扩展类型单独保留调试接口，不进入高频生产路径。

验收标准：

• 高频订单查询不再调用 dir()。
• 返回 JSON 字段固定并有接口契约测试。
• 相同数据量下序列化 CPU 时间明显下降。

3.5 回调同步写 JSON 文件

位置：api/QMT_API.py:1475-1516

影响：目录创建、反射序列化和格式化写盘可能阻塞 QMT 回调线程。

解决方案：

3. 生产环境关闭 indent=4。
4. 使用临时文件替换，避免半写文件。

验收标准：

• 回调函数本身在毫秒级返回。
• 磁盘慢或不可写时不会阻塞交易回调。
• 写入失败可监控且不会静默丢失。

3.6 客户端 HTTP 没有连接池

位置：py-client/sdk/client.py:28-47

影响：每次 urlopen() 都可能新建连接，高频轮询产生额外 TCP 开销。

解决方案：

1. 改用支持连接池的 HTTP 客户端，如 httpx.Client 或 requests.Session。
2. 整个策略生命周期复用一个 Client。
3. 设置连接、读取和总超时，不只设置单一 timeout。
4. 只对幂等查询配置有限重试；下单和撤单不能自动盲重试。

验收标准：

• 连续请求复用 TCP 连接。
• 查询超时能重试，下单超时进入“结果未知、需对账”状态而不是重复下单。

---

四、P1：客户端其他逻辑与可靠性问题

4.1 新开仓订单锁可能在同一轮失效

位置：

• py-client/strategy/trend/open.py:24
• py-client/strategy/trend/order.py:61-65
• py-client/strategy/trend/order.py:99-101

现状：开仓检查 busy()，该方法只查看 data；新下单后只把键加入 index，没有加入 data。

解决方案：

1. 统一锁判断，只保留一个权威接口。
2. 下单成功后立即插入本地 pending OrderItem。
3. 信号进入处理前按证券代码去重。
4. 每轮刷新券商订单后用真实订单覆盖本地 pending 状态。

验收标准：同一轮两个来源返回同一证券信号时最多提交一笔买单。

4.2 Runtime 文档和字段不一致

位置：py-client/strategy/trend/runtime.py

现状：文档描述 peak_grids，实际 dataclass 没有该字段；持仓代码仍可能访问它。

解决方案：

2. 如果统一使用 GridTrailingTracker，删除 peak_grids 及所有引用。
3. 不应同时保留两套止盈峰值实现。

验收标准：项目中只有一种网格峰值状态来源。

4.3 ping_api_host() 参数无效且吞掉退出信号

位置：py-client/main.py:59-76

问题：

• rpc_host 参数没有使用。
• connect_timeout 参数没有使用。
• 使用裸 except:，会捕获 KeyboardInterrupt 和 SystemExit。
• 无限重试没有最大日志节流或取消事件。

解决方案：

1. 函数重命名为 wait_for_qmt_api()，删除无用参数。
2. 仅捕获网络类异常和 APIError。
3. 允许 KeyboardInterrupt 正常终止。
4. 使用 threading.Event.wait() 或可取消等待。

验收标准：API 不可用时可以通过 Ctrl+C 立即退出。

4.5 状态文件缺少完整对账和生命周期

位置：py-client/strategy/trend/state.py

解决方案：

1. 启动时用真实持仓、订单和成交三方对账。
2. ING 状态必须根据真实订单结果转为 OK、FAILED、CANCELED 或 UNKNOWN。
3. 已清仓证券应从状态中删除，并清除观察器和止盈峰值。
4. 状态文件不增加版本号，不增加新字段。

验收标准：程序在下单后崩溃并重启，能够从券商真实状态恢复，而不会重复下单。

4.6 日志调用格式错误且异常上下文不足

位置：py-client/

现状：不符合 logging 格式化规则。

解决方案：

1. 统一优化日志打印同时输出至文本文件（每天一个文件）。

验收标准：日志输出期间不出现 logging 自身的格式化异常。