feat: 完善 QMT 交易模块

2026-02-24 13:06:14 +08:00
parent 29706da299
commit 5628fbb34c
13 changed files with 1249 additions and 5368 deletions
--- a/qmt/qmt_functionality.md
+++ b/qmt/qmt_functionality.md
@@ -58,7 +58,13 @@ QMT 模块是 NewStock 量化交易系统的实盘交易执行模块，通过 `x

 交易信号通过 Redis 消息队列传递，每个策略对应一个独立的队列。消息格式为 JSON 对象，包含股票代码、操作类型、价格、时间戳等字段。系统对每条消息进行严格校验，包括日期校验、时间戳校验、必填字段校验等，确保只有当天的有效指令才会被执行。

-买入逻辑支持槽位控制，通过 `total_slots` 参数限制同时持有的股票数量。系统根据可用资金和目标槽位自动计算每只股票的买入数量，金额过小或股数不足的请求会被拦截。卖出逻辑则根据 Redis 中的虚拟持仓和实盘可用持仓计算实际卖出数量，确保不会超卖。
+买入逻辑支持两种模式：
+
+1. **槽位控制模式**：通过 `total_slots` 参数限制同时持有的股票数量。系统根据可用资金和目标槽位自动计算每只股票的买入数量，金额过小或股数不足的请求会被拦截。
+
+2. **仓位百分比模式**：通过 `position_pct` 参数指定目标持仓占账户总资产的比例。系统根据账户总资产计算目标金额，然后转换为具体股数进行下单。该模式无持仓数量限制。
+
+卖出逻辑根据策略配置模式有所不同：槽位模式下根据 Redis 中的虚拟持仓和实盘可用持仓计算实际卖出数量；百分比模式下执行清仓操作。

 ### 3.3 持仓管理

@@ -193,9 +199,41 @@ QMT 模块是 NewStock 量化交易系统的实盘交易执行模块，通过 `x
 | `redis` | Object | Redis 连接配置，支持 host、port、db、password 等参数 |
 | `qmt_terminals` | Array | QMT 终端列表，每个终端包含唯一标识、别名、路径、账户信息 |
 | `strategies` | Object | 策略配置，键为策略名，值包含使用的终端 ID 和执行参数 |
-| `total_slots` | Integer | 策略的最大持仓股票数量 |
+| `total_slots` | Integer | 策略的最大持仓股票数量（槽位模式） |
+| `order_mode` | String | 下单模式，可选 `slots`（槽位）或 `percentage`（百分比），默认为 `slots` |
 | `auto_reconnect` | Object | 自动重连配置，包含启用状态和执行时间 |

+**槽位模式配置示例：**
+
+```json
+{
+  "strategies": {
+    "strategy_a": {
+      "qmt_id": "terminal_001",
+      "order_mode": "slots",
+      "total_slots": 5,
+      "execution": {
+        "buy_amount_per_stock": 20000,
+        "min_buy_amount": 2000
+      }
+    }
+  }
+}
+```
+
+**百分比模式配置示例：**
+
+```json
+{
+  "strategies": {
+    "strategy_b": {
+      "qmt_id": "terminal_001",
+      "order_mode": "percentage"
+    }
+  }
+}
+```
+
 ## 6. Web 仪表盘功能

 ### 6.1 功能概览
@@ -317,7 +355,152 @@ Web 仪表盘基于 Vue 3 和 Naive UI 组件库开发，提供可视化的系
 | 聚宽 | `.XSHE` / `.XSHG` | `000001.XSHE`、`600519.XSHG` |
 | QMT | `.SZ` / `.SH` | `000001.SZ`、`600519.SH` |

-## 8. 系统架构
+## 8. 百分比下单信号发送端（qmt_percentage_sender.py）
+
+### 8.1 模块定位
+
+`qmt_percentage_sender.py` 是基于**仓位百分比**的 QMT 信号发送端，与槽位模式的 `qmt_signal_sender.py` 并行存在。该模块用于配置为 `order_mode: "percentage"` 的策略，通过指定目标持仓占账户总资产的比例来触发交易。
+
+### 8.2 核心函数
+
+#### `send_qmt_percentage_signal(code, position_pct, action, price, is_backtest, timestamp, redis_config)`
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `code` | str | 股票代码，聚宽格式（如 `000001.XSHE`、`600519.XSHG`） |
+| `position_pct` | float | 目标持仓占总资产的比例，范围 0.0 ~ 1.0（如 0.2 表示 20%） |
+| `action` | str | 交易动作，固定为 `"BUY"` 或 `"SELL"` |
+| `price` | float | 当前最新价格，用于实盘限价单参考 |
+| `is_backtest` | bool | 是否为回测模式（True/False） |
+| `timestamp` | str | 时间戳字符串，格式 `"YYYY-MM-DD HH:MM:SS"` |
+| `redis_config` | dict | Redis 连接配置，包含 `host`、`port`、`password`、`db`、`strategy_name` 等字段 |
+
+### 8.3 处理流程
+
+```
+策略触发信号
+    │
+    ▼
+1. 环境判断与流量控制
+   ├─ 实盘模式 → 直接通过
+   └─ 回测模式 → 限制最多发送 10 条（防止回测刷爆队列）
+    │
+    ▼
+2. 建立 Redis 连接（socket_timeout=1s）
+    │
+    ▼
+3. 数据转换与规范化
+   └─ 股票代码格式转换：.XSHE → .SZ，.XSHG → .SH
+    │
+    ▼
+4. 构建 JSON 消息体（包含 position_pct 字段）
+    │
+    ▼
+5. 队列路由
+   ├─ 回测 → {strategy_name}_backtest（TTL: 1 小时）
+   └─ 实盘 → {strategy_name}_real（TTL: 7 天）
+    │
+    ▼
+6. 控制台日志输出
+```
+
+### 8.4 消息格式
+
+发送到 Redis 队列的 JSON 消息结构：
+
+```json
+{
+  "strategy_name": "my_strategy",
+  "stock_code": "000001.SZ",
+  "action": "BUY",
+  "price": 15.50,
+  "position_pct": 0.2,
+  "timestamp": "2026-02-17 14:30:00",
+  "is_backtest": false
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `strategy_name` | str | 策略名称，来自 `redis_config['strategy_name']`，用于队列路由和持仓管理 |
+| `stock_code` | str | QMT 格式的股票代码（`.SZ` / `.SH`） |
+| `action` | str | 交易动作，`BUY` 或 `SELL` |
+| `price` | float | 信号触发时的最新价格 |
+| `position_pct` | float | 目标持仓占账户总资产的比例，范围 0.0 ~ 1.0 |
+| `timestamp` | str | 信号生成时间，格式 `YYYY-MM-DD HH:MM:SS` |
+| `is_backtest` | bool | 是否为回测环境发出的信号 |
+
+### 8.5 买卖意图判定逻辑
+
+与槽位模式不同，百分比模式需要**显式指定**交易动作：
+
+- **`action = "BUY"`**：策略意向买入该股票，目标持仓占比为 `position_pct`。交易引擎根据账户总资产计算目标金额，然后转换为具体股数下单。
+- **`action = "SELL"`**：策略意向清仓该股票。百分比模式下卖出采用简化逻辑，直接执行清仓操作。
+
+### 8.6 买入计算公式
+
+当 QMT 端接收到百分比模式的买入信号时，按以下公式计算买入股数：
+
+```
+目标金额 = 账户总资产 × position_pct
+可用金额 = min(目标金额, 可用资金)
+买入股数 = int(可用金额 / 价格 / 100) × 100
+```
+
+**边界处理：**
+- 单笔金额 < 2000 元 → 拦截不下单
+- 计算股数 < 100 股 → 拦截不下单
+- 价格 ≤ 0 → 强制设为 1.0（仅测试用）
+
+### 8.7 与槽位模式的对比
+
+| 特性 | 槽位模式 (slots) | 百分比模式 (percentage) |
+|------|------------------|------------------------|
+| 核心参数 | `total_slots` | `position_pct` |
+| 持仓限制 | 有（同时持仓数量限制） | 无 |
+| 资金分配 | 按剩余槽位均分资金 | 按总资产比例计算 |
+| 卖出逻辑 | 按持仓数量计算 | 清仓 |
+| 配置方式 | 配置文件设置 `order_mode: "slots"` | 配置文件设置 `order_mode: "percentage"` |
+| 信号发送 | `send_qmt_signal()` | `send_qmt_percentage_signal()` |
+
+### 8.8 使用示例
+
+```python
+from qmt_percentage_sender import send_qmt_percentage_signal
+
+# Redis 配置
+redis_config = {
+    "host": "localhost",
+    "port": 6379,
+    "password": None,
+    "db": 0,
+    "strategy_name": "MyPercentageStrategy"
+}
+
+# 买入信号：目标持仓占账户总资产的 20%
+send_qmt_percentage_signal(
+    code="000001.XSHE",
+    position_pct=0.2,
+    action="BUY",
+    price=15.5,
+    is_backtest=False,
+    timestamp="2026-02-17 14:30:00",
+    redis_config=redis_config
+)
+
+# 卖出信号：清仓
+send_qmt_percentage_signal(
+    code="000001.XSHE",
+    position_pct=0,
+    action="SELL",
+    price=15.8,
+    is_backtest=False,
+    timestamp="2026-02-17 14:35:00",
+    redis_config=redis_config
+)
+```
+
+## 9. 系统架构

 ### 8.1 组件关系图

@@ -400,7 +583,7 @@ Web 仪表盘基于 Vue 3 和 Naive UI 组件库开发，提供可视化的系
 7. **订单执行**：调用 QMT API 下单，成功则缓存订单信息
 8. **状态更新**：标记虚拟持仓，异步等待成交回调

-## 9. 启动与停止
+## 10. 启动与停止

 ### 9.1 Windows 启动

@@ -427,7 +610,7 @@ python run.py
 |------|----------|------|
 | API 服务 | 8001 | Web 仪表盘和 RESTful API 监听端口 |

-## 10. 注意事项
+## 11. 注意事项

 1. **QMT 终端要求**：确保 QMT 终端已登录且路径配置正确
 2. **Redis 服务**：系统依赖 Redis 运行，请确保 Redis 服务可用