# 数据类型与字段

单位、缺失值和时间含义都是接口的一部分。交易视图字段未知时为 None，行情数值初始为 NaN；不要把未知值当作 0。

## Quote

合约行情快照；通过观察句柄的 data() 获取，不随后续更新改变。

Attributes:
    symbol: 合约代码，如 SHFE.rb2610 或 DCE.a2611-C-3700。
    trading_day: 交易日，格式 YYYYMMDD。
    timestamp: 行情时间，Unix 毫秒。
    open: 开盘价。
    highest: 最高价。
    lowest: 最低价。
    last_price: 最新价。
    pre_settlement: 昨结算价。
    pre_close: 昨收盘价。
    upper_limit: 涨停价。
    lower_limit: 跌停价。
    volume: 成交量。
    turnover: 成交额。
    open_interest: 持仓量。
    bids: 买盘档位，每档为（价格，数量）。
    asks: 卖盘档位，每档为（价格，数量）。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `symbol` | `str` | 合约代码，如 SHFE.rb2610 或 DCE.a2611-C-3700。 |
| `trading_day` | `str` | 交易日，格式 YYYYMMDD。 |
| `timestamp` | `int` | 行情时间，Unix 毫秒。 |
| `open` | `float` | 开盘价。 |
| `highest` | `float` | 最高价。 |
| `lowest` | `float` | 最低价。 |
| `last_price` | `float` | 最新价。 |
| `pre_settlement` | `float` | 昨结算价。 |
| `pre_close` | `float` | 昨收盘价。 |
| `upper_limit` | `float` | 涨停价。 |
| `lower_limit` | `float` | 跌停价。 |
| `volume` | `float` | 成交量。 |
| `turnover` | `float` | 成交额。 |
| `open_interest` | `float` | 持仓量。 |
| `bids` | `list` | 买盘档位，每档为（价格，数量）。 |
| `asks` | `list` | 卖盘档位，每档为（价格，数量）。 |

初始 symbol 由订阅决定，trading_day=""，timestamp=0，数值字段为 NaN，盘口为空列表。对象字段只读，快照不随后续更新变化。盘口不保证固定档数。

## ExError

SDK 数据或交易服务异常，status 为可选的响应状态码。

```text
ExError(message: str, *, status: int | None = None)
```

继承 Exception；str(error) 为可供业务读取的提示，error.status 为可选 HTTP 状态码。内部重新包装异常时 status 可能为 None，不能只依赖此字段分类所有故障。

## CtpAccount

CTP 直连账户配置，交易凭据不会发送至行情服务。

Args:
    broker_id: 期货公司代码。
    user_id: 资金账号。
    password: 交易密码。
    front_url: 交易前置地址，格式为 tcp://地址:端口。
    app_id: 期货公司提供的客户端标识。
    auth_code: 期货公司提供的客户端授权码。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `broker_id` | `str` | 期货公司代码。 |
| `user_id` | `str` | 资金账号。 |
| `password` | `str` | 交易密码。 |
| `front_url` | `str` | 交易前置地址，格式为 tcp://地址:端口。 |
| `app_id` | `str` | 期货公司提供的客户端标识。 |
| `auth_code` | `str` | 期货公司提供的客户端授权码。 |

全部参数必填，front_url 必须以 tcp:// 开头。password/auth_code 不出现在默认 repr 中；仍不要输出整个配置。校验失败抛 ValueError。

## Account

只读资金快照；金额单位为人民币元，未知字段为 None。

金额仅由完整柜台查询更新，不根据行情或成交估算；交易日来自登录回报。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `account_id` | `str \| None` | 资金账号。 |
| `trading_day` | `str \| None` | 交易日，格式 YYYYMMDD。 |
| `balance` | `float \| None` | 账户权益。 |
| `available` | `float \| None` | 可用资金。 |
| `margin` | `float \| None` | 已占用保证金。 |
| `frozen_margin` | `float \| None` | 冻结保证金。 |
| `commission` | `float \| None` | 当日累计实际手续费。 |
| `frozen_commission` | `float \| None` | 冻结手续费。 |
| `close_profit` | `float \| None` | 当日平仓盈亏。 |
| `position_profit` | `float \| None` | 持仓盈亏。 |
| `deposit` | `float \| None` | 当日入金。 |
| `withdraw` | `float \| None` | 当日出金。 |
| `updated_at` | `int \| None` | 最近一次完整查询完成的本地时间，Unix 毫秒。 |

## Position

只读持仓快照；数量单位为手。

登录查询建立基线，之后根据真实成交本地更新；未知数量为 None。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `symbol` | `str` | 合约代码，如 SHFE.rb2610。 |
| `pos_long` | `int \| None` | 多头持仓。 |
| `pos_short` | `int \| None` | 空头持仓。 |
| `pos_long_today` | `int \| None` | 剩余多头今仓。 |
| `pos_short_today` | `int \| None` | 剩余空头今仓。 |
| `available_long` | `int \| None` | 本地参考可平多头手数：多头持仓减已知有效卖出平仓委托的冻结量；最终由柜台校验。 |
| `available_short` | `int \| None` | 本地参考可平空头手数：空头持仓减已知有效买入平仓委托的冻结量；最终由柜台校验。 |

## Order

只读订单快照；断线后观察句柄保留最后一次已提交的数据。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `order_id` | `str` | FrontID:SessionID:OrderRef 格式的本地订单标识。 |
| `order_sys_id` | `str \| None` | CTP 返回的交易所订单号 OrderSysID，尚未收到时为 None。 |
| `symbol` | `str` | 合约代码。 |
| `direction` | `str \| None` | BUY 买入，SELL 卖出。 |
| `offset` | `str \| None` | 实际委托开平标志：OPEN、CLOSE、CLOSE_TODAY 或 CLOSE_YESTERDAY。 |
| `limit_price` | `float \| None` | 委托限价。 |
| `volume_original` | `int \| None` | 原始委托数量，单位为手。 |
| `volume_traded` | `int \| None` | 已成交数量，单位为手。 |
| `volume_left` | `int \| None` | 未成交数量；撤单结束后仍可大于零。 |
| `status` | `Literal['PENDING', 'ALIVE', 'FILLED', 'CANCELLED', 'REJECTED'] \| None` | 待回报、尚未确认终态、全部成交、未全成且不再排队、提交失败或被拒；未知时为 None。 |
| `status_msg` | `str \| None` | 最近一次订单状态说明。 |
| `cancel_pending` | `bool` | 撤单请求待发送或等待柜台结果时为 True。 |
| `cancel_error` | `str \| None` | 撤单失败原因；没有失败时为 None。 |
| `insert_time` | `int \| None` | 委托时间，Unix 毫秒。 |

status 允许 PENDING、ALIVE、FILLED、CANCELLED、REJECTED。CANCELLED 不代表剩余数量为零；cancel_pending / cancel_error 反映撤单过程，不是新的成交。

## Trade

只读真实成交快照，不包含估算手续费；断线后保留最后一次已提交的数据。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `trade_id` | `str` | CTP 返回的原始成交号 TradeID。 |
| `order_sys_id` | `str` | CTP 返回的交易所订单号 OrderSysID。 |
| `symbol` | `str` | 合约代码。 |
| `direction` | `str \| None` | BUY 买入，SELL 卖出。 |
| `offset` | `str \| None` | OPEN 开仓，CLOSE 普通平仓，CLOSE_TODAY 平今，CLOSE_YESTERDAY 平昨。 |
| `price` | `float \| None` | 实际成交价格。 |
| `volume` | `int \| None` | 实际成交数量，单位为手。 |
| `trade_time` | `int \| None` | 成交时间，Unix 毫秒。 |

trade_id 为原始 CTP TradeID；通过 order_sys_id 关联 Order.order_sys_id。成交不包含估算手续费。

## TradingResult

一次交易操作的即时提交结果；不是最终委托或撤单结果。

| 字段 | 类型 | 含义 |
| --- | --- | --- |
| `status` | `Literal['SUBMITTED', 'REJECTED', 'UNKNOWN']` | SUBMITTED / REJECTED / UNKNOWN，即时提交结果。 |
| `order_id` | `str \| None` | 关联本地订单号；下单本地拒绝为 None。 |
| `message` | `str` | 即时结果说明，默认空字符串。 |

## K 线 DataFrame

| 列 | 含义 |
| --- | --- |
| timestamp | K 线周期结束时间，Unix 毫秒；日线使用交易日北京时间零点 |
| trading_day | YYYYMMDD 交易日 |
| open / high / low / close | 开盘 / 最高 / 最低 / 收盘价 |
| volume | 成交量 |
| turnover | 成交额 |
| open_interest | 持仓量 |

frame.attrs 包含 symbol 与 period。数据为独立快照，最新一行可能仍在变化；新建指标列不会进入下一份 SDK 快照。

## 合约详情字典

query_symbol_info() 顶层固定含 symbol、exchange_id、product_id、ins_class、is_main、data。data 的内部键按服务实际返回读取，SDK 不承诺固定的静态字段集合。

## 只读集合

watch_position、watch_order、watch_trade 的 data() 返回只读 Mapping。分别按 symbol、order_id、trade_id 索引；即使指定单个合约也返回映射。不要向映射或交易快照字段赋值。