futu_gateway_core/bridge/

utils.rs

//! bridge 工具函数（v1.4.60 Phase E1 从 bridge/mod.rs 抽出）
//!
//! 纯 utility 函数：无状态 / 无 `GatewayBridge` 依赖 / 无 async / 无 I/O。
//! 统一 `pub(crate)` 让 bridge 子模块 + GatewayBridge 自己都能用。
//!
//! 包含：
//! - `split_host_port` — "IP:port" 拆解
//! - `listing_date_to_str` — stock-list 上市日时间戳 → HK/China 日期
//! - `timestamp_to_datetime_str` — Unix 时间戳 → 市场本地日期时间
//! - `qot_market_to_tz` — FTAPI QotMarket → IANA 时区（v1.4.68）
//! - `market_code_to_qot_market` — backend NN_QuoteMktID → FTAPI QotMarket
//! - `market_code_to_exch_type` — backend NN_QuoteMktID → FTAPI ExchType
//! - `*_with_security` — market_code 未知时，用 stock_list 证券类型/code 做受控兜底
//! - `security_firm_to_broker_id` — SecurityFirm → broker_id 反查

/// 把 "IP:port" 字符串拆成 (IP, port)。失败时返回默认 port 9595。
/// 用于 TCP 登录时上报 `ReqEncryptData.host_ip` / `host_port`。
pub(crate) fn split_host_port(addr: &str) -> (String, u32) {
    match addr.rsplit_once(':') {
        Some((host, port_text)) if !host.is_empty() => {
            let port = port_text.parse::<u32>().unwrap_or(9595);
            (host.to_string(), port)
        }
        _ => (addr.to_string(), 9595),
    }
}

// v1.4.69 A1: `qot_market_to_tz` 已迁移到 `futu_core::market::qot_market_to_tz`
// （跨 crate 共享，bridge + qot handler 都 `use futu_core::market::qot_market_to_tz`）
// 本 inline 实装删除，依 futu-core 单一 source of truth。
pub(crate) use futu_core::market::qot_market_to_tz;
use futu_core::market::{BackendMktId, QotMarketId};

/// listing_date (Unix timestamp 秒) → "YYYY-MM-DD" HK/China 日期
///
/// C++ `GetStockStaticInfo` / `StockSnapshot` explicitly render stock-list
/// `nListingDate` with `QotMarket_HK_Security`:
/// “后台返回的上市时间都是中国时区转出来的”. Do not use the quote market timezone
/// here; US static `list_time` would otherwise move one day earlier.
pub fn listing_date_to_str(ts: u32, _market: i32) -> String {
    // C++ 对 listing_date=0 也正常格式化为 "1970-01-01"（不跳过）
    use chrono::DateTime;
    let tz = qot_market_to_tz(1);
    match DateTime::from_timestamp(ts as i64, 0) {
        Some(dt) => dt.with_timezone(&tz).format("%Y-%m-%d").to_string(),
        None => String::new(),
    }
}

/// Unix 时间戳(秒) → "YYYY-MM-DD HH:MM:SS" 市场本地时区
///
/// v1.4.68 Bug fix：原实装 hardcode `+8*3600` HKT → push 行情 update_time
/// 美股显示差 12-13h。对齐 C++ `APITimeStampToTimeStr_Qot`。
pub fn timestamp_to_datetime_str(ts: f64, market: i32) -> String {
    if ts <= 0.0 {
        return String::new();
    }
    use chrono::DateTime;
    let tz = qot_market_to_tz(market);
    match DateTime::from_timestamp(ts as i64, 0) {
        Some(dt) => dt
            .with_timezone(&tz)
            .format("%Y-%m-%d %H:%M:%S")
            .to_string(),
        None => String::new(),
    }
}

// v1.4.68: days_to_ymd helper 已删除（bridge/utils.rs 里曾被 listing_date_to_str
// + timestamp_to_datetime_str 用，v1.4.68 改用 chrono-tz 后不再需要 manual
// Rata Die 算法。trd/max_qty.rs 仍有独立 copy 作 free cash flow 日期计算）。

/// 后端 market_code (NN_QuoteMktID) → FTAPI QotMarket 映射
/// 对齐 C++: NN_QuoteMktType_From_NN_QuoteMktID() → Market_NNToAPI()
pub(crate) fn market_code_to_qot_market(market_code: u32) -> i32 {
    market_code_to_qot_market_id(BackendMktId::new(market_code)).raw_i32()
}

/// Typed backend `NN_QuoteMktID` → public FTAPI `QotMarket`.
pub(crate) fn market_code_to_qot_market_id(market_code: BackendMktId) -> QotMarketId {
    QotMarketId::new(match market_code.raw_u32() {
        // HK market: mainboard, gemboard, nasdaq, extend → QotMarket_HK_Security
        1..=4 => 1,
        // HK futures (old/new) → QotMarket_HK_Security (QotMarket_HK_Future=2 已废弃)
        5 | 6 => 1,
        // HK options (stock option, index option) → QotMarket_HK_Security
        7 | 8 => 1,
        // US market: NYSE, NASDAQ, AMEX, PINK, etc.
        10..=29 => 11, // QotMarket_US_Security
        // CN A-shares
        30 | 32 | 33 | 34 | 36..=40 => 21, // SH, KCB → QotMarket_CNSH_Security
        31 | 35 => 22,                     // SZ, CYB → QotMarket_CNSZ_Security
        // US options
        41..=49 => 11, // QotMarket_US_Security
        // US futures: NYMEX, COMEX, CBOT, CME, CBOE
        60..=109 => 11, // QotMarket_US_Security
        // HK futures (new range)
        110..=119 => 1, // QotMarket_HK_Security
        // Forex
        120..=123 => 81, // QotMarket_FX_Security
        // SG futures
        160..=179 => 31, // QotMarket_SG_Security
        // SG cash
        180..=184 => 31, // QotMarket_SG_Security
        // JP futures
        185..=194 => 41, // QotMarket_JP_Security
        // Crypto / digital currency.
        //
        // Ref:
        // - FutuOpenD/Src/NNBase/NNBase_Define_Enum.h:
        //   NN_QuoteMktID_Digital_CCY_Min=360,
        //   NN_QuoteMktID_Digital_CCY_Max=459.
        // - FutuOpenD/Src/NNBase/NNBase_Define_Inline.h:
        //   NN_QuoteMktType_From_NN_QuoteMktID maps this range to
        //   NN_QuoteMktType_CRYPTO.
        360..=459 => 91, // QotMarket_CC_Security
        // HK index option
        570 => 1, // QotMarket_HK_Security
        // JP cash/index
        800..=849 => 41, // QotMarket_JP_Security
        // HK HSI index
        1000..=1049 => 1, // QotMarket_HK_Security
        // US new market codes
        1200..=1249 => 11, // QotMarket_US_Security
        // MY cash
        1350..=1399 => 61, // QotMarket_MY_Security
        _ => 0,            // Unknown
    })
}

const STOCK_LIST_SEC_TYPE_FUTURE: u32 = 10;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum FuturesRegion {
    Hk,
    Us,
    Sg,
    Jp,
}

/// backend stock_list 里未知 market_code 的受控 fallback。
///
/// 正常路径仍以 `market_code_to_qot_market()` 为准；只有当旧 C++ enum / Rust
/// 静态表不认识 market_code，且 `instrument_type=10(Future)` 时，才看 code。
/// C++ 10.7 source defines `NN_QuoteMktID_MY_Futures_Min/Max = 1400..1449`,
/// but does not map that range through `NN_QuoteMktType_From_NN_QuoteMktID`
/// or `ExchType_NNToAPI`. Keep it fail-closed instead of resurrecting the
/// older private-HK-future fallback.
pub fn market_code_to_qot_market_with_security(
    market_code: u32,
    code: &str,
    instrument_type: u32,
) -> i32 {
    let mapped = market_code_to_qot_market(market_code);
    if mapped != 0 {
        return mapped;
    }

    if instrument_type != STOCK_LIST_SEC_TYPE_FUTURE {
        return 0;
    }

    if (1400..=1449).contains(&market_code) {
        return 0;
    }

    match infer_futures_region_from_code(code) {
        Some(FuturesRegion::Hk) => 1,
        Some(FuturesRegion::Us) => 11,
        Some(FuturesRegion::Sg) => 31,
        Some(FuturesRegion::Jp) => 41,
        None => 0,
    }
}

/// 后端 market_code → FTAPI ExchType 映射
/// 对齐 C++ `APIServer_Inner_API.cpp::ExchType_NNToAPI`.
///
/// v1.4.93 P1-3 (BUG-5318-003 / BUG-60b0-004 30+ 版未修): 补 US 期货子交易所
/// (NYMEX/COMEX/CBOT/CME/CBOE) 映射. mkt_id range 对齐
/// `handlers/trd/security_type::us_futures_sub_exchange_from_mkt_id`:
/// - 60..=69 → NYMEX (ExchType_US_NYMEX=9)
/// - 70..=79 → COMEX (ExchType_US_COMEX=10)
/// - 80..=89 → CBOT  (ExchType_US_CBOT=11)
/// - 90..=99 → CME   (ExchType_US_CME=12)
/// - 100..=109 → CBOE (ExchType_US_CBOE=13)
///
/// 之前 fallthrough `_ => 0` (Unknown) 导致 snapshot.exch_type 永远 None
/// (CLAUDE.md 坑 #45 silent-success 变种: cache miss 走 default 0 silent
/// drop). cross 30+ 版未修 (v1.4.57 BUG-60b0-004 → v1.4.90 BUG-5318-003).
pub(crate) fn market_code_to_exch_type(market_code: u32) -> i32 {
    match market_code {
        1 => 1,        // HK MainBoard → ExchType_HK_MainBoard
        2 => 2,        // HK GEM → ExchType_HK_GEMBoard
        3..=9 => 3,    // HK other → ExchType_HK_HKEX
        10 => 4,       // US NYSE → ExchType_US_NYSE
        11 => 5,       // US Nasdaq → ExchType_US_Nasdaq
        12 => 7,       // US AMEX → ExchType_US_AMEX
        13 => 6,       // US OTC → ExchType_US_Pink
        30 => 14,      // CN SH → ExchType_CN_SH
        31 | 35 => 15, // CN SZ / ChiNext → ExchType_CN_SZ
        32 => 16,      // CN KCB → ExchType_CN_STIB
        41 => 8,       // US Option → ExchType_US_Option
        // v1.4.93 P1-3: US 期货子交易所 (BUG-5318-003)
        60..=69 => 9,      // US Futures NYMEX → ExchType_US_NYMEX
        70..=79 => 10,     // US Futures COMEX → ExchType_US_COMEX
        80..=89 => 11,     // US Futures CBOT  → ExchType_US_CBOT
        90..=99 => 12,     // US Futures CME   → ExchType_US_CME
        100..=109 => 13,   // US Futures CBOE → ExchType_US_CBOE
        110..=119 => 3,    // HK Futures → ExchType_HK_HKEX
        1200 => 13,        // US .VIX series → ExchType_US_CBOE
        160..=184 => 17,   // SG Futures/Cash → ExchType_SG_SGX
        185..=194 => 18,   // JP Futures → ExchType_JP_OSE
        360..=459 => 19,   // Digital CCY → ExchType_CC_CRYPTO
        800..=829 => 22,   // JP Nikkei → ExchType_JP_Nikkei
        830..=849 => 21,   // JP TSE → ExchType_JP_TSE
        1350..=1399 => 20, // MY Securities → ExchType_MY_MYX
        _ => 0,            // Unknown
    }
}

/// `market_code_to_exch_type()` 的证券上下文版本。
///
/// 用于 stock_list sync / SQLite reload 这类已有 `code + instrument_type` 的路径；
/// 普通 handler 不应只拿 code 猜 exchange，应优先走 cache-first。
pub fn market_code_to_exch_type_with_security(
    market_code: u32,
    code: &str,
    instrument_type: u32,
) -> i32 {
    let mapped = market_code_to_exch_type(market_code);
    if mapped != 0 {
        return mapped;
    }

    if instrument_type != STOCK_LIST_SEC_TYPE_FUTURE {
        return 0;
    }

    if (1400..=1449).contains(&market_code) {
        return 0;
    }

    match infer_futures_region_from_code(code) {
        Some(FuturesRegion::Hk) => 3,
        Some(FuturesRegion::Sg) => 17,
        Some(FuturesRegion::Jp) => 18,
        // US futures 的子交易所需要 NYMEX/COMEX/CBOT/CME/CBOE 精细判断；
        // 这里没有 backend market_code range 时不猜具体 ExchType，避免把
        // `NQmain` 以外的合约误标。QotMarket 已可归 US，exch_type 保持 Unknown。
        Some(FuturesRegion::Us) | None => 0,
    }
}

fn infer_futures_region_from_code(code: &str) -> Option<FuturesRegion> {
    let trimmed = code.trim();
    if trimmed.is_empty() {
        return None;
    }

    if let Some((prefix, _)) = trimmed.split_once('.') {
        match prefix.to_ascii_uppercase().as_str() {
            "HK" => return Some(FuturesRegion::Hk),
            "US" => return Some(FuturesRegion::Us),
            "SG" => return Some(FuturesRegion::Sg),
            "JP" => return Some(FuturesRegion::Jp),
            _ => {}
        }
    }

    let ticker = extract_futures_ticker_for_region(trimmed);
    match ticker.as_str() {
        // HKFE 常见指数/波指/商品/连续合约代码。`FUCOmain/current/next`
        // 是 external tester 2026-05-05 真机日志里的触发样本。
        "HSI" | "HHI" | "HTI" | "MHI" | "MCH" | "VHSI" | "CSI300" | "CSI500" | "CSI800"
        | "FUCO" => Some(FuturesRegion::Hk),
        // CME Group / US 期货常见 ticker。这里只用于 QotMarket 粗分，exch_type
        // 不在未知 market_code 下进一步猜。
        "NQ" | "MNQ" | "ES" | "MES" | "RTY" | "M2K" | "NKD" | "YM" | "MYM" | "6E" | "6J" | "6B"
        | "6A" | "6C" | "6S" | "6M" | "6N" | "GE" | "SR3" | "BTC" | "MBT" | "ETH" | "MET"
        | "CL" | "MCL" | "NG" | "MNG" | "HO" | "RB" | "BZ" | "WBS" | "GC" | "MGC" | "SI"
        | "SIL" | "HG" | "MHG" | "PL" | "PA" | "ZS" | "ZC" | "ZW" | "ZO" | "ZR" | "ZT" | "ZF"
        | "ZN" | "ZB" | "UB" | "TN" | "VX" | "VXM" => Some(FuturesRegion::Us),
        "NK" | "N225" | "JGB" => Some(FuturesRegion::Jp),
        "CN" | "STW" | "SIR" | "FEF" => Some(FuturesRegion::Sg),
        _ => None,
    }
}

fn extract_futures_ticker_for_region(code: &str) -> String {
    let mut s = code.trim();
    if let Some((_, rest)) = s.split_once('.') {
        s = rest;
    }

    let mut upper = s.to_ascii_uppercase();
    for suffix in ["CURRENT", "NEXT", "MAIN"] {
        if upper.ends_with(suffix) && upper.len() > suffix.len() {
            upper.truncate(upper.len() - suffix.len());
            return upper;
        }
    }

    if upper.len() > 4 && upper[upper.len() - 4..].chars().all(|c| c.is_ascii_digit()) {
        upper.truncate(upper.len() - 4);
    }
    upper
}

/// v1.4.93 P1-3 (BUG-5318-003): exch_type 派生 fallback for proto field.
///
/// 优先用 cached `exch_type` (cache hit + populated → 直通); cache miss / 历史
/// SQLite 行 / backend 默认 → 用 `mkt_id` 转换. 二者都 0 → 返 None (符合 proto
/// optional 语义).
///
/// 这是 CLAUDE.md 坑 #35 的"cache-first, mkt_id-derive fallback, None as last
/// resort"模式. 之前 `make_static_info` hardcode `exch_type != 0 ? Some : None`
/// 没考虑 mkt_id 派生路径 → US 期货 snapshot/static_info 永远 None.
pub fn derive_exch_type_with_fallback(cached_exch_type: i32, mkt_id: u32) -> Option<i32> {
    if cached_exch_type != 0 {
        return Some(cached_exch_type);
    }
    let derived = market_code_to_exch_type(mkt_id);
    if derived != 0 { Some(derived) } else { None }
}

/// SecurityFirm 枚举 → broker_id 反查。
///
/// 正向映射在 `GatewayBridge::broker_to_security_firm`，这里是反向版本：
/// CachedTrdAcc 里存的是 `security_firm`，`dispatch_trade_data_queries` 需要
/// 按账户拿到对应的 broker_id 进而路由到 broker 通道。
pub(crate) fn security_firm_to_broker_id(sf: i32) -> Option<u32> {
    futu_trd::currency::security_firm_to_broker_id(sf)
}

#[cfg(test)]
mod tests;