futu_core/

market.rs

//! 市场 enum 与时区 dispatch（v1.4.69 跨 crate 共享）
//!
//! v1.4.68 以前 `bridge/utils.rs` 和 `qot/util.rs` 各维护一份 `qot_market_to_tz`
//! 实装（L40 一行 match）。注释约定 "修改需同步 sync"。v1.4.69 合并到
//! `futu-core::market`，两个调用方都 `use futu_core::market::qot_market_to_tz`
//! 避免重复维护。
//!
//! 对齐 C++ `APIServer_Inner_API.cpp::GetTimeZoneByAPIQotMkt` (L3684) — 按
//! FTAPI `QotMarket` enum 值分 IANA 时区。
//!
//! **映射表**:
//!
//! | FTAPI QotMarket | 值 | IANA Tz | C++ E_StandardTime |
//! |---|---|---|---|
//! | HK_Security | 1 | Asia/Hong_Kong | China |
//! | HK_Future (deprecated) | 2 | Asia/Hong_Kong | China |
//! | US_Security | 11 | America/New_York (DST) | USEastern |
//! | CNSH_Security | 21 | Asia/Hong_Kong | China |
//! | CNSZ_Security | 22 | Asia/Hong_Kong | China |
//! | SG_Security | 31 | Asia/Singapore | SG |
//! | JP_Security | 41 | Asia/Tokyo | JP |
//! | AU_Security | 51 | Australia/Sydney (DST) | AU |
//! | MY_Security | 61 | Asia/Kuala_Lumpur | MY |
//! | CA_Security | 71 | America/Toronto (DST) | CA |
//! | FX_Security | 81 | Asia/Hong_Kong (fallback) | — |
//! | CC_Security | 91 | America/New_York (DST) | USEastern |
//! | EventContract | 101 | America/New_York (DST) | USEastern |
//! | 其他/Unknown | — | Asia/Hong_Kong (fallback 零回归) | China default |

/// FTAPI `Qot_Common.QotMarket` domain.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct QotMarketId(i32);

impl QotMarketId {
    #[must_use]
    pub const fn new(raw: i32) -> Self {
        Self(raw)
    }

    #[must_use]
    pub const fn raw_i32(self) -> i32 {
        self.0
    }
}

/// FTAPI `Trd_Common.TrdSecMarket` domain.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct TrdSecMarketId(i32);

impl TrdSecMarketId {
    #[must_use]
    pub const fn new(raw: i32) -> Self {
        Self(raw)
    }

    #[must_use]
    pub const fn raw_i32(self) -> i32 {
        self.0
    }
}

/// Backend `NN_QuoteMktID` / mkt_id domain.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub struct BackendMktId(u32);

impl BackendMktId {
    #[must_use]
    pub const fn new(raw: u32) -> Self {
        Self(raw)
    }

    #[must_use]
    pub const fn raw_u32(self) -> u32 {
        self.0
    }
}

/// **Stable API** (since v1.4.69) — 市场 dispatch 表 entry（跨 crate 共享）。
///
/// 合并 3 个 fn 的重复 match case：
/// - `sec_market_from_code_prefix`（prefix → sec_market）
/// - `sec_market_to_qot_market`（sec_market → qot_market）
/// - `sec_market_to_exchange_str`（sec_market → exchange_str）
///
/// 每 entry 覆盖一个 market family（9 个标准市场）。新加市场只需加表一行，
/// 3 个 helper 自动支持（vs 之前 3 处独立 match 容易漏 case）。
///
/// **CN 特例**：CN prefix 没有标 sec_market（由 code 首数字判 SH(31) vs
/// SZ(32)），因此 `prefix == "CN."` 的 entry 不放表里，`sec_market_from_code_prefix`
/// 对 `CN.` 单独处理。
pub struct MarketDispatchEntry {
    pub prefix: &'static str,
    pub sec_market: i32,
    pub qot_market: u32,
    pub exchange_str: &'static str,
}

/// **Stable API** (since v1.4.69) — 9 个标准市场 dispatch 表常量。
///
/// 对齐 C++ `_NNProto_Trd_Comm.cpp::GetStockExchangeByMktID` + FTAPI
/// QotMarket/TrdSecMarket proto 枚举。
pub const MARKET_DISPATCH: &[MarketDispatchEntry] = &[
    MarketDispatchEntry {
        prefix: "HK.",
        sec_market: 1,
        qot_market: 1,
        exchange_str: "SEHK",
    },
    MarketDispatchEntry {
        prefix: "US.",
        sec_market: 2,
        qot_market: 11,
        exchange_str: "US",
    },
    MarketDispatchEntry {
        prefix: "SH.",
        sec_market: 31,
        qot_market: 21,
        exchange_str: "SSE",
    },
    MarketDispatchEntry {
        prefix: "SZ.",
        sec_market: 32,
        qot_market: 22,
        exchange_str: "SZSE",
    },
    MarketDispatchEntry {
        prefix: "SG.",
        sec_market: 41,
        qot_market: 31,
        exchange_str: "SGX",
    },
    MarketDispatchEntry {
        prefix: "JP.",
        sec_market: 51,
        qot_market: 41,
        exchange_str: "TSE",
    },
    MarketDispatchEntry {
        prefix: "AU.",
        sec_market: 61,
        qot_market: 51,
        exchange_str: "ASX",
    },
    MarketDispatchEntry {
        prefix: "MY.",
        sec_market: 71,
        qot_market: 61,
        exchange_str: "BURSA",
    },
    MarketDispatchEntry {
        prefix: "CA.",
        sec_market: 81,
        qot_market: 71,
        exchange_str: "TSX",
    },
];

/// **Stable API** (since v1.4.69) — 查 sec_market 对应的 entry（O(n)，n=9 常数时间）。
pub fn entry_by_sec_market(sec_market: i32) -> Option<&'static MarketDispatchEntry> {
    entry_by_trd_sec_market_id(TrdSecMarketId::new(sec_market))
}

/// Typed lookup for `TrdSecMarketId` → market dispatch entry.
pub fn entry_by_trd_sec_market_id(
    sec_market: TrdSecMarketId,
) -> Option<&'static MarketDispatchEntry> {
    MARKET_DISPATCH
        .iter()
        .find(|e| e.sec_market == sec_market.raw_i32())
}

/// Typed lookup for `QotMarketId` → market dispatch entry.
pub fn entry_by_qot_market_id(qot_market: QotMarketId) -> Option<&'static MarketDispatchEntry> {
    MARKET_DISPATCH
        .iter()
        .find(|e| e.qot_market as i32 == qot_market.raw_i32())
}

/// User-facing display prefix for public `Qot_Common.QotMarket` values.
///
/// Spot/security markets come from [`MARKET_DISPATCH`] so new market families
/// are not re-hardcoded per surface. `HK_FUTURE`, `FX`, and `CC` are public
/// QotMarket values that do not map to the stock dispatch table.
#[must_use]
pub fn qot_market_display_prefix(qot_market: QotMarketId) -> Option<&'static str> {
    if let Some(entry) = entry_by_qot_market_id(qot_market) {
        return Some(entry.prefix.strip_suffix('.').unwrap_or(entry.prefix));
    }

    match qot_market.raw_i32() {
        2 => Some("HK_FUTURE"),
        81 => Some("FX"),
        91 => Some("CC"),
        // Ref: APIServer_Inner_API.cpp:5306-5307 GetMarketCodePrefix.
        101 => Some("EC"),
        _ => None,
    }
}

/// `Qot_Common.QotMarketState` enum -> user-facing diagnostic label.
///
/// Strictly follows `proto/Qot_Common.proto` market-state values, including
/// night/overnight/futures states. This is display-only: protocol handlers
/// must keep forwarding the original numeric value.
#[must_use]
pub const fn qot_market_state_label(state: i32) -> &'static str {
    match state {
        0 => "None",
        1 => "Auction",
        2 => "WaitingOpen",
        3 => "Morning",
        4 => "Rest",
        5 => "Afternoon",
        6 => "Closed",
        8 => "PreMarketBegin",
        9 => "PreMarketEnd",
        10 => "AfterHoursBegin",
        11 => "AfterHoursEnd",
        12 => "FutuSwitchDate",
        13 => "NightOpen",
        14 => "NightEnd",
        15 => "FutureDayOpen",
        16 => "FutureDayBreak",
        17 => "FutureDayClose",
        18 => "FutureDayWaitForOpen",
        19 => "HkCas",
        20 => "FutureNightWait",
        21 => "FutureAfternoon",
        22 => "FutureSwitchDate",
        23 => "FutureOpen",
        24 => "FutureBreak",
        25 => "FutureBreakOver",
        26 => "FutureClose",
        27 => "StibAfterHoursWait",
        28 => "StibAfterHoursBegin",
        29 => "StibAfterHoursEnd",
        30 => "CloseAuction",
        31 => "AfternoonEnd",
        32 => "Night",
        33 => "OvernightBegin",
        34 => "OvernightEnd",
        35 => "TradeAtLast",
        36 => "TradeAuction",
        37 => "Overnight",
        _ => "Unknown",
    }
}

/// Typed conversion from `TrdSecMarketId` to public `QotMarketId`.
pub fn trd_sec_market_to_qot_market_id(sec_market: TrdSecMarketId) -> Option<QotMarketId> {
    entry_by_trd_sec_market_id(sec_market).map(|e| QotMarketId::new(e.qot_market as i32))
}

/// **Stable API** (since v1.4.69) — 查 code prefix 对应的 entry（含 `CN.` 特殊分派）。
///
/// `CN.` 按 code 首数字判 SH(31) vs SZ(32)：
/// - `6` / `9` → SH entry (sec_market=31)
/// - `0` / `2` / `3` → SZ entry (sec_market=32)
/// - 其他 → SH entry（default）
pub fn entry_by_code_prefix(code: &str) -> Option<&'static MarketDispatchEntry> {
    // CN. 特殊分派（SH/SZ by first digit）
    if let Some(bare) = code.strip_prefix("CN.") {
        let sec_market = match bare.chars().next() {
            Some('6') | Some('9') => 31,
            Some('0') | Some('2') | Some('3') => 32,
            _ => 31, // default SH
        };
        return entry_by_sec_market(sec_market);
    }
    MARKET_DISPATCH.iter().find(|e| code.starts_with(e.prefix))
}

/// **Stable API** (since v1.4.69) — FTAPI QotMarket 值 → IANA 时区 dispatch。
///
/// 已知未覆盖：FX_Security / 未知 market 值 → HKT fallback 保证零回归。
#[must_use]
pub fn qot_market_to_tz(market: i32) -> chrono_tz::Tz {
    qot_market_id_to_tz(QotMarketId::new(market))
}

/// Typed variant of [`qot_market_to_tz`].
#[must_use]
pub fn qot_market_id_to_tz(market: QotMarketId) -> chrono_tz::Tz {
    match market.raw_i32() {
        1 | 2 | 21 | 22 => chrono_tz::Asia::Hong_Kong, // HK / HK_Future / CNSH / CNSZ
        11 => chrono_tz::America::New_York,            // US (DST-aware)
        31 => chrono_tz::Asia::Singapore,              // SG
        41 => chrono_tz::Asia::Tokyo,                  // JP
        51 => chrono_tz::Australia::Sydney,            // AU (DST-aware)
        61 => chrono_tz::Asia::Kuala_Lumpur,           // MY
        71 => chrono_tz::America::Toronto,             // CA (DST-aware)
        // Ref: APIServer_Inner_API.cpp:5699-5704. Both crypto and event
        // contracts use E_StandardTime_USEastern in the C++ runtime.
        91 | 101 => chrono_tz::America::New_York,
        _ => chrono_tz::Asia::Hong_Kong, // 未知 fallback HKT
    }
}

/// **Stable API** (since v1.4.71) — FTAPI `TrdMarket` 值 → IANA 时区 dispatch。
///
/// **对齐 C++ `GetTimeZoneByTrdMkt`**（`APIServer_Inner_API.cpp:4022`），用于：
/// 1. 用户传的 `begin_time` / `end_time` 字符串解析（C++ `APITimeStrToTimeStamp_Trd`）
/// 2. backend 返回的时间戳 → market local 时间字符串（C++ `TimeStampToAPITimeStr_Trd`）
/// 3. 历史查询 default time range fallback（查 US 账户 "最近 90 天" 应按 US tz 算）
///
/// | FTAPI TrdMarket | 值 | 时区 | C++ `E_StandardTime` |
/// |---|---|---|---|
/// | HK / CN / HKCC | 1/3/4 | Asia/Hong_Kong (UTC+8) | China |
/// | US | 2 | America/New_York (DST-aware EDT/EST) | USEastern |
/// | SG | 6 | Asia/Singapore (UTC+8) | SG |
/// | AU | 8 | Australia/Sydney (DST-aware AEDT/AEST) | AU |
/// | JP | 15 | Asia/Tokyo (UTC+9) | JP |
/// | MY | 111 | Asia/Kuala_Lumpur (UTC+8) | MY |
/// | CA | 112 | America/Toronto (DST-aware EDT/EST) | CA |
/// | Futures (5) / Unknown (0) | 5/0/其他 | Asia/Hong_Kong fallback | China |
///
/// Futures/Prediction callers that possess backend `mkt_id` must use
/// [`trd_market_with_mkt_id_to_tz_like_cpp`]. This market-only helper keeps the
/// C++ China/HK fallback for callers without that sub-exchange identity.
#[must_use]
pub fn trd_market_to_tz(trd_market: i32) -> chrono_tz::Tz {
    match trd_market {
        1 | 3 | 4 => chrono_tz::Asia::Hong_Kong, // HK / CN / HKCC
        2 => chrono_tz::America::New_York,       // US (DST-aware)
        6 => chrono_tz::Asia::Singapore,         // SG
        8 => chrono_tz::Australia::Sydney,       // AU (DST-aware)
        15 => chrono_tz::Asia::Tokyo,            // JP
        111 => chrono_tz::Asia::Kuala_Lumpur,    // MY
        112 => chrono_tz::America::Toronto,      // CA (DST-aware)
        // Futures (5) / Unknown (0) / 未映射：fallback HKT
        // C++ Futures 按 mkt_id 细分，Rust struct 无此上下文 → 保守 HKT
        _ => chrono_tz::Asia::Hong_Kong,
    }
}

/// Resolve a trade timestamp timezone from the FTAPI/NN trade market plus the
/// backend quote-market identity exactly like C++ `GetTimeZoneByTrdMkt`.
///
/// The numeric ranges below are protocol enum constants, not server-configured
/// routing data. Ref: `APIServer_Inner_API.cpp:5757-5882` and
/// `NNBase_Define_Enum.h:174-177,874-903,952-979,1026-1031`. They must be
/// revisited if those upstream enum ranges or `GetFutureStandardTime` change.
#[must_use]
pub fn trd_market_with_mkt_id_to_tz_like_cpp(
    trd_market: Option<i32>,
    mkt_id: Option<u32>,
) -> chrono_tz::Tz {
    // Ref: `NNBase_Define_Enum.h:174-177` defines the literal 10/11/12/13
    // identities; `APIServer_Inner_API.cpp:5794-5801,5836-5879` defines their
    // timezone behavior. These are fixed protocol constants, not dynamic
    // server data; replace this dispatch only if the upstream NN_TrdMarket
    // enum changes.
    match trd_market.unwrap_or(0) {
        10 => return chrono_tz::Asia::Hong_Kong,
        11 => return chrono_tz::America::New_York,
        12 => return chrono_tz::Asia::Singapore,
        13 => return chrono_tz::Asia::Tokyo,
        _ => {}
    }

    // Ref: `APIServer_Inner_API.cpp:5760-5786,5816-5819,5876-5879`.
    // Futures=5 and Prediction=17 deliberately share the backend mkt-id table.
    if matches!(trd_market, Some(5 | 17)) {
        return match mkt_id {
            Some(60..=79) => chrono_tz::America::New_York,
            Some(80..=109) => chrono_tz::America::Chicago,
            Some(160..=179) => chrono_tz::Asia::Singapore,
            Some(185..=194 | 800..=849) => chrono_tz::Asia::Tokyo,
            _ => chrono_tz::Asia::Hong_Kong,
        };
    }

    trd_market_to_tz(trd_market.unwrap_or(0))
}

#[cfg(test)]
mod tests;