tradingSystem/QMT_INTERFACE_REQUIREMENTS.md

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

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

---

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

#	数据项	需要的字段	期望更新时延	用途	答复
A1	持仓快照 trading_position	股票代码（点式）、持仓数量、可用数量（T+1 可卖）、成本价（如有）、冻结数量（如有）	盘中 ≤ 5 分钟	账本对账基准。当前 PMS 只确认过 stock_code 列可用，请提供该表完整字段定义（DDL），尤其确认是否已有"可用数量"列——若无，PMS 自行按 T+1 规则推算
A2	委托与成交 trading_order	委托号、股票代码、方向、委托价、委托量、状态（完整状态枚举文档）、成交量、成交均价、委托/成交时间、来源标识	状态变更后 ≤ 1 分钟	成交回放入账（批次/成本）、指令执行确认。请提供完整 DDL 与状态流转说明（现掌握的 submitted/filled/completed/pending/failed 为推断口径，需正式确认）
A3	账户资金快照（新增需求）	总资产、可用资金、冻结资金、当日卖出可用资金（T+0 回笼）	盘中 ≤ 5 分钟；日终必须	总规模校准与买入前资金校验。形式不限：新表 / 现有表 / HTTP 接口均可，请给出可行方案
A4	成交回报明细（可选）	若 A2 已含逐笔或聚合成交（成交量/均价），本项可免；否则请提供逐笔成交表	同 A2	部分成交场景的精确入账
A5	上游买入计划 trading_buy_plan	PMS 将作为该表的承接方（替代原决策系统 ENTRY_GATE 的角色）。请确认：①下游当前是否仍轮询 is_active=6 自动挂单？②切换后是否可以停止该轮询（统一走 B1 通道），或保留作为过渡（方案 X）	—	旧通道处置（见 C2）

B. PMS 写入：统一指令通道（新增，核心协商项）

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 自动挂单。此后下游只接受 B1 通道指令。请确认停用方式与时点
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	含索引与状态枚举正式定义
D2	下游执行行为说明	委托拆单逻辑（如有）、涨跌停处理、集合竞价时段行为
D3	现有信号消费点清单	下游当前消费决策系统信号的全部位置（用于 C2 停用核对，防遗漏）