# 持仓系统 ↔ 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 流）

```sql
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 停用核对，防遗漏） | |