.. _qpro_httpserver_schema:

========================================
QPro HTTP server 表结构与字段说明
========================================

HTTP server 查询的是 QPro 本地节点数据写入的 SQLite 快照表。当前提供四张表：

* ``AccountSnap``：账户资金快照。
* ``PositionSnap``：持仓快照。
* ``OrderSnap``：委托快照。
* ``TradeSnap``：成交快照。

实际可查询字段可以通过 ``GET /tables`` 获取。本文说明当前版本的字段含义。

刷新机制
=========

QPro 写入线程大约每 500ms 从节点数据库读取一次数据，并按 ``node_key`` 对 SQLite 表执行 upsert。表内每行代表一个账户、持仓、委托或成交对象的最新快照。

``insert_time`` 是本地 SQLite 首次插入该行的时间。``update_time`` 是该行最近一次被 QPro upsert 的 SQLite 时间，不等同于交易所事件时间。

账户数据会在账户 ready 后写入，持仓数据会在持仓 ready 后写入。委托和成交按节点数据到达情况写入。

公共字段
=========

.. list-table::
   :header-rows: 1
   :widths: 24 76

   * - 字段
     - 含义
   * - ``node_key``
     - QPro 节点数据中的唯一键，也是各表主键。
   * - ``insert_time``
     - 本地 SQLite 首次插入该行的时间。
   * - ``update_time``
     - 本地 SQLite 最近一次更新该行的时间。
   * - ``user_key``
     - QPro 内部账户 key。过滤单个账户时优先使用该字段。
   * - ``investor_id``
     - 柜台/经纪商侧投资者账号。
   * - ``user_desc``
     - QPro 中显示的账户描述。

枚举字段
=========

.. list-table::
   :header-rows: 1
   :widths: 26 74

   * - 字段
     - 可能取值
   * - ``direction``
     - ``BUY``、``SELL``、``INVALID``
   * - ``offset``
     - ``OPEN``、``CLOSE``、``CLOSE_TODAY``、``CLOSE_YESTERDAY``、``INVALID``
   * - ``hedge_flag``
     - ``SPECULATION``、``ARBITRAGE``、``HEDGE``、``MARKET_MAKER``、``COVERED``、``SPEC_AND_HEDGE``、``HEDGE_AND_SPEC``、``INVALID``
   * - ``price_type``
     - ``LIMIT``、``BEST``、``FIVE_LEVEL``、``ANY``、``INVALID``
   * - ``volume_condition``
     - ``ANY``、``MIN``、``ALL``、``INVALID``
   * - ``time_condition``
     - ``IOC``、``GFS``、``GFD``、``GTD``、``GTC``、``GFA``、``INVALID``
   * - ``status``
     - ``ALIVE``、``DEAD``、``INVALID``
   * - ``force_close_reason``
     - ``NOT_FORCE_CLOSE``、``LACK_DEPOSIT``、``CLIENT_OVER_POSITION_LIMIT``、``MEMBER_OVER_POSITION_LIMIT``、``NOT_MULTIPLE``、``VIOLATION``、``OTHER``、``PERSON_DELIV``、``HEDGE_OVER_POSITION_LIMIT``、``OVERSEAS_GROUP_OVER_POSITION_LIMIT``、``INVALID``
   * - ``ins_class``
     - ``CONT``、``FUTURE``、``OPTION``、``COMBINE``、``INDEX``、``SPOT``、``STOCK``、``BOND``、``FUND``、``CUS_COMBINE``、``INVALID``

AccountSnap
===========

索引：

* ``account_update_time_idx(update_time DESC)``
* ``account_user_key_idx(user_key)``

.. list-table::
   :header-rows: 1
   :widths: 28 72

   * - 字段
     - 含义
   * - ``currency``
     - 币种，默认 ``CNY``。
   * - ``pre_balance``
     - 上日结存。
   * - ``deposit``
     - 入金。
   * - ``withdraw``
     - 出金。
   * - ``close_profit``
     - 平仓盈亏。
   * - ``position_profit``
     - 持仓盈亏。
   * - ``float_profit``
     - 浮动盈亏。
   * - ``client_equity``
     - 客户权益。
   * - ``balance``
     - 账户余额。
   * - ``margin``
     - 当前保证金占用。
   * - ``frozen_margin``
     - 冻结保证金。
   * - ``commission``
     - 手续费。
   * - ``frozen_commission``
     - 冻结手续费。
   * - ``premium``
     - 权利金。
   * - ``frozen_premium``
     - 冻结权利金。
   * - ``available``
     - 可用资金。
   * - ``risk_ratio``
     - 风险度。
   * - ``ref_risk_ratio``
     - 参考风险度。
   * - ``option_market_value``
     - 期权市值。
   * - ``option_buy_market_value``
     - 期权买持市值。
   * - ``option_sell_market_value``
     - 期权卖持市值。
   * - ``mortgage``
     - 质押金额。

PositionSnap
============

索引：

* ``position_update_time_idx(update_time DESC)``
* ``position_user_key_idx(user_key)``
* ``position_instrument_id_idx(instrument_id)``

.. list-table::
   :header-rows: 1
   :widths: 28 72

   * - 字段
     - 含义
   * - ``exchange_id``
     - 交易所代码。
   * - ``instrument_id``
     - 合约代码。
   * - ``symbol``
     - QPro 行情模型中的 symbol。
   * - ``product_id``
     - 品种代码。
   * - ``volume_multiple``
     - 合约乘数。
   * - ``last_price``
     - 持仓快照使用的最新价。
   * - ``risk_position``
     - 是否风险持仓，``1`` 表示是。
   * - ``volume_long``
     - 多头总持仓。
   * - ``volume_long_frozen``
     - 多头冻结持仓。
   * - ``volume_short``
     - 空头总持仓。
   * - ``volume_short_frozen``
     - 空头冻结持仓。
   * - ``volume_net``
     - 净持仓，通常为多头减空头。
   * - ``volume_yesterday``
     - 昨仓数量。
   * - ``volume_yesterday_net``
     - 昨仓净数量。
   * - ``volume_total``
     - 总持仓数量。
   * - ``volume_today``
     - 今仓数量。
   * - ``volume_frozen``
     - 冻结持仓数量。
   * - ``volume_comb``
     - 组合持仓数量。
   * - ``volume_long_comb``
     - 多头组合持仓数量。
   * - ``volume_short_comb``
     - 空头组合持仓数量。
   * - ``total_other_position``
     - 其他类别持仓总量。
   * - ``float_profit``
     - 浮动盈亏。
   * - ``position_profit``
     - 持仓盈亏。
   * - ``close_profit``
     - 平仓盈亏。
   * - ``close_profit_by_open``
     - 按开仓价计算的平仓盈亏。
   * - ``margin``
     - 该持仓保证金占用。
   * - ``premium``
     - 该持仓权利金。
   * - ``untrade_profit``
     - 未实现/未交易盈亏字段。
   * - ``trade_profit``
     - 交易盈亏字段。
   * - ``commission``
     - 该持仓手续费。
   * - ``long_market_value``
     - 多头市值。
   * - ``short_market_value``
     - 空头市值。
   * - ``long_market_value_yesterday``
     - 昨日多头市值。
   * - ``short_market_value_yesterday``
     - 昨日空头市值。
   * - ``unit_id``
     - 交易单元 id，默认交易单元通常为 ``0``。
   * - ``ins_class``
     - 合约类型。

持仓子字段
----------

``PositionSnap`` 还展开了四组子持仓字段：

* ``long_spec_``：多头投机。
* ``long_other_``：多头其他。
* ``short_spec_``：空头投机。
* ``short_other_``：空头其他。

每组前缀都有以下后缀：

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - 后缀
     - 含义
   * - ``volume_yesterday``
     - 昨仓数量。
   * - ``volume_today``
     - 今仓数量。
   * - ``volume_his``
     - 历史持仓数量。
   * - ``volume_comb``
     - 组合持仓数量。
   * - ``volume_today_frozen``
     - 今仓冻结数量。
   * - ``volume_his_frozen``
     - 历史持仓冻结数量。
   * - ``strike_frozen``
     - 行权/执行冻结数量。
   * - ``strike_his_frozen``
     - 历史行权/执行冻结数量。
   * - ``open_price``
     - 开仓价。
   * - ``float_profit``
     - 浮动盈亏。
   * - ``position_price``
     - 持仓价。
   * - ``position_profit``
     - 持仓盈亏。
   * - ``close_profit``
     - 平仓盈亏。
   * - ``close_profit_by_open``
     - 按开仓价计算的平仓盈亏。
   * - ``margin``
     - 保证金。
   * - ``market_value``
     - 市值。
   * - ``market_value_yesterday``
     - 昨日市值。
   * - ``commission``
     - 手续费。
   * - ``untrade_profit``
     - 未实现/未交易盈亏。
   * - ``premium``
     - 权利金。

例如 ``long_spec_volume_today``、``short_other_margin``、``short_spec_position_profit`` 都是有效字段。

OrderSnap
=========

索引：

* ``order_update_time_idx(update_time DESC)``
* ``order_insert_date_time_idx(insert_date_time DESC)``
* ``order_instrument_id_idx(instrument_id)``

.. list-table::
   :header-rows: 1
   :widths: 28 72

   * - 字段
     - 含义
   * - ``user_id``
     - 柜台侧用户 id。
   * - ``exchange_id``
     - 交易所代码。
   * - ``instrument_id``
     - 合约代码。
   * - ``symbol``
     - QPro 行情模型中的 symbol。
   * - ``product_id``
     - 品种代码。
   * - ``volume_multiple``
     - 合约乘数。
   * - ``ins_class``
     - 合约类型。
   * - ``order_id``
     - QPro/源模型委托 id，可与 ``TradeSnap.order_id`` 配合 ``user_key`` 关联。
   * - ``is_swap_order``
     - 是否互换/换仓相关委托，``1`` 表示是。
   * - ``is_quote``
     - 是否询价/报价相关委托，``1`` 表示是。
   * - ``hedge_flag``
     - 投保标志。
   * - ``direction``
     - 买卖方向。
   * - ``offset``
     - 开平标志。
   * - ``price_type``
     - 价格类型。
   * - ``limit_price``
     - 限价。
   * - ``volume_orign``
     - 原始委托数量。字段名沿用源模型拼写。
   * - ``volume_left``
     - 剩余未成交数量。
   * - ``volume_trade``
     - 已成交数量。
   * - ``volume_condition``
     - 成交量类型。
   * - ``min_volume``
     - 最小成交数量。
   * - ``time_condition``
     - 有效期类型。
   * - ``status``
     - 委托状态。
   * - ``exchange_order_id``
     - 交易所委托编号。
   * - ``insert_date_time``
     - 源模型委托插入时间，BIGINT。
   * - ``dead_date_time``
     - 源模型委托结束时间，BIGINT。
   * - ``last_trade_date_time``
     - 最近成交时间，BIGINT。
   * - ``status_msg``
     - 状态消息。
   * - ``force_close_reason``
     - 强平原因。
   * - ``user_product_info``
     - 用户产品信息。
   * - ``order_local_id``
     - 本地委托编号。
   * - ``trader_id``
     - 交易员代码。
   * - ``order_ref``
     - 报单引用。
   * - ``front_id``
     - 前置编号。
   * - ``session_id``
     - 会话编号。
   * - ``unit_id``
     - 交易单元 id。
   * - ``seq_no``
     - 序号。
   * - ``flow_index``
     - QPro 源模型流水索引。
   * - ``request_id``
     - 请求编号。
   * - ``trade_price``
     - 委托模型中的成交价格字段。
   * - ``trade_total_volume``
     - 委托模型中的累计成交数量字段。
   * - ``is_trade_ready``
     - 成交信息是否 ready，``1`` 表示 ready。
   * - ``send_date_time``
     - 发送时间，BIGINT。
   * - ``receive_date_time``
     - 接收时间，BIGINT。
   * - ``memo_user_info``
     - 用户备注信息。

TradeSnap
=========

索引：

* ``trade_update_time_idx(update_time DESC)``
* ``trade_trade_date_time_idx(trade_date_time DESC)``
* ``trade_instrument_id_idx(instrument_id)``

.. list-table::
   :header-rows: 1
   :widths: 28 72

   * - 字段
     - 含义
   * - ``user_id``
     - 柜台侧用户 id。
   * - ``exchange_trade_id``
     - 交易所成交编号。
   * - ``exchange_id``
     - 交易所代码。
   * - ``instrument_id``
     - 合约代码。
   * - ``symbol``
     - QPro 行情模型中的 symbol。
   * - ``product_id``
     - 品种代码。
   * - ``volume_multiple``
     - 合约乘数。
   * - ``ins_class``
     - 合约类型。
   * - ``exchange_order_id``
     - 交易所委托编号。
   * - ``order_id``
     - QPro/源模型委托 id，可与 ``OrderSnap.order_id`` 配合 ``user_key`` 关联。
   * - ``direction``
     - 买卖方向。
   * - ``offset``
     - 开平标志。
   * - ``hedge_flag``
     - 投保标志。
   * - ``volume``
     - 成交数量。
   * - ``volume_close_today``
     - 平今数量。
   * - ``volume_close_yesterday``
     - 平昨数量。
   * - ``price``
     - 成交价。
   * - ``trade_date_time``
     - 源模型成交时间，BIGINT。
   * - ``commission``
     - 手续费。
   * - ``order_local_id``
     - 本地委托编号。
   * - ``trader_id``
     - 交易员代码。
   * - ``seq_no``
     - 序号。
   * - ``flow_index``
     - QPro 源模型流水索引。
   * - ``unit_id``
     - 交易单元 id。
   * - ``memo_user_info``
     - 用户备注信息。