futu_trd/

misc.rs

// 交易杂项: 最大可买卖、订阅推送、确认订单、历史订单/成交

use std::sync::atomic::{AtomicU32, Ordering};

use futu_core::error::{FutuError, Result};
use futu_core::proto_id;
use futu_net::client::FutuClient;

use crate::market::derive_sec_market;
use crate::query::{Order, OrderFill};
use crate::types::TrdHeader;

// ===== 最大可买卖数量 =====

/// 最大可买卖数量查询参数
#[derive(Debug, Clone)]
pub struct MaxTrdQtysParams {
    pub header: TrdHeader,
    pub order_type: i32,
    pub code: String,
    pub price: f64,
    pub order_id: Option<u64>,
}

fn build_get_max_trd_qtys_request(
    params: &MaxTrdQtysParams,
) -> futu_proto::trd_get_max_trd_qtys::Request {
    futu_proto::trd_get_max_trd_qtys::Request {
        c2s: futu_proto::trd_get_max_trd_qtys::C2s {
            header: params.header.to_proto(),
            order_type: params.order_type,
            code: params.code.clone(),
            price: params.price,
            order_id: params.order_id,
            adjust_price: None,
            adjust_side_and_limit: None,
            sec_market: Some(derive_sec_market(
                0,
                params.header.trd_market as i32,
                &params.code,
            )),
            order_id_ex: None,
            session: None,
            position_id: None,
        },
    }
}

/// 获取最大可买卖数量（原始 proto 响应）
pub async fn get_max_trd_qtys(
    client: &FutuClient,
    params: &MaxTrdQtysParams,
) -> Result<futu_proto::trd_get_max_trd_qtys::S2c> {
    let req = build_get_max_trd_qtys_request(params);

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client.request(proto_id::TRD_GET_MAX_TRD_QTYS, body).await?;
    let resp: futu_proto::trd_get_max_trd_qtys::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    if resp.ret_type != 0 {
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    resp.s2c
        .ok_or(FutuError::Codec("missing s2c in GetMaxTrdQtys".into()))
}

// ===== 订阅账户推送 =====

/// 订阅交易账户的推送（订单/成交更新）
pub async fn sub_acc_push(client: &FutuClient, acc_ids: &[u64]) -> Result<()> {
    let req = futu_proto::trd_sub_acc_push::Request {
        c2s: futu_proto::trd_sub_acc_push::C2s {
            acc_id_list: acc_ids.to_vec(),
        },
    };

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client.request(proto_id::TRD_SUB_ACC_PUSH, body).await?;
    let resp: futu_proto::trd_sub_acc_push::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    if resp.ret_type != 0 {
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    Ok(())
}

// ===== 确认订单 =====

/// v1.4.71: RECONFIRM serial_no 起点（从 20,000,000 开始避免与其他 serial 冲突）。
/// 命名 const 避免魔法数。
const RECONFIRM_SERIAL_INIT: u32 = 20_000_000;
static RECONFIRM_SERIAL: AtomicU32 = AtomicU32::new(RECONFIRM_SERIAL_INIT);

/// 再次确认订单
pub async fn reconfirm_order(
    client: &FutuClient,
    header: &TrdHeader,
    order_id: u64,
    reason: i32,
) -> Result<u64> {
    let serial = RECONFIRM_SERIAL.fetch_add(1, Ordering::Relaxed);
    let req = futu_proto::trd_reconfirm_order::Request {
        c2s: futu_proto::trd_reconfirm_order::C2s {
            packet_id: futu_proto::common::PacketId {
                // Echo InitConnect S2C connID like C++ FTAPI clients. The
                // gateway replay guard compares it with the actual TCP conn_id.
                conn_id: client.conn_id().ok_or(FutuError::NotInitialized)?,
                serial_no: serial,
            },
            header: header.to_proto(),
            order_id,
            reconfirm_reason: reason,
        },
    };

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client.request(proto_id::TRD_RECONFIRM_ORDER, body).await?;
    let resp: futu_proto::trd_reconfirm_order::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    if resp.ret_type != 0 {
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    let s2c = resp
        .s2c
        .ok_or(FutuError::Codec("missing s2c in ReconfirmOrder".into()))?;

    Ok(s2c.order_id)
}

// ===== 历史订单 =====

/// 历史订单过滤条件
#[derive(Debug, Clone)]
pub struct HistoryFilterConditions {
    pub code_list: Vec<String>,
    pub id_list: Vec<u64>,
    pub begin_time: Option<String>,
    pub end_time: Option<String>,
    pub filter_market: Option<i32>,
}

impl HistoryFilterConditions {
    pub fn to_proto(&self) -> futu_proto::trd_common::TrdFilterConditions {
        futu_proto::trd_common::TrdFilterConditions {
            code_list: self.code_list.clone(),
            id_list: self.id_list.clone(),
            begin_time: self.begin_time.clone(),
            end_time: self.end_time.clone(),
            order_id_ex_list: vec![],
            filter_market: self.filter_market,
        }
    }
}

/// 查询历史订单列表
pub async fn get_history_order_list(
    client: &FutuClient,
    header: &TrdHeader,
    filter: &HistoryFilterConditions,
) -> Result<Vec<Order>> {
    let req = futu_proto::trd_get_history_order_list::Request {
        c2s: futu_proto::trd_get_history_order_list::C2s {
            header: header.to_proto(),
            filter_conditions: filter.to_proto(),
            filter_status_list: vec![],
        },
    };

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client
        .request(proto_id::TRD_GET_HISTORY_ORDER_LIST, body)
        .await?;
    let resp: futu_proto::trd_get_history_order_list::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    if resp.ret_type != 0 {
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    let s2c = resp.s2c.ok_or(FutuError::Codec(
        "missing s2c in GetHistoryOrderList".into(),
    ))?;

    Ok(s2c.order_list.iter().map(Order::from_proto).collect())
}

/// 查询历史成交列表
pub async fn get_history_order_fill_list(
    client: &FutuClient,
    header: &TrdHeader,
    filter: &HistoryFilterConditions,
) -> Result<Vec<OrderFill>> {
    let req = futu_proto::trd_get_history_order_fill_list::Request {
        c2s: futu_proto::trd_get_history_order_fill_list::C2s {
            header: header.to_proto(),
            filter_conditions: filter.to_proto(),
        },
    };

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client
        .request(proto_id::TRD_GET_HISTORY_ORDER_FILL_LIST, body)
        .await?;
    let resp: futu_proto::trd_get_history_order_fill_list::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    if resp.ret_type != 0 {
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    let s2c = resp.s2c.ok_or(FutuError::Codec(
        "missing s2c in GetHistoryOrderFillList".into(),
    ))?;

    s2c.order_fill_list
        .iter()
        .map(OrderFill::from_proto)
        .collect()
}

// ===== 订单费用查询（CMD 2225 TRD_GET_ORDER_FEE）=====

#[cfg(test)]
mod tests;

/// 订单费用明细条目
#[derive(Debug, Clone)]
pub struct OrderFeeItem {
    pub title: String,
    pub value: f64,
}

/// 单个订单费用
#[derive(Debug, Clone)]
pub struct OrderFee {
    pub order_id_ex: String,
    pub fee_amount: f64,
    pub fee_list: Vec<OrderFeeItem>,
}

/// 查询订单费用（按 `order_id_ex` 列表）
///
/// 对齐 C++ `TRD_GET_ORDER_FEE`（proto_id 2225），接收扩展订单号列表，
/// 返回每个订单的费用总额 + 明细拆分（佣金、平台费、印花税等）。
///
/// 典型调用时机：下单后或撤单前估算费用。
pub async fn get_order_fee(
    client: &FutuClient,
    header: &TrdHeader,
    order_id_ex_list: &[String],
) -> Result<Vec<OrderFee>> {
    let req = futu_proto::trd_get_order_fee::Request {
        c2s: futu_proto::trd_get_order_fee::C2s {
            header: header.to_proto(),
            order_id_ex_list: order_id_ex_list.to_vec(),
        },
    };

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client.request(proto_id::TRD_GET_ORDER_FEE, body).await?;
    let resp: futu_proto::trd_get_order_fee::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    if resp.ret_type != 0 {
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    let s2c = resp
        .s2c
        .ok_or(FutuError::Codec("missing s2c in GetOrderFee".into()))?;

    Ok(s2c
        .order_fee_list
        .iter()
        .map(|o| OrderFee {
            order_id_ex: o.order_id_ex.clone(),
            fee_amount: o.fee_amount.unwrap_or(0.0),
            fee_list: o
                .fee_list
                .iter()
                .map(|i| OrderFeeItem {
                    title: i.title.clone().unwrap_or_default(),
                    value: i.value.unwrap_or(0.0),
                })
                .collect(),
        })
        .collect())
}

// ===== 融资融券比率查询（CMD 2223 TRD_GET_MARGIN_RATIO）=====

/// 单个标的的融资融券比率信息（精简版）
#[derive(Debug, Clone)]
pub struct MarginRatio {
    /// 市场 + 代码（用 Python SDK 的 `HK.00700` 格式字符串，方便上层展示）
    pub code: String,
    pub is_long_permit: bool,
    pub is_short_permit: bool,
    pub short_pool_remain: f64,
    pub short_fee_rate: f64,
    /// 融资初始保证金率
    pub im_long_ratio: f64,
    /// 融券初始保证金率
    pub im_short_ratio: f64,
}

/// 按标的列表查询融资融券比率。对齐 C++ `TRD_GET_MARGIN_RATIO`（2223）
/// 和 Python SDK `OpenTradeContext.get_margin_ratio`。
///
/// `securities` 是 `(market, code)` 元组列表，market 对齐 Qot_Common.QotMarket。
pub async fn get_margin_ratio(
    client: &FutuClient,
    header: &TrdHeader,
    securities: &[(i32, String)],
) -> Result<Vec<MarginRatio>> {
    use futu_proto::qot_common;
    let sec_list: Vec<qot_common::Security> = securities
        .iter()
        .map(|(m, c)| qot_common::Security {
            market: *m,
            code: c.clone(),
        })
        .collect();
    let req = futu_proto::trd_get_margin_ratio::Request {
        c2s: futu_proto::trd_get_margin_ratio::C2s {
            header: header.to_proto(),
            security_list: sec_list,
        },
    };

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client.request(proto_id::TRD_GET_MARGIN_RATIO, body).await?;
    let resp: futu_proto::trd_get_margin_ratio::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    if resp.ret_type != 0 {
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    let s2c = resp
        .s2c
        .ok_or(FutuError::Codec("missing s2c in GetMarginRatio".into()))?;

    Ok(s2c
        .margin_ratio_info_list
        .iter()
        .map(|m| MarginRatio {
            code: format!(
                "{}.{}",
                market_to_prefix(m.security.market),
                m.security.code
            ),
            is_long_permit: m.is_long_permit.unwrap_or(false),
            is_short_permit: m.is_short_permit.unwrap_or(false),
            short_pool_remain: m.short_pool_remain.unwrap_or(0.0),
            short_fee_rate: m.short_fee_rate.unwrap_or(0.0),
            im_long_ratio: m.im_long_ratio.unwrap_or(0.0),
            im_short_ratio: m.im_short_ratio.unwrap_or(0.0),
        })
        .collect())
}

/// QotMarket → `HK` / `US` / `SH` / `SZ` 等前缀（对齐 Python SDK 的
/// `MARKET.CODE` 约定）。未知 market 返回 `"UNK"`。
fn market_to_prefix(m: i32) -> &'static str {
    // Qot_Common.QotMarket 枚举，见 Qot_Common.proto
    match m {
        1 => "HK",
        11 => "US",
        21 => "SH",
        22 => "SZ",
        31 => "SG",
        41 => "JP",
        42 => "AU",
        _ => "UNK",
    }
}