tradingSystem/QMT_INTERFACE_REQUIREMENTS.md

持仓系统 ↔ QMT 侧下游系统 · 数据与接口需求清单

用途：本清单由用户持有，与 QMT 侧（下游交易系统）协商。请下游按编号逐项答复（能提供/字段差异/时延/替代方案），答复直接回填本文档「答复」列，作为对接定稿依据。 背景：架构调整后，对下游的指挥权由决策系统（bionic_trader）移交持仓系统（tradingSystem/PMS）。trading_order / trading_position 两表仍归下游维护，PMS 只读；PMS 新增一条带数量的统一指令通道（见 B 部分）。 版本：V2.0（2026-07-28） —— QMT 侧已就六项问询答复，本版回填答复并调整通道方案。

本版最大变化：B 部分的表通道方案已废止。双方商定指令下发与执行回报改走 WebSocket 双向长连接，协议细节见同目录 QMT_WS_PROTOCOL.md。B 部分保留仅供追溯，不再作为实现依据。A 部分（只读数据）与 C 部分（切换约定）继续有效。

---

A. PMS 需要读取的数据（下游提供，153 代理可达、严格单表查询）

#	数据项	需要的字段	期望更新时延	用途	答复
A1	持仓快照 trading_position	股票代码（点式）、持仓数量、可用数量（T+1 可卖）、成本价（如有）、冻结数量（如有）	盘中 ≤ 5 分钟	账本对账基准。当前 PMS 只确认过 stock_code 列可用，请提供该表完整字段定义（DDL），尤其确认是否已有"可用数量"列——若无，PMS 自行按 T+1 规则推算	PMS 侧实机探明（2026-07-27，待下游确认语义）：该表 14 列，含 stock_code / stock_name / total_quantity / available_quantity / frozen_quantity / cost_price / market_price / market_value / profit_loss。可用数量列已存在（available_quantity），本项数据需求实质已满足，PMS 已按此列对接。仍请确认：①available_quantity 是否即 T+1 可卖口径 ②更新时延 ③stock_code 格式（点式/前缀式）
A2	委托与成交 trading_order	委托号、股票代码、方向、委托价、委托量、状态（完整状态枚举文档）、成交量、成交均价、委托/成交时间、来源标识	状态变更后 ≤ 1 分钟	成交回放入账（批次/成本）、指令执行确认。请提供完整 DDL 与状态流转说明（现掌握的 submitted/filled/completed/pending/failed 为推断口径，需正式确认）	PMS 侧实机探明：该表 20 列，已见 order_id / strategy_id / stock_code / stock_name / order_side / order_quantity / order_price / target_price / order_status 等。仍缺两项，是本清单里最卡 PMS 的：①状态枚举的正式定义 ②成交来源标识（哪条委托对应 PMS 的哪条指令）。在来源标识到位前，PMS 只能按「同股同向 + 下发早于成交 + FIFO」贪心认领，认领不上即判外部成交并告警——人工与 PMS 同时下单时会误判
A3	账户资金快照（新增需求）	总资产、可用资金、冻结资金、当日卖出可用资金（T+0 回笼）	盘中 ≤ 5 分钟；日终必须	总规模校准与买入前资金校验。形式不限：新表 / 现有表 / HTTP 接口均可，请给出可行方案	已确认可提供，走 WebSocket 实时回传。字段与消息格式见新协议 §5.7 snapshot{kind:"funds"}。sell_return_today（当日卖出回笼）务必提供，PMS 买入前的资金校验依赖它
A4	成交回报明细（可选）	若 A2 已含逐笔或聚合成交（成交量/均价），本项可免；否则请提供逐笔成交表	同 A2	部分成交场景的精确入账	已升格为必需项：QMT 侧确认可回传「逐笔和最终结果」。PMS 账本以逐笔 trade 消息为唯一入账依据，order_update 仅作状态跟踪与终态校验。见新协议 §5.5
A5	上游买入计划 trading_buy_plan	PMS 将作为该表的承接方（替代原决策系统 ENTRY_GATE 的角色）。请确认：①下游当前是否仍轮询 is_active=6 自动挂单？②切换后是否可以停止该轮询（统一走 B1 通道），或保留作为过渡（方案 X）	—	旧通道处置（见 C2）	未答复，仍待确认（新协议 Q1）。另注：该表唯一约束为 (stock_code, trading_time) 且 buy_amount 是金额非股数，单股分批会撞约束——这也是通道改走 WebSocket 后不再受制于该表的原因之一

B. PMS 写入：统一指令通道 【已废止 · 2026-07-28】

本节方案已被 WebSocket 通道取代，不再作为实现依据，保留仅供追溯。 双方商定：指令下发与执行结果（逐笔成交、最终结果、落库结果）全部走 WebSocket 双向长连接； 幂等与防重放由「PMS 生成的 instruction_id + 签名 + 时间窗」保证，不再依赖表的唯一约束。 现行方案见 QMT_WS_PROTOCOL.md。 下方 B1.1~B1.7 的协商点已在新协议中逐条落实：通道形式（§1）、响应节奏（§1 心跳/实时推送）、 部分成交（§5.4/§5.5）、撤单（§4.3）、拒绝码（§7.3）、市价语义（§4.2，改为限价必填）、建表归属（不再需要）。

B1 pms_order_request —— 带数量的统一买卖指令（建议表结构，可等价改为 Redis 流）

CREATE TABLE pms_order_request (
  id             BIGINT PRIMARY KEY AUTO_INCREMENT,
  instruction_id VARCHAR(64)  NOT NULL UNIQUE COMMENT '幂等键, PMS 生成, 重复插入应被拒绝',
  ts_code        VARCHAR(16)  NOT NULL COMMENT '点式, 如 600000.SH',
  side           VARCHAR(8)   NOT NULL COMMENT 'buy / sell',
  qty            INT          NOT NULL COMMENT '股数, 整百',
  limit_price    DECIMAL(10,2) NULL   COMMENT '限价; NULL=按下游默认方式',
  valid_until    DATETIME     NOT NULL COMMENT '有效期, 过期未执行由下游置 EXPIRED',
  source         VARCHAR(16)  NOT NULL DEFAULT 'pms',
  status         VARCHAR(16)  NOT NULL DEFAULT 'NEW'
                 COMMENT 'NEW→ACCEPTED→EXECUTING→FILLED / PARTIAL / REJECTED / EXPIRED / CANCELLED',
  exec_qty       INT          NULL COMMENT '已成交数量(聚合)',
  exec_avg_price DECIMAL(10,2) NULL COMMENT '成交均价(聚合)',
  reject_reason  VARCHAR(200) NULL,
  cancel_flag    TINYINT      NOT NULL DEFAULT 0 COMMENT 'PMS 置 1 请求撤单, 下游确认后置 status=CANCELLED',
  create_time    DATETIME     NOT NULL,
  update_time    DATETIME     NOT NULL,
  KEY idx_status (status), KEY idx_code (ts_code)
);

#	协商点	说明	答复
B1.1	通道形式	表轮询（上述 DDL）还是 Redis 流？下游选定形式，字段语义不变
B1.2	轮询/响应节奏	下游多久拉一次 NEW？期望 ≤ 1 分钟；状态回写时延期望 ≤ 1 分钟
B1.3	部分成交	有效期内持续执行到 FILLED 或到期置 PARTIAL（exec_qty 如实回写）——可否按此语义？
B1.4	撤单	PMS 置 cancel_flag=1 → 下游撤在途委托并回写 CANCELLED（已成交部分保留在 exec_qty）——可行？
B1.5	拒绝码	涨跌停/停牌/资金不足/数量非法等 reject_reason 枚举，请提供清单
B1.6	市价语义	limit_price=NULL 时下游按什么方式执行（对手价/最新价±滑点）？
B1.7	建表归属	该表建在下游库还是 153 代理侧？（PMS 经 153 代理单表读写均可）

C. 行为与切换约定

#	事项	说明	答复
C1	幂等与重复防护	instruction_id 唯一约束由表/流层保证；下游对同一 instruction_id 只执行一次
C2	旧通道停用清单	切换生效后，下游停止：①直接执行决策系统的卖出指令与盘中 ENTRY/EXIT 信号 ②（若 A5 确认）轮询 trading_buy_plan 自动挂单。此后下游只接受 WebSocket 通道指令。请确认停用方式与时点	⚠️ 本轮答复未涉及，是当前最大的未决项（新协议 Q1）。不定死时点，切换当天两套系统会对同一只票同时下单。PMS 侧已完成信号订阅改造（PMS 现已自行消化决策系统信号），下游停用的前置条件已具备
C3	灰度共存期	切换初期建议双轨观察 N 个交易日（旧通道只读不执行、B1 实际执行），请确认可行性
C4	时钟与代码格式	双方统一点式代码（600000.SH）与服务器时钟（NTP）；日期时间字段时区 Asia/Shanghai
C5	故障约定	下游不可用时 PMS 指令停发并告警（PMS 侧守成）；下游恢复后不补执行已过期指令
C6	账号与权限	PMS 需要的库账号/代理路由（读 A1-A5、读写 B1），请提供

D. 请提供的文档

#	文档	说明	答复
D1	trading_position / trading_order / trading_buy_plan 完整 DDL	含索引与状态枚举正式定义	列名已由 PMS 实机探明（docker compose run --rm pms-web python scripts/check_db.py 的 [3] 段会打印三表完整列定义，可直接贴进本表）：trading_position 14 列 / trading_order 20 列 / trading_buy_plan 25 列。仍需下游正式提供的是语义而非列名：状态枚举取值与流转、各数量列口径、索引
D2	下游执行行为说明	委托拆单逻辑（如有）、涨跌停处理、集合竞价时段行为
D3	现有信号消费点清单	下游当前消费决策系统信号的全部位置（用于 C2 停用核对，防遗漏）