simulation-trading

⚙️ 本技能遵循公共运行环境契约（最高优先级，先于本文其余内容执行）： 详见 _shared/env-contract.md，执行前先读它。

模拟交易技能

QuantMind 模拟交易（纸面交易）完整操作：下单、持仓、成交、账户、资金快照、模拟盘启动。默认模拟资金 100 万，不影响实盘。

实盘 / 模拟盘切换

• 前端切换：顶部 HeaderBar 右上角 REAL/SIM 拨动开关，切换实盘（通达信桥）与模拟盘。选择持久化到 localStorage['qm:trading_mode_pref']，默认模拟盘（simulation）。
• 后端分流：账户按 GET /api/v1/real-trading/status 返回的 mode + 前端分流——SIMULATION 调 /simulation/account，REAL 调 /account。
• 启动参数：POST /api/v1/real-trading/start 接收 trading_mode=SIMULATION/REAL；实盘需 ENABLE_REAL_TRADING=true 环境变量。
• 交易就绪检查：/api/v1/real-trading/trading-precheck 返回信号就绪/交易权限（可交易/观察态/阻断）。

# 检查交易就绪（启动前必查）
curl -s -H "$AUTH" "$BASE/api/v1/real-trading/trading-precheck"
# 返回: {passed, items:[{key,passed,detail}], signal_readiness, trading_permission}

认证

BASE=http://127.0.0.1:8000
TOKEN=$(curl -s -X POST $BASE/api/v1/auth/login -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"admin123","tenant_id":"default"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('access_token',''))")
AUTH="Authorization: Bearer $TOKEN"
CT="Content-Type: application/json"

1. 账户状态

1.1 查看模拟账户

curl -s -H "$AUTH" "$BASE/api/v1/simulation/account"
# 返回: {cash, total_asset, market_value, positions, initial_equity, ...}
# 默认现金 100 万，positions 为当前持仓

1.2 模拟交易设置

curl -s -H "$AUTH" "$BASE/api/v1/simulation/settings"

1.3 重置模拟账户

curl -s -X POST -H "$AUTH" "$BASE/api/v1/simulation/reset"

1.4 资金快照

# 手动捕获资金快照
curl -s -X POST -H "$AUTH" "$BASE/api/v1/simulation/snapshots/capture"
# 每日资金快照（总资产/现金/市值序列）
curl -s -H "$AUTH" "$BASE/api/v1/simulation/snapshots/daily"

2. 下单（核心）

2.1 买入/卖出

curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/simulation/orders" \
  -d '{
    "symbol": "600519.SH",
    "side": "buy",            # buy / sell
    "order_type": "market",   # market / limit
    "quantity": 100,
    "price": null,            # 限价单必填，市价单可空
    "remarks": "AI策略买入"
  }'

参数：

字段	说明
symbol	股票代码（600519.SH / SH600519）
side	buy / sell
order_type	market（市价）/ limit（限价）
quantity	数量（股）
price	限价单必填，市价单可空
remarks	备注（可选）

返回：order_id + 订单状态（pending/filled/...）

2.2 撤单

curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/simulation/orders/{order_id}/cancel" \
  -d '{"reason":"手动撤单"}'

3. 订单与成交查询

3.1 订单列表

curl -s -H "$AUTH" "$BASE/api/v1/simulation/orders"
# 返回: [{order_id, symbol, side, order_type, quantity, status, ...}]

3.2 单笔订单

curl -s -H "$AUTH" "$BASE/api/v1/simulation/orders/{order_id}"

3.3 成交记录

curl -s -H "$AUTH" "$BASE/api/v1/simulation/trades"
# 返回: [{trade_id, symbol, side, quantity, price, ...}]

3.4 单笔成交

curl -s -H "$AUTH" "$BASE/api/v1/simulation/trades/{trade_id}"

3.5 成交统计

curl -s -H "$AUTH" "$BASE/api/v1/simulation/trades/stats/summary"
# 返回: 盈亏/胜率/交易次数等统计

4. 模拟盘启动（real-trading）

模拟盘生命周期：策略绑定 → 预检查 → 启动 → 持仓跟踪 → 停止。

# 策略绑定到组合（策略信号 → 下单）
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/portfolios/{portfolio_id}/bind-strategy" \
  -d '{"strategy_id":"strategy_xxx","model_id":"mdl_cn_xxx"}'

# 交易预检查（信号就绪 / 资金 / 风控）
curl -s -H "$AUTH" "$BASE/api/v1/real-trading/trading-precheck"

# 启动模拟盘
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/real-trading/start" \
  -d '{"portfolio_id":"xxx","strategy_id":"strategy_xxx"}'
# 停止模拟盘
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/real-trading/stop"

# 运行状态 / 日志 / 订单 / 历史
curl -s -H "$AUTH" "$BASE/api/v1/real-trading/status"
curl -s -H "$AUTH" "$BASE/api/v1/real-trading/logs"
curl -s -H "$AUTH" "$BASE/api/v1/real-trading/orders"
curl -s -H "$AUTH" "$BASE/api/v1/real-trading/history"

组合（Portfolio）管理：

# 创建/列表组合
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/portfolios" -d '{"name":"我的组合","initial_capital":1000000}'
curl -s -H "$AUTH" "$BASE/api/v1/portfolios"
# 组合详情/绩效（分布只有全量口径，见持仓管理节）
curl -s -H "$AUTH" "$BASE/api/v1/portfolios/{id}"
curl -s -H "$AUTH" "$BASE/api/v1/portfolios/{id}/performance"
# 结算/快照/同步
curl -s -X POST -H "$AUTH" "$BASE/api/v1/portfolios/{id}/settlement"
curl -s -X POST -H "$AUTH" "$BASE/api/v1/portfolios/{id}/snapshot"
curl -s -X POST -H "$AUTH" "$BASE/api/v1/portfolios/{id}/sync-status"

持仓管理：

# 组合持仓
curl -s -H "$AUTH" "$BASE/api/v1/portfolios/{id}/positions"
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/portfolios/{id}/positions" -d '{"symbol":"600519.SH","quantity":100}'
# 调整/清仓（注意是 positions/{position_id} 口径，不是 portfolios/{id} 下挂 adjust/close）
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/positions/{position_id}/adjust" -d '{"quantity":100}'
curl -s -X POST -H "$AUTH" -H "$CT" "$BASE/api/v1/positions/{position_id}/close"
curl -s -X PUT -H "$AUTH" -H "$CT" "$BASE/api/v1/positions/{position_id}/price" -d '{"price":1500.0}'
# 全量资产分布（无单组合 distribution，查全量再过滤）
curl -s -H "$AUTH" "$BASE/api/v1/portfolios/distribution"

5. 实战流程（推荐）

当用户要求"模拟交易/买入/卖出"时：

1. 查账户：/simulation/account 看现金和持仓
2. 确认标的：查股票当前价（用 [[quantdb-sdk]] 或 K线）
3. 下单：/simulation/orders POST（市价/限价）
4. 确认成交：/simulation/orders/{order_id} 查状态
5. 查看持仓：/simulation/account 看更新后的 positions
6. 统计：/simulation/trades/stats/summary 看收益

当用户要求"启动模拟盘 / 跑实盘模拟"时：

1. 建组合：/portfolios POST 创建
2. 绑定策略：/portfolios/{id}/bind-strategy（strategy_id + model_id）
3. 预检查：/real-trading/trading-precheck 确认信号就绪
4. 启动：/real-trading/start
5. 监控：/real-trading/status + /simulation/account
6. 停止：/real-trading/stop

6. 相关技能

• [[stock-market-analysis]] — 分析选哪只股票（371 字段 + 风险评分）
• [[smart-strategy-stock-picking]] — 条件选股找标的
• [[quantdb-sdk]] — 查 K 线/估值确定买卖价
• [[backtest-center]] — 回测验证策略后再模拟执行
• [[ai-ide-strategy-writing]] — 写策略并执行回测

7. 常见问题

现象	处理
买入资金不足	查 account cash，减仓或调小 quantity
卖出无持仓	查 account positions 确认持有
限价单未成交	价格远离现价，改市价或调价
想重置	/simulation/reset 恢复 100 万初始资金
模拟盘启动失败	查 /real-trading/trading-precheck 看信号就绪状态
策略信号未生成	确认模型已推理（见 [[quantmind-operations]]）