futu_qot/

subscription_plan.rs

//! QOT subscribe request planning helpers.
//!
//! This module owns small pure decisions that turn public `Qot_Sub` request
//! flags into backend subscription options.  Surface handlers should call this
//! layer instead of re-deriving session/detail semantics inline.

pub const SESSION_NONE: i32 = 0;
pub const SESSION_RTH: i32 = 1;
pub const SESSION_ETH: i32 = 2;
pub const SESSION_ALL: i32 = 3;
pub const SESSION_OVERNIGHT: i32 = 5;
pub const SECURITY_TYPE_DRVT: i32 = 8;
pub const SECURITY_TYPE_FUTURE: i32 = 10;

// Internal subscribe-market markers consumed by futu-backend::quote_sub.
// They are derived from cached security metadata, not accepted as public
// QotMarket input. Ref: C++ APIServer_Qot_StockBasic.cpp:45-51 and
// APIServer_Qot_OrderBook.cpp:42-48 first PullOptinoInfo/GetStockID for
// options, then subscribe/read using the resolved StockKey.
pub const BACKEND_MARKET_HK_OPTION: i32 = 9;
pub const BACKEND_MARKET_US_OPTION: i32 = 15;

// Ref: `proto/Qot_Common.proto::SubType`. These are public FTAPI enum values,
// not backend-dynamic configuration; keep them centralized so subscribe,
// first-push, and cache-read gates do not drift.
pub const SUB_TYPE_NONE: i32 = 0;
pub const SUB_TYPE_BASIC: i32 = 1;
pub const SUB_TYPE_ORDER_BOOK: i32 = 2;
pub const SUB_TYPE_TICKER: i32 = 4;
pub const SUB_TYPE_RT: i32 = 5;
pub const SUB_TYPE_KL_DAY: i32 = 6;
pub const SUB_TYPE_KL_5MIN: i32 = 7;
pub const SUB_TYPE_KL_15MIN: i32 = 8;
pub const SUB_TYPE_KL_30MIN: i32 = 9;
pub const SUB_TYPE_KL_60MIN: i32 = 10;
pub const SUB_TYPE_KL_1MIN: i32 = 11;
pub const SUB_TYPE_KL_WEEK: i32 = 12;
pub const SUB_TYPE_KL_MONTH: i32 = 13;
pub const SUB_TYPE_BROKER: i32 = 14;
pub const SUB_TYPE_KL_QUARTER: i32 = 15;
pub const SUB_TYPE_KL_YEAR: i32 = 16;
pub const SUB_TYPE_KL_3MIN: i32 = 17;

pub const VALID_QOT_SUB_TYPES: &[i32] = &[
    SUB_TYPE_BASIC,
    SUB_TYPE_ORDER_BOOK,
    SUB_TYPE_TICKER,
    SUB_TYPE_RT,
    SUB_TYPE_KL_DAY,
    SUB_TYPE_KL_5MIN,
    SUB_TYPE_KL_15MIN,
    SUB_TYPE_KL_30MIN,
    SUB_TYPE_KL_60MIN,
    SUB_TYPE_KL_1MIN,
    SUB_TYPE_KL_WEEK,
    SUB_TYPE_KL_MONTH,
    SUB_TYPE_BROKER,
    SUB_TYPE_KL_QUARTER,
    SUB_TYPE_KL_YEAR,
    SUB_TYPE_KL_3MIN,
];

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct SubscribeOptionsPlan {
    pub requested_session: i32,
    pub backend_session: i32,
    pub extended_time: bool,
    pub orderbook_detail: bool,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RegQotPushResolvedSecurity {
    pub sec_key: String,
    pub stock_id: u64,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RegQotPushLookup {
    Missing,
    Present { stock_id: u64 },
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum SubscribePlanError {
    OvernightSessionUnsupported,
}

impl SubscribeOptionsPlan {
    /// Normalize Qot_Sub option fields.
    ///
    /// C++ `APIServer_Qot_Sub.cpp:194-200` rejects `Session_OVERNIGHT`.
    /// C++ `ToSession(bExtendedTime, Session_NONE)` maps omitted session to
    /// ETH when `extended_time=true`, otherwise RTH.
    pub fn from_raw(
        requested_session: Option<i32>,
        extended_time: Option<bool>,
        orderbook_detail: Option<bool>,
    ) -> Result<Self, SubscribePlanError> {
        let requested_session = requested_session.unwrap_or(SESSION_NONE);
        if requested_session == SESSION_OVERNIGHT {
            return Err(SubscribePlanError::OvernightSessionUnsupported);
        }

        let extended_time = extended_time.unwrap_or(false);
        let backend_session = if requested_session == SESSION_NONE {
            if extended_time {
                SESSION_ETH
            } else {
                SESSION_RTH
            }
        } else {
            requested_session
        };

        Ok(Self {
            requested_session,
            backend_session,
            extended_time,
            orderbook_detail: orderbook_detail.unwrap_or(false),
        })
    }
}

/// Whether a public `Qot_Common.QotMarket` value is accepted by `Qot_Sub`.
///
/// This intentionally mirrors the historical gateway gate exactly. `RegQotPush`
/// also uses this predicate, but does not use [`normalize_qot_sub_market`]
/// because C++ `RegQotPush` resolves the submitted `Qot_Common::Security` as-is.
/// Ref: `proto/Qot_Common.proto:8-21`.
#[must_use]
pub fn is_valid_qot_market(market: i32) -> bool {
    matches!(market, 1 | 11 | 21 | 22 | 31 | 41 | 51 | 61 | 71 | 81 | 91)
}

/// Normalize `Qot_Sub` market input.
///
/// `Qot_Sub` is a user-facing API and historically accepted callers that sent
/// `Trd_Common.TrdMarket` enum values instead of `Qot_Common.QotMarket`.
/// Preserve that compatibility in the shared QOT domain so gateway surfaces do
/// not each carry their own mapping table. `RegQotPush` intentionally bypasses
/// this helper; see [`is_valid_qot_market`].
#[must_use]
pub fn normalize_qot_sub_market(market: i32) -> Option<i32> {
    if is_valid_qot_market(market) {
        return Some(market);
    }

    // Ref: `proto/Trd_Common.proto:24-40` and `proto/Qot_Common.proto:8-21`.
    // This is compatibility for callers that accidentally send TrdMarket enum
    // values to Qot_Sub; new code should send QotMarket values directly.
    match market {
        2 => Some(11),   // TrdMarket.US -> QotMarket.US
        3 => Some(21),   // TrdMarket.CN -> QotMarket.CNSH（默认上海）
        4 => Some(1),    // TrdMarket.HKCC -> QotMarket.HK
        5 => Some(1),    // TrdMarket.Futures -> QotMarket.HK（fallback）
        6 => Some(31),   // TrdMarket.SG -> QotMarket.SG
        7 => Some(91),   // TrdMarket.Crypto -> QotMarket.CC
        8 => Some(51),   // TrdMarket.AU -> QotMarket.AU
        15 => Some(41),  // TrdMarket.JP -> QotMarket.JP
        111 => Some(61), // TrdMarket.MY -> QotMarket.MY
        112 => Some(71), // TrdMarket.CA -> QotMarket.CA
        _ => None,
    }
}

/// Resolve `Qot_RegQotPush.security_list` to cache keys and stock ids.
///
/// Unlike `Qot_Sub`, C++ `RegQotPush` resolves the submitted
/// `Qot_Common::Security` as-is and does not apply the TrdMarket compatibility
/// mapping. The caller supplies a cache lookup closure so this pure domain
/// helper stays independent from `futu-cache`.
pub fn resolve_reg_qot_push_securities<F>(
    securities: &[futu_proto::qot_common::Security],
    mut lookup_stock_id: F,
) -> Result<Vec<RegQotPushResolvedSecurity>, String>
where
    F: FnMut(&str) -> RegQotPushLookup,
{
    let mut resolved = Vec::with_capacity(securities.len());
    for sec in securities {
        if sec.code.trim().is_empty() {
            return Err(
                "RegQotPush: code 不能为空。C++ 会先对 securityList 逐项调用 GetStockID，\
                 空 code 不能进入 push 注册/取消。"
                    .to_string(),
            );
        }
        if !is_valid_qot_market(sec.market) {
            return Err(format!(
                "RegQotPush: 非法 market={} for code={}。valid QotMarket: \
                 1=HK/11=US/21=CNSH/22=CNSZ/31=SG/41=JP/51=AU/61=MY/71=CA/81=FX/91=CC。",
                sec.market, sec.code
            ));
        }

        let sec_key = format!("{}_{}", sec.market, sec.code);
        match lookup_stock_id(&sec_key) {
            RegQotPushLookup::Missing => {
                return Err(format!(
                    "RegQotPush: 未知证券 {}。C++ APIServer_Qot_RegQotPush.cpp:36-47 \
                     在 register/unregister 前都会先 GetStockID；daemon 无法从静态表解析该证券，\
                     不执行 push 注册状态变更。",
                    sec_key
                ));
            }
            RegQotPushLookup::Present { stock_id: 0 } => {
                return Err(format!(
                    "RegQotPush: 证券 {} 缺少 stock_id。C++ 需要 GetStockID 成功后才会调用 \
                     RegOrUnRegPush；daemon 不执行 push 注册状态变更。",
                    sec_key
                ));
            }
            RegQotPushLookup::Present { stock_id } => {
                resolved.push(RegQotPushResolvedSecurity { sec_key, stock_id });
            }
        }
    }
    Ok(resolved)
}

#[must_use]
pub fn is_kl_sub_type(sub_type: i32) -> bool {
    matches!(
        sub_type,
        SUB_TYPE_KL_DAY
            | SUB_TYPE_KL_5MIN
            | SUB_TYPE_KL_15MIN
            | SUB_TYPE_KL_30MIN
            | SUB_TYPE_KL_60MIN
            | SUB_TYPE_KL_1MIN
            | SUB_TYPE_KL_WEEK
            | SUB_TYPE_KL_MONTH
            | SUB_TYPE_KL_QUARTER
            | SUB_TYPE_KL_YEAR
            | SUB_TYPE_KL_3MIN
    )
}

#[must_use]
pub fn is_valid_sub_type(sub_type: i32) -> bool {
    VALID_QOT_SUB_TYPES.contains(&sub_type)
}

/// Return the public name for option sub types rejected by C++ Qot_Sub.
///
/// Ref: C++ `APIServer_Qot_Sub.cpp::IsOptionSupportSub`. This is a fixed
/// public proto compatibility matrix, not dynamic backend configuration.
#[must_use]
pub fn unsupported_option_sub_type_name(sub_type: i32) -> Option<&'static str> {
    match sub_type {
        SUB_TYPE_NONE => Some("None"),
        SUB_TYPE_KL_30MIN => Some("KL_30Min"),
        SUB_TYPE_KL_WEEK => Some("KL_Week"),
        SUB_TYPE_KL_MONTH => Some("KL_Month"),
        SUB_TYPE_KL_QUARTER => Some("KL_Quarter"),
        SUB_TYPE_KL_YEAR => Some("KL_Year"),
        SUB_TYPE_KL_3MIN => Some("KL_3Min"),
        _ => None,
    }
}

#[must_use]
pub fn reg_push_rehab_types(sub_type: i32, requested: &[i32]) -> Vec<i32> {
    if is_kl_sub_type(sub_type) {
        if requested.is_empty() {
            // C++ RegOrUnRegPush: KL 未指定 rehab 时默认前复权.
            vec![1]
        } else {
            requested.to_vec()
        }
    } else {
        vec![0]
    }
}

#[must_use]
pub fn kl_type_for_sub_type(sub_type: i32) -> Option<i32> {
    match sub_type {
        SUB_TYPE_KL_1MIN => Some(1),
        SUB_TYPE_KL_DAY => Some(2),
        SUB_TYPE_KL_WEEK => Some(3),
        SUB_TYPE_KL_MONTH => Some(4),
        SUB_TYPE_KL_YEAR => Some(5),
        SUB_TYPE_KL_5MIN => Some(6),
        SUB_TYPE_KL_15MIN => Some(7),
        SUB_TYPE_KL_30MIN => Some(8),
        SUB_TYPE_KL_60MIN => Some(9),
        SUB_TYPE_KL_3MIN => Some(10),
        SUB_TYPE_KL_QUARTER => Some(11),
        _ => None,
    }
}

#[must_use]
pub fn backend_subscribe_market_for_security(
    requested_market: i32,
    sec_type: i32,
    mkt_id: u32,
) -> i32 {
    if sec_type == SECURITY_TYPE_DRVT {
        return match mkt_id {
            // Ref: futu-backend stock_list::market_id_matches(HKOption/USOption).
            // C++ resolves option rows before subscription; when the option row
            // is known, route CMD6211 to the option NN_QuoteMktType bucket
            // instead of the owner market bucket.
            7 | 8 | 570..=579 => BACKEND_MARKET_HK_OPTION,
            41..=45 => BACKEND_MARKET_US_OPTION,
            // Some option-chain/static rows may not carry the precise market_id
            // in older caches. In that case the public owner market still
            // identifies HK vs US options.
            _ => match requested_market {
                1 => BACKEND_MARKET_HK_OPTION,
                11 => BACKEND_MARKET_US_OPTION,
                _ => requested_market,
            },
        };
    }

    if sec_type != SECURITY_TYPE_FUTURE {
        return requested_market;
    }

    match mkt_id {
        // C++ `APIServer_Inner_API.cpp::Market_NNToAPI` exposes HK futures as
        // QotMarket_HK_Security to clients, while backend CMD6211 still needs
        // NN_QuoteMktType_FUT_HK / FUT_HK_NEW in header reserved[0]. The
        // `mkt_id` ranges below mirror `stock_list::market_id_matches`.
        5 => 5,
        6 | 110..=119 => 6,
        60..=109 => 14,
        160..=179 => 13,
        185..=194 => 16,
        // v1.4.108 Henry live report: HK futures such as FUCOnext/FUCOmain
        // can arrive with private market_code=1406. Treat the whole 1400
        // bucket as HK futures only after sec_type has proven this row is a
        // future; non-future rows never enter this branch.
        1400..=1499 => 6,
        _ => match requested_market {
            1 | 2 => 6,
            11 => 14,
            31 => 13,
            41 => 16,
            _ => requested_market,
        },
    }
}

/// Extract the public `QotMarket` prefix from a gateway/cache sec_key.
///
/// The canonical key format is `"{market}_{code}"`. The code part is allowed
/// to contain additional underscores because only the first separator belongs
/// to the key envelope.
#[must_use]
pub fn public_market_from_sec_key(sec_key: &str) -> Option<i32> {
    let (market, code) = sec_key.split_once('_')?;
    if code.is_empty() {
        return None;
    }
    market.parse().ok()
}

/// Derive the backend desired-set key for a cached subscription row.
///
/// `Qot_Sub` stores subscriptions under the public FTAPI sec_key, but backend
/// CMD6211 desired set must use the precise backend quote market for futures.
/// This helper keeps the "parse public key, then derive backend market from
/// cache sec_type/mkt_id" rule in one place for normal unsubscribe and
/// unsub-all paths.
#[must_use]
pub fn backend_desired_key_for_sec_key(
    sec_key: &str,
    stock_id: u64,
    sec_type: i32,
    mkt_id: u32,
) -> Option<(u64, i32)> {
    if stock_id == 0 {
        return None;
    }
    let public_market = public_market_from_sec_key(sec_key)?;
    Some((
        stock_id,
        backend_subscribe_market_for_security(public_market, sec_type, mkt_id),
    ))
}

#[cfg(test)]
mod tests;