Skip to main content

Crate ek_converter

Crate ek_converter 

Source
Expand description

§ek-converter —— enkeep ek 生态的持仓账本与开平转换器

§ek-converter

enkeep ek 生态的持仓账本与开平转换器:逐合约维护「净持仓/昨仓/今仓 + 六个冻结量 + 活跃委托表」, 并按下单请求拆出今平/昨平/锁仓/净仓腿。Python 原稿 enkeep_trade/trader/converter.py(447 行)忠实移植。

§快速开始

use ek_converter::{ConvertMode, OffsetConverter};
use ek_data::constant::{Asset, Direction, Exchange, Offset, OrderType};
use ek_data::contract::ContractData;
use ek_data::order_request::OrderRequest;
use ek_data::position::PositionData;

let contract = ContractData {
    gateway_name: "xt".into(),
    symbol: "IF2506".into(),
    exchange: Exchange::SHFE,
    name: "IF2506".into(),
    asset: Asset::FUTURES,
    ..Default::default()
};

// 持仓:空向 10 手,其中昨仓 4、今仓 6
let mut conv = OffsetConverter::new();
conv.update_position(&PositionData {
    gateway_name: "xt".into(),
    symbol: "IF2506".into(),
    exchange: Exchange::SHFE,
    direction: Direction::SHORT,
    volume: 10.0,
    yd_volume: 4.0,
    ..Default::default()
}, Some(&contract));

// 多向平 8 手 → SHFE 自动拆分:先平今,再平昨
let legs = conv.convert_order_request(&OrderRequest {
    symbol: "IF2506".into(),
    exchange: Exchange::SHFE,
    direction: Direction::LONG,
    order_type: OrderType::LIMIT,
    volume: 8.0,
    price: 3500.0,
    offset: Offset::CLOSE,
    ..Default::default()
}, ConvertMode::Auto, Some(&contract));

assert_eq!(legs.len(), 2);
assert_eq!((legs[0].offset, legs[0].volume), (Offset::CLOSETODAY, 6.0));
assert_eq!((legs[1].offset, legs[1].volume), (Offset::CLOSEYESTERDAY, 2.0));

§依赖

  • 唯一运行时依赖:ek-data(装版引用,纪律:自研 crate 之间也禁止 path 耦合)。
  • 零第三方:f64 账本 + std::HashMap;不引 log/serde/chrono/anyhow。 0.1.5 起零 dev-deps:跨 crate 集成测试(tests/assembly.rs,真插件对真总线)已整文件迁至 ek-station/tests/assembly.rs —— 本 crate 的依赖图只剩 ek-data。

§语义速览

  • 双层 API:OffsetConverter(表管理 + 合约闸门 + 模式分派)→ PositionHolding(纯账本 + 三策略)。
  • 合约按次传入 Option<&ContractData>(不变量:合约 en_symbol 必须与数据对象一致); 入账三入口 0.1.3 起 None 不再拦截——用数据自带的 en_symbol/exchange 建账(回报侧 不依赖合约在册);下单面仍拦截:更新不入账、拆单原样返回。
  • 交易所判断的来源逐处照抄:成交更新看 TradeData::exchange,锁仓看账本 exchange, SHFE/净仓拆分看 OrderRequest::exchange。
  • 空 Vec = 可平不足、拒单;零量腿与负持仓/负冻结可能出现 —— 均为原稿真身行为(tests/golden.rs 逐条对拍)。
  • ConvertMode::{Auto, Lock, Net}:原稿 (lock, net=False) 双布尔升枚举,Lock > Net 优先级保住。

§保真对拍

两层机制,全部跑 Python 原稿(只读导入,不改原稿):

  • probe/gen_vectors.py → 30 组手选黄金向量,tests/golden.rs 硬编码 (含零量腿/负持仓/负冻结/负可用量/拒单/分派优先级等语义要点)。
  • probe/gen_matrix.py → 990 场景全矩阵差分(成交账本/冻结/拆单的 方向×开平×交易所×基础态×模式×量全组合),答案入 tests/fixtures/matrix.txt, tests/matrix.rs 逐行重放比对 —— 审计层,与硬编码无关,一呼再生。
  • Rust-only 路径(门闸/错误返回/多段 id)在 tests/semantics.rs 锁定。
  • 要求:本机有 enkeep_trade 原稿 checkout + Python ≥3.12(答案已入库,重生成才需要)。

§生态位

ek-oms 按 gateway 托管本 crate 实例、从总线喂入 update_* 并经服务对外读账本; optionmaster 式消费者可只读 holding()。上一个:ek-data 0.2;同代:ek-core 0.3(宿主)。

§版本

0.1.0(首版)


Python 原稿:enkeep_trade/enkeep_trade/trader/converter.py(447 行)。

§全局决定(DESIGN.md 有全文)

  1. 一个结构体一个文件:holding 放账本 PositionHolding与 三条拆分策略;converter 放表管理 OffsetConverter;枚举 ConvertMode 独立一处(生态同款纪律)。
  2. 双层 API:入口层(converter::OffsetConverter)带合约闸门 (Option<&ContractData>),账本层(holding::PositionHolding)纯状态零合约参数。
  3. 合约按次传入(决策①):不注入宿主、不要 trait,纯算法零宿主依赖。
  4. 错误面最窄(决策②③):畸形 en_orderid 返回 false 不 panic; 拆分结果保持 Vec<OrderRequest>(空 = 拒单),与原稿一致。
  5. 零第三方:f64 账本 + HashMap,不引 log/serde;0.1.5 起零 dev-deps (跨 crate 集成套 tests/assembly.rs 已整文件迁至 ek-station/tests/assembly.rs, 本 crate 因此是纯叶子:依赖图只有 ek-data); 保真向量由 probe/gen_vectors.py(跑原稿)生成后硬编码进 tests。

§Python → Rust 对照总表

Python(converter.py)Rust
OffsetConverter(20-101)converter::OffsetConverter
PositionHolding(104-289)holding::PositionHolding
convert_order_request_shfe/lock/net(291/325/372)holding::PositionHolding::convert_order_request_shfe / …_lock / …_net
(lock: bool, net: bool=False)ConvertMode

Re-exports§

pub use convert_mode::ConvertMode;
pub use converter::OffsetConverter;
pub use holding::PositionHolding;

Modules§

convert_mode
转换模式 ConvertMode(Python trader/converter.py:70-89 的两个布尔参数)。
converter
表管理入口 OffsetConverter(Python trader/converter.py:20-101)。
holding
持仓账本 PositionHolding(Python trader/converter.py:104-289)与 三条拆单策略(converter.py:291-447)。