This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
miniQMT 是一个基于迅投QMT API的无人值守量化交易系统,实现自动化交易策略执行、持仓管理、止盈止损和网格交易。
核心特性:
- 🔄 双层存储架构(内存数据库 + SQLite持久化)
- 🎯 信号检测与执行分离设计
- 🧵 多线程协同工作 + 线程自愈机制
- 📈 动态止盈止损策略(含 xtquant_manager 独立运行模式)
- 🤖 自动买入模块(独立进程,复用 Web 买入 API 下单)
- 🌐 Web前端实时监控界面(Flask web1.0 + Vue3 web2.0 双版本)
- 🚪 XtQuantManager HTTP 网关(多账号统一管理、远程 API、PWA 支持)
- 🛡️ 无人值守运行(线程监控、超时保护、优雅关闭)
- 🔀 交易通道四选一:默认 miniQMT xttrader 直连,可选 XtQuantManager / 大QMT 文件 IPC / 大QMT RPC(Redis/ZMQ),控制台可一键切换直连/IPC/RPC
- 📊 Tushare Pro 数据源(历史K线优先 + 股票名称补充查询,标准模式 Tushare → Mootdx 降级链)
- 🔧 .env fallback 配置(Windows 用户级环境变量 >
.env,零依赖自解析,测试隔离保护)
v3.7.0 新增配置开关:
ENABLE_QMT_RPC_FALLBACK— 大QMT RPC 交易通道开关(Redis/ZMQ RPC,默认 false)QMT_RPC_TRANSPORT— RPC 传输方式:redis(默认) / zmq(低延迟) / mysql(兜底)QMT_RPC_REDIS_HOST/PORT/DB/PASSWORD— Redis 连接参数QMT_RPC_ALLOW_ORDER— RPC 下单二次确认开关(默认 false,只读安全)ENABLE_QMT_IPC_FALLBACK— 大QMT文件IPC交易通道开关(已有,默认 false)QMT_IPC_ROOT— IPC 文件目录(已有,默认C:\QuantIPC).env文件现由config.py自动加载(_load_dotenv_fallback),优先级:Windows 环境变量 > .env- 控制台
miniqmt.bat菜单[n]Tushare /[o]IPC /[p]XtTrader 通道总控 可直接切换 - 三个可选后端互斥:
ENABLE_XTQUANT_MANAGER/ENABLE_QMT_IPC_FALLBACK/ENABLE_QMT_RPC_FALLBACK同时最多开一个;都不开时使用默认 xttrader 直连 - 详细配置参考 docs/site/miniqmt/configuration.md 配置全景图
隐私安全提醒:
⚠️ 绝不硬编码任何 Token/密码/账号ID — 一律使用环境变量或配置文件account_config.json已在.gitignore中排除- Pushplus Token 使用
PUSHPLUS_TOKEN环境变量 - Redis 密码使用
QMT_RPC_REDIS_PASSWORD环境变量(.env.example为占位值)
环境要求:
- Python 3.8+ (推荐 3.9),例如用户目录下的Anaconda3/envs/python39
- 操作系统: Windows (QMT仅支持Windows)
- QMT客户端: 实盘交易需要安装并登录QMT
依赖安装:
pip install -r utils/requirements.txt执行任何代码修改前必须遵守:
- 配置集中管理: 所有可配置参数在 config.py 中,严禁硬编码魔法数字
- 模拟交易优先: 测试新功能前必须设置
ENABLE_SIMULATION_MODE = True - 线程安全: 修改共享数据必须使用
threading.Lock()保护 - 信号验证: 交易信号必须经过
validate_trading_signal()验证,防止重复执行 - 双层存储同步: 修改内存数据库后必须调用
_increment_data_version() - 线程注册规范: 注册线程监控时必须使用
lambda获取线程对象(见下文) - Git操作: 除非用户明确要求,不要主动执行git提交和分支操作
# 创建虚拟环境
python -m venv venv
# 激活虚拟环境
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate
# 安装依赖
pip install -r utils/requirements.txt
# 验证安装
python utils/check_dependencies.py创建 account_config.json 和 stock_pool.json (参见文档末尾)。
配置项可通过 .env 文件或 Windows 环境变量覆写,优先级:环境变量 > .env。复制 .env.example 为 .env 并修改即可。
Web 远程/局域网/公网映射访问前必须设置强随机 QMT_API_TOKEN;配置后所有 web1.0 /api/*(含 GET/SSE)都需要 X-API-Token。公网映射建议同时设置 WEB_PUBLIC_MODE=true。
python main.py首次运行: 系统会自动创建 data/positions.db 数据库文件
项目集成了完整的回归测试框架 (test/run_integration_regression_tests.py),支持按模块运行、快速验证和失败重试。测试组配置在 test/integration_test_config.json。
# 快速验证(5分钟内完成,检查关键功能)
python test/run_integration_regression_tests.py --fast
# 运行所有回归测试
python test/run_integration_regression_tests.py --all
# 运行所有回归测试,并包含 fast 组
python test/run_integration_regression_tests.py --all-with-fast
# 按组运行
python test/run_integration_regression_tests.py --group autobuy # 自动买入
python test/run_integration_regression_tests.py --group system_integration # 系统集成
python test/run_integration_regression_tests.py --group stop_profit # 止盈止损
python test/run_integration_regression_tests.py --group grid_signal # 网格信号
python test/run_integration_regression_tests.py --group grid_session # 网格会话
python test/run_integration_regression_tests.py --group grid_trade # 网格交易
python test/run_integration_regression_tests.py --group grid_exit # 网格退出
python test/run_integration_regression_tests.py --group grid_validation # 网格参数
python test/run_integration_regression_tests.py --group grid_comprehensive # 网格综合
python test/run_integration_regression_tests.py --group grid_bug_regression # Bug回归验证
python test/run_integration_regression_tests.py --group grid_full_range_coverage # 全区间覆盖
python test/run_integration_regression_tests.py --group grid_true_pnl # 真实盈亏账本
python test/run_integration_regression_tests.py --group simulation_trading_e2e # 模拟交易端到端
# 其他选项
python test/run_integration_regression_tests.py --all --retry-failed # 失败重试
python test/run_integration_regression_tests.py --all --verbose # 详细输出
python test/run_integration_regression_tests.py --all --skip-env-prep # 跳过环境准备
python test/run_integration_regression_tests.py --all --no-backup # 不备份生产DB测试报告自动输出到 test/integration_test_report.json 和 test/integration_test_report.md。
# 运行单个测试模块
python test/run_single_test.py test.test_unattended_operation
# 直接使用 unittest
python -m unittest test.test_system_integration -v
# 运行全部网格测试
python test/run_all_grid_tests.py浏览器访问: http://localhost:5000
- web1.0: Flask 模板渲染 (
web1.0/), 自动运行 - web2.0: Vue3 + Vite + TypeScript + PWA (
web2.0/), 需构建后使用
cd web2.0
npm install # 安装依赖(仅首次)
npm run dev # 开发模式 (http://localhost:5173, 热更新)
npm run build # 生产构建 → dist/构建产物 dist/ 可直接部署到 Vercel 或由 Flask web_server / xtquant_manager 托管。
详见 web2.0/VERCEL_DEPLOY.md。
web2.0 支持两种后端连接模式,通过前端「连接设置」切换:
| 模式 | 后端 | 端口 | 适用场景 |
|---|---|---|---|
| Flask 直连 | 每账号独立 Flask (web_server.py) | :5000, :5001... | 完整功能:配置管理/自动操作总开关/模拟买入/初始化持仓 |
| 网关模式 | xtquant_manager 统一入口 | :8888 | 多账号只读监控 + 下单;配置/监控/初始化需 Flask 直连 |
网关模式能力边界(截至 2026-08-09):
- ✅ 多账号持仓查看(字段完整、账号隔离、现价反推)
- ✅ 账户资产/状态、连接状态、交易记录
- ✅ 参数展示(只读)、动态止盈状态、网格会话只读列表
- ✅ 账号自动发现(从 xtquant_manager 同步真实 ID)
- 🔑 所有数据端点(含只读)均需
X-API-Token— 只读端点会返回持仓成本/盈亏/成交明细,属财务隐私数据;唯一例外是/api/v1/health(存活探针,无 Token 时只返回计数、不返回accounts明细) - 🔒 配置保存/自动操作总开关/模拟买入/初始化持仓 — 需 Flask 直连模式
- 🔒 SSE 实时推送不可用 — 依赖 3s/10s 轮询更新
技术要点:
- 网关兼容端点 (
/api/positions,/api/status等) 在 server.py 中实现 - 网格会话兼容端点
/api/grid/sessions在网关模式下从账号 SQLite 只读返回,盈亏口径为兼容降级快照 - QMT 实时数据 (量/价/市值) + SQLite 持久化元数据 (名称/建仓/止损/止盈) 合并返回
- 前端通过
X-Account-Id请求头切换目标账号,isGatewayMode()检测当前模式 - 网关默认
trust_proxy=false,不信任X-Forwarded-For:该头可伪造成127.0.0.1冒充本机,一次绕过 Token 免验证 / IP 白名单 / 速率限制三处判定。仅在受信任反向代理之后才可在xtquant_manager_config.json置"trust_proxy": true _launcher.py菜单选项 [7]/[9] 启动时记忆 web 模式偏好 (data/.web_mode)- 网关重启 (菜单 [h]) 自动等待端口释放防止旧进程残留
miniqmt.bat # 打开交互式菜单
python scripts/_launcher.py menu # 等效命令菜单功能一览(分页:首页放日常运行 + 三个二级页,一屏装得下):
| 页 | 选项 | 功能 |
|---|---|---|
| 首页 | [5]-[6] | 查看账号配置、运行状态 |
| [7]-[9] | 启动所有(实盘)/所有(模拟)/指定账号 | |
| [a]-[c] | 优雅停止全部/指定、强制停止全部 | |
| [1] | → 环境与部署页 | |
| [2] | → 服务管理页 | |
| [3] | → 数据与配置页 | |
| 环境与部署 | [0]-[4] | 首次向导、检查环境、装依赖、校验配置、git pull |
| 服务管理 | [d]-[i] | XtQuantManager 网关 启动/停止/状态/UI/重启/日志 |
| [j]-[m] | 自动买入 启动/停止/状态/日志 | |
| 数据与配置 | [n]-[p] | Tushare / 大QMT IPC / XtTrader 通道总控 |
| [r]-[u] | 交割单:迁移 / 历史回填 / 导入对账单 / 导出 |
二级页内
[b]或直接回车返回主菜单;[q]在任何页都退出。 各页按键不重叠(env 用 0-4 / 首页用 5-9,a-c / services 用 d-m / data 用 n-p,r-u), 因此底层分派链是共用的,只在入口按页校验按键。 首页底部显示账号运行摘要,执行过可能改变运行状态的操作后会重新采集(有缓存)。
[r][s][t]会改写trade_records,内置停机守卫:仍有账号运行时直接拒绝执行, 且强制先跑 dry-run 预演、需输入yes才正式执行。[u]导出是只读,随时可跑。 对应 CLI:python scripts/_launcher.py settlement-{migrate,backfill,import,export}
# 检查系统状态
python -m unittest test.test_system_integration -v
# 诊断QMT连接
python -m unittest test.test_qmt_connection -v
# 查看实时日志
tail -f logs/qmt_trading.log # Linux/Mac
Get-Content logs/qmt_trading.log -Wait # Windows PowerShell1. 信号检测与执行分离 (最重要!)
持仓监控线程(始终运行) → 检测信号 → latest_signals队列
↓
策略执行线程 → 检查ENABLE_AUTO_OPERATION + ENABLE_AUTO_TRADING → 执行/忽略信号
网格交易线程 → 检查ENABLE_AUTO_OPERATION + ENABLE_GRID_TRADING + grid_trading_sessions.enabled → 执行/暂停新网格单
关键点:
- 监控线程始终运行,持续检测信号
ENABLE_AUTO_OPERATION是全局自动操作总开关,关闭时所有自动策略不产生新交易动作ENABLE_AUTO_TRADING只控制动态止盈止损等非网格自动策略- 动态止盈止损信号入队门控:监控线程仅在
ENABLE_DYNAMIC_STOP_PROFIT且ENABLE_AUTO_TRADING同时开启、且该股positions.stop_profit_enabled为真时才检测并写入latest_signals(_detect_and_enqueue_dynamic_signal)。任一关闭时不检测/不入队,避免"检测→策略因自动交易关闭而清除→再检测"的每 3 秒日志刷屏。网格检测走独立分支(ENABLE_GRID_TRADING),不受此门控影响 - 个股级动态止盈止损开关:
positions.stop_profit_enabled(默认 1=开)与全局开关是 AND 关系,可在 web1.0 持仓列表末列拨动开关单独暂停某只股票;写入走PositionManager.set_stop_profit_enabled()(仿set_session_enabled,只更新单列 +_increment_data_version(),不动update_position)。网关模式xtquant_manager/stop_profit.py同样遵守该开关 ENABLE_GRID_TRADING控制网格模块,grid_trading_sessions.enabled控制单只股票网格会话“自动/暂停”ENABLE_PAUSE_GRID_AFTER_TAKE_PROFIT_FULL(默认 True)控制清仓成交确认后的网格联动:take_profit_full与stop_loss(两者都卖出available全量)成交后只暂停同股活跃网格会话(enabled=False),不停止/删除会话,也不修改任何网格配置(中心价/档位/投入上限/有效期),便于人工复核后原样恢复- 每个信号都要经过
validate_trading_signal()验证,防止重复执行
2. 双层存储架构
实盘模式:
QMT实盘账户 → position_manager.qmt_trader.position() → 内存数据库
内存数据库 → 定时同步(15秒) → SQLite数据库
模拟模式:
Web界面 → trading_executor → position_manager.simulate_buy/sell() → 内存数据库
(跳过QMT接口,资金从SIMULATION_BALANCE扣除/增加)
关键点:
- 内存数据库存储高频更新数据(价格、市值、盈亏比例)
- SQLite持久化关键状态(开仓日期、止盈触发标记、最高价)
- 修改内存数据后必须调用
_increment_data_version()触发前端更新
config.py # 集中配置管理(所有魔法数字都在这里)
logger.py # 统一日志管理
db_migrate.py # 数据库 schema 迁移(幂等补列/迁移前备份/测试库守卫/账号发现) ⭐
settlement_db.py # 交割单数据落库(持仓快照/每日净值/运行事件/成交统一写入口) ⭐
main.py # 系统启动入口和线程管理
thread_monitor.py # 线程健康监控与自愈(无人值守核心)⭐
data_manager.py # 历史数据获取(xtdata接口)
indicator_calculator.py # 技术指标计算
position_manager.py # 持仓管理核心(内存+SQLite双层)⭐
trading_executor.py # 交易执行器(模拟/实盘下单入口,实盘通道由 position_manager 工厂选择)
strategy.py # 交易策略逻辑⭐
web_server.py # RESTful API服务(Flask)
easy_qmt_trader.py # QMT交易API封装 (xttrader 直连)
qmt-trader/ # 大QMT 降级交易通道
_qmt_trader_base.py # IPC/RPC 共享件 (列名/Fake对象/纯逻辑)
qmt_rpc_trader.py # 大QMT RPC 适配器 (Redis/ZMQ RPC 驱动大QMT) [v3.7.0]
qmt_ipc_trader.py # 大QMT 文件IPC 适配器 (JSON文件驱动大QMT)
qmt_trade_executor.py # 大QMT executor 脚本 (模型交易策略入口)
qmt_trade_client.py # 策略端客户端库
premarket_sync.py # 盘前同步与初始化(每天9:25重新初始化xtquant)
config_manager.py # 配置持久化管理
sell_monitor.py # 卖出委托单超时监控与撤单⭐
grid_trading_manager.py # 网格交易会话管理(独立线程)
grid_database.py # 网格交易数据持久化(SQLite)
grid_validation.py # 网格交易参数校验
autobuy/ # 自动买入模块(独立进程,候选池筛选→Web买入API)
xtquant_manager/ # XtQuantManager HTTP网关(多账户管理,可选)
xtquant_manager/stop_profit.py # 网关模式动态止盈止损(后台线程,复用 position_manager 算法)
web2.0/ # Vue3+Vite+TS+PWA 新版Web界面
test/test_xqm_flask_compat.py # 网关Flask兼容端点测试(21用例,字段映射/账号隔离/SQLite注入)
| 线程 | 启动位置 | 职责 | 频率 | 关键配置 |
|---|---|---|---|---|
| 线程监控 | thread_monitor.start() |
检测线程崩溃并自动重启 | 60秒 | ENABLE_THREAD_MONITOR |
| 数据更新 | data_manager.start_data_update_thread() |
更新股票池行情 | 60秒 | - |
| 持仓监控 | position_manager.start_position_monitor_thread() |
同步实盘持仓、更新价格、检测止盈止损 | 3秒 | MONITOR_LOOP_INTERVAL |
| 策略执行 | strategy.start_strategy_thread() |
获取非网格信号、执行交易 | 5秒 | ENABLE_AUTO_OPERATION + ENABLE_AUTO_TRADING |
| 网格交易 | grid_trading_manager 内部线程 |
网格信号检测与买卖执行 | 5秒 | ENABLE_AUTO_OPERATION + ENABLE_GRID_TRADING + grid_trading_sessions.enabled |
| 卖出监控 | sell_monitor 单例线程 |
委托单超时撤单 | 2秒 | ENABLE_SELL_MONITOR |
| 定时同步 | position_manager.start_sync_thread() |
内存→SQLite同步 | 15秒 | POSITION_SYNC_INTERVAL |
| Web服务 | web_server.start_web_server() |
RESTful API | 持续 | - |
| 心跳日志 | start_heartbeat_logger() |
定期输出系统运行状态 | 1800秒 | ENABLE_HEARTBEAT_LOG |
| 盘前同步 | premarket_sync.start_premarket_sync_scheduler() |
每天9:25重新初始化xtquant | 每日9:25 | ENABLE_PREMARKET_XTQUANT_REINIT |
# 核心开关
ENABLE_SIMULATION_MODE = True # True=模拟, False=实盘 ⚠️
ENABLE_AUTO_OPERATION = False # 全局自动操作总开关 ⚠️
ENABLE_AUTO_TRADING = False # 非网格自动策略执行开关
ENABLE_DYNAMIC_STOP_PROFIT = True # 止盈止损功能
ENABLE_GRID_TRADING = True # 网格交易功能
ENABLE_PAUSE_GRID_AFTER_TAKE_PROFIT_FULL = True # 全仓止盈/止损成交后暂停同股网格会话
ENABLE_MACD_SELL = False # MACD技术指标卖出开关(False=仅记录信号不实盘卖出,2026-08-19修复price_type后新增)
ENABLE_THREAD_MONITOR = True # 线程健康监控(无人值守必需)⭐
ENABLE_SELL_MONITOR = True # 卖出委托单超时监控
ENABLE_XTQUANT_MANAGER = False # XtQuantManager HTTP网关(多账户时开启)
DEBUG = False # 调试模式check_buy_signal() / check_sell_signal()(indicator_calculator.py)基于
最近两根已收盘日线判定「MACD 金叉/死叉 + 均线多头/空头排列」,存在固有 T+1 延迟:
- 当日日线要到
HISTORY_TODAY_DAILY_AVAILABLE_AFTER(默认 15:30)之后才入库 (data_manager._get_completed_history_end_date()保证不用盘中未定型数据) - 但数据更新线程与策略线程都只在
is_trade_time()内运行(A股 15:00 收盘) - 结论:T 日收盘产生的死叉,实际在 T+1 开盘后才被检测并执行。这是日线策略的
正常行为,不是缺陷;但开启
ENABLE_MACD_SELL=True前必须知悉此延迟
信号去重与开关语义(2026-08-20 修复):
processed_signals仅作用于 MACD 技术指标信号(check_buy_signal/check_sell_signal), 按buy_/sell_{code}_{YYYYMMDD}去重,每股每日各最多执行一次;由_rollover_signal_cache_if_new_day()在跨交易日时自动清空(无人值守长跑防内存增长)⚠️ 止盈/止损/补仓/网格不受processed_signals约束,它们走position_manager.latest_signals队列 +mark_signal_processed()(仅出队、不写日级标记), 基于实时现价每 3 秒重新检测。因此同一只股票同一天内可以先止盈、后止损—— position_manager.py 中stop_loss_1(首次止盈后回落触发止损) 正是为该场景设计的分支- MACD 之所以按日去重:其信号源是已收盘日线柱的符号翻转,盘中不变;不去重会导致 同一个死叉被每 10 秒重复执行
ENABLE_MACD_SELL=False或ENABLE_AUTO_TRADING=False期间,信号只写入独立的macd_sell_notified降噪集合,不写processed_signals—— 因此盘中把开关改为 True 后,当日信号无需重启进程即可立即生效- MACD 卖出使用
position['available'](可用持仓)下单,与止盈止损口径一致, 避免 T+1 冻结股份触发 QMT 拒单
ENABLE_SIMULATION_MODE = False(切换到实盘)ENABLE_AUTO_OPERATION = True(打开全局自动操作总开关)- 按需打开分开关:
ENABLE_AUTO_TRADING=True和/或ENABLE_GRID_TRADING=True - QMT客户端已启动并登录
account_config.json配置正确
# 线程监控
ENABLE_THREAD_MONITOR = True # 启用线程自愈
THREAD_CHECK_INTERVAL = 60 # 检查间隔(秒)
THREAD_RESTART_COOLDOWN = 60 # 重启冷却时间(秒)
# 持仓监控优化
MONITOR_LOOP_INTERVAL = 3 # 监控循环间隔(秒)
MONITOR_CALL_TIMEOUT = 8.0 # API调用超时(秒)
MONITOR_NON_TRADE_SLEEP = 60 # 非交易时段休眠(秒)
# 性能优化
QMT_POSITION_QUERY_INTERVAL = 10.0 # QMT持仓查询间隔(秒)
POSITION_SYNC_INTERVAL = 15.0 # SQLite同步间隔(秒)STOP_LOSS_RATIO = -0.075 # 止损比例: 成本价下跌7.5%
INITIAL_TAKE_PROFIT_RATIO = 0.06 # 首次止盈: 盈利6%
INITIAL_TAKE_PROFIT_RATIO_PERCENTAGE = 0.6 # 首次止盈卖出60%
# 动态止盈 (最高盈利比例, 止盈位系数)
DYNAMIC_TAKE_PROFIT = [
(0.05, 0.96), # 最高浮盈5%时,止盈位=最高价*96%
(0.10, 0.93),
(0.15, 0.90),
(0.20, 0.87),
(0.30, 0.85),
]
# 动态信号保活 (防止瞬时止盈信号在被策略线程消费前丢失)
# 监控线程 3 秒检测一次,策略线程单只股票消费周期约 10+持仓数+股票池数 秒;
# 首次止盈是"跨过即触发"的瞬时信号,价格回踩会让下一轮检测返回 None。
# 开启后已入队未消费的信号在窗口内不被删除;执行前再按 MAX_AGE 做时效兜底,
# 避免以过旧的价格快照下单。
ENABLE_DYNAMIC_SIGNAL_KEEPALIVE = True # 信号保活开关
DYNAMIC_SIGNAL_KEEPALIVE_SECONDS = 90 # 保活窗口(秒)
DYNAMIC_SIGNAL_MAX_AGE_SECONDS = 120 # 执行前信号最大年龄(秒),超过判定过期数据来源分类:
| 字段 | 数据来源 | 更新时机 |
|---|---|---|
stock_code, volume, available, cost_price |
QMT实盘 qmt_trader.position() |
每10秒同步一次 |
current_price |
data_manager.get_latest_data() |
实时更新 |
market_value, profit_ratio |
计算得出 | 价格更新时重新计算 |
open_date, profit_triggered, highest_price, stop_loss_price, stop_profit_enabled |
持久化字段 | 策略状态变化或成交回报确认后同步到SQLite;stop_profit_enabled 由 Web 开关即时写入 |
关键字段说明:
profit_triggered: 是否已完成首次止盈(卖出60%)成交确认,影响后续动态止盈逻辑highest_price: 持仓期间最高价,用于计算动态止盈位stop_loss_price: 止损价格,低于此价格触发止损
记录所有买卖交易,包含:
stock_code,trade_type(BUY/SELL),price,volumetrade_id: 订单ID (实盘为QMT返回的order_id, 模拟为SIM{timestamp}{counter})strategy: 策略标识 (simu/auto_partial/auto_full/stop_loss/grid/manual/M_real/M_simu/manual_real/manual_simu/external/default/add_position/reorder_take_profit_half/reorder_take_profit_full/reorder_stop_loss)- Web 显示标签映射需三处同步:web_server.py
strategy_labels(服务端下发strategy_label,web2.0 Flask 直连模式优先取此值)、web1.0/script.jsLOG_STRATEGY_LABELS(只认原始strategy)、web2.0/src/components/OrderLog.vuestrategyLabels(网关模式兜底,因网关不下发strategy_label) - 手动买卖:
M_real=手买 /M_simu=模买 /manual_real=手卖 /manual_simu=模卖 reorder_*由position_manager._reorder_after_cancel()以f"reorder_{signal_type}"动态拼接产生(委托超时撤单后自动重挂)。新增卖出信号类型时,这三处标签表也要同步补reorder_前缀的键,否则前端会回退显示英文原始值
- Web 显示标签映射需三处同步:web_server.py
归因所需的一切必须在成交当下落库,导出退化为纯 SELECT。相关模块见 db_migrate.py 与 settlement_db.py。
新增表(均为幂等 CREATE TABLE IF NOT EXISTS):
position_snapshot(每交易日 09:25 open / 15:05 close 全量持仓)、
account_equity_daily(每日净值 + 恒等式校验 + 跳变告警)、
run_events(结构化事件)、trade_records_sim(模拟成交独立表)。
trade_records 扩展列: account / deal_time / deal_time_str / time_source /
order_id / fills / strategy_label / is_simulation / commission_source /
row_status 等 17 列。
核心约定:
- 成交写入统一走
settlement_db.record_trade(),用INSERT OR IGNORE+ 唯一索引ux_trade_records_deal做原子幂等。历史上一笔成交被写两遍,正是因为判重是 「先 SELECT 再 INSERT」且当时没有唯一索引 time_source取值:exchange/local_fallback/reconcile_backfill/broker。 取不到交易所成交时间时如实标local_fallback,禁止用now()冒充- 唯一索引必须写成
(COALESCE(account,''), trade_id, stock_code, trade_time): SQLite 唯一索引中 NULL 互不相等,历史行account全为 NULL 时索引会形同虚设 - 网格路径写入的
trade_id是str(order_id)而非成交号,order_id跨股跨日复用, 所以索引必须带stock_code - 模拟成交落
trade_records_sim,绝不与实盘同表
上线顺序(不可颠倒):
# 1. 停止 miniQMT,确认无残留 python 进程
tasklist | findstr python
# 2. 预演(只读,不会写库)
python scripts/migrate_settlement.py --accounts all --dry-run
# 3. 正式迁移(自动备份到 data/backup/migrations/)
python scripts/migrate_settlement.py --accounts all
# 4. 重启,确认日志出现「启动收盘快照线程」record_trade() 会自动降级为旧列写入(成交不丢,
但归因字段缺失)并在日志告警。反之,占位流水未清理就建唯一索引会直接 IntegrityError。
导出:
python scripts/export_settlement.py --start 2026-09-14 --end 2026-10-10 --accounts all --out export/只读、不依赖 logs/*.log;禁止在导出时剔除任何股票;positions_begin 无快照时
报错退出,不许用 0 填充。合并规则 merge_deals() 是全项目单点实现(10 秒窗口、不跨日界)。
历史回填(把改造前的存量行补齐归因字段):
python scripts/backfill_trade_records.py --accounts all --dry-run # 先看
python scripts/backfill_trade_records.py --accounts alltime_source 一律标 local_fallback —— 绝不伪装 exchange;手续费来源按证据判定
(amount×0.0003 可证实是旧版写死的估算会被重算,来源不明的标 unknown 且不动)。
券商对账单导入(历史成交时间的唯一来源 —— xttrader 没有历史成交查询接口):
python scripts/import_broker_statement.py --dir "<对账单目录>" --dry-run
python scripts/import_broker_statement.py --dir "<对账单目录>"对账单为 GBK 编码。匹配按三级优先级:① 成交编号 == trade_id
② 订单编号 == trade_id 且代码相同(order_id 会跨股跨日复用,必须消歧)
③ 代码+方向+价量相同且时间邻近(默认 60 秒)。
回填 time_source='broker';对账单手续费为 0 时不覆盖本地估算(0.00 通常表示该字段未导出)。
broker_deals / broker_orders 留存原始对账数据供审计。
系统支持长期持续运行,通过线程健康监控实现自动恢复。详见 在线文档 · 无人值守运行
关键实现 (thread_monitor.py):
from thread_monitor import get_thread_monitor
# 在main.py中启动线程监控
if config.ENABLE_THREAD_MONITOR:
thread_monitor = get_thread_monitor()
# ⚠️ 必须使用lambda获取最新对象引用
thread_monitor.register_thread(
"持仓监控",
lambda: position_manager.monitor_thread, # ✅ 正确: lambda
position_manager.start_position_monitor_thread
)
thread_monitor.start()❌ 常见错误:
# 错误: 直接传递线程对象,重启后对象引用会变化
monitor.register_thread(
"持仓监控",
position_manager.monitor_thread, # ❌ 错误: 直接传递对象
restart_func
)工作原理:
- 每60秒检查一次线程存活状态
- 检测到崩溃立即重启,60秒冷却时间防止重启风暴
- 完整的重启历史记录
系统退出时的正确关闭顺序(在 main.py 的 cleanup() 函数中实现):
1. Web服务器 → 停止接收新请求
2. 线程监控器 → 停止监控循环,避免误触发重启
3. 业务线程 → 停止数据更新、持仓监控、策略执行
4. 核心模块 → 按依赖顺序关闭(策略→执行器→数据管理器/数据库)
重要: 每个关闭步骤都有独立的异常处理,确保单个步骤失败不影响其他资源清理。
持仓监控线程中的API调用有超时保护(当前默认 8 秒):
try:
future.result(timeout=config.MONITOR_CALL_TIMEOUT) # 默认8秒
except TimeoutError:
logger.warning("API调用超时,跳过本次更新")
# 继续执行,不阻塞循环# 非交易时段立即跳过,避免无效API调用
if not config.is_trade_time():
logger.debug(f"非交易时间(第{loop_count}次循环), 休眠60秒")
time.sleep(60)
continue效果: 非交易时段CPU占用从~30%降至<2%
# ❌ 错误: 硬编码魔法数字
if profit_ratio > 0.06:
...
# ✅ 正确: 使用配置
if profit_ratio > config.INITIAL_TAKE_PROFIT_RATIO:
...logger.debug()- 详细调试信息(变量值、执行路径)logger.info()- 关键流程节点(系统启动、交易执行)logger.warning()- 异常但可恢复(数据缺失、连接超时)logger.error()- 严重错误(模块初始化失败、数据库错误)
try:
result = qmt_trader.order_stock(...)
logger.info(f"下单成功: {result}")
except Exception as e:
logger.error(f"下单失败: {str(e)}")
return Nonewith self.signal_lock:
self.latest_signals[stock_code] = signal_info# ✅ 正确: 参数化查询
cursor.execute("SELECT * FROM positions WHERE stock_code=?", (stock_code,))
# ❌ 错误: 字符串拼接(SQL注入风险)
cursor.execute(f"SELECT * FROM positions WHERE stock_code='{stock_code}'")def simulate_buy_position(self, ...):
# ... 执行模拟买入逻辑 ...
self._increment_data_version() # ⚠️ 必须调用,否则前端不更新原因: 信号验证失败或未正确标记为已处理
解决:
- 检查
validate_trading_signal()和mark_signal_processed()调用链 - 查看日志中的信号验证详情
- 确认信号有效期过滤正常工作:信号入队时写入
latest_signals[stock_code]['timestamp'],get_pending_signals()会过滤超过 300 秒的过期信号
原因: 未触发数据版本号更新
解决:
def simulate_buy_position(self, ...):
# ... 执行模拟买入逻辑 ...
self._increment_data_version() # 必须调用检查:
# 检查连接状态
position_manager.qmt_trader.xt_trader.is_connected()
# 重新连接
position_manager.qmt_trader.connect()
# 检查路径配置
# config.py中的QMT_PATH是否正确排查:
# 1. 检查配置
config.ENABLE_POSITION_MONITOR # 应为True
# 2. 检查线程状态
import threading
print(threading.enumerate())
# 3. 查看日志
# 搜索 "启动持仓监控线程" 或 "持仓监控线程异常"原因: 使用了错误的线程注册方式
正确做法:
# ❌ 错误: 直接传递线程对象
monitor.register_thread(
"持仓监控",
position_manager.monitor_thread, # 重启后对象引用会变化
restart_func
)
# ✅ 正确: 使用lambda获取最新对象
monitor.register_thread(
"持仓监控",
lambda: position_manager.monitor_thread, # 每次获取最新引用
restart_func
)原因: 关闭顺序不正确,Web服务器在数据库关闭后仍在处理请求
解决: 确保 main.py 中的 cleanup() 函数按正确顺序关闭
验证: 退出系统时查看日志,应该看到有序的关闭步骤,无ERROR日志
原因: 在 QMT 回调线程内反向调用 QMT 同步接口(如 qmt_trader.position()),与回调线程互等死锁
约束(修改成交回调链路时必须遵守):
- 外部成交(QMT 客户端手工下单等本机未发的委托)走
_record_external_trade_after_callback(),只置零last_position_update_time让下轮监控自己同步,绝不在回调里请求持仓快刷 _confirm_filled_order()仅在matched_key or order_info为真(确实匹配到本机委托)时才调_request_immediate_position_refresh()- 回调链路上写流水时用
data_manager.get_stock_name(stock_code, allow_qmt_lookup=False)关闭 QMT 持仓回查
相关保护: easy_qmt_trader._stop_trader_with_timeout() 把 xt_trader.stop() 放进 daemon 线程并按 config.QMT_STOP_TIMEOUT(默认5秒)超时放弃,避免底层 stop 卡死拖垮重连
系统状态:
GET /api/status- 获取系统运行状态GET /api/connection/status- 检查QMT连接状态
持仓管理:
GET /api/positions- 获取所有持仓GET /api/positions-all- 获取全部持仓详情GET /api/sse- SSE实时推送数据
交易操作:
POST /api/actions/execute_buy- 执行买入 (参数: strategy, quantity, stocks;自动买入模块也复用该路径)POST /api/holdings/update- 更新持仓参数(止盈标记/最高价/止损价)POST /api/holdings/stop_profit- 设置个股「动态止盈止损」开关(参数: stock_code, enabled)
网格交易:
POST /api/grid/start- 启动网格会话POST /api/grid/stop/<session_id>- 停止指定网格会话GET /api/grid/sessions- 获取所有网格会话(网关模式只读兼容)GET /api/grid/trades/<session_id>- 获取网格成交记录GET /api/grid/ledger/<session_id>- 获取网格真实账本详情(批次、LIFO配对、盈亏汇总)GET /api/grid/status/<stock_code>- 获取指定股票网格状态
配置管理:
GET /api/config- 获取系统配置POST /api/config/save- 保存配置参数
import xtquant.xtdata as xt
# 连接行情服务
xt.connect()
# 获取历史数据
xt.get_market_data(
field_list=['open', 'high', 'low', 'close', 'volume'],
stock_list=['000001.SZ'],
period='1d',
start_time='20230101',
end_time='20231231'
)
# 获取实时Tick
xt.get_full_tick(['000001.SZ'])from xtquant.xttrader import XtQuantTrader
from xtquant.xttype import StockAccount
# 创建交易对象
xt_trader = XtQuantTrader(path, session_id)
xt_trader.start()
# 连接账户
acc = StockAccount(account_id, account_type)
xt_trader.connect()
# 下单
xt_trader.order_stock(
acc,
stock_code,
order_type, # 23=限价买入, 24=限价卖出
order_volume,
order_price
)
# 查询持仓
xt_trader.query_stock_positions(acc)
# 查询资产
xt_trader.query_stock_asset(acc)# config.py
DEBUG = True
LOG_LEVEL = "DEBUG"# config.py
ENABLE_SIMULATION_MODE = True
DEBUG_SIMU_STOCK_DATA = True # 绕过交易时间限制# 查看内存持仓
position_manager.get_all_positions()
# 查看待执行信号
position_manager.get_pending_signals()
# 检查账户信息
position_manager.get_account_info()
# 查看信号队列
position_manager.latest_signals
# 查看线程监控状态
thread_monitor.get_status()测试代码位于 test/ 目录,使用标准 unittest。当前回归配置见 test/integration_test_config.json,包含 32 个测试组(含 fast 快速子集)。
- test/test_base.py:
TestBase基类,提供测试DB创建、持仓 fixture、线程断言、条件等待等工具方法 - test/test_mocks.py:
MockQmtTrader完整模拟 QMT API(连接、持仓查询、下单),无需真实 QMT 环境即可运行测试 - test/test_utils.py: 通用测试辅助函数
| 组名 | 优先级 | 内容 |
|---|---|---|
autobuy |
high | 自动买入候选池/条件检查/防重/HTTP下单 |
system_integration |
critical | 系统集成、无人值守、线程监控 |
stop_profit |
high | 动态止盈止损策略(7个模块) |
grid_signal |
high | 网格信号检测与价格追踪 |
grid_session |
high | 网格会话生命周期管理 |
grid_trade |
high | 网格买卖执行与资金管理 |
grid_mece_regression |
critical | 网格状态机、并发预占、委托回调、真实账本、重启恢复边界 |
grid_exit |
high | 网格退出条件检测 |
grid_comprehensive |
high | 网格综合端到端场景 |
grid_validation |
medium | 参数校验与边界情况 |
grid_bugfix_c1 |
critical | BUG-C1修复验证(冷却防重单、DESIGN-4设计约束) |
grid_bug_regression |
high | 4个已修复Bug的回归验证 |
order_rejection |
critical | QMT拒单保护与卖出冷却缩短 |
grid_qa_fixes |
high | MECE审查6个修复的验证 |
grid_max_investment_safety |
critical | max_investment三重防护验证 |
core_metrics |
high | 网格利润计算与风险分级 |
trader_callback |
critical | 卖出委托Callback兜底机制 |
web_api |
critical | RESTful API功能测试(含Bug修复回归) |
multi_account_isolation |
critical | 多账号配置/数据目录/端口隔离 |
launcher_deployment |
high | 总控制台环境检查/配置校验 |
db_thread_safety |
critical | 数据库线程安全与Web缓存验证 |
dual_layer_storage |
critical | 内存+SQLite双层存储一致性 |
xtdata_data_source |
high | xtdata动态订阅与fallback路径 |
indicator_calculator |
high | 技术指标计算器全方法验证 |
grid_qa_gap_supplement |
critical | QA缺口补充(信号优先级/最小卖出/position_snapshot降级) |
grid_full_range_coverage |
critical | 全网格区间覆盖(114个用例,A-K 11个套件) |
grid_true_pnl |
critical | 网格 True P&L / LIFO 真实盈亏验证 |
grid_simulation |
high | 价格模拟测试(30个用例) |
qmt_ipc_fallback |
high | 大QMT文件IPC降级通道(客户端/执行器/集成) |
qmt_rpc |
high | 大QMT RPC 交易后端(契约兼容、只读门禁、回调/委托映射) |
simulation_trading_e2e |
critical | 模拟交易模式端到端(核心链路/Web下单/策略四分支/模式切换) |
p1_fixes |
high | 重连缓存刷新/QMT自恢复探测/信号保活与时效兜底/超时泄漏可观测 |
fast |
critical | 快速验证子集(当前配置 43 个模块、1037 个用例) |
测试统计(当前配置): 36组(含 fast)。--all 默认排除重复的 fast 组;最近一次(2026-09-14, v3.9.2)使用 Anaconda python39 执行 --all-with-fast 实测为 36组、148个模块、3166个用例,100% 通过;具体以本地运行报告为准。
from test.test_base import TestBase
from test.test_mocks import MockQmtTrader
class TestMyFeature(TestBase):
def setUp(self):
super().setUp()
self.mock_trader = MockQmtTrader()
self.mock_trader.add_mock_position("000001.SZ", volume=1000, cost_price=10.0)
def test_something(self):
# 测试代码...
self.wait_for_condition(lambda: condition_met, timeout=5)测试运行时自动备份生产DB,测试完成后恢复。使用 --skip-env-prep 跳过备份(仅限开发调试)。
- 无人值守运行 - 线程监控、超时保护、非交易时段优化
- Web 前端 - web1.0 / web2.0 双模式
- 自动买入 - 候选池筛选、指数门禁、防重买入
- 网格交易 - 网格实盘闭环与真实盈亏账本(含固定金额/固定股数交易份额模式,按 MACD DEA 趋势推荐默认)
- QMT order_id 匹配 - 异步下单
seq -> order_id的实盘行为结论、匹配优先级与 unknown 委托防重复下单
{
"account_id": "您的交易账号",
"account_type": "STOCK",
"qmt_path": "C:/光大证券金阳光QMT实盘/userdata_mini"
}[
"000001.SZ",
"600036.SH",
"920118.BJ"
]股票池支持 .SH / .SZ / .BJ 后缀,也支持裸代码自动补全;发布配置建议显式写后缀。
ALWAYS RESPOND IN SIMPLIFIED CHINESE!!!